docker_container – manage docker containers¶

New in version 2.1.

Synopsis
Requirements
Parameters
Notes
Examples
Return Values
Status

Synopsis ¶

Manage the life cycle of docker containers.
Supports check mode. Run with –check and –diff to view config difference and list of actions to be taken.

Requirements ¶

The below requirements are needed on the host that executes this module.

python >= 2.6
docker-py >= 1.7.0
Please note that the docker-py Python module has been superseded by docker (see here for details). For Python 2.6, docker-py must be used. Otherwise, it is recommended to install the docker Python module. Note that both modules should not be installed at the same time. Also note that when both modules are installed and one of them is uninstalled, the other might no longer function and a reinstall of it is required.
Docker API >= 1.20

Parameters ¶

Parameter		Choices/Defaults	Comments
api_version -		Default: "auto"	The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by docker-py. If the value is not specified in the task, the value of environment variable `DOCKER_API_VERSION` will be used instead. If the environment variable is not set, the default value will be used. aliases: docker_api_version
auto_remove boolean added in 2.4		Choices: no ← yes	enable auto-removal of the container on daemon side when the container's process exits
blkio_weight -			Block IO (relative weight), between 10 and 1000.
cacert_path -			Use a CA certificate when performing server verification by providing the path to a CA certificate file. If the value is not specified in the task and the environment variable `DOCKER_CERT_PATH` is set, the file `ca.pem` from the directory specified in the environment variable `DOCKER_CERT_PATH` will be used. aliases: tls_ca_cert
cap_drop - added in 2.7			List of capabilities to drop from the container.
capabilities -			List of capabilities to add to the container.
cert_path -			Path to the client's TLS certificate file. If the value is not specified in the task and the environment variable `DOCKER_CERT_PATH` is set, the file `cert.pem` from the directory specified in the environment variable `DOCKER_CERT_PATH` will be used. aliases: tls_client_cert
cleanup boolean added in 2.2		Choices: no ← yes	Use with detach=false to remove the container after successful execution.
command -			Command to execute when the container starts. A command may be either a string or a list. Prior to version 2.4, strings were split on commas.
cpu_period -			Limit CPU CFS (Completely Fair Scheduler) period
cpu_quota -			Limit CPU CFS (Completely Fair Scheduler) quota
cpu_shares -			CPU shares (relative weight).
cpuset_cpus -			CPUs in which to allow execution `1,3` or `1-3`.
cpuset_mems -			Memory nodes (MEMs) in which to allow execution `0-3` or `0,1`
debug boolean		Choices: no ← yes	Debug mode
detach boolean		Choices: no yes ←	Enable detached mode to leave the container running in background. If disabled, the task will reflect the status of the container run (failed if the command failed).
devices -			List of host device bindings to add to the container. Each binding is a mapping expressed in the format: <path_on_host>:<path_in_container>:<cgroup_permissions>
dns_opts -			list of DNS options
dns_search_domains -			List of custom DNS search domains.
dns_servers -			List of custom DNS servers.
docker_host -		Default: "unix://var/run/docker.sock"	The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection string. For example, 'tcp://192.0.2.23:2376'. If TLS is used to encrypt the connection, the module will automatically replace 'tcp' in the connection URL with 'https'. If the value is not specified in the task, the value of environment variable `DOCKER_HOST` will be used instead. If the environment variable is not set, the default value will be used. aliases: docker_url
domainname - added in 2.5			Container domainname.
entrypoint -			Command that overwrites the default ENTRYPOINT of the image.
env dictionary			Dictionary of key,value pairs. Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (e.g. `"true"`) in order to avoid data loss.
env_file - added in 2.2			Path to a file, present on the target, containing environment variables FOO=BAR. If variable also present in `env`, then `env` value will override.
etc_hosts -			Dict of host-to-IP mappings, where each host name is a key in the dictionary. Each host name will be added to the container's /etc/hosts file.
exposed_ports -			List of additional container ports which informs Docker that the container listens on the specified network ports at runtime. If the port is already exposed using EXPOSE in a Dockerfile, it does not need to be exposed again. aliases: exposed, expose
force_kill boolean		Choices: no ← yes	Use the kill command when stopping a running container. aliases: forcekill
groups -			List of additional group names and/or IDs that the container process will run as.
hostname -			Container hostname.
ignore_image boolean added in 2.2		Choices: no ← yes	When `state` is present or started the module compares the configuration of an existing container to requested configuration. The evaluation includes the image version. If the image version in the registry does not match the container, the container will be recreated. Stop this behavior by setting `ignore_image` to True.
image -			Repository path and tag used to create the container. If an image is not found or pull is true, the image will be pulled from the registry. If no tag is included, 'latest' will be used.
init boolean added in 2.6		Choices: no ← yes	Run an init inside the container that forwards signals and reaps processes. This option requires Docker API 1.25+.
interactive boolean		Choices: no ← yes	Keep stdin open after a container is launched, even if not attached.
ipc_mode -			Set the IPC mode for the container. Can be one of 'container:<name\|id>' to reuse another container's IPC namespace or 'host' to use the host's IPC namespace within the container.
keep_volumes boolean		Choices: no yes ←	Retain volumes associated with a removed container.
kernel_memory -			Kernel memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be `B` (byte), `K` (kibibyte, 1024B), `M` (mebibyte), `G` (gibibyte), `T` (tebibyte), or `P` (pebibyte). Minimum is `4M`. Omitting the unit defaults to bytes.
key_path -			Path to the client's TLS key file. If the value is not specified in the task and the environment variable `DOCKER_CERT_PATH` is set, the file `key.pem` from the directory specified in the environment variable `DOCKER_CERT_PATH` will be used. aliases: tls_client_key
kill_signal -			Override default signal used to kill a running container.
labels -			Dictionary of key value pairs.
links -			List of name aliases for linked containers in the format `container_name:alias`. Setting this will force container to be restarted.
log_driver -			Specify the logging driver. Docker uses json-file by default. See here for possible choices.
log_options -			Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/ for details. aliases: log_opt
mac_address -			Container MAC address (e.g. 92:d0:c6:0a:29:33)
memory -		Default: "0"	Memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be `B` (byte), `K` (kibibyte, 1024B), `M` (mebibyte), `G` (gibibyte), `T` (tebibyte), or `P` (pebibyte). Omitting the unit defaults to bytes.
memory_reservation -			Memory soft limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be `B` (byte), `K` (kibibyte, 1024B), `M` (mebibyte), `G` (gibibyte), `T` (tebibyte), or `P` (pebibyte). Omitting the unit defaults to bytes.
memory_swap -			Total memory limit (memory + swap, format: `<number>[<unit>]`). Number is a positive integer. Unit can be `B` (byte), `K` (kibibyte, 1024B), `M` (mebibyte), `G` (gibibyte), `T` (tebibyte), or `P` (pebibyte). Omitting the unit defaults to bytes.
memory_swappiness -			Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. If not set, the value will be remain the same if container exists and will be inherited from the host machine if it is (re-)created.
name - / required			Assign a name to a new container or match an existing container. When identifying an existing container name may be a name or a long or short container ID.
network_mode -			Connect the container to a network. Choices are "bridge", "host", "none" or "container:<name\|id>"
networks list added in 2.2			List of networks the container belongs to. For examples of the data structure and usage see EXAMPLES below. To remove a container from one or more networks, use the `purge_networks` option. Note that as opposed to `docker run ...`, docker_container does not remove the default network if `networks` is specified. You need to explicity use `purge_networks` to enforce the removal of the default network (and all other networks not explicitly mentioned in `networks`).
	aliases list		List of aliases for this container in this network. These names can be used in the network to reach this container.
	ipv4_address string		The container's IPv4 address in this network.
	ipv6_address string		The container's IPv6 address in this network.
	links list		A list of containers to link to.
	name string / required		The network's name.
oom_killer boolean		Choices: no yes	Whether or not to disable OOM Killer for the container.
oom_score_adj - added in 2.2			An integer value containing the score given to the container in order to tune OOM killer preferences.
output_logs boolean added in 2.7		Choices: no ← yes	If set to true, output of the container command will be printed (only effective when log_driver is set to json-file or journald.
paused boolean		Choices: no ← yes	Use with the started state to pause running processes inside the container.
pid_mode -			Set the PID namespace mode for the container. Note that docker-py < 2.0 only supports 'host'. Newer versions allow all values supported by the docker daemon.
privileged boolean		Choices: no ← yes	Give extended privileges to the container.
published_ports -			List of ports to publish from the container to the host. Use docker CLI syntax: `8000`, `9000:8000`, or `0.0.0.0:9000:8000`, where 8000 is a container port, 9000 is a host port, and 0.0.0.0 is a host interface. A value of `all` will publish all exposed container ports to random host ports, ignoring any other mappings. If `networks` parameter is provided, will inspect each network to see if there exists a bridge network with optional parameter com.docker.network.bridge.host_binding_ipv4. If such a network is found, then published ports where no host IP address is specified will be bound to the host IP pointed to by com.docker.network.bridge.host_binding_ipv4. Note that the first bridge network with a com.docker.network.bridge.host_binding_ipv4 value encountered in the list of `networks` is the one that will be used. aliases: ports
pull boolean		Choices: no ← yes	If true, always pull the latest version of an image. Otherwise, will only pull an image when missing.
purge_networks boolean added in 2.2		Choices: no ← yes	Remove the container from ALL networks not included in `networks` parameter. Any default networks such as bridge, if not found in `networks`, will be removed as well.
read_only boolean		Choices: no ← yes	Mount the container's root file system as read-only.
recreate boolean		Choices: no ← yes	Use with present and started states to force the re-creation of an existing container.
restart boolean		Choices: no ← yes	Use with started state to force a matching container to be stopped and restarted.
restart_policy -		Choices: no on-failure always unless-stopped	Container restart policy. Place quotes around no option.
restart_retries -			Use with restart policy to control maximum number of restart attempts.
security_opts -			List of security options in the form of `"label:user:User"`
shm_size -			Size of `/dev/shm` (format: `<number>[<unit>]`). Number is positive integer. Unit can be `B` (byte), `K` (kibibyte, 1024B), `M` (mebibyte), `G` (gibibyte), `T` (tebibyte), or `P` (pebibyte). Omitting the unit defaults to bytes. If you omit the size entirely, the system uses `64M`.
ssl_version -			Provide a valid SSL version number. Default value determined by ssl.py module. If the value is not specified in the task, the value of environment variable `DOCKER_SSL_VERSION` will be used instead.
state -		Choices: absent present stopped started ←	absent - A container matching the specified name will be stopped and removed. Use force_kill to kill the container rather than stopping it. Use keep_volumes to retain volumes associated with the removed container. present - Asserts the existence of a container matching the name and any provided configuration parameters. If no container matches the name, a container will be created. If a container matches the name but the provided configuration does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and re-created with the requested config. Image version will be taken into account when comparing configuration. To ignore image version use the ignore_image option. Use the recreate option to force the re-creation of the matching container. Use force_kill to kill the container rather than stopping it. Use keep_volumes to retain volumes associated with a removed container. started - Asserts there is a running container matching the name and any provided configuration. If no container matches the name, a container will be created and started. If a container matching the name is found but the configuration does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and a new container will be created with the requested configuration and started. Image version will be taken into account when comparing configuration. To ignore image version use the ignore_image option. Use recreate to always re-create a matching container, even if it is running. Use restart to force a matching container to be stopped and restarted. Use force_kill to kill a container rather than stopping it. Use keep_volumes to retain volumes associated with a removed container. stopped - Asserts that the container is first present, and then if the container is running moves it to a stopped state. Use force_kill to kill a container rather than stopping it.
stop_signal -			Override default signal used to stop the container.
stop_timeout -			Number of seconds to wait for the container to stop before sending SIGKILL.
sysctls - added in 2.4			Dictionary of key,value pairs.
timeout -		Default: 60	The maximum amount of time in seconds to wait on a response from the API. If the value is not specified in the task, the value of environment variable `DOCKER_TIMEOUT` will be used instead. If the environment variable is not set, the default value will be used.
tls boolean		Choices: no ← yes	Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. If the value is not specified in the task, the value of environment variable `DOCKER_TLS` will be used instead. If the environment variable is not set, the default value will be used.
tls_hostname -		Default: "localhost"	When verifying the authenticity of the Docker Host server, provide the expected name of the server. If the value is not specified in the task, the value of environment variable `DOCKER_TLS_HOSTNAME` will be used instead. If the environment variable is not set, the default value will be used.
tls_verify boolean		Choices: no ← yes	Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. If the value is not specified in the task, the value of environment variable `DOCKER_TLS_VERIFY` will be used instead. If the environment variable is not set, the default value will be used.
tmpfs - added in 2.4			Mount a tmpfs directory
trust_image_content boolean		Choices: no ← yes	If `yes`, skip image verification.
tty boolean		Choices: no ← yes	Allocate a pseudo-TTY.
ulimits -			List of ulimit options. A ulimit is specified as `nofile:262144:262144`
user -			Sets the username or UID used and optionally the groupname or GID for the specified command. Can be [ user \| user:group \| uid \| uid:gid \| user:gid \| uid:group ]
userns_mode - added in 2.5			Set the user namespace mode for the container. Currently, the only valid value is `host`.
uts -			Set the UTS namespace mode for the container.
volume_driver -			The container volume driver.
volumes -			List of volumes to mount within the container. Use docker CLI-style syntax: `/host:/container[:mode]` You can specify a read mode for the mount with either `ro` or `rw`. SELinux hosts can additionally use `z` or `Z` to use a shared or private label for the volume.
volumes_from -			List of container names or Ids to get volumes from.
working_dir - added in 2.4			Path to the working directory.

Notes ¶

Note

Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docker-py.readthedocs.io/en/stable/machine/ for more details.
When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls] with pip.
Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/docker/config.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.

Examples ¶

- name: Create a data container
  docker_container:
    name: mydata
    image: busybox
    volumes:
      - /data

- name: Re-create a redis container
  docker_container:
    name: myredis
    image: redis
    command: redis-server --appendonly yes
    state: present
    recreate: yes
    exposed_ports:
      - 6379
    volumes_from:
      - mydata

- name: Restart a container
  docker_container:
    name: myapplication
    image: someuser/appimage
    state: started
    restart: yes
    links:
     - "myredis:aliasedredis"
    devices:
     - "/dev/sda:/dev/xvda:rwm"
    ports:
     - "8080:9000"
     - "127.0.0.1:8081:9001/udp"
    env:
        SECRET_KEY: "ssssh"
        # Values which might be parsed as numbers, booleans or other types by the YAML parser need to be quoted
        BOOLEAN_KEY: "yes"

- name: Container present
  docker_container:
    name: mycontainer
    state: present
    image: ubuntu:14.04
    command: sleep infinity

- name: Stop a container
  docker_container:
    name: mycontainer
    state: stopped

- name: Start 4 load-balanced containers
  docker_container:
    name: "container{{ item }}"
    recreate: yes
    image: someuser/anotherappimage
    command: sleep 1d
  with_sequence: count=4

- name: remove container
  docker_container:
    name: ohno
    state: absent

- name: Syslogging output
  docker_container:
    name: myservice
    image: busybox
    log_driver: syslog
    log_options:
      syslog-address: tcp://my-syslog-server:514
      syslog-facility: daemon
      # NOTE: in Docker 1.13+ the "syslog-tag" option was renamed to "tag" for
      # older docker installs, use "syslog-tag" instead
      tag: myservice

- name: Create db container and connect to network
  docker_container:
    name: db_test
    image: "postgres:latest"
    networks:
      - name: "{{ docker_network_name }}"

- name: Start container, connect to network and link
  docker_container:
    name: sleeper
    image: ubuntu:14.04
    networks:
      - name: TestingNet
        ipv4_address: "172.1.1.100"
        aliases:
          - sleepyzz
        links:
          - db_test:db
      - name: TestingNet2

- name: Start a container with a command
  docker_container:
    name: sleepy
    image: ubuntu:14.04
    command: ["sleep", "infinity"]

- name: Add container to networks
  docker_container:
    name: sleepy
    networks:
      - name: TestingNet
        ipv4_address: 172.1.1.18
        links:
          - sleeper
      - name: TestingNet2
        ipv4_address: 172.1.10.20

- name: Update network with aliases
  docker_container:
    name: sleepy
    networks:
      - name: TestingNet
        aliases:
          - sleepyz
          - zzzz

- name: Remove container from one network
  docker_container:
    name: sleepy
    networks:
      - name: TestingNet2
    purge_networks: yes

- name: Remove container from all networks
  docker_container:
    name: sleepy
    purge_networks: yes

- name: Start a container and use an env file
  docker_container:
    name: agent
    image: jenkinsci/ssh-slave
    env_file: /var/tmp/jenkins/agent.env

- name: Create a container with limited capabilities
  docker_container:
    name: sleepy
    image: ubuntu:16.04
    command: sleep infinity
    capabilities:
      - sys_time
    cap_drop:
      - all

Return Values ¶

Common return values are documented here, the following are the fields unique to this module:

Key	Returned	Description
docker_container dictionary	always	Before 2.3 this was 'ansible_docker_container' but was renamed due to conflicts with the connection plugin. Facts representing the current state of the container. Matches the docker inspection output. Note that facts are not part of registered vars but accessible directly. Empty if `state` is absent If detached is False, will include Output attribute containing any output from container run. Sample: { "AppArmorProfile": "", "Args": [], "Config": { "AttachStderr": false, "AttachStdin": false, "AttachStdout": false, "Cmd": [ "/usr/bin/supervisord" ], "Domainname": "", "Entrypoint": null, "Env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], "ExposedPorts": { "443/tcp": {}, "80/tcp": {} }, "Hostname": "8e47bf643eb9", "Image": "lnmp_nginx:v1", "Labels": {}, "OnBuild": null, "OpenStdin": false, "StdinOnce": false, "Tty": false, "User": "", "Volumes": { "/tmp/lnmp/nginx-sites/logs/": {} }, ... }

Status ¶

This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Community. [community]

Authors¶

Cove Schneider (@cove)
Joshua Conner (@joshuaconner)
Pavel Antonov (@softzilla)
Thomas Steinbach (@ThomasSteinbach)
Philippe Jandot (@zfil)
Daan Oosterveld (@dusdanig)
Chris Houseknecht (@chouseknecht)
Kassian Sun (@kassiansun)

Hint

If you notice any issues in this documentation you can edit this document to improve it.

docker_container – manage docker containers¶

Synopsis¶

Requirements¶

Parameters¶

Notes¶

Examples¶

Return Values¶

Status¶