community.docker.docker_container module – manage docker containers
Note
This module is part of the community.docker collection (version 2.7.3).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.docker.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.docker.docker_container.
Synopsis
Manage the life cycle of docker containers.
Supports check mode. Run with
--checkand--diffto view config difference and list of actions to be taken.
Requirements
The below requirements are needed on the host that executes this module.
Docker API >= 1.20
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). For Python 2.6,
docker-pymust be used. Otherwise, it is recommended to install thedockerPython 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 SDK for Python >= 1.8.0 (use docker-py for Python 2.6)
Parameters
Parameter |
Comments |
|---|---|
The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon. If the value is not specified in the task, the value of environment variable Default: |
|
Enable auto-removal of the container on daemon side when the container’s process exits. If container_default_behavior is set to Choices:
|
|
Block IO (relative weight), between 10 and 1000. |
|
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 |
|
List of capabilities to drop from the container. |
|
List of capabilities to add to the container. This is equivalent to |
|
Specify the parent cgroup for the container. |
|
Use with detach=false to remove the container after successful execution. Choices:
|
|
Path to the client’s TLS certificate file. If the value is not specified in the task and the environment variable |
|
Path to the client’s TLS key file. If the value is not specified in the task and the environment variable |
|
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. See command_handling for differences in how strings and lists are handled. |
|
The default behavior for command (when provided as a list) and entrypoint is to convert them to strings without considering shell quoting rules. (For comparing idempotency, the resulting string is split considering shell quoting rules.) Also, setting command to an empty list of string, and setting entrypoint to an empty list will be handled as if these options are not specified. This is different from idempotency handling for other container-config related options. When this is set to When this is set to In community.docker 3.0.0, the default will change to Choices:
|
|
Allows to specify how properties of existing containers are compared with module options to decide whether the container should be recreated / updated or not. Only options which correspond to the state of a container as handled by the Docker daemon can be specified, as well as networks. Must be a dictionary specifying for an option one of the keys If
The wildcard option See the examples for details. |
|
In older versions of this module, various module options used to have default values. This caused problems with containers which use different values for these options. The default value is now This affects the auto_remove, detach, init, interactive, memory, paused, privileged, read_only and tty options. Choices:
|
|
Limit CPU CFS (Completely Fair Scheduler) period. See cpus for an easier to use alternative. |
|
Limit CPU CFS (Completely Fair Scheduler) quota. See cpus for an easier to use alternative. |
|
CPU shares (relative weight). |
|
Specify how much of the available CPU resources a container can use. A value of |
|
CPUs in which to allow execution |
|
Memory nodes (MEMs) in which to allow execution |
|
Debug mode Choices:
|
|
Define the default host IP to use. Must be an empty string, an IPv4 address, or an IPv6 address. With Docker 20.10.2 or newer, this should be set to an empty string ( By default, the module will try to auto-detect this value from the |
|
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). If container_default_behavior is set to Choices:
|
|
List of device path and read rate (bytes per second) from device. |
|
Device path in the container. |
|
Device read limit in format Number is a positive integer. Unit can be one of Omitting the unit defaults to bytes. |
|
List of device and read rate (IO per second) from device. |
|
Device path in the container. |
|
Device read limit. Must be a positive integer. |
|
Allows to request additional resources, such as GPUs. |
|
List of lists of strings to request capabilities. The top-level list entries are combined by OR, and for every list entry, the entries in the list it contains are combined by AND. The driver tries to satisfy one of the sub-lists. Available capabilities for the |
|
Number or devices to request. Set to |
|
List of device IDs. |
|
Which driver to use for this device. |
|
Driver-specific options. |
|
List of device and write rate (bytes per second) to device. |
|
Device path in the container. |
|
Device read limit in format Number is a positive integer. Unit can be one of Omitting the unit defaults to bytes. |
|
List of device and write rate (IO per second) to device. |
|
Device path in the container. |
|
Device read limit. Must be a positive integer. |
|
List of host device bindings to add to the container. Each binding is a mapping expressed in the format |
|
List of DNS options. |
|
List of custom DNS search domains. |
|
List of custom DNS servers. |
|
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, If the value is not specified in the task, the value of environment variable Default: |
|
Container domainname. |
|
Command that overwrites the default See command_handling for differences in how strings and lists are handled. |
|
Dictionary of key,value pairs. Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example Please note that if you are passing values in with Jinja2 templates, like |
|
Path to a file, present on the target, containing environment variables FOO=BAR. If variable also present in env, then the env value will override. |
|
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 |
|
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 |
|
Use the kill command when stopping a running container. Choices:
|
|
List of additional group names and/or IDs that the container process will run as. |
|
Configure a check that is run to determine whether or not containers for this service are “healthy”. See the docs for the HEALTHCHECK Dockerfile instruction for details on how healthchecks work. interval, timeout and start_period are specified as durations. They accept duration as a string in a format that look like: |
|
Time between running the check. The default used by the Docker daemon is |
|
Consecutive number of failures needed to report unhealthy. The default used by the Docker daemon is |
|
Start period for the container to initialize before starting health-retries countdown. The default used by the Docker daemon is |
|
Command to run to check health. Must be either a string or a list. If it is a list, the first item must be one of |
|
Maximum time to allow one check to run. The default used by the Docker daemon is |
|
The container’s hostname. |
|
When state is Warning: This option is ignored if Choices:
|
|
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, Can also be an image ID. If this is the case, the image is assumed to be available locally. The pull option is ignored for this case. |
|
How to handle labels inherited from the image that are not set explicitly. When When Warning: This option is ignored unless Choices:
|
|
Run an init inside the container that forwards signals and reaps processes. This option requires Docker API >= 1.25. If container_default_behavior is set to Choices:
|
|
Keep stdin open after a container is launched, even if not attached. If container_default_behavior is set to Choices:
|
|
Set the IPC mode for the container. Can be one of |
|
Retain anonymous volumes associated with a removed container. Choices:
|
|
Kernel memory limit in format Omitting the unit defaults to bytes. |
|
Override default signal used to kill a running container. |
|
Dictionary of key value pairs. |
|
List of name aliases for linked containers in the format Setting this will force container to be restarted. |
|
Specify the logging driver. Docker uses See here for possible choices. |
|
Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/ for details. log_driver needs to be specified for log_options to take effect, even if using the default |
|
Container MAC address (for example, |
|
Memory limit in format Omitting the unit defaults to bytes. If container_default_behavior is set to |
|
Memory soft limit in format Omitting the unit defaults to bytes. |
|
Total memory limit (memory + swap) in format Omitting the unit defaults to bytes. |
|
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. |
|
Specification for mounts to be added to the container. More powerful alternative to volumes. |
|
The consistency requirement for the mount. Choices:
|
|
User-defined name and labels for the volume. Only valid for the |
|
False if the volume should be populated with the data from the target. Only valid for the The default value is Choices:
|
|
Propagation mode. Only valid for the Choices:
|
|
Whether the mount should be read-only. Choices:
|
|
Mount source. For example, this can be a volume name or a host path. If not supplied when type=volume an anonymous volume will be created. |
|
Path inside the container. |
|
The permission mode for the tmpfs mount. |
|
The size for the tmpfs mount in bytes in format <number>[<unit>]. Number is a positive integer. Unit can be one of Omitting the unit defaults to bytes. |
|
The mount type. Note that Choices:
|
|
Specify the volume driver. Only valid for the See here for details. |
|
Dictionary of options specific to the chosen volume_driver. See here for details. |
|
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. |
|
Connect the container to a network. Choices are Since community.docker 2.0.0, if networks_cli_compatible is |
|
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. If networks_cli_compatible is set to |
|
List of aliases for this container in this network. These names can be used in the network to reach this container. |
|
The container’s IPv4 address in this network. |
|
The container’s IPv6 address in this network. |
|
A list of containers to link to. |
|
The network’s name. |
|
If networks_cli_compatible is set to When networks_cli_compatible is set to Choices:
|
|
Whether or not to disable OOM Killer for the container. Choices:
|
|
An integer value containing the score given to the container in order to tune OOM killer preferences. |
|
If set to true, output of the container command will be printed. Only effective when log_driver is set to Choices:
|
|
Use with the started state to pause running processes inside the container. If container_default_behavior is set to Choices:
|
|
Set the PID namespace mode for the container. Note that Docker SDK for Python < 2.0 only supports |
|
Set PIDs limit for the container. It accepts an integer value. Set |
|
Give extended privileges to the container. If container_default_behavior is set to Choices:
|
|
Publish all ports to the host. Any specified port bindings from published_ports will remain intact when Choices:
|
|
List of ports to publish from the container to the host. Use docker CLI syntax: Port ranges can be used for source and destination ports. If two ranges with different lengths are specified, the shorter range will be used. Since community.general 0.2.0, if the source port range has length 1, the port will not be assigned to the first port of the destination range, but to a free port in that range. This is the same behavior as for Bind addresses must be either IPv4 or IPv6 addresses. Hostnames are not allowed. This is different from the A value of If networks parameter is provided, will inspect each network to see if there exists a bridge network with optional parameter |
|
If true, always pull the latest version of an image. Otherwise, will only pull an image when missing. Note: images are only pulled when specified by name. If the image is specified as a image ID (hash), it cannot be pulled. Choices:
|
|
Remove the container from ALL networks not included in networks parameter. Any default networks such as Choices:
|
|
Mount the container’s root file system as read-only. If container_default_behavior is set to Choices:
|
|
Use with present and started states to force the re-creation of an existing container. Choices:
|
|
When removing an existing container, the docker daemon API call exists after the container is scheduled for removal. Removal usually is very fast, but it can happen that during high I/O load, removal can take longer. By default, the module will wait until the container has been removed before trying to (re-)create it, however long this takes. By setting this option, the module will wait at most this many seconds for the container to be removed. If the container is still in the removal phase after this many seconds, the module will fail. |
|
Use with started state to force a matching container to be stopped and restarted. Choices:
|
|
Container restart policy. Place quotes around Choices:
|
|
Use with restart policy to control maximum number of restart attempts. |
|
Runtime to use for the container. |
|
List of security options in the form of |
|
Size of Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses |
|
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 |
|
To control what will be taken into account when comparing configuration, see the comparisons option. To avoid that the image version will be taken into account, you can also use the ignore_image option. Use the recreate option to always force re-creation of a matching container, even if it is running. If the container should be killed instead of stopped in case it needs to be stopped for recreation, or because state is Use keep_volumes to retain anonymous volumes associated with a removed container. Choices:
|
|
Override default signal used to stop the container. |
|
Number of seconds to wait for the container to stop before sending When the container is stopped, will be used as a timeout for stopping the container. In case the container has a custom |
|
Storage driver options for this container as a key-value mapping. |
|
Dictionary of key,value pairs. |
|
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 Default: |
|
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if validate_certs is set to If the value is not specified in the task, the value of environment variable Choices:
|
|
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 The current default value is |
|
Mount a tmpfs directory. |
|
Allocate a pseudo-TTY. If container_default_behavior is set to Choices:
|
|
List of ulimit options. A ulimit is specified as |
|
For SSH transports, use the Requires Docker SDK for Python 4.4.0 or newer. Choices:
|
|
Sets the username or UID used and optionally the groupname or GID for the specified command. Can be of the forms |
|
Set the user namespace mode for the container. Currently, the only valid value are |
|
Set the UTS namespace mode for the container. |
|
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 Choices:
|
|
The container volume driver. |
|
List of volumes to mount within the container. Use docker CLI-style syntax: Mount modes can be a comma-separated list of various modes such as SELinux hosts can additionally use Note that Ansible 2.7 and earlier only supported one mode, which had to be one of |
|
List of container names or IDs to get volumes from. |
|
Path to the working directory. |
Notes
Note
For most config changes, the container needs to be recreated. This means that the existing container has to be destroyed and a new one created. This can cause unexpected data loss and downtime. You can use the comparisons option to prevent this.
If the module needs to recreate the container, it will only use the options provided to the module to create the new container (except image). Therefore, always specify all options relevant to the container.
When restart is set to
true, the module will only restart the container if no config changes are detected.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_VERIFYandDOCKER_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://docs.docker.com/machine/reference/env/ 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 ansible.builtin.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.jsonif theDOCKER_CONFIGenvironment variable is not specified, and use$DOCKER_CONFIG/config.jsonotherwise.This module uses the Docker SDK for Python to communicate with the Docker daemon.
Examples
- name: Create a data container
community.docker.docker_container:
name: mydata
image: busybox
volumes:
- /data
- name: Re-create a redis container
community.docker.docker_container:
name: myredis
image: redis
command: redis-server --appendonly yes
state: present
recreate: true
exposed_ports:
- 6379
volumes_from:
- mydata
- name: Restart a container
community.docker.docker_container:
name: myapplication
image: someuser/appimage
state: started
restart: true
links:
- "myredis:aliasedredis"
devices:
- "/dev/sda:/dev/xvda:rwm"
ports:
# Publish container port 9000 as host port 8080
- "8080:9000"
# Publish container UDP port 9001 as host port 8081 on interface 127.0.0.1
- "127.0.0.1:8081:9001/udp"
# Publish container port 9002 as a random host port
- "9002"
# Publish container port 9003 as a free host port in range 8000-8100
# (the host port will be selected by the Docker daemon)
- "8000-8100:9003"
# Publish container ports 9010-9020 to host ports 7000-7010
- "7000-7010:9010-9020"
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
community.docker.docker_container:
name: mycontainer
state: present
image: ubuntu:14.04
command: sleep infinity
- name: Stop a container
community.docker.docker_container:
name: mycontainer
state: stopped
- name: Start 4 load-balanced containers
community.docker.docker_container:
name: "container{{ item }}"
recreate: true
image: someuser/anotherappimage
command: sleep 1d
with_sequence: count=4
- name: Remove container
community.docker.docker_container:
name: ohno
state: absent
- name: Syslogging output
community.docker.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
community.docker.docker_container:
name: db_test
image: "postgres:latest"
networks:
- name: "{{ docker_network_name }}"
- name: Start container, connect to network and link
community.docker.docker_container:
name: sleeper
image: ubuntu:14.04
networks:
- name: TestingNet
ipv4_address: "172.16.1.100"
aliases:
- sleepyzz
links:
- db_test:db
- name: TestingNet2
- name: Start a container with a command
community.docker.docker_container:
name: sleepy
image: ubuntu:14.04
command: ["sleep", "infinity"]
- name: Add container to networks
community.docker.docker_container:
name: sleepy
networks:
- name: TestingNet
ipv4_address: 172.16.1.18
links:
- sleeper
- name: TestingNet2
ipv4_address: 172.16.10.20
- name: Update network with aliases
community.docker.docker_container:
name: sleepy
networks:
- name: TestingNet
aliases:
- sleepyz
- zzzz
- name: Remove container from one network
community.docker.docker_container:
name: sleepy
networks:
- name: TestingNet2
purge_networks: true
- name: Remove container from all networks
community.docker.docker_container:
name: sleepy
purge_networks: true
- name: Start a container and use an env file
community.docker.docker_container:
name: agent
image: jenkinsci/ssh-slave
env_file: /var/tmp/jenkins/agent.env
- name: Create a container with limited capabilities
community.docker.docker_container:
name: sleepy
image: ubuntu:16.04
command: sleep infinity
capabilities:
- sys_time
cap_drop:
- all
- name: Finer container restart/update control
community.docker.docker_container:
name: test
image: ubuntu:18.04
env:
arg1: "true"
arg2: "whatever"
volumes:
- /tmp:/tmp
comparisons:
image: ignore # do not restart containers with older versions of the image
env: strict # we want precisely this environment
volumes: allow_more_present # if there are more volumes, that's ok, as long as `/tmp:/tmp` is there
- name: Finer container restart/update control II
community.docker.docker_container:
name: test
image: ubuntu:18.04
env:
arg1: "true"
arg2: "whatever"
comparisons:
'*': ignore # by default, ignore *all* options (including image)
env: strict # except for environment variables; there, we want to be strict
- name: Start container with healthstatus
community.docker.docker_container:
name: nginx-proxy
image: nginx:1.13
state: started
healthcheck:
# Check if nginx server is healthy by curl'ing the server.
# If this fails or timeouts, the healthcheck fails.
test: ["CMD", "curl", "--fail", "http://nginx.host.com"]
interval: 1m30s
timeout: 10s
retries: 3
start_period: 30s
- name: Remove healthcheck from container
community.docker.docker_container:
name: nginx-proxy
image: nginx:1.13
state: started
healthcheck:
# The "NONE" check needs to be specified
test: ["NONE"]
- name: Start container with block device read limit
community.docker.docker_container:
name: test
image: ubuntu:18.04
state: started
device_read_bps:
# Limit read rate for /dev/sda to 20 mebibytes per second
- path: /dev/sda
rate: 20M
device_read_iops:
# Limit read rate for /dev/sdb to 300 IO per second
- path: /dev/sdb
rate: 300
- name: Start container with GPUs
community.docker.docker_container:
name: test
image: ubuntu:18.04
state: started
device_requests:
- # Add some specific devices to this container
device_ids:
- '0'
- 'GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a'
- # Add nVidia GPUs to this container
driver: nvidia
count: -1 # this means we want all
capabilities:
# We have one OR condition: 'gpu' AND 'utility'
- - gpu
- utility
# See https://github.com/NVIDIA/nvidia-container-runtime#supported-driver-capabilities
# for a list of capabilities supported by the nvidia driver
- name: Start container with storage options
community.docker.docker_container:
name: test
image: ubuntu:18.04
state: started
storage_opts:
# Limit root filesystem to 12 MB - note that this requires special storage backends
# (https://fabianlee.org/2020/01/15/docker-use-overlay2-with-an-xfs-backing-filesystem-to-limit-rootfs-size/)
size: 12m
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Facts representing the current state of the container. Matches the docker inspection output. Empty if state is If detach=false, will include Returned: success; or when state=started and detach=false, and when waiting for the container result did not fail Sample: |
|
In case a container is started without detaching, this contains the exit code of the process in the container. Before community.docker 1.1.0, this was only returned when non-zero. Returned: when state=started and detach=false, and when waiting for the container result did not fail Sample: |
Collection links
Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication