Links

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
  • Secrets
Check these topics for more information about containers and virtual machines:
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: • httphttps 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: • httphttps 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