Sandboxes

Search…
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 or virtual machines. 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
Cloud accounts:
Google Cloud Platform (GCP) project
AWS account
Azure subscription
Check these topics for more information about containers and virtual machines:
​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 in the Sandbox tab:
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
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 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
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 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
​
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
​
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
How-to guides - Previous
Migrate from Katacoda
Sandbox hosts
Last modified 2mo ago
Copy link
Edit on GitHub
Outline
What is a sandbox?
Sandbox resources
Appearance
Sandbox properties
What is a sandbox?

Sandbox resources

Appearance

Sandbox properties

Container

Virtual machine

GCP project

AWS account

Azure subscription

Container

Example `config.yml`

Virtual machine

Example `config.yml`

GCP project

Example `config.yml`

AWS account

Example `config.yml`

Azure subscription

Example `config.yml`

What is a sandbox?

Sandbox resources

Appearance

Sandbox properties

Container

Virtual machine

GCP project

AWS account

Azure subscription

Container

Example config.yml

Virtual machine

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`
