--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "Resource docker_container - terraform-provider-docker" subcategory: "" description: |- Manages the lifecycle of a Docker container. --- # Resource (docker_container) Manages the lifecycle of a Docker container. ## Example Usage ```terraform # Start a container resource "docker_container" "ubuntu" { name = "foo" image = docker_image.ubuntu.image_id } # Find the latest Ubuntu precise image. resource "docker_image" "ubuntu" { name = "ubuntu:precise" } ``` ## Schema ### Required - `image` (String) The ID of the image to back this container. The easiest way to get this value is to use the `image_id` attribute of the `docker_image` resource as is shown in the example. - `name` (String) The name of the container. ### Optional - `attach` (Boolean) If `true` attach to the container after its creation and waits the end of its execution. Defaults to `false`. - `capabilities` (Block Set, Max: 1) Add or drop certain linux capabilities. (see [below for nested schema](#nestedblock--capabilities)) - `cgroup_parent` (String) Optional parent cgroup for the container - `cgroupns_mode` (String) Cgroup namespace mode to use for the container. Possible values are: `private`, `host`. - `command` (List of String) The command to use to start the container. For example, to run `/usr/bin/myprogram -f baz.conf` set the command to be `["/usr/bin/myprogram","-f","baz.conf"]`. - `container_read_refresh_timeout_milliseconds` (Number) The total number of milliseconds to wait for the container to reach status 'running' - `cpu_period` (Number) Specify the CPU CFS scheduler period (in microseconds), which is used alongside `cpu-quota`. Is ignored if `cpus` is set. - `cpu_quota` (Number) Impose a CPU CFS quota on the container (in microseconds). The number of microseconds per `cpu-period` that the container is limited to before throttled. Is ignored if `cpus` is set. - `cpu_set` (String) A comma-separated list or hyphen-separated range of CPUs a container can use, e.g. `0-1`. - `cpu_shares` (Number) CPU shares (relative weight) for the container. - `cpus` (String) Specify how much of the available CPU resources a container can use. e.g a value of 1.5 means the container is guaranteed at most one and a half of the CPUs. Has precedence over `cpu_period` and `cpu_quota`. - `destroy_grace_seconds` (Number) If defined will attempt to stop the container before destroying. Container will be destroyed after `n` seconds or on successful stop. - `device_read_bps` (Block Set) Limit read rate (bytes per second) from a device. This is the equivalent to repeating `--device-read-bps` for `docker run`. (see [below for nested schema](#nestedblock--device_read_bps)) - `device_read_iops` (Block Set) Limit read rate (IO per second) from a device. This is the equivalent to repeating `--device-read-iops` for `docker run`. (see [below for nested schema](#nestedblock--device_read_iops)) - `device_requests` (Block Set) Device requests for the container, such as CDI devices (e.g., `nvidia.com/gpu=all`) or GPU requests. This is the equivalent to using the `--device` flag for CDI devices in `docker run`. (see [below for nested schema](#nestedblock--device_requests)) - `device_write_bps` (Block Set) Limit write rate (bytes per second) to a device. This is the equivalent to repeating `--device-write-bps` for `docker run`. (see [below for nested schema](#nestedblock--device_write_bps)) - `device_write_iops` (Block Set) Limit write rate (IO per second) to a device. This is the equivalent to repeating `--device-write-iops` for `docker run`. (see [below for nested schema](#nestedblock--device_write_iops)) - `devices` (Block Set) Bind traditional devices to the container (e.g., `/dev/nvidia0`). For CDI devices, use `device_requests` instead. (see [below for nested schema](#nestedblock--devices)) - `dns` (Set of String) DNS servers to use. - `dns_opts` (Set of String) DNS options used by the DNS provider(s), see `resolv.conf` documentation for valid list of options. - `dns_search` (Set of String) DNS search domains that are used when bare unqualified hostnames are used inside of the container. - `domainname` (String) Domain name of the container. - `entrypoint` (List of String) The command to use as the Entrypoint for the container. The Entrypoint allows you to configure a container to run as an executable. For example, to run `/usr/bin/myprogram` when starting a container, set the entrypoint to be `"/usr/bin/myprogram"]`. - `env` (Set of String) Environment variables to set in the form of `KEY=VALUE`, e.g. `DEBUG=0` - `gpus` (String) GPU devices to add to the container. Supported values are `all` or `device=`, for example `device=0,2` or `device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a`. - `group_add` (Set of String) Additional groups for the container user - `healthcheck` (Block List, Max: 1) A test to perform to check that the container is healthy (see [below for nested schema](#nestedblock--healthcheck)) - `host` (Block Set) Additional hosts to add to the container. (see [below for nested schema](#nestedblock--host)) - `hostname` (String) Hostname of the container. - `init` (Boolean) Configured whether an init process should be injected for this container. If unset this will default to the `dockerd` defaults. - `ipc_mode` (String) IPC sharing mode for the container. Possible values are: `none`, `private`, `shareable`, `container:` or `host`. - `labels` (Block Set) User-defined key/value metadata (see [below for nested schema](#nestedblock--labels)) - `log_driver` (String) The logging driver to use for the container. - `log_opts` (Map of String) Key/value pairs to use as options for the logging driver. - `logs` (Boolean) Save the container logs (`attach` must be enabled). Defaults to `false`. - `max_retry_count` (Number) The maximum amount of times to an attempt a restart when `restart` is set to 'on-failure'. - `memory` (Number) The memory limit for the container in MBs. - `memory_reservation` (Number) The memory-resveration for the container in MBs. Defaults to 0. Allows you to specify a soft limit smaller than `memory` which is activated when Docker detects contention or low memory on the host machine. If you use `memory-reservation`, it must be set lower than `memory` for it to take precedence. Because it is a soft limit, it doesn't guarantee that the container doesn't exceed the limit. - `memory_swap` (Number) The total memory limit (memory + swap) for the container in MBs. This setting may compute to `-1` after `terraform apply` if the target host doesn't support memory swap, when that is the case docker will use a soft limitation. - `mounts` (Block Set) Specification for mounts to be added to containers created as part of the service. (see [below for nested schema](#nestedblock--mounts)) - `must_run` (Boolean) If `true`, then the Docker container will be kept running. If `false`, Terraform leaves the container alone. This attribute is also used to trigger a restart of a stopped container. If your container is stopped, Terraform will set `must_run` to `false` and this will trigger a change. Defaults to `true`. - `network_mode` (String) Network mode of the container. Defaults to `bridge`. If your host OS is any other OS, you need to set this value explicitly, e.g. `nat` when your container will be running on an Windows host. See https://docs.docker.com/engine/network/ for more information. - `networks_advanced` (Block Set) The networks the container is attached to. This is the equivalent to the ``--network`` option of `docker run` (see [below for nested schema](#nestedblock--networks_advanced)) - `pid_mode` (String) The PID (Process) Namespace mode for the container. Either `container:` or `host`. - `platform` (String) Platform in the format `os[/arch[/variant]]` used for image lookup and container runtime, for example `linux/amd64`. - `ports` (Block List) Publish a container's port(s) to the host. (see [below for nested schema](#nestedblock--ports)) - `privileged` (Boolean) If `true`, the container runs in privileged mode. - `publish_all_ports` (Boolean) Publish all ports of the container. - `read_only` (Boolean) If `true`, the container will be started as readonly. Defaults to `false`. - `remove_volumes` (Boolean) If `true`, it will remove anonymous volumes associated with the container. Defaults to `true`. - `restart` (String) The restart policy for the container. Must be one of 'no', 'on-failure', 'always', 'unless-stopped'. Defaults to `no`. - `rm` (Boolean) If `true`, then the container will be automatically removed when it exits. Defaults to `false`. - `runtime` (String) Runtime to use for the container. - `security_opts` (Set of String) List of string values to customize labels for MLS systems, such as SELinux. See https://docs.docker.com/engine/reference/run/#security-configuration. - `shm_size` (Number) Size of `/dev/shm` in MBs. - `start` (Boolean) If `true`, then the Docker container will be started after creation. If `false`, then the container is only created. Defaults to `true`. - `stdin_open` (Boolean) If `true`, keep STDIN open even if not attached (`docker run -i`). Defaults to `false`. - `stop_signal` (String) Signal to stop a container (default `SIGTERM`). - `stop_timeout` (Number) Timeout (in seconds) to stop a container. - `storage_opts` (Map of String) Key/value pairs for the storage driver options, e.g. `size`: `120G` - `sysctls` (Map of String) A map of kernel parameters (sysctls) to set in the container. - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts)) - `tmpfs` (Map of String) A map of container directories which should be replaced by `tmpfs mounts`, and their corresponding mount options. - `tty` (Boolean) If `true`, allocate a pseudo-tty (`docker run -t`). Defaults to `false`. - `ulimit` (Block Set) Ulimit options to add. (see [below for nested schema](#nestedblock--ulimit)) - `upload` (Block Set) Specifies files to upload to the container before starting it. Only one of `content` or `content_base64` can be set and at least one of them has to be set. (see [below for nested schema](#nestedblock--upload)) - `user` (String) User used for run the first process. Format is `user` or `user:group` which user and group can be passed literally or by name. - `userns_mode` (String) Sets the usernamespace mode for the container when usernamespace remapping option is enabled. - `volumes` (Block Set) Spec for mounting volumes in the container. (see [below for nested schema](#nestedblock--volumes)) - `wait` (Boolean) If `true`, then the Docker container is waited for being healthy state after creation. This requires your container to have a healthcheck, otherwise this provider will error. If `false`, then the container health state is not checked. Defaults to `false`. - `wait_timeout` (Number) The timeout in seconds to wait the container to be healthy after creation. Defaults to `60`. - `working_dir` (String) The working directory for commands to run in. ### Read-Only - `bridge` (String) The network bridge of the container as read from its NetworkSettings. - `container_logs` (String) The logs of the container if its execution is done (`attach` must be disabled). - `exit_code` (Number) The exit code of the container if its execution is done (`must_run` must be disabled). - `id` (String) The ID of this resource. - `network_data` (List of Object) The data of the networks the container is connected to. (see [below for nested schema](#nestedatt--network_data)) ### Nested Schema for `capabilities` Optional: - `add` (Set of String) List of linux capabilities to add. - `drop` (Set of String) List of linux capabilities to drop. ### Nested Schema for `device_read_bps` Required: - `path` (String) The device path on the host, e.g. `/dev/sda`. - `rate` (Number) The read rate limit in bytes per second. ### Nested Schema for `device_read_iops` Required: - `path` (String) The device path on the host, e.g. `/dev/sda`. - `rate` (Number) The read IOPS limit. ### Nested Schema for `device_requests` Optional: - `capabilities` (Set of String) List of device capabilities. Only used with `nvidia` driver (e.g., `gpu`, `compute`, `utility`). - `count` (Number) Number of devices to request. Use -1 for all devices. Only used with `nvidia` driver. - `device_ids` (Set of String) List of device IDs or CDI device identifiers (e.g., `nvidia.com/gpu=all`). - `driver` (String) The device driver to use. Common values: `cdi` for CDI devices, `nvidia` for NVIDIA GPU requests. - `options` (Map of String) Driver-specific options. ### Nested Schema for `device_write_bps` Required: - `path` (String) The device path on the host, e.g. `/dev/sda`. - `rate` (Number) The write rate limit in bytes per second. ### Nested Schema for `device_write_iops` Required: - `path` (String) The device path on the host, e.g. `/dev/sda`. - `rate` (Number) The write IOPS limit. ### Nested Schema for `devices` Required: - `host_path` (String) The path on the host where the device is located. Optional: - `container_path` (String) The path in the container where the device will be bound. If not set, it defaults to the value of `host_path`. - `permissions` (String) The cgroup permissions given to the container to access the device. Defaults to `rwm`. ### Nested Schema for `healthcheck` Optional: - `interval` (String) Time between running the check (ms|s|m|h). Defaults to `0s`. - `retries` (Number) Consecutive failures needed to report unhealthy. Defaults to `0`. - `start_interval` (String) Interval before the healthcheck starts (ms|s|m|h). Defaults to `0s`. - `start_period` (String) Start period for the container to initialize before counting retries towards unstable (ms|s|m|h). Defaults to `0s`. - `test` (List of String) Command to run to check health. For example, to run `curl -f localhost/health` set the command to be `["CMD", "curl", "-f", "localhost/health"]`. It works in the same way, and has the same default values, as the HEALTHCHECK Dockerfile instruction set by the service's Docker image. Your Compose file can override the values set in the Dockerfile. - `timeout` (String) Maximum time to allow one check to run (ms|s|m|h). Defaults to `0s`. ### Nested Schema for `host` Required: - `host` (String) Hostname to add - `ip` (String) IP address this hostname should resolve to. ### Nested Schema for `labels` Required: - `label` (String) Name of the label - `value` (String) Value of the label ### Nested Schema for `mounts` Required: - `target` (String) Container path - `type` (String) The mount type Optional: - `bind_options` (Block List, Max: 1) Optional configuration for the bind type. (see [below for nested schema](#nestedblock--mounts--bind_options)) - `read_only` (Boolean) Whether the mount should be read-only. - `source` (String) Mount source (e.g. a volume name, a host path). - `tmpfs_options` (Block List, Max: 1) Optional configuration for the tmpfs type. (see [below for nested schema](#nestedblock--mounts--tmpfs_options)) - `volume_options` (Block List, Max: 1) Optional configuration for the volume type. (see [below for nested schema](#nestedblock--mounts--volume_options)) ### Nested Schema for `mounts.bind_options` Optional: - `propagation` (String) A propagation mode with the value. ### Nested Schema for `mounts.tmpfs_options` Optional: - `mode` (Number) The permission mode for the tmpfs mount in an integer. - `size_bytes` (Number) The size for the tmpfs mount in bytes. ### Nested Schema for `mounts.volume_options` Optional: - `driver_name` (String) Name of the driver to use to create the volume. - `driver_options` (Map of String) key/value map of driver specific options. - `labels` (Block Set) User-defined key/value metadata. (see [below for nested schema](#nestedblock--mounts--volume_options--labels)) - `no_copy` (Boolean) Populate volume with data from the target. - `subpath` (String) Path within the volume to mount. Requires docker server version 1.45 or higher. ### Nested Schema for `mounts.volume_options.labels` Required: - `label` (String) Name of the label - `value` (String) Value of the label ### Nested Schema for `networks_advanced` Required: - `name` (String) The name or id of the network to use. You can use `name` or `id` attribute from a `docker_network` resource. Optional: - `aliases` (Set of String) The network aliases of the container in the specific network. - `driver_opts` (Set of String) An array of driver options for the network endpoint, e.g. `opts1=value`. This is the equivalent to repeating `--driver-opt` for `docker run`. - `gw_priority` (Number) Gateway priority for this endpoint. The endpoint with the highest priority will provide the default gateway for the container. This is the equivalent to `--gw-priority` for `docker run`. - `ipv4_address` (String) The IPV4 address of the container in the specific network. - `ipv6_address` (String) The IPV6 address of the container in the specific network. - `link_local_ips` (Set of String) The link-local IPs of the container in the specific network. This is the equivalent to repeating `--link-local-ip` for `docker run`. - `mac_address` (String) The MAC address of the container in the specific network. ### Nested Schema for `ports` Required: - `internal` (Number) Port within the container. Optional: - `external` (Number) Port exposed out of the container. If not given a free random port `>= 32768` will be used. - `ip` (String) IP address/mask that can access this port. Defaults to `0.0.0.0`. - `protocol` (String) Protocol that can be used over this port. Defaults to `tcp`. ### Nested Schema for `timeouts` Optional: - `create` (String) - `delete` (String) - `update` (String) ### Nested Schema for `ulimit` Required: - `hard` (Number) The hard limit - `name` (String) The name of the ulimit - `soft` (Number) The soft limit ### Nested Schema for `upload` Required: - `file` (String) Path to the file in the container where is upload goes to Optional: - `content` (String) Literal string value to use as the object content, which will be uploaded as UTF-8-encoded text. Conflicts with `content_base64` & `source` - `content_base64` (String) Base64-encoded data that will be decoded and uploaded as raw bytes for the object content. This allows safely uploading non-UTF8 binary data, but is recommended only for larger binary content such as the result of the `base64encode` interpolation function. See [here](https://github.com/terraform-providers/terraform-provider-docker/issues/48#issuecomment-374174588) for the reason. Conflicts with `content` & `source` - `executable` (Boolean) If `true`, the file will be uploaded with user executable permission. Defaults to `false`. - `permissions` (String) The permission mode for the file in the container. Has precedence over `executable`. - `source` (String) A filename that references a file which will be uploaded as the object content. This allows for large file uploads that do not get stored in state. Conflicts with `content` & `content_base64` - `source_hash` (String) If using `source`, this will force an update if the file content has updated but the filename has not. ### Nested Schema for `volumes` Optional: - `container_path` (String) The path in the container where the volume will be mounted. - `from_container` (String) The container where the volume is coming from. - `host_path` (String) The path on the host where the volume is coming from. If `host_path` is set, it takes precedence over `volume_name`. - `read_only` (Boolean) If `true`, this volume will be readonly. Defaults to `false`. - `selinux_relabel` (String) SELinux relabel mode for bind mounts. Supported values are `z` and `Z`. - `volume_name` (String) The name of the docker volume which should be mounted. Ignored when `host_path` is set. ### Nested Schema for `network_data` Read-Only: - `gateway` (String) - `global_ipv6_address` (String) - `global_ipv6_prefix_length` (Number) - `ip_address` (String) - `ip_prefix_length` (Number) - `ipv6_gateway` (String) - `mac_address` (String) - `network_name` (String) ## Import Import is supported using the following syntax by providing the `id`: ```shell #!/bin/bash terraform import docker_container.foo id ``` ### Example Assuming you created a `container` as follows ```shell #!/bin/bash docker run --name foo -p8080:80 -d nginx # prints the container ID 9a550c0f0163d39d77222d3efd58701b625d47676c25c686c95b5b92d1cba6fd ``` you provide the definition for the resource as follows ```terraform resource "docker_container" "foo" { name = "foo" image = "nginx" ports { internal = "80" external = "8080" } } ``` then the import command is as follows ```shell #!/bin/bash terraform import docker_container.foo 9a550c0f0163d39d77222d3efd58701b625d47676c25c686c95b5b92d1cba6fd ```