docker_container – manage docker containers¶
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 | Choices/Defaults | Comments | |
|---|---|---|---|
| api_version 
                    string
                                                                 | Default: "auto" | 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  DOCKER_API_VERSIONwill 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 | 
 | Enable auto-removal of the container on daemon side when the container's process exits. | |
| blkio_weight 
                    integer
                                                                 | Block IO (relative weight), between 10 and 1000. | ||
| ca_cert 
                    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_PATHis set, the fileca.pemfrom the directory specified in the environment variableDOCKER_CERT_PATHwill be used.aliases: tls_ca_cert, cacert_path | ||
| cap_drop 
                    list
                     / elements=string                                             added in 2.7 | List of capabilities to drop from the container. | ||
| capabilities 
                    list
                     / elements=string                                             | List of capabilities to add to the container. | ||
| cleanup 
                    boolean
                                                                 | 
 | Use with detach=false to remove the container after successful execution. | |
| client_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_PATHis set, the filecert.pemfrom the directory specified in the environment variableDOCKER_CERT_PATHwill be used.aliases: tls_client_cert, cert_path | ||
| client_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_PATHis set, the filekey.pemfrom the directory specified in the environment variableDOCKER_CERT_PATHwill be used.aliases: tls_client_key, key_path | ||
| command 
                    raw
                                                                 | 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. | ||
| comparisons 
                    dictionary
                                                                 added in 2.8 | 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  strict,ignoreandallow_more_present.If  strictis specified, values are tested for equality, and changes always result in updating or restarting. Ifignoreis specified, changes are ignored.allow_more_presentis allowed only for lists, sets and dicts. If it is specified for lists or sets, the container will only be updated or restarted if the module option contains a value which is not present in the container's options. If the option is specified for a dict, the container will only be updated or restarted if the module option contains a key which isn't present in the container's option, or if the value of a key present differs.The wildcard option  *can be used to set one of the default valuesstrictorignoreto *all* comparisons which are not explicitly set to other values.See the examples for details. | ||
| cpu_period 
                    integer
                                                                 | Limit CPU CFS (Completely Fair Scheduler) period. | ||
| cpu_quota 
                    integer
                                                                 | Limit CPU CFS (Completely Fair Scheduler) quota. | ||
| cpu_shares 
                    integer
                                                                 | CPU shares (relative weight). | ||
| cpuset_cpus 
                    string
                                                                 | CPUs in which to allow execution  1,3or1-3. | ||
| cpuset_mems 
                    string
                                                                 | Memory nodes (MEMs) in which to allow execution  0-3or0,1. | ||
| debug 
                    boolean
                                                                 | 
 | Debug mode | |
| detach 
                    boolean
                                                                 | 
 | 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). | |
| device_read_bps 
                    list
                     / elements=dictionary                                             added in 2.8 | List of device path and read rate (bytes per second) from device. | ||
| path 
                    string
                                             / required                     | Device path in the container. | ||
| rate 
                    string
                                             / required                     | Device read limit in format  <number>[<unit>].Number is a positive integer. Unit can be one of  B(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).Omitting the unit defaults to bytes. | ||
| device_read_iops 
                    list
                     / elements=dictionary                                             added in 2.8 | List of device and read rate (IO per second) from device. | ||
| path 
                    string
                                             / required                     | Device path in the container. | ||
| rate 
                    integer
                                             / required                     | Device read limit. Must be a positive integer. | ||
| device_write_bps 
                    list
                     / elements=dictionary                                             added in 2.8 | List of device and write rate (bytes per second) to device. | ||
| path 
                    string
                                             / required                     | Device path in the container. | ||
| rate 
                    string
                                             / required                     | Device read limit in format  <number>[<unit>].Number is a positive integer. Unit can be one of  B(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).Omitting the unit defaults to bytes. | ||
| device_write_iops 
                    list
                     / elements=dictionary                                             added in 2.8 | List of device and write rate (IO per second) to device. | ||
| path 
                    string
                                             / required                     | Device path in the container. | ||
| rate 
                    integer
                                             / required                     | Device read limit. Must be a positive integer. | ||
| devices 
                    list
                     / elements=string                                             | 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
                     / elements=string                                             | List of DNS options. | ||
| dns_search_domains 
                    list
                     / elements=string                                             | List of custom DNS search domains. | ||
| dns_servers 
                    list
                     / elements=string                                             | List of custom DNS servers. | ||
| docker_host 
                    string
                                                                 | 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 replacetcpin the connection URL withhttps.If the value is not specified in the task, the value of environment variable  DOCKER_HOSTwill be used instead. If the environment variable is not set, the default value will be used.aliases: docker_url | |
| domainname 
                    string
                                                                 added in 2.5 | Container domainname. | ||
| entrypoint 
                    list
                     / elements=string                                             | Command that overwrites the default  ENTRYPOINTof 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 
                    path
                                                                 | 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. | ||
| etc_hosts 
                    dictionary
                                                                 | 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/hostsfile. | ||
| exposed_ports 
                    list
                     / elements=string                                             | 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  EXPOSEin a Dockerfile, it does not need to be exposed again.aliases: exposed, expose | ||
| force_kill 
                    boolean
                                                                 | 
 | Use the kill command when stopping a running container. aliases: forcekill | |
| groups 
                    list
                     / elements=string                                             | List of additional group names and/or IDs that the container process will run as. | ||
| healthcheck 
                    dictionary
                                                                 added in 2.8 | 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:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh. | ||
| interval 
                    string
                                                                 | Time between running the check. The default used by the Docker daemon is  30s. | ||
| retries 
                    integer
                                                                 | Consecutive number of failures needed to report unhealthy. The default used by the Docker daemon is  3. | ||
| start_period 
                    string
                                                                 | Start period for the container to initialize before starting health-retries countdown. The default used by the Docker daemon is  0s. | ||
| test 
                    raw
                                                                 | 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  NONE,CMDorCMD-SHELL. | ||
| timeout 
                    string
                                                                 | Maximum time to allow one check to run. The default used by the Docker daemon is  30s. | ||
| hostname 
                    string
                                                                 | The container's hostname. | ||
| ignore_image 
                    boolean
                                                                 | 
 | When state is  presentorstarted, 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. You can stop this behavior by setting ignore_image toTrue.*Warning:* This option is ignored if  image: ignoreor*: ignoreis specified in the comparisons option. | |
| image 
                    string
                                                                 | 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,  latestwill be used.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. | ||
| init 
                    boolean
                                                                 added in 2.6 | 
 | Run an init inside the container that forwards signals and reaps processes. This option requires Docker API >= 1.25. | |
| interactive 
                    boolean
                                                                 | 
 | Keep stdin open after a container is launched, even if not attached. | |
| ipc_mode 
                    string
                                                                 | Set the IPC mode for the container. Can be one of  container:<name|id>to reuse another container's IPC namespace orhostto use the host's IPC namespace within the container. | ||
| keep_volumes 
                    boolean
                                                                 | 
 | Retain anonymous volumes associated with a removed container. | |
| kernel_memory 
                    string
                                                                 | Kernel memory limit in format  <number>[<unit>]. Number is a positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte). Minimum is4M.Omitting the unit defaults to bytes. | ||
| kill_signal 
                    string
                                                                 | Override default signal used to kill a running container. | ||
| labels 
                    dictionary
                                                                 | Dictionary of key value pairs. | ||
| links 
                    list
                     / elements=string                                             | List of name aliases for linked containers in the format  container_name:alias.Setting this will force container to be restarted. | ||
| log_driver 
                    string
                                                                 | Specify the logging driver. Docker uses  json-fileby default.See here for possible choices. | ||
| log_options 
                    dictionary
                                                                 | 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 
                    string
                                                                 | Container MAC address (e.g. 92:d0:c6:0a:29:33). | ||
| memory 
                    string
                                                                 | Default: "0" | Memory limit in format  <number>[<unit>]. Number is a positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).Omitting the unit defaults to bytes. | |
| memory_reservation 
                    string
                                                                 | Memory soft limit in format  <number>[<unit>]. Number is a positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).Omitting the unit defaults to bytes. | ||
| memory_swap 
                    string
                                                                 | Total memory limit (memory + swap) in format  <number>[<unit>]. Number is a positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).Omitting the unit defaults to bytes. | ||
| memory_swappiness 
                    integer
                                                                 | 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. | ||
| mounts 
                    list
                     / elements=dictionary                                             added in 2.9 | Specification for mounts to be added to the container. More powerful alternative to volumes. | ||
| consistency 
                    string
                                                                 | 
 | The consistency requirement for the mount. | |
| labels 
                    dictionary
                                                                 | User-defined name and labels for the volume. Only valid for the  volumetype. | ||
| no_copy 
                    boolean
                                                                 | 
 | False if the volume should be populated with the data from the target. Only valid for the  volumetype.The default value is  false. | |
| propagation 
                    string
                                                                 | 
 | Propagation mode. Only valid for the  bindtype. | |
| read_only 
                    boolean
                                                                 | 
 | Whether the mount should be read-only. | |
| source 
                    string
                                                                 | Mount source (e.g. a volume name or a host path). | ||
| target 
                    string
                                             / required                     | Path inside the container. | ||
| tmpfs_mode 
                    string
                                                                 | The permission mode for the tmpfs mount. | ||
| tmpfs_size 
                    string
                                                                 | The size for the tmpfs mount in bytes in format <number>[<unit>]. Number is a positive integer. Unit can be one of  B(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).Omitting the unit defaults to bytes. | ||
| type 
                    string
                                                                 | 
 | The mount type. Note that  npipeis only supported by Docker for Windows. | |
| volume_driver 
                    string
                                                                 | Specify the volume driver. Only valid for the  volumetype.See here for details. | ||
| volume_options 
                    dictionary
                                                                 | Dictionary of options specific to the chosen volume_driver. See here for details. | ||
| name 
                    string
                                             / 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 
                    string
                                                                 | Connect the container to a network. Choices are  bridge,host,noneorcontainer:<name|id>. | ||
| networks 
                    list
                     / elements=dictionary                                             | 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 explicitly use purge_networks to enforce the removal of the default network (and all other networks not explicitly mentioned in networks). Alternatively, use the networks_cli_compatible option, which will be enabled by default from Ansible 2.12 on. | ||
| aliases 
                    list
                     / elements=string                                             | 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
                     / elements=string                                             | A list of containers to link to. | ||
| name 
                    string
                                             / required                     | The network's name. | ||
| networks_cli_compatible 
                    boolean
                                                                 added in 2.8 | 
 | When networks are provided to the module via the networks option, the module behaves differently than  docker run --network:docker run --network otherwill create a container with networkotherattached, but the default network not attached. This module with networks: {name: other} will create a container with bothdefaultandotherattached. If purge_networks is set toyes, thedefaultnetwork will be removed afterwards.If networks_cli_compatible is set to  yes, this module will behave asdocker run --networkand will *not* add the default network if networks is specified. If networks is not specified, the default network will be attached.Note that docker CLI also sets network_mode to the name of the first network added if  --networkis specified. For more compatibility with docker CLI, you explicitly have to set network_mode to the name of the first network you're adding.Current value is  no. A new default ofyeswill be set in Ansible 2.12. | |
| oom_killer 
                    boolean
                                                                 | 
 | Whether or not to disable OOM Killer for the container. | |
| oom_score_adj 
                    integer
                                                                 | An integer value containing the score given to the container in order to tune OOM killer preferences. | ||
| output_logs 
                    boolean
                                                                 added in 2.7 | 
 | If set to true, output of the container command will be printed. Only effective when log_driver is set to  json-fileorjournald. | |
| paused 
                    boolean
                                                                 | 
 | Use with the started state to pause running processes inside the container. | |
| pid_mode 
                    string
                                                                 | Set the PID namespace mode for the container. Note that Docker SDK for Python < 2.0 only supports  host. Newer versions of the Docker SDK for Python (docker) allow all values supported by the Docker daemon. | ||
| pids_limit 
                    integer
                                                                 added in 2.8 | Set PIDs limit for the container. It accepts an integer value. Set  -1for unlimited PIDs. | ||
| privileged 
                    boolean
                                                                 | 
 | Give extended privileges to the container. | |
| published_ports 
                    list
                     / elements=string                                             | List of ports to publish from the container to the host. Use docker CLI syntax:  8000,9000:8000, or0.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.Port ranges can be used for source and destination ports. If two ranges with different lengths are specified, the shorter range will be used. Bind addresses must be either IPv4 or IPv6 addresses. Hostnames are *not* allowed. This is different from the  dockercommand line utility. Use the dig lookup to resolve hostnames.A value of  allwill 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 bycom.docker.network.bridge.host_binding_ipv4. Note that the first bridge network with acom.docker.network.bridge.host_binding_ipv4value encountered in the list of networks is the one that will be used.aliases: ports | ||
| pull 
                    boolean
                                                                 | 
 | 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. | |
| purge_networks 
                    boolean
                                                                 | 
 | 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
                                                                 | 
 | Mount the container's root file system as read-only. | |
| recreate 
                    boolean
                                                                 | 
 | Use with present and started states to force the re-creation of an existing container. | |
| restart 
                    boolean
                                                                 | 
 | Use with started state to force a matching container to be stopped and restarted. | |
| restart_policy 
                    string
                                                                 | 
 | Container restart policy. Place quotes around  nooption. | |
| restart_retries 
                    integer
                                                                 | Use with restart policy to control maximum number of restart attempts. | ||
| runtime 
                    string
                                                                 added in 2.8 | Runtime to use for the container. | ||
| security_opts 
                    list
                     / elements=string                                             | List of security options in the form of  "label:user:User". | ||
| shm_size 
                    string
                                                                 | Size of  /dev/shmin format<number>[<unit>]. Number is positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses  64M. | ||
| ssl_version 
                    string
                                                                 | 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_VERSIONwill be used instead. | ||
| state 
                    string
                                                                 | 
 | 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 anonymous 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.started- Asserts that the container is firstpresent, and then if the container is not running moves it to a running state. Use restart to force a matching container to be stopped and restarted.stopped- Asserts that the container is firstpresent, and then if the container is running moves it to a stopped state.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  stopped, please use the force_kill option. Use keep_volumes to retain anonymous volumes associated with a removed container.Use keep_volumes to retain anonymous volumes associated with a removed container. | |
| stop_signal 
                    string
                                                                 | Override default signal used to stop the container. | ||
| stop_timeout 
                    integer
                                                                 | Number of seconds to wait for the container to stop before sending  SIGKILL. When the container is created by this module, itsStopTimeoutconfiguration will be set to this value.When the container is stopped, will be used as a timeout for stopping the container. In case the container has a custom  StopTimeoutconfiguration, the behavior depends on the version of the docker daemon. New versions of the docker daemon will always use the container's configuredStopTimeoutvalue if it has been configured. | ||
| sysctls 
                    dictionary
                                                                 added in 2.4 | Dictionary of key,value pairs. | ||
| timeout 
                    integer
                                                                 | 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_TIMEOUTwill be used instead. If the environment variable is not set, the default value will be used. | |
| tls 
                    boolean
                                                                 | 
 | 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  yesas well, it will take precedence.If the value is not specified in the task, the value of environment variable  DOCKER_TLSwill be used instead. If the environment variable is not set, the default value will be used. | |
| tls_hostname 
                    string
                                                                 | 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_HOSTNAMEwill be used instead. If the environment variable is not set, the default value will be used. | |
| tmpfs 
                    list
                     / elements=string                                             added in 2.4 | Mount a tmpfs directory. | ||
| trust_image_content 
                    boolean
                                                                 | 
 | If  yes, skip image verification. | |
| tty 
                    boolean
                                                                 | 
 | Allocate a pseudo-TTY. | |
| ulimits 
                    list
                     / elements=string                                             | List of ulimit options. A ulimit is specified as  nofile:262144:262144. | ||
| user 
                    string
                                                                 | Sets the username or UID used and optionally the groupname or GID for the specified command. Can be of the forms  user,user:group,uid,uid:gid,user:gidoruid:group. | ||
| userns_mode 
                    string
                                                                 added in 2.5 | Set the user namespace mode for the container. Currently, the only valid value are  hostand the empty string. | ||
| uts 
                    string
                                                                 | Set the UTS namespace mode for the container. | ||
| validate_certs 
                    boolean
                                                                 | 
 | 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_VERIFYwill be used instead. If the environment variable is not set, the default value will be used.aliases: tls_verify | |
| volume_driver 
                    string
                                                                 | The container volume driver. | ||
| volumes 
                    list
                     / elements=string                                             | List of volumes to mount within the container. Use docker CLI-style syntax:  /host:/container[:mode]Mount modes can be a comma-separated list of various modes such as  ro,rw,consistent,delegated,cached,rprivate,private,rshared,shared,rslave,slave, andnocopy. Note that the docker daemon might not support all modes and combinations of such modes.SELinux hosts can additionally use  zorZto use a shared or private label for the volume.Note that Ansible 2.7 and earlier only supported one mode, which had to be one of  ro,rw,z, andZ. | ||
| volumes_from 
                    list
                     / elements=string                                             | List of container names or IDs to get volumes from. | ||
| working_dir 
                    string
                                                                 added in 2.4 | Path to the working directory. | ||
Notes¶
Note
- For most config changes, the container needs to be recreated, i.e. 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. Please note that several options have default values; if the container to be restarted uses different values for these options, it will be recreated instead. The options with default values which can cause this are auto_remove, detach, init, interactive, memory, paused, privileged, read_only and tty.
- 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 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.
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
- name: Finer container restart/update control
  docker_container:
    name: test
    image: ubuntu:18.04
    env:
      arg1: "true"
      arg2: "whatever"
    volumes:
      - /tmp:/tmp
    comparisons:
      image: ignore   # don't 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
  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
  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
  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
  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
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
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)
- Felix Fontein (@felixfontein)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
