Instruqt Labs (beta)
  • Instruqt
  • Getting started
    • Setting up Version Control
    • Install Instruqt CLI
    • Creating your first lab
    • Configuration basics
    • Exploring the lab configuration
    • Adding your first chapter
    • Configuring sandboxes
    • Adding quizzes
    • Adding tasks and gating content
    • Finishing up
  • Documentation
    • Writing Lab Content
      • Project Structure
      • Markdown and Components
    • Integrations
      • Version Control
    • Lab reference
      • Content
        • Lab
        • Page
        • Activities
          • Task
          • Quiz
            • Multiple Choice
            • Single Choice
            • Text Answer
            • Numeric Answer
        • Layout
        • Tabs
          • Terminal
          • Service
          • Editor
          • External Website
          • Note
      • Sandbox
        • Containers
          • Container
          • Sidecar Container
        • Kubernetes
          • Cluster
          • Config
          • Helm
        • Nomad
          • Cluster
          • Job
        • Networking
          • Network
          • Ingress
        • Cloud Accounts
          • AWS
          • Azure
          • Google Cloud
        • Terraform
        • Template
        • Exec
        • Copy
        • Certificates
          • Root
          • Leaf
        • Random
          • Number
          • ID
          • UUID
          • Password
          • Creature
      • Functions
    • Tools
      • Instruqt CLI
    • Glossary
Powered by GitBook
On this page
  • Container
  • NetworkAttachment
  • Image
  • Volume
  • Port
  • PortRange
  • Resources
  • Capabilities
  • User
  • HealthCheckContainer
  • HealthCheckHTTP
  • HealthCheckTCP
  • HealthCheckExec
  • Examples
Edit on GitHub
Export as PDF
  1. Documentation
  2. Lab reference
  3. Sandbox
  4. Containers

Container

Container

Container defines a structure for creating Docker containers


resource "container" "name" {
  ...
}

Attributes

Attribute
Description

Image defines a Docker image to use when creating the container.

A port stanza allows you to expose container ports on the local network or host. This stanza can be specified multiple times.

A port_range stanza allows you to expose a range of container ports on the local network or host. This stanza can be specified multiple times.

The following example would create 11 ports from 80 to 90 (inclusive) and expose them to the host machine.

Command command type: []string

Command allows you to specify a command to execute when starting a container. Command is specified as an array of strings, each part of the command is a separate string.

For example, to start a container and follow logs at /dev/null the following command could be used.

Environment environment type: map[string]string

Allows you to set environment variables in the container.

Labels labels type: map[string]string

Labels to apply to the container

A volume allows you to specify a local volume which is mounted to the container when it is created. This stanza can be specified multiple times.

Network attaches the container to an existing network defined in a separate stanza. This block can be specified multiple times to attach the container to multiple networks.

Entrypoint entrypoint type: []string

Entrypoint for the container, if not set, Jumppad starts the container using the entrypoint defined in the Docker image.

DNS dns type: []string

The nameservers to use to resolve dns requests.

Privileged privileged type: bool

Should the container run in Docker privileged mode?

The capabilities to add or drop.

MaxRestartCount max_restart_count type: int

The maximum number of times a container will be restarted when it exits with a status code other than 0

Define resource constraints for the container

Define a health check for the container, the resource will only be marked as successfully created when the health check passes.

Allows the container to be run as a specific user or group.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute
Description

Meta ID meta.id string

The full ID of the resource e.g. resource.type.name. This is computed from the full resource path:

Meta Type meta.type string

The type of the resource. This taken from the type label of the resource definition.

Meta Name meta.name string

The name of the resource. This taken from the name label of the resource definition.

ContainerName container_name type: string

Fully qualified resource name for the container, this value can be used to access the container from within the Docker network. container_name is also the name of the created Docker container.


NetworkAttachment

Network attachment defines a network to which the container is attached.


network {
  ...
}

Attributes

Attribute
Description

ID id required type: string

ID of the network to attach the container to, specified in reference format. e.g. to attach to a network called cloud.

IPAddress ip_address type: 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.

Aliases aliases type: []string

Aliases allow alternate names to specified for the container. Aliases can be used to reference a container across the network, the container will respond to ping and other network resolution using the primary assigned name [name].container.shipyard.run and the aliases.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute
Description

Name name type: string

Name will equal the name of the network as created by jumppad.

AssignedAddress assigned_address type: string

assigned_address will equal the assigned IP address for the network. This will equal ip_address if set; otherwise, this is the automatically assigned IP address.


Image

Image defines a Docker image used when creating this container. An Image can be stored in a public or a private repository.


container {
  image {
    ...
  }
}

Attributes

Attribute
Description

Name name required type: string

Name of the image to use when creating the container, can either be the full canonical name or short name for Docker official images. e.g. consul:v1.6.1 or docker.io/consul:v1.6.1.

Username username type: string

Username to use when connecting to a private image repository

Password password type: string

Password to use when connecting to a private image repository, for both username and password interpolated environment variables can be used in place of static values.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute
Description

ID id type: string

ID is the 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. ID string hcl:"id,optional" json:"id,omitempty"


Volume

A volume type allows the specification of an attached volume.


container {
  volume {
    ...
  }
}

Attributes

Attribute
Description

Source source required type: 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.

Destination destination required type: string

The destination in the container to mount the volume to, must be an absolute path.

Type type 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

ReadOnly read_only type: bool

Whether or not the volume is read only.

BindPropagation bind_propagation type: 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 https://docs.docker.com/storage/bind-mounts/#configure-bind-propagation

BindPropagationNonRecursive bind_propagation_non_recursive type: 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. or 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 thetmpfs which is typically mounted to /run on the host is not propagated into the container.

SelinuxRelabel selinux_relabel type: 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)

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.


Port

A port stanza defines host to container communications


container {
  port {
    ...
  }
}

Attributes

Attribute
Description

Local local required type: string

The local port in the container.

Host host type: string

The host port to map the local port to.

Protocol protocol type: string

The protocol to use when exposing the port, can be tcp, or udp.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.


PortRange

A port_range stanza defines host to container communications by exposing a range of ports for the container.


container {
  port_range {
    ...
  }
}

Attributes

Attribute
Description

Range range required type: string

The port range to expose, e.g, 8080-8082 would expose the ports 8080, 8081, 8082.

EnableHost enable_host type: bool

Expose the port range on the host.

Protocol protocol type: string

The protocol to use when exposing the port, can be tcp, or udp.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.


Resources

A resources type allows you to configure the maximum resources which can be consumed.


container {
  resources {
    ...
  }
}

Attributes

Attribute
Description

CPU cpu type: int

Set the maximum CPU which can be consumed by the container in MHz, 1 CPU == 1000MHz.

CPUPin cpu_pin type: []int

Pin the container CPU consumption to one or more logical CPUs. For example to pin the container to the core 1 and 4.

Memory memory type: int

Maximum memory which a container can consume, specified in Megabytes.

GPU settings to pass through to container

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.


Capabilities


container {
  capabilities {
    ...
  }
}

Attributes

Attribute
Description

Add add type: []string

CapAdd is a list of kernel capabilities to add to the container

Drop drop type: []string

CapDrop is a list of kernel capabilities to remove from the container

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.


User

User and Group configuration to be used when running a container, by default Docker runs commands in the container as root id 0.


user {
  ...
}

Attributes

Attribute
Description

User user required type: string

Linux user ID or user name to run the container as, this overrides the default user configured in the container image.

Group group required type: string

Linux group ID or group name to run the container as, this overrides the default group configured in the container image.

group = "root"

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.


HealthCheckContainer

A health_check stanza allows the definition of a health check which must pass before the container is marked as successfully created. There are three different types of healthcheck http, tcp, and exec, these are not mutually exclusive, it is possible to define more than one health check.

Health checks are executed sequentially, if one health check fails, the following checks are not executed. The execution order is http, tcp, exec.


health_check {
  ...
}

Attributes

Attribute
Description

Timeout timeout required type: 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.

HTTP Health Check block defining the address to check and expected status codes.

Can be specified more than once.

TCP Health Check block defining the address to test.

Can be specified more than once.

Exec Health Check block defining either a command to run in the current container, or a script to execute.

Can be specified more than once.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.


HealthCheckHTTP

A HTTP health check executes an HTTP request for the given address and evaluates the response against the expected success_codes. If the reponse matches any of the given codes the check passes.


health_check {
  http {
    ...
  }
}

Attributes

Attribute
Description

Address address required type: string

The URL to check, health check expects a HTTP status code to be returned by the URL in order to pass the health check.

Method method type: string

HTTP method to use when executing the check

Body body type: string

HTTP body to send with the request

Headers headers type: map[string]string

HTTP headers to send with the check

SuccessCodes success_codes type: []int

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.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.


HealthCheckTCP

A TCP health check attempts to open a connection to the given address. If a connection can be opened then the check passes.


health_check {
  tcp {
    ...
  }
}

Attributes

Attribute
Description

Address address required type: string

The adress to check.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.


HealthCheckExec

Exec health checks allow you to execute a command or script in the current container. If the command or script receives an exit code 0 the check passes.


health_check {
  exec {
    ...
  }
}

Attributes

Attribute
Description

Command command type: []string

The command to execute, the command is run in the target container.

Script script type: string

A script to execute in the target container, the script is coppied to the container into the /tmp directory and is then executed.

ExitCode exit_code type: int

ExitCode to mark a successful check, default 0

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Examples

Minimal Example


resource "container" "unique_name" {
    network {
        id         = resource.network.cloud.meta.id
        ip_address = "10.16.0.203"
        aliases    = ["my_unique_name_ip_address"]
    }

    image {
        name = "consul:1.6.1"
    }
}

Full Example


resource "container" "unique_name" {
    depends_on = ["resource.container.another"]

    network {
        id         = resource.network.cloud.meta.id
        ip_address = "10.16.0.200"
        aliases    = ["my_unique_name_ip_address"]
    }

    image {
        name     = "consul:1.6.1"
        username = "repo_username"
        password = "repo_password"
    }

    command = [
        "consul",
        "agent"
    ]

    environment = {
        CONSUL_HTTP_ADDR = "http://localhost:8500"
    }

    volume {
        source      = "./config"
        destination = "/config"
    }

    port {
        local  = 8500
        remote = 8500
        host   = 18500
    }

    port_range {
        range       = "9000-9002"
        enable_host = true
    }

    privileged = false
}
PreviousContainersNextSidecar Container

Last updated 4 days ago

Image image required type: block

Ports port type: []block

PortRanges port_range type: []block

Volumes volume type: []block

Networks network type: []block

Capabilities capabilities type: block

Resources resources type: block

HealthCheck health_check type: block

RunAs run_as type: block

GPU gpu type: block

HTTP http type: []block

TCP tcp type: []block

Exec exec type: []block

image {
  name = "redis:latest"
}
port {
  local = 80
  host  = 8080
}
port_range {
  range       = "80-90"
  enable_host = true
}
command = [
  "tail",
  "-f",
  "/dev/null"
]
environment = {
  PATH = "/user/local/bin"
}
labels = {
  key = "value"
}
volume {
  source      = "./"
  destination = "/files"
}
network {
  id = resource.network.main.meta.id
}
dns = ["1.1.1.1", "8.8.8.8"]
privileged = true
capabilities {
  add = ["AUDIT_CONTROL"]
drop = ["SETUID"]
}
max_restart_count = 3
resources {
  cpu = 100
memory = 1024
}
health_check {
  timeout = "30s"
  http {
    address = "http://localhost:8500/v1/status/leader"
    success_codes = [200]
  }

  tcp {
    address = "localhost:8500"
  }

  exec {
    script = <<-EOF
      #!/bin/bash

      curl "http://localhost:9090"
    EOF
  }
}
run_as = "ubuntu"
// given the following resource
resource "container" "ubuntu" {
  ...
}

// the resulting id will be
resource.container.ubuntu
// given the following resource
resource "container" "ubuntu" {
  ...
}

// the resulting type will be
container
// given the following resource
resource "container" "ubuntu" {
  ...
}

// the resulting name will be
ubuntu
name.container.local.jmpd.in
id = resource.network.main.meta.id
ip_address = "10.0.5.24"
aliases = [
  "alt1.container.local.jmpd.in",
  "alt2.container.local.jmpd.in"
]
name = "redis:latest"
username = "my_username"
password = "my_password"
source = "./files/nginx"
destination = "/etc/nginx"
type = "bind"
read_only = true
bind_propagation = "shared"
bind_propagation_non_recursive = true
selinux_relabel = "shared"
local = 80
host = 8080
protocol = "tcp"
range = "8080-8082"
enable_host = true
protocol = "tcp"
cpu = 100
cpi_pin = [1,4]
memory = 2048
gpu {
  driver = "nvidia"
  device_ids = ["0", "1"]
}
add = ["IPC_LOCK"]
drop = ["SETUID"]
user = "root"
timeout = "60s"
http {
  address = "localhost:8500"
}
tcp {
  address = "localhost:8500"
}
exec {
  command = ["pg_isready"]
}
address = "http://localhost:8500/v1/status/leader"
method = "POST"
body = <<-EOF
{
  {"test": "123"}
}
EOF
headers = {
  "X-Auth-Token": ["abc123"]
}
success_codes = [200, 403]
address = "localhost:8500"
command = ["pg_isready"]
script = <<-EOF
  #!/bin/bash
  FILE=/etc/resolv.conf
  if [ -f "$FILE" ]; then
    echo "$FILE exists."
  fi
EOF
exit_code = 0
Image
Port
PortRange
Volume
NetworkAttachment
Capabilities
Resources
HealthCheckContainer
User
GPU
HealthCheckHTTP
HealthCheckTCP
HealthCheckExec