terraform-provider-docker/docs/resources/container.md

---
# 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.
---
<!-- Bug: Type and Name are switched -->
# 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.latest
}

# Find the latest Ubuntu precise image.
resource "docker_image" "ubuntu" {
  name = "ubuntu:precise"
}
```

<!-- schema generated by tfplugindocs -->
## Schema

### Required

- `image` (String) The ID of the image to back this container. The easiest way to get this value is to use 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 certrain linux capabilities. (see [below for nested schema](#nestedblock--capabilities))
- `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","-","baz.con"]`.
- `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.
- `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.
- `devices` (Block Set) Bind devices to the container. (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/myprogra"]`.
- `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. Currently, only the value `all` is supported. Passing any other value will result in unexpected behavior.
- `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:<name|id>` or `host`.
- `labels` (Block Set) User-defined key/value metadata (see [below for nested schema](#nestedblock--labels))
- `links` (Set of String, Deprecated) Set of links for link based connectivity between containers that are running on the same host.
- `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_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`, then as long as the container exists, Terraform assumes it is successful. Defaults to `true`.
- `network_alias` (Set of String, Deprecated) Set an alias for the container in all specified networks
- `network_mode` (String) Network mode of the container.
- `networks` (Set of String, Deprecated) ID of the networks in which the container is.
- `networks_advanced` (Block Set) The networks the container is attached to (see [below for nested schema](#nestedblock--networks_advanced))
- `pid_mode` (String) he PID (Process) Namespace mode for the container. Either `container:<name|id>` or `host`.
- `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.
- `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 literraly 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))
- `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).
- `gateway` (String, Deprecated) The network gateway of the container.
- `id` (String) The ID of this resource.
- `ip_address` (String, Deprecated) The IP address of the container.
- `ip_prefix_length` (Number, Deprecated) The IP prefix length of the container.
- `network_data` (List of Object) The data of the networks the container is connected to. (see [below for nested schema](#nestedatt--network_data))

<a id="nestedblock--capabilities"></a>
### 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.


<a id="nestedblock--devices"></a>
### 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.
- `permissions` (String) The cgroup permissions given to the container to access the device. Defaults to `rwm`.


<a id="nestedblock--healthcheck"></a>
### Nested Schema for `healthcheck`

Required:

- `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"]`.

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_period` (String) Start period for the container to initialize before counting retries towards unstable (ms|s|m|h). Defaults to `0s`.
- `timeout` (String) Maximum time to allow one check to run (ms|s|m|h). Defaults to `0s`.


<a id="nestedblock--host"></a>
### Nested Schema for `host`

Required:

- `host` (String) Hostname to add
- `ip` (String) IP address this hostname should resolve to.


<a id="nestedblock--labels"></a>
### Nested Schema for `labels`

Required:

- `label` (String) Name of the label
- `value` (String) Value of the label


<a id="nestedblock--mounts"></a>
### 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))

<a id="nestedblock--mounts--bind_options"></a>
### Nested Schema for `mounts.bind_options`

Optional:

- `propagation` (String) A propagation mode with the value.


<a id="nestedblock--mounts--tmpfs_options"></a>
### 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.


<a id="nestedblock--mounts--volume_options"></a>
### 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.

<a id="nestedblock--mounts--volume_options--labels"></a>
### Nested Schema for `mounts.volume_options.labels`

Required:

- `label` (String) Name of the label
- `value` (String) Value of the label




<a id="nestedblock--networks_advanced"></a>
### Nested Schema for `networks_advanced`

Required:

- `name` (String) The name of the network.

Optional:

- `aliases` (Set of String) The network aliases of the container in the specific network.
- `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.


<a id="nestedblock--ports"></a>
### 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`.


<a id="nestedblock--ulimit"></a>
### Nested Schema for `ulimit`

Required:

- `hard` (Number) The hard limit
- `name` (String) The name of the ulimit
- `soft` (Number) The soft limit


<a id="nestedblock--upload"></a>
### 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`.
- `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.


<a id="nestedblock--volumes"></a>
### 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.
- `read_only` (Boolean) If `true`, this volume will be readonly. Defaults to `false`.
- `volume_name` (String) The name of the docker volume which should be mounted.


<a id="nestedatt--network_data"></a>
### 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)
- `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
```