Container

Defined insandbox.hcl

The container resource defines Docker containers that run as part of your lab’s sandbox environment. Containers provide isolated environments for running applications, services, and tools that users interact with during the lab.

Running setup scripts

Containers do not have a top-level script attribute. For setup or initialization scripts, use a separate Exec resource targeting the container - see Running Scripts below. The script field under health_check.exec is only for health checks, not setup scripts.

Use Cases

As a lab author, you can use containers to create diverse lab environments:

• Run Standard Images: Deploy your applications directly from standard Docker images without modification
• Development Environments: Provide pre-configured development environments with specific tools, languages, and frameworks installed
• Multi-Service Architectures: Build complex distributed systems with multiple interconnected containers representing different components

Containers are the primary building blocks for creating interactive, hands-on learning experiences in Instruqt labs.

HCL Syntax

Basic Syntax

resource "container" "name" {
  image {
    name = "ubuntu:22.04"
  }
}

Full Syntax

resource "container" "name" {
  image {
    name = "image:tag"
  }

  # Optional configurations
  entrypoint      = ["executable", "param1"]
  command         = ["arg1", "arg2"]
  environment     = { KEY = "value" }
  privileged      = false

  # Network configuration
  network {
    id = resource.network.main.meta.id
    ip_address = "10.0.0.5"
  }

  # Resource constraints
  resources {
    cpu = 1000      # 1 CPU = 1000
    memory = 512    # MB

    gpu {
      driver = "nvidia"
      device_ids = ["0"]
    }
  }

  # Volumes
  volume {
    source = "/host/path"
    destination = "/container/path"
    read_only = false
  }

  # Ports
  port {
    local = 8080
    host = 8080
    protocol = "tcp"
  }

  port_range {
    range = "3000-3010"
    enable_host = true
    protocol = "tcp"
  }

  # Security
  capabilities {
    add = ["SYS_ADMIN"]
    drop = ["NET_RAW"]
  }

  # User configuration
  run_as {
    user = "1000"
    group = "1000"
  }

  # Health check
  health_check {
    timeout = "10s"

    http {
      address = "http://localhost/health"
      method = "GET"
    }
  }
}

Port numbers (local, host) are integers between 1 and 65535 - quoting them as strings fails validation. Only port_range.range is a string (for example "3000-3010").

Resource Structure

container
├─ image (required)
│  └─ name, username, password
├─ basic configuration
│  ├─ entrypoint, command
│  ├─ environment, labels
│  ├─ dns
│  ├─ privileged
│  ├─ max_restart_count
├─ networking
│  └─ network[] (repeatable)
│     ├─ id, ip_address, aliases
├─ storage
│  └─ volume[] (repeatable)
│     ├─ source, destination, type
│     └─ read_only
├─ port exposure
│  ├─ port[] (repeatable)
│  │  ├─ local, host, protocol
│  └─ port_range[] (repeatable)
│     ├─ range, enable_host, protocol
├─ resource limits
│  └─ resources
│     ├─ cpu, memory
│     └─ gpu
│        ├─ driver, device_ids
├─ security
│  ├─ capabilities
│  │  ├─ add[], drop[]
│  └─ run_as
│     ├─ user, group
└─ monitoring
   └─ health_check
      ├─ timeout
      ├─ http[] (address, method, body, headers, success_codes)
      ├─ tcp[] (address)
      └─ exec[] (command, script, exit_code)

The script under health_check → exec[] is a health probe: it runs repeatedly to decide whether the container is healthy. It is not a place for setup or lifecycle scripting.

Fields

Field	Type	Required	Description
entrypoint	list(string)	—	Define the command or script that runs automatically when the container starts ConstraintsSpaces are not allowed, add a new item instead
command	list(string)	—	Add commands that run when the container starts to configure or initialize your environment
environment	map(string)	—	Set environment variables to pass configuration values, API keys, or secrets to the container
labels	map(string)	—	Use labels to organize or identify containers with metadata, such as environment or version tags
dns	list(string)	—	Configure DNS servers or custom hostnames for your container to resolve network addresses ConstraintsMust be a valid IP address
privileged	bool	—	Allow the container to run with extended system permissions. Only enable this for advanced use cases. Defaultfalse
max_restart_count	number	—	Set how many times the container should restart automatically if it stops or fails Default0 ConstraintsMust be at least -1 (-1 for unlimited, 0 to disable, positive for specific count); Maximum 10
image	block	✓	Image to use for the container
network	block	—	Connect this resource to a specific network so it can communicate with other containers or servicesrepeatable
port	block	—	Expose specific ports so learners can access web apps, APIs, or services running in this resourcerepeatable
port_range	block	—	Specify a range of ports to open for applications that require multiple connections, such as clusters or multi-service environmentsrepeatable
volume	block	—	Attach persistent storage or share data between containers using volumesrepeatable
capabilities	block	—	Add or remove Linux capabilities to control system-level permissions available inside the container
resources	block	—	Resource constraints for the container
health_check	block	—	Define checks to confirm that your container is running and responsive. Helps restart unhealthy containers automatically.
run_as	block	—	Set the user and group under which the container runs. This helps control permissions and improve security.

Image

container→Image

Image to use for the container

Field	Type	Required	Description
name	string	✓	Full Docker image reference, including the registry and an optional tag. Include a specific tag to ensure consistent lab environments. ConstraintsMust be a valid Docker image reference (e.g. ubuntu:24.04, docker.io/hashicorp/vault:1.14)
username	string	—	Only required for private Docker registries. Leave empty for public images.
password	string	—	Only required for private Docker registries. Leave empty for public images.

Network

container→Network

Attach to the correct network

Field	Type	Required	Description
id	string	—	ID of the network to attach the container
target	referencenetwork	—	The network to attach the container to
ip_address	string	—	Static IP address to assign container for the network, the ip address must be within range defined by the network subnet. If this parameter is omitted an IP address will be automatically assigned. ConstraintsMust be a valid IPv4 address (e.g., 192.168.1.10)
aliases	list(string)	—	Aliases allow alternate names to specified for the container

Port

container→Port

Ports to expose

Field	Type	Required	Description
local	number	✓	The local port in the container ConstraintsMinimum 1; Maximum 65535
host	number	—	The host port to map the local port to ConstraintsMinimum 1; Maximum 65535
protocol	string	—	The protocol to use when exposing the port Allowedtcp udp Defaulttcp

Port Range

container→Port Range

Range of ports to expose

Field	Type	Required	Description
range	string	✓	The port range to expose, e.g, `8080-8082` would expose the ports `8080`, `8081`, `8082` ConstraintsMust be a valid port range (e.g., 8080-8082) with ports between 1 and 65535
enable_host	bool	—	Expose the port range on the host
protocol	string	—	The protocol to use when exposing the port Allowedtcp udp Defaulttcp

Volume

container→Volume

Volumes to attach to the container

Field	Type	Required	Description
source	string	✓	The source volume to mount in the container, can be specified as a relative `./` or absolute path `/usr/local/bin`. Relative paths are relative to the file declaring the container. ConstraintsSource path must not be empty
destination	string	✓	The destination in the container to mount the volume to, must be an absolute path ConstraintsDestination path must not be empty
type	string	—	The type of the mount, can be one of the following values: - bind: bind the source path to the destination path in the container - volume: source is a Docker volume - tmpfs: create a temporary filesystem Allowedbind volume tmpfs Defaultbind
read_only	bool	—	Whether or not the volume is read only
bind_propagation	string	—	Configures bind propagation for Docker volume mounts, only applies to bind mounts, can be one of the following values: - shared - slave - private - rslave - rprivate For more information please see the Docker documentation Allowedshared private slave rslave rprivate Defaultshared
bind_propagation_non_recursive	bool	—	Configures recursiveness of the bind mount. By default Docker mounts with the equivalent of `mount --rbind` meaning that mounts below the the source directory are visible in the container. For instance running `docker run --rm --mount type=bind,src=/,target=/host,readonly` busybox will make `/run` of the host available as `/host/run` in the container. To make matters even worse it will be writable (since only the toplevel bind is set readonly, not the children). If `bind_propagation_non_recursive` is set to true then the container will only see an empty `/host/run`, meaning the `tmpfs` which is typically mounted to `/run` on the host is not propagated into the container.
selinux_relabel	string	—	Configures Selinux relabeling for the container (usually specified as :z or :Z) and can be one of the following values: - shared (Equivalent to :z) - private (Equivalent to :Z) Allowed shared private

Capabilities

container→Capabilities

Capabilities to add or drop from the container

Field	Type	Required	Description
add	list(string)	—	List of kernel capabilities to add to the container Allowed 41 values CAP_AUDIT_CONTROLCAP_AUDIT_READCAP_AUDIT_WRITECAP_BLOCK_SUSPENDCAP_BPFCAP_CHECKPOINT_RESTORECAP_CHOWNCAP_DAC_OVERRIDECAP_DAC_READ_SEARCHCAP_FOWNERCAP_FSETIDCAP_IPC_LOCKCAP_IPC_OWNERCAP_KILLCAP_LEASECAP_LINUX_IMMUTABLECAP_MAC_ADMINCAP_MAC_OVERRIDECAP_MKNODCAP_NET_ADMINCAP_NET_BIND_SERVICECAP_NET_BROADCASTCAP_NET_RAWCAP_PERFMONCAP_SETFCAPCAP_SETGIDCAP_SETPCAPCAP_SETUIDCAP_SYS_ADMINCAP_SYS_BOOTCAP_SYS_CHROOTCAP_SYS_MODULECAP_SYS_NICECAP_SYS_PACCTCAP_SYS_PTRACECAP_SYS_RAWIOCAP_SYS_RESOURCECAP_SYS_TIMECAP_SYS_TTY_CONFIGCAP_SYSLOGCAP_WAKE_ALARM
drop	list(string)	—	List of kernel capabilities to drop from the container Allowed 41 values CAP_AUDIT_CONTROLCAP_AUDIT_READCAP_AUDIT_WRITECAP_BLOCK_SUSPENDCAP_BPFCAP_CHECKPOINT_RESTORECAP_CHOWNCAP_DAC_OVERRIDECAP_DAC_READ_SEARCHCAP_FOWNERCAP_FSETIDCAP_IPC_LOCKCAP_IPC_OWNERCAP_KILLCAP_LEASECAP_LINUX_IMMUTABLECAP_MAC_ADMINCAP_MAC_OVERRIDECAP_MKNODCAP_NET_ADMINCAP_NET_BIND_SERVICECAP_NET_BROADCASTCAP_NET_RAWCAP_PERFMONCAP_SETFCAPCAP_SETGIDCAP_SETPCAPCAP_SETUIDCAP_SYS_ADMINCAP_SYS_BOOTCAP_SYS_CHROOTCAP_SYS_MODULECAP_SYS_NICECAP_SYS_PACCTCAP_SYS_PTRACECAP_SYS_RAWIOCAP_SYS_RESOURCECAP_SYS_TIMECAP_SYS_TTY_CONFIGCAP_SYSLOGCAP_WAKE_ALARM

Resources

container→Resources

Resource constraints for the container

Field	Type	Required	Description
cpu	number	—	Limit how much CPU power your container can use to optimize performance and cost ConstraintsMinimum 100; Maximum 8000
cpu_pin	list(number)	—	Pin your container to specific CPU cores for more predictable performance or isolation ConstraintsAt least 1 item(s); At most 32 item(s)
memory	number	—	Specify how much memory the container can use to prevent crashes or resource contention ConstraintsMinimum 128; Maximum 32768
disk	number	—	Disk space limit in MB
gpu	block	—	GPU resource constraints

GPU

container→Resources→GPU

GPU resource constraints

Field	Type	Required	Description
driver	string	✓	Select the GPU driver to use for hardware acceleration or GPU-based workloads
device_ids	list(string)	✓	Specify which GPU devices the container can access when running GPU-based tasks

Health Check

container→Health Check

Health checks for the container

Field	Type	Required	Description
timeout	string	✓	The maximum duration to wait before marking the health check as failed. Expressed as a Go duration, e.g. 1s = 1 second, 100ms = 100 milliseconds. Default30s ConstraintsMust be a valid duration (e.g. 30s, 5m)
exec	block	—	Runs a command or script inside the container. The check passes when the command exits with code 0.repeatable
http	block	—	Sends an HTTP request to the address and passes when the response matches the expected success codesrepeatable
tcp	block	—	Attempts to open a TCP connection to the address. If the connection opens, the check passes.repeatable

Exec Health Check

container→Health Check→Exec Health Check

Execute command health check

Field	Type	Required	Description
command	list(string)	—	The command to run, given as the executable followed by its arguments. Use either a command or a script, not both.
script	string	—	An inline shell script to run instead of a single command. Must start with a shebang, e.g. #!/bin/bash.
exit_code	number	—	The exit code that counts as healthy. Defaults to 0.

HTTP Health Check

container→Health Check→HTTP Health Check

HTTP health check

Field	Type	Required	Description
address	string	—	The URL to check. Leave empty to check this resource on the given port; set it to check a specific endpoint, such as another resource by its sandbox.internal name. The check passes when the endpoint returns one of the success codes.
scheme	string	—	http or https; used when address is empty Allowedhttp https Defaulthttp
port	number	—	The port the app listens on inside this resource ConstraintsMinimum 1; Maximum 65535
path	string	—	The HTTP path to request when checking this resource via port Default/
method	string	—	HTTP method to use when executing the check
body	string	—	HTTP body to send with the request
headers	map(list(string))	—	HTTP headers to send with the check
success_codes	list(number)	—	HTTP status codes returned from the endpoint when called. If the returned status code matches any in the array then the health check will pass.

TCP Health Check

container→Health Check→TCP Health Check

TCP health check

Field	Type	Required	Description
address	string	—	Host and port to connect to, e.g. db.sandbox.internal:5432. Leave empty to check this resource on the given port. The check passes as soon as the connection is accepted.
port	number	—	The port the app listens on inside this resource ConstraintsMinimum 1; Maximum 65535

Run As

container→Run As

User block for mapping the user id and group id inside the container

Field	Type	Required	Description
user	string	✓	The user to run the container as
group	string	✓	The group to run the container as

Computed Attributes

These attributes are set by the system and are read-only.

Attribute	Type	Description
container_name	string	Fully qualified domain name for the container, this can be used to access the container from other sources
image.id	string	Unique identifier for the image, this is independent of tag and changes each time the image is built. An image that has been tagged multiple times also shares the same ID.
network[].name	string	Name will equal the name of the network as created by jumppad
network[].assigned_address	string	AssignedAddress will equal if IPAddress is set, else it will be the value automatically assigned from the network

Sizing: CPU and Memory

All of a lab’s sandbox resources run on one sandbox host, and the host is sized to fit the sum of their resources blocks. There is no machine-type field.

• cpu: millicores (1 CPU = 1000).
• memory: memory in MB, for example 512.

A container without a resources block is counted as 128 MB and 0.1 CPU when the host is sized, but it runs with no memory limit. If the containers together use more memory than the host has, the whole sandbox runs out of memory: the lab stops responding and its logs stop. Set memory on every container that runs more than a small process, such as a database or a JVM application:

resource "container" "mongo" {
  image {
    name = "mongo:7"
  }

  resources {
    memory = 512
  }
}

Running Scripts

The container resource has no script attribute. To run setup or lifecycle scripts against a container - installing packages, seeding data, starting background processes - define an Exec resource with target set to the container:

resource "exec" "setup" {
  target = resource.container.ubuntu
  script = "scripts/exec/setup/script.sh"
}

Create the script file relative to your HCL file, starting with a shebang such as #!/bin/sh. See Exec for more examples and execution options.

Examples

Basic Container

resource "container" "ubuntu" {
  image {
    name = "ubuntu:22.04"
  }
}

Web Application Container

resource "container" "webapp" {
  image {
    name = "myapp:latest"
  }

  environment = {
    NODE_ENV = "production"
    PORT = "3000"
  }

  port {
    local = 3000
    host = 8080
  }

  resources {
    cpu = 2000    # 2 CPUs
    memory = 1024 # 1GB
  }

  health_check {
    timeout = "5s"

    http {
      address = "http://localhost:3000/health"
      method = "GET"
    }
  }
}

Database Container with Volume

resource "container" "postgres" {
  image {
    name = "postgres:15"
  }

  environment = {
    POSTGRES_PASSWORD = "secret"
    POSTGRES_DB = "myapp"
  }

  volume {
    source = "postgres-data"
    destination = "/var/lib/postgresql/data"
  }

  port {
    local = 5432
  }

  network {
    id = resource.network.backend.meta.id
  }
}

Development Container with Multiple Networks

resource "container" "devbox" {
  image {
    name = "instruqt/devbox:latest"
  }

  privileged = true

  network {
    id = resource.network.frontend.meta.id
    ip_address = "10.0.1.10"
  }

  network {
    id = resource.network.backend.meta.id
    ip_address = "10.0.2.10"
  }

  volume {
    source = "./code"
    destination = "/workspace"
  }

  volume {
    source = "/var/run/docker.sock"
    destination = "/var/run/docker.sock"
  }

  capabilities {
    add = ["SYS_PTRACE"]
  }

  run_as {
    user = "developer"
    group = "developer"
  }
}

GPU-Enabled Container

resource "container" "ml_workspace" {
  image {
    name = "tensorflow/tensorflow:latest-gpu"
  }

  resources {
    cpu = 4000
    memory = 8192

    gpu {
      driver = "nvidia"
      device_ids = ["0", "1"]
    }
  }

  environment = {
    CUDA_VISIBLE_DEVICES = "0,1"
  }
}

Best Practices

1. Image Tags: Always specify explicit image tags rather than using latest
2. Resource Limits: Set appropriate CPU and memory limits to prevent resource exhaustion
3. Health Checks: Configure health checks for services to ensure availability
4. Non-Root Users: Use the run_as block to run containers as non-root users when possible
5. Environment Variables: Use environment variables for configuration instead of hardcoding values