Container container

The container resource allows you to create Docker containers.

Properties

  • Name
    network
    Type
    (network_attachment: {})
    Required
    required
    Readonly
    Description

    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.

  • Name
    image
    Type
    (image: {})
    Required
    required
    Readonly
    Description

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

  • Name
    entrypoint
    Type
    ([]string: [])
    Required
    Readonly
    Description

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

  • Name
    command
    Type
    ([]string: [])
    Required
    Readonly
    Description

    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.

    command = [
        "tail",
        "-f",
        "/dev/null"
    ]
    
  • Name
    environment
    Type
    (map[string]string: map[]{})
    Required
    Readonly
    Description

    Allows you to set environment variables in the container.

    environment = {
      PATH = "/user/local/bin"
    }
    
  • Name
    volume
    Type
    (volume: {})
    Required
    Readonly
    Description

    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.

      volume {
        source      = "./"
        destination = "/files"
      }
    
  • Name
    port
    Type
    (port: {})
    Required
    Readonly
    Description

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

      port {
        local = 80
        remote = 80
        host  = 8080
      }
    
  • Name
    port_range
    Type
    (port_range: {})
    Required
    Readonly
    Description

    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.

      port {
        range       = "80-90"
        enable_host = true
      }
    
  • Name
    privileged
    Type
    (bool: false)
    Required
    Readonly
    Description

    Should the container run in Docker privileged mode?

  • Name
    max_restart_count
    Type
    (int: 0)
    Required
    Readonly
    Description

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

  • Name
    resources
    Type
    (resources: {})
    Required
    Readonly
    Description

    Define resource constraints for the container

  • Name
    health_check
    Type
    (health_check: {})
    Required
    Readonly
    Description

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

      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
        }
      }
    
  • Name
    run_as
    Type
    (run_as: {})
    Required
    Readonly
    Description

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

      run_as {
        user = "1000"
        group = "nicj"
      }
    
  • Name
    container_name
    Type
    (string: "")
    Required
    Readonly
    readonly
    Description

    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.

      name.container.local.jmpd.in
    

network_attachment

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

  • Name
    id
    Type
    (string: "")
    Required
    required
    Readonly
    Description

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

    network {
      id = "network.cloud"
    }
    
  • Name
    ip_address
    Type
    (string: "")
    Required
    Readonly
    Description

    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.

  • Name
    aliases
    Type
    ([]string: [])
    Required
    Readonly
    Description

    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.

    network {
      name    = "network.cloud"
      aliases = [
        "alt1.container.local.jmpd.in", 
        "alt2.container.local.jmpd.in"
      ]
    }
    
  • Name
    name
    Type
    (string: "")
    Required
    Readonly
    readonly
    Description

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

  • Name
    assigned_address
    Type
    (string: "")
    Required
    Readonly
    readonly
    Description

    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.

  • Name
    name
    Type
    (string: "")
    Required
    required
    Readonly
    Description

    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.

  • Name
    username
    Type
    (string: "")
    Required
    Readonly
    Description

    Username to use when connecting to a private image repository

  • Name
    password
    Type
    (string: "")
    Required
    Readonly
    Description

    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.

    image {
      name = "myregistry.io/myimage:latest"
      username = env("REGISTRY_USERNAME")
      password = env("REGISTRY_PASSWORD")
    }
    

volume

A volume type allows the specification of an attached volume.

  • Name
    source
    Type
    (string: "")
    Required
    required
    Readonly
    Description

    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.

  • Name
    destination
    Type
    (string: "")
    Required
    required
    Readonly
    Description

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

  • Name
    type
    Type
    (string: bind)
    Required
    Readonly
    Description

    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
  • Name
    bind_propagation
    Type
    (string: rprivate)
    Required
    Readonly
    Description

    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

  • Name
    bind_propagation_non_recursive
    Type
    (boolean: false)
    Required
    Readonly
    Description

    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 -- and 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.

  • Name
    selinux_relabel
    Type
    (string: "")
    Required
    Readonly
    Description

    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)

port

A port stanza defines host to container communications

  • Name
    local
    Type
    (string: "")
    Required
    required
    Readonly
    Description

    The local port in the container.

  • Name
    host
    Type
    (string: "")
    Required
    required
    Readonly
    Description

    The host port to map the local port to.

  • Name
    protocol
    Type
    (string: "")
    Required
    Readonly
    Description

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

  • Name
    open_in_browser
    Type
    (string: /)
    Required
    Readonly
    Description

    Should a browser window be automatically opened when this resource is created. Browser windows will open at the path specified by this property.


port_range

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

  • Name
    range
    Type
    (string: "")
    Required
    required
    Readonly
    Description

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

  • Name
    enable_host
    Type
    (bool: false)
    Required
    Readonly
    Description

    The host port to map the local port to.

  • Name
    protocol
    Type
    (string: tcp)
    Required
    Readonly
    Description

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


health_check

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 {
    timeout = "30s"
    http {
      address = "http://localhost:8500/v1/status/leader"
      success_codes = [200]
    }
    
    http {
      address = "http://localhost:8500/v1"
      success_codes = [200]
    }
    
    tcp {
      address = "localhost:8500"
    }
    
   exec {
      script = <<-EOF
        #!/bin/bash

        curl "http://localhost:9090"
      EOF
    }
  }
  • Name
    timeout
    Type
    (duration: )
    Required
    required
    Readonly
    Description

    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.

  • Name
    http
    Type
    (http_health_check: {})
    Required
    Readonly
    Description

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

    Can be specified more than once.

  • Name
    tcp
    Type
    (tpc_health_check: {})
    Required
    Readonly
    Description

    TCP Health Check block defining the address to test.

    Can be specified more than once.

  • Name
    exec
    Type
    (exec_health_check: {})
    Required
    Readonly
    Description

    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.


http_health_check

A HTTP health check executes a HTTP GET 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.

http {
  address = "http://localhost:8500/v1/status/leader"
  method  = "GET"
  body    = <<-EOF
    {"test": "123"}
  EOF
  headers = {
    "X-Auth-Token": ["abc123"]
  }
  success_codes = [200]
}
  • Name
    address
    Type
    (string: "")
    Required
    required
    Readonly
    Description

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

  • Name
    method
    Type
    (string: GET)
    Required
    Readonly
    Description

    HTTP method to use when executing the check

  • Name
    body
    Type
    (string: "")
    Required
    Readonly
    Description

    HTTP body to send with the request

  • Name
    body
    Type
    (string: "")
    Required
    Readonly
    Description

    HTTP body to send with the request

  • Name
    headers
    Type
    (map[string][string]: map[]{})
    Required
    Readonly
    Description

    HTTP headers to send with the check

  • Name
    success_codes
    Type
    ([]number: 200)
    Required
    Readonly
    Description

    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

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

tcp {
  address = "localhost:8500"
}
  • Name
    address
    Type
    (string: "")
    Required
    required
    Readonly
    Description

    The adress to check.

exec_health_check

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.

  • Name
    command
    Type
    ([]string: [])
    Required
    Readonly
    Description

    A command to execute.

    exec {
      command = ["pg_isready"]
    }
    
  • Name
    script
    Type
    (string: "")
    Required
    Readonly
    Description

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

    exec {
      script = <<-EOF
        #!/bin/bash
        
        FILE=/etc/resolv.conf
        if [ -f "$FILE" ]; then
            echo "$FILE exists."
        fi
      EOF
    }
    

resources

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

  • Name
    cpu
    Type
    (int: )
    Required
    Readonly
    Description

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

  • Name
    cpu_pin
    Type
    ([]number: [])
    Required
    Readonly
    Description

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

    resources {
      cpi_pin = [1,4]
    }
    
  • Name
    memory
    Type
    (string: "")
    Required
    Readonly
    Description

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

  • Name
    gpu
    Type
    (gpu: {})
    Required
    Readonly
    Description

    GPU settings to pass through to container

gpu

GPU support allows you to pass through GPU devices to the container, this is useful for running GPU accelerated workloads.

For more information on GPU support in Docker see the official documentation.

  • Name
    driver
    Type
    (string: "")
    Required
    Readonly
    Description

    The GPU driver to use, i.e "nvidia", note: This has not been tested this with AMD or other GPUs.

  • Name
    device_ids
    Type
    ([]string: [])
    Required
    Readonly
    Description

    The GPUs to pass to the container, i.e "0", "1", "2".

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

run_as

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

  • Name
    user
    Type
    (string: "")
    Required
    Readonly
    Description

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

  • Name
    group
    Type
    (string: "")
    Required
    Readonly
    Description

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


Examples

Minimal Example

The following example creates a container from an existing registry image.

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
}