ansible / ansible.builtin / v2.6.0 / module / _docker
Removed in 2.4
Reason:Replaced by dedicated modules. | Alternative:Use M(docker_container) and M(docker_image) instead.
manage docker containers
| "added in version" 1.4 of ansible.builtin"
Authors: Cove Schneider (@cove), Joshua Conner (@joshuaconner), Pavel Antonov (@softzilla), Thomas Steinbach (@ThomasSteinbach), Philippe Jandot (@zfil), Daan Oosterveld (@dusdanig)
deprecated | supported by community
pip
Install with pip install ansible==2.6.0
This is the original Ansible module for managing the Docker container life cycle.
NOTE - Additional and newer modules are available. For the latest on orchestrating containers with Ansible visit our Getting Started with Docker Guide at U(https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/guide_docker.rst).
# Containers are matched either by name (if provided) or by an exact match of # the image they were launched with and the command they're running. The module # can accept either a name to target a container uniquely, or a count to operate # on multiple containers at once when it makes sense to do so. # Ensure that a data container with the name "mydata" exists. If no container # by this name exists, it will be created, but not started. - name: data container docker: name: mydata image: busybox state: present volumes: - /data
# Ensure that a Redis server is running, using the volume from the data # container. Expose the default Redis port. - name: redis container docker: name: myredis image: redis command: redis-server --appendonly yes state: started expose: - 6379 volumes_from: - mydata
# Ensure that a container of your application server is running. This will: # - pull the latest version of your application image from DockerHub. # - ensure that a container is running with the specified name and exact image. # If any configuration options have changed, the existing container will be # stopped and removed, and a new one will be launched in its place. # - link this container to the existing redis container launched above with # an alias. # - grant the container read write permissions for the host's /dev/sda device # through a node named /dev/xvda # - bind TCP port 9000 within the container to port 8080 on all interfaces # on the host. # - bind UDP port 9001 within the container to port 8081 on the host, only # listening on localhost. # - specify 2 ip resolutions. # - set the environment variable SECRET_KEY to "ssssh". - name: application container docker: name: myapplication image: someuser/appimage state: reloaded pull: always links: - "myredis:aliasedredis" devices: - "/dev/sda:/dev/xvda:rwm" ports: - "8080:9000" - "127.0.0.1:8081:9001/udp" extra_hosts: host1: "192.168.0.1" host2: "192.168.0.2" env: SECRET_KEY: ssssh
# Ensure that exactly five containers of another server are running with this # exact image and command. If fewer than five are running, more will be launched; # if more are running, the excess will be stopped. - name: load-balanced containers docker: state: reloaded count: 5 image: someuser/anotherappimage command: sleep 1d
# Unconditionally restart a service container. This may be useful within a # handler, for example. - name: application service docker: name: myservice image: someuser/serviceimage state: restarted
# Stop all containers running the specified image. - name: obsolete container docker: image: someuser/oldandbusted state: stopped
# Stop and remove a container with the specified name. - name: obsolete container docker: name: ohno image: someuser/oldandbusted state: absent
# Example Syslogging Output - name: myservice container docker: name: myservice image: someservice/someimage state: reloaded log_driver: syslog log_opt: syslog-address: tcp://my-syslog-server:514 syslog-facility: daemon syslog-tag: myservice
dns: description: - List of custom DNS servers for the container. env: description: - Pass a dict of environment variables to the container. net: default: 'no' description: - 'Network mode for the launched container: bridge, none, container:<name|id>' - or host. - Requires docker >= 0.11. type: bool version_added: '1.8' version_added_collection: ansible.builtin pid: description: - Set the PID namespace mode for the container (currently only supports 'host'). - Requires docker-py >= 1.0.0 and docker >= 1.5.0 version_added: '1.9' version_added_collection: ansible.builtin tty: default: 'no' description: - Allocate a pseudo-tty within the container. type: bool version_added: '1.6' version_added_collection: ansible.builtin name: description: - Name used to match and uniquely name launched containers. Explicit names are used to uniquely identify a single container or to link among containers. Mutually exclusive with a "count" other than "1". version_added: '1.5' version_added_collection: ansible.builtin pull: choices: - always - missing default: missing description: - Control when container images are updated from the C(docker_url) registry. - If C(missing), images will be pulled only when missing from the host; - if C(always), the registry will be checked for a newer version of the image each time the task executes. version_added: '1.9' version_added_collection: ansible.builtin count: default: 1 description: - Number of matching containers that should be in the desired state. email: description: - Remote API email. image: description: - Container image used to match and launch containers. required: true links: description: - List of other containers to link within this container with an optional. - 'alias. Use docker CLI-style syntax: C(redis:myredis).' version_added: '1.5' version_added_collection: ansible.builtin ports: description: - 'List containing private to public port mapping specification. Use docker ''CLI-style syntax: C(8000), C(9000:8000), or C(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. The container ports need to be exposed either in the Dockerfile or via the C(expose) option.' version_added: '1.5' version_added_collection: ansible.builtin state: choices: - absent - killed - present - reloaded - restarted - started - stopped default: started description: - Assert the container's desired state. "present" only asserts that the matching containers exist. "started" asserts that the matching containers both exist and are running, but takes no action if any configuration has changed. "reloaded" (added in Ansible 1.9) asserts that all matching containers are running and restarts any that have any images or configuration out of date. "restarted" unconditionally restarts (or starts) the matching containers. "stopped" and '"killed" stop and kill all matching containers. "absent" stops and then' removes any matching containers. detach: default: 'yes' description: - Enable detached mode to leave the container running in background. If disabled, fail unless the process exits cleanly. type: bool expose: description: - List of additional container ports to expose for port mappings or links. If the port is already exposed using EXPOSE in a Dockerfile, you don't need to expose it again. version_added: '1.5' version_added_collection: ansible.builtin labels: description: - Set container labels. - Requires docker >= 1.6 and docker-py >= 1.2.0. version_added: '2.1' version_added_collection: ansible.builtin signal: default: KILL description: - With the state "killed", you can alter the signal sent to the container. version_added: '2.0' version_added_collection: ansible.builtin cap_add: default: 'no' description: - Add capabilities for the container. - Requires docker-py >= 0.5.0. type: bool version_added: '2.0' version_added_collection: ansible.builtin command: description: - Command used to match and launch containers. cpu_set: description: - CPUs in which to allow execution. - Requires docker-py >= 0.6.0. version_added: '2.0' version_added_collection: ansible.builtin devices: description: - List of host devices to expose to container. version_added: '2.1' version_added_collection: ansible.builtin log_opt: description: - Additional options to pass to the logging driver selected above. See Docker `log-driver <https://docs.docker.com/reference/logging/overview/>` documentation for more information. Requires docker >=1.7.0. version_added: '2.0' version_added_collection: ansible.builtin timeout: default: 60 description: - Docker daemon response timeout in seconds. version_added: '2.1' version_added_collection: ansible.builtin ulimits: description: - ulimits, list ulimits with name, soft and optionally hard limit separated by colons. e.g. C(nofile:1024:2048) - Requires docker-py >= 1.2.0 and docker >= 1.6.0 version_added: '2.1' version_added_collection: ansible.builtin use_tls: choices: - encrypt - false - verify description: - Whether to use tls to connect to the docker server. "no" means not to use tls (and ignore any other tls related parameters). "encrypt" means to use tls to encrypt the connection to the server. "verify" means to also verify that the server's certificate is valid for the server (this both verifies the certificate against the CA and that the certificate was issued for that host. If this is unspecified, tls will only be used if one of the other tls options require it. version_added: '1.9' version_added_collection: ansible.builtin volumes: description: - List of volumes to mount within the container. - 'Use docker CLI-style syntax: C(/host:/container[:mode])' - You can specify a read mode for the mount with either C(ro) or C(rw). Starting at version 2.1, SELinux hosts can additionally use C(z) or C(Z) mount options to use a shared or private label for the volume. cap_drop: default: 'no' description: - Drop capabilities for the container. - Requires docker-py >= 0.5.0. type: bool version_added: '2.0' version_added_collection: ansible.builtin env_file: description: - Pass in a path to a file with environment variable (FOO=BAR). If a key value is present in both explicitly presented (i.e. as 'env') and in the environment file, the explicit value will override. Requires docker-py >= 1.4.0. version_added: '2.1' version_added_collection: ansible.builtin hostname: description: - Container hostname. lxc_conf: description: - LXC configuration parameters, such as C(lxc.aa_profile:unconfined). password: description: - Remote API password. registry: default: DockerHub description: - Remote registry URL to pull images from. version_added: '1.8' version_added_collection: ansible.builtin username: description: - Remote API username. read_only: description: - Mount the container's root filesystem as read only. version_added: '2.0' version_added_collection: ansible.builtin cpu_shares: default: 0 description: - CPU shares (relative weight). - Requires docker-py >= 0.6.0. version_added: '2.1' version_added_collection: ansible.builtin docker_url: default: ${DOCKER_HOST} or unix://var/run/docker.sock description: - URL of the host running the docker daemon. This will default to the env var DOCKER_HOST if unspecified. domainname: description: - Container domain name. entrypoint: description: - Corresponds to C(--entrypoint) option of C(docker run) command and C(ENTRYPOINT) directive of Dockerfile. - Used to match and launch containers. version_added: '2.1' version_added_collection: ansible.builtin log_driver: choices: - awslogs - fluentd - gelf - journald - json-file - none - syslog default: json-file description: - You can specify a different logging driver for the container than for the daemon. - C(awslogs) - (added in 2.1) Awslogs logging driver for Docker. Writes log messages to AWS Cloudwatch Logs. - C(fluentd) - Fluentd logging driver for Docker. Writes log messages to "fluentd" (forward input). - C(gelf) - Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash. - C(journald) - Journald logging driver for Docker. Writes log messages to "journald". - C(json-file) - Default logging driver for Docker. Writes JSON messages to file. docker logs command is available only for this logging driver. - C(none) - disables any logging for the container. - C(syslog) - Syslog logging driver for Docker. Writes log messages to syslog. docker logs command is not available for this logging driver. - Requires docker >= 1.6.0. version_added: '2.0' version_added_collection: ansible.builtin privileged: default: 'no' description: - Whether the container should run in privileged mode or not. type: bool stdin_open: default: 'no' description: - Keep stdin open after a container is launched. type: bool version_added: '1.6' version_added_collection: ansible.builtin docker_user: description: - Username or UID to use within the container version_added: '2.0' version_added_collection: ansible.builtin extra_hosts: description: - Dict of custom host-to-IP mappings to be defined in the container version_added: '2.0' version_added_collection: ansible.builtin tls_ca_cert: default: ${DOCKER_CERT_PATH}/ca.pem description: - Path to a PEM-encoded certificate authority to secure the Docker connection. This has no effect if use_tls is encrypt. version_added: '1.9' version_added_collection: ansible.builtin memory_limit: default: 0 description: - RAM allocated to the container as a number of bytes or as a human-readable string like "512MB". - Leave as "0" to specify no limit. stop_timeout: default: 10 description: - How many seconds to wait for the container to stop before killing it. version_added: '2.0' version_added_collection: ansible.builtin tls_hostname: default: Taken from docker_url description: - A hostname to check matches what's supplied in the docker server's certificate. If unspecified, the hostname is taken from the docker_url. version_added: '1.9' version_added_collection: ansible.builtin volumes_from: description: - List of names of containers to mount volumes from. restart_policy: choices: - always - false - on-failure - unless-stopped description: - Container restart policy. - The 'unless-stopped' choice is only available starting in Ansible 2.1 and for Docker 1.9 and above. version_added: '1.9' version_added_collection: ansible.builtin tls_client_key: default: ${DOCKER_CERT_PATH}/key.pem description: - Path to the PEM-encoded key used to authenticate docker client. If specified tls_client_cert must be valid version_added: '1.9' version_added_collection: ansible.builtin tls_client_cert: default: ${DOCKER_CERT_PATH}/cert.pem description: - Path to the PEM-encoded certificate used to authenticate docker client. If specified tls_client_key must be valid version_added: '1.9' version_added_collection: ansible.builtin insecure_registry: default: 'no' description: - Use insecure private registry by HTTP instead of HTTPS. - Needed for docker-py >= 0.5.0. type: bool version_added: '1.9' version_added_collection: ansible.builtin publish_all_ports: default: 'no' description: - Publish all exposed ports to the host interfaces. type: bool version_added: '1.5' version_added_collection: ansible.builtin docker_api_version: default: docker-py default remote API version description: - Remote API version to use. This defaults to the current default as specified by docker-py. version_added: '1.8' version_added_collection: ansible.builtin restart_policy_retry: default: 0 description: - Maximum number of times to restart a container. - Leave as "0" for unlimited retries. version_added: '1.9' version_added_collection: ansible.builtin