Comment on page

Sandboxes

This pages describes sandboxes, which provide the environment for tracks.

What is a sandbox?
A sandbox is a self-contained environment created using actual products to match real-world scenarios. A sandbox can contain sandbox hosts which are containers, virtual machines or virtual browsers. And you can add multiple hosts to a sandbox. 
Learners can access sandboxes using only a web browser. And with sandboxes, learners can experiment and learn without setting up anything themselves and worrying about breaking things.
See the overview for where the sandbox fits into the Instruqt environment.
Sandbox resources
A sandbox is made up of the following resources:
Containers
Virtual machines
Virtual browsers
Cloud accounts:
Google Cloud Platform (GCP) project
AWS account
Azure subscription
Secrets
Check these topics for more information about containers, virtual machines and virtual browsers:
​Hosts and images​
​Machine types​
​
And check the cloud accounts topics for more information about cloud accounts.
Appearance
🌐 Web UI
💻 Instruqt CLI
In the Web UI, the sandbox appears within a track on the Sandbox page:
sandboxcontainer
├── 01-creating-a-directory
│   ├── assignment.md
│   ├── check-container
│   ├── cleanup-container
│   ├── setup-container
│   └── solve-container
├── config.yml
└── track.yml
In Instruqt CLI, the sandbox appears as the config.yml file (line 8) in the main directory of the track. 
Sandbox properties
You specify a sandbox by setting its properties through the Web UI or Instruqt CLI. 
For Web UI, you will find the properties as fields in the Sandbox tab of the Track details. For Instruqt CLI, you will find the properties in the configuration file config.yml as in this example:
YAML
version: "3"
containers:
- name: container
  image: ubuntu
  shell: /bin/bash
  memory: 256
The following tables show the sandbox properties grouped by resource:
🌐 Web UI
💻 Instruqt CLI
Container
Field
Description
Type
Required
Hostname
Name of the container. 

Visible to learners and becomes the short DNS hostname of the container.
string
Required
Container image
The container image URL to use for this container.
string
Required
Entrypoint
Set the container's ENTRYPOINT.

If not specified, the container image's default is used.
string
Optional
Cmd
Set the container's CMD.

If not specified, the container image's default is used.
string
Optional
Shell
Set the command to run as a shell for the learner.

If not specified, /bin/sh is used.
string
Optional
Ports
Ports to expose.
list
Optional
Environment Variables
A map of key-value pairs that will be injected as environment variables.
map
Optional
Memory
The memory limit for the container in MB. 

The maximum is 10240 MB.
integer
Required
​
Virtual machine
Field
Description
Type
Required
Hostname
Name of the virtual machine. 

Visible to learners and becomes part of the short DNS hostname of the virtual machine.
string
Required
GCP compute image
The Google Compute Engine image to use for this virtual macine.

Instruqt needs permission to pull the image. 
string
Required
Machine type
The machine type of the virtual machine.

Overview of all supported machine types  (up to 32 vCPUs and 28.8 GB memory)
string
Required
Environment Variables
A map of key-value pairs that will be injected as environment variables.
map
Optional
Shell
Defaults to /bin/sh for maximum compatibility. Set this to /bin/bash for more features.
string
Optional
Allow external ingress
Allow inbound traffic from external sources.

Valid options: 
• http
• https
• high-ports

This feature is documented on the networking page: usage instructions.
[]string
Optional
Provision SSL Certificate
Provisions an SSL certificate for this VM for the following domain names:
${hostname}.${_SANDBOX_ID}.instruqt.io
*.${hostname}.${_SANDBOX_ID}.instruqt.io
This option is only available when also enabling "Allow external ingress" for https and/or high-ports.

Read more how to use this feature.
boolean
Optional
Virtual Browser
Field
Description
Type
Required
Website name
Name of the virtual browser host
string
Required
Website URL
URL to your target saas website. The virtual browser will open this URL for learners. It should be correct url starting with "https://"
string
Required
GCP project
Field
Description
Type
Required
Name
The name of the GCP project.
string
Required
Services
Use this field to enable services on the Google Cloud project.

For a list of available services, visit the API library page or run gcloud services list --available. 

🚫You can not enable serviceusage.googleapis.com
list
Optional
Roles
Use this field to grant IAM roles to User and Service account on the Google Cloud project.
​
For a list of available roles, visit the Understanding roles page or run gcloud iam roles list.
​
Roles will default to the Owner role (roles/owner) if no roles are specified.
​
The Owner role will only be applied to the Service account. The User account will fall back to the Editor role (roles/editor). This is a limitation with Google Cloud IAM which does not allow configuring the Owner role for "external" Users.
​
⚠️ The Owner role gives full control to a project. To limit potential abuse, we suggest using more specialized roles that only give permissions to the resources/services required.
list
Optional
​
AWS account
Field
Description
Type
Required
Name
The name of the AWS account.
string
Required
IAM Policy
The Identity and Access Management (IAM) Policy document that will be attached to the account.

This can be specified as either YAML or JSON.
string
Optional
Managed Policies
A list of all managed policies that will be attached to the account.

An overview of all policies can be found in the AWS Console (requires log in)​
list
Optional
SCP Policy
The Service Control Policies (SCP) Policy document that will be attached to the account
string
Optional
​
Azure subscription
Field
Description
Type
Required
Name
The name of the Azure subscription.
string
Required
User
Only create an Azure Active Diretory (AAD) user, without an Azure Subscription.

Useful when you only need an AAD user, for instance when using Azure DevOps.
boolean
Optional
Assigned Roles
A list of roles that will be attached to the account.

You can use any built-in Azure IAM roles, such as Contributor or Owner. 

See https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles for details on the available roles.
list
Optional
Container
Main property: containers:
Sub properties:
Property
Description
Type
Required
name
Name of the container. 

Visible to learners and becomes the short DNS hostname of the container.
string
Required
image
The container image URL to use for this container.
string
Required
entrypoint
Set the container's ENTRYPOINT.

If not specified, the container image's default is used.
string
Optional
cmd
Set the container's CMD.

If not specified, the container image's default is used.
string
Optional
shell
Set the command to run as a shell for the learner.

If not specified, /bin/sh is used.
string
Optional
ports
Ports to expose.
list
Optional
environment
A map of key-value pairs that will be injected as environment variables.
map
Optional
memory
The memory limit for the container in MB. 

The maximum is 10240 MB.
integer
Optional
​
Example config.yml
YAML
version: "3"
containers:
- name: container
  image: ubuntu
  shell: /bin/bash
  memory: 256
​
Virtual machine
Main property: virtualmachines:
Sub properties:
Property
Description
Type
Required
name
Name of the virtual machine. 

Visible to learners and becomes part of the short DNS hostname of the virtual machine.
string
Required
image
The Google Compute Engine image to use for this virtual macine.

Instruqt needs permission to pull the image. 
string
Required
machine_type
The machine type of the virtual machine.

Overview of all supported machine types  (up to 32 vCPUs and 28.8 GB memory)
string
Required
environment
A map of key-value pairs that will be injected as environment variables.
map
Optional
shell
Defaults to /bin/sh for maximum compatibility. Set this to /bin/bash for more features.
string
Optional
allow_external_ingress
Allow inbound traffic from external sources.

Valid options: 
• http
• https
• high-ports

This feature is documented on the networking page: usage instructions.
[]string
Optional
Example config.yml
YAML
version: "3"
virtualmachines:
- name: vm
  image: debian-cloud/debian-9
  machine_type: g1-small
Virtual browser
Main property: virtualbrowsers:
Sub properties:
Property
Description
Type
Required
name
Name of the virtual browser. 
string
Required
url
URL to your target saas website. The virtual browser will open this URL for learners. It should be correct url starting with "https://".
string
Required
Example config.yml
YAML
version: "3"
virtualbrowsers:
- name: invites
  url: https://play.instruqt.dev
GCP project
Main property: gcp_projects:
Sub properties:
Property
Description
Type
Required
name
The name of the GCP project.
string
Required
services
Use this field to enable services on the Google Cloud project.

For a list of available services, visit the API library page or run gcloud services list --available. 

🚫You can not enable serviceusage.googleapis.com
list
Optional
roles
Use this field to grant IAM roles to User and Service account on the Google Cloud project.
​
For a list of available roles, visit the Understanding roles page or run gcloud iam roles list.
​
Roles will default to the Owner role (roles/owner) if no roles are specified.
​
The Owner role will only be applied to the Service account. The User account will fall back to the Editor role (roles/editor). This is a limitation with Google Cloud IAM which does not allow configuring the Owner role for "external" Users.
​
⚠️ The Owner role gives full control to a project. To limit potential abuse, we suggest using more specialized roles that only give permissions to the resources/services required.
list
Optional
​
Example config.yml
YAML
version: "3"
gcp_projects:
- name: gcptrack
  services:
  - compute.googleapis.com
  - container.googleapis.com
  roles:
  - roles/compute.admin
  - roles/container.admin
​
AWS account
Main property: aws_accounts: 
Sub properties:
Property
Description
Type
Required
name
The name of the AWS account.
string
Required
iam_policy
The IAM policy document that will be attached to the account.

This can be specified as either YAML or JSON.
string
Optional
managed_policies
A list of all managed policies that will be attached to the account.

An overview of all policies can be found in the AWS Console (requires log in)​
list
Optional
scp_policy
The SCP policy document that will be attached to the account
string
Optional
​
Example config.yml
YAML
version: "3"
aws_accounts:
- name: aws-iam-track
  iam_policy: |-
    {
      "Version": "2012-10-17",
      "Statement": [
        {
            "Sid":"EC2DefaultAllow",
            "Effect": "Allow",
            "Action": "ec2:*",
            "Resource": "*"
        }
      ]
    }
  scp_policy: |-
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "RequireLessThanXLInstanceType",
          "Effect": "Deny",
          "Action": "ec2:RunInstances",
          "Resource": "arn:aws:ec2:::instance/*",
          "Condition": {
            "StringNotEquals": {
              "ec2:InstanceType": [
                "t2.nano"
              ]
            }
          }
        }
      ]
    }
​
Azure subscription
Main property: azure_subscriptions:
Sub properties:
Property
Description
Type
Required
name
The name of the Azure subscription.
string
Required
user_only
Only create an AAD user, without an Azure Subscription.

Useful when you only need an AAD user, for instance when using Azure DevOps.
boolean
Optional
roles
A list of roles that will be attached to the account.

You can use any built-in Azure IAM roles, such as Contributor or Owner. 

See https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles for details on the available roles.
list
Optional
​
Example config.yml
YAML
version: "3"
azure_subscriptions:
- name: azuresubscription

Field	Description	Type	Required
Hostname	Name of the container. Visible to learners and becomes the short DNS hostname of the container.	`string`	Required
Container image	The container image URL to use for this container.	`string`	Required
Entrypoint	Set the container's ENTRYPOINT. If not specified, the container image's default is used.	`string`	Optional
Cmd	Set the container's CMD. If not specified, the container image's default is used.	`string`	Optional
Shell	Set the command to run as a shell for the learner. If not specified, `/bin/sh` is used.	`string`	Optional
Ports	Ports to expose.	`list`	Optional
Environment Variables	A map of key-value pairs that will be injected as environment variables.	`map`	Optional
Memory	The memory limit for the container in MB. The maximum is 10240 MB.	`integer`	Required

Field	Description	Type	Required
Hostname	Name of the virtual machine. Visible to learners and becomes part of the short DNS hostname of the virtual machine.	`string`	Required
GCP compute image	The Google Compute Engine image to use for this virtual macine. Instruqt needs permission to pull the image.	`string`	Required
Machine type	The machine type of the virtual machine. Overview of all supported machine types (up to 32 vCPUs and 28.8 GB memory)	`string`	Required
Environment Variables	A map of key-value pairs that will be injected as environment variables.	`map`	Optional
Shell	Defaults to `/bin/sh` for maximum compatibility. Set this to `/bin/bash` for more features.	`string`	Optional
Allow external ingress	Allow inbound traffic from external sources. Valid options: • `http` • `https`• `high-ports` This feature is documented on the networking page: usage instructions.	`[]string`	Optional
Provision SSL Certificate	Provisions an SSL certificate for this VM for the following domain names: `${hostname}.${_SANDBOX_ID}.instruqt.io` `*.${hostname}.${_SANDBOX_ID}.instruqt.io` This option is only available when also enabling "Allow external ingress" for `https` and/or `high-ports`. Read more how to use this feature.	`boolean`	Optional

Field	Description	Type	Required
Website name	Name of the virtual browser host	`string`	Required
Website URL	URL to your target saas website. The virtual browser will open this URL for learners. It should be correct url starting with "https://"	`string`	Required

Field	Description	Type	Required
Name	The name of the GCP project.	`string`	Required
Services	Use this field to enable services on the Google Cloud project. For a list of available services, visit the API library page or run `gcloud services list --available`. 🚫You can not enable serviceusage.googleapis.com	`list`	Optional
Roles	Use this field to grant IAM roles to User and Service account on the Google Cloud project. For a list of available roles, visit the Understanding roles page or run `gcloud iam roles list`. Roles will default to the Owner role (roles/owner) if no roles are specified. The Owner role will only be applied to the Service account. The User account will fall back to the Editor role (roles/editor). This is a limitation with Google Cloud IAM which does not allow configuring the Owner role for "external" Users. ⚠️ The Owner role gives full control to a project. To limit potential abuse, we suggest using more specialized roles that only give permissions to the resources/services required.	`list`	Optional

Field	Description	Type	Required
Name	The name of the AWS account.	`string`	Required
IAM Policy	The Identity and Access Management (IAM) Policy document that will be attached to the account. This can be specified as either YAML or JSON.	`string`	Optional
Managed Policies	A list of all managed policies that will be attached to the account. An overview of all policies can be found in the AWS Console (requires log in)	`list`	Optional
SCP Policy	The Service Control Policies (SCP) Policy document that will be attached to the account	`string`	Optional

Field	Description	Type	Required
Name	The name of the Azure subscription.	`string`	Required
User	Only create an Azure Active Diretory (AAD) user, without an Azure Subscription. Useful when you only need an AAD user, for instance when using Azure DevOps.	`boolean`	Optional
Assigned Roles	A list of roles that will be attached to the account. You can use any built-in Azure IAM roles, such as `Contributor` or `Owner`. See https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles for details on the available roles.	`list`	Optional

Property	Description	Type	Required
`name`	Name of the container. Visible to learners and becomes the short DNS hostname of the container.	`string`	Required
`image`	The container image URL to use for this container.	`string`	Required
`entrypoint`	Set the container's ENTRYPOINT. If not specified, the container image's default is used.	`string`	Optional
`cmd`	Set the container's CMD. If not specified, the container image's default is used.	`string`	Optional
`shell`	Set the command to run as a shell for the learner. If not specified, `/bin/sh` is used.	`string`	Optional
`ports`	Ports to expose.	`list`	Optional
`environment`	A map of key-value pairs that will be injected as environment variables.	`map`	Optional
`memory`	The memory limit for the container in MB. The maximum is 10240 MB.	`integer`	Optional

Property	Description	Type	Required
`name`	Name of the virtual machine. Visible to learners and becomes part of the short DNS hostname of the virtual machine.	`string`	Required
`image`	The Google Compute Engine image to use for this virtual macine. Instruqt needs permission to pull the image.	`string`	Required
`machine_type`	The machine type of the virtual machine. Overview of all supported machine types (up to 32 vCPUs and 28.8 GB memory)	`string`	Required
`environment`	A map of key-value pairs that will be injected as environment variables.	`map`	Optional
`shell`	Defaults to `/bin/sh` for maximum compatibility. Set this to `/bin/bash` for more features.	`string`	Optional
`allow_external_ingress`	Allow inbound traffic from external sources. Valid options: • `http` • `https`• `high-ports` This feature is documented on the networking page: usage instructions.	`[]string`	Optional

Property	Description	Type	Required
`name`	Name of the virtual browser.	`string`	Required
`url`	URL to your target saas website. The virtual browser will open this URL for learners. It should be correct url starting with "https://".	`string`	Required

Property	Description	Type	Required
`name`	The name of the GCP project.	`string`	Required
`services`	Use this field to enable services on the Google Cloud project. For a list of available services, visit the API library page or run `gcloud services list --available`. 🚫You can not enable serviceusage.googleapis.com	`list`	Optional
`roles`	Use this field to grant IAM roles to User and Service account on the Google Cloud project. For a list of available roles, visit the Understanding roles page or run `gcloud iam roles list`. Roles will default to the Owner role (roles/owner) if no roles are specified. The Owner role will only be applied to the Service account. The User account will fall back to the Editor role (roles/editor). This is a limitation with Google Cloud IAM which does not allow configuring the Owner role for "external" Users. ⚠️ The Owner role gives full control to a project. To limit potential abuse, we suggest using more specialized roles that only give permissions to the resources/services required.	`list`	Optional

Property	Description	Type	Required
`name`	The name of the AWS account.	`string`	Required
`iam_policy`	The IAM policy document that will be attached to the account. This can be specified as either YAML or JSON.	`string`	Optional
`managed_policies`	A list of all managed policies that will be attached to the account. An overview of all policies can be found in the AWS Console (requires log in)	`list`	Optional
`scp_policy`	The SCP policy document that will be attached to the account	`string`	Optional

Property	Description	Type	Required
`name`	The name of the Azure subscription.	`string`	Required
`user_only`	Only create an AAD user, without an Azure Subscription. Useful when you only need an AAD user, for instance when using Azure DevOps.	`boolean`	Optional
`roles`	A list of roles that will be attached to the account. You can use any built-in Azure IAM roles, such as `Contributor` or `Owner`. See https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles for details on the available roles.	`list`	Optional

Concepts - Previous

Sandboxes

What is a sandbox?

Sandbox resources

Appearance

Sandbox properties

Container

Virtual machine

Virtual Browser

GCP project

AWS account

Azure subscription

Container

Example `config.yml`

Virtual machine

Example `config.yml`

Virtual browser

Example `config.yml`

GCP project

Example `config.yml`

AWS account

Example `config.yml`

Azure subscription

Example `config.yml`

Sandboxes

What is a sandbox?

Sandbox resources

Appearance

Sandbox properties

Container

Virtual machine

Virtual Browser

GCP project

AWS account

Azure subscription

Container

Example config.yml

Virtual machine

Example config.yml

Virtual browser

Example config.yml

GCP project

Example config.yml

AWS account

Example config.yml

Azure subscription

​

Example config.yml

Example `config.yml`

Example `config.yml`

Example `config.yml`

Example `config.yml`

Example `config.yml`

Example `config.yml`