Comment on page
Sandboxes
This pages describes sandboxes, which provide the environment for tracks.
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.
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:
🌐 Web UI
💻 Instruqt CLI
In the Web UI, the sandbox appears within a track on the Sandbox page:
.png?alt=media&token=8a68ad51-2f87-4e73-b405-97f671151166)
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. 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
Field | Description | Type | Required |
---|---|---|---|
Hostname | 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:
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. 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 |
Main property:
containers:
Sub properties:
Property | Description | Type | Required |
---|---|---|---|
name | 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 |
YAML
version: "3"
containers:
- name: container
image: ubuntu
shell: /bin/bash
memory: 256
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 |
YAML
version: "3"
virtualmachines:
- name: vm
image: debian-cloud/debian-9
machine_type: g1-small
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 |
YAML
version: "3"
virtualbrowsers:
- name: invites
url: https://play.instruqt.dev
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. 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 |
YAML
version: "3"
gcp_projects:
- name: gcptrack
services:
- compute.googleapis.com
- container.googleapis.com
roles:
- roles/compute.admin
- roles/container.admin
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 |
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"
]
}
}
}
]
}
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 |
YAML
version: "3"
azure_subscriptions:
- name: azuresubscription
Last modified 21d ago