ansible / ansible.builtin / v2.3.3.0-1 / module / docker_container manage docker containers | "added in version" 2.1 of ansible.builtin" Authors: Cove Schneider (@cove), Joshua Conner (@joshuaconner), Pavel Antonov (@softzilla), Thomas Steinbach (@ThomasSteinbach), Philippe Jandot (@zfil), Daan Oosterveld (@dusdanig), James Tanner (@jctanner), Chris Houseknecht (@chouseknecht) preview | supported by communityansible.builtin.docker_container (v2.3.3.0-1) — module
pip
Install with pip install ansible==2.3.3.0.post1
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.
- 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
- 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
env: default: null description: - Dictionary of key,value pairs. required: false tls: default: false description: - Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if I(validate_certs) is set to C(yes) as well, it will take precedence. - If the value is not specified in the task, the value of environment variable C(DOCKER_TLS) will be used instead. If the environment variable is not set, the default value will be used. type: bool tty: default: false description: - Allocate a psuedo-TTY. required: false uts: default: null description: - Set the UTS namespace mode for the container. required: false name: description: - 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. required: true pull: default: false description: - If true, always pull the latest version of an image. Otherwise, will only pull an image when missing. required: false user: default: null description: - 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 ] required: false debug: default: false description: - Debug mode type: bool image: default: null description: - 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. required: false links: default: null description: - List of name aliases for linked containers in the format C(container_name:alias) required: false state: choices: - absent - present - stopped - started default: started description: - I(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. - I(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. - I(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. - I(stopped) - Asserts that the container is first I(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. required: false detach: default: true description: - 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). required: false groups: default: null description: - List of additional group names and/or IDs that the container process will run as. required: false labels: default: null description: - Dictionary of key value pairs. required: false memory: default: 0 description: - 'Memory limit (format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g' required: false paused: default: false description: - Use with the started state to pause running processes inside the container. required: false ca_cert: aliases: - tls_ca_cert - cacert_path description: - 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 C(DOCKER_CERT_PATH) is set, the file C(ca.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used. type: path cleanup: default: false description: - Use with I(detach) to remove the container after successful execution. required: false version_added: '2.2' version_added_collection: ansible.builtin command: default: null description: - Command to execute when the container starts. required: false devices: default: null description: - '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>' required: false restart: default: false description: - Use with started state to force a matching container to be stopped and restarted. required: false timeout: default: 60 description: - 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 C(DOCKER_TIMEOUT) will be used instead. If the environment variable is not set, the default value will be used. type: int ulimits: default: null description: - List of ulimit options. A ulimit is specified as C(nofile:262144:262144) required: false volumes: default: null 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). - SELinux hosts can additionally use C(z) or C(Z) to use a shared or private label for the volume. required: false env_file: default: null description: - Path to a file containing environment variables I(FOO=BAR). - If variable also present in C(env), then C(env) value will override. - Requires docker-py >= 1.4.0. required: false version_added: '2.2' version_added_collection: ansible.builtin hostname: default: null description: - Container hostname. required: false ipc_mode: default: null description: - 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. required: false networks: default: null description: - List of networks the container belongs to. - Each network is a dict with keys C(name), C(ipv4_address), C(ipv6_address), C(links), C(aliases). - For each network C(name) is required, all other keys are optional. - If included, C(links) or C(aliases) are lists. - For examples of the data structure and usage see EXAMPLES below. - To remove a container from one or more networks, use the C(purge_networks) option. required: false version_added: '2.2' version_added_collection: ansible.builtin pid_mode: default: null description: - Set the PID namespace mode for the container. Currently only supports 'host'. required: false recreate: default: false description: - Use with present and started states to force the re-creation of an existing container. required: false shm_size: default: null description: - Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). - Omitting the unit defaults to bytes. If you omit the size entirely, the system uses `64m`. required: false cpu_quota: default: 0 description: - Limit CPU CFS (Completely Fair Scheduler) quota required: false etc_hosts: default: null description: - 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. required: false read_only: default: false description: - Mount the container's root file system as read-only. required: false client_key: aliases: - tls_client_key - key_path description: - Path to the client's TLS key file. - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set, the file C(key.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used. type: path cpu_period: default: 0 description: - Limit CPU CFS (Completely Fair Scheduler) period required: false cpu_shares: default: null description: - CPU shares (relative weight). required: false entrypoint: default: null description: - Command that overwrites the default ENTRYPOINT of the image. required: false force_kill: default: false description: - Use the kill command when stopping a running container. required: false log_driver: choices: - none - json-file - syslog - journald - gelf - fluentd - awslogs - splunk default: null description: - Specify the logging driver. Docker uses json-file by default. required: false oom_killer: default: false description: - Whether or not to disable OOM Killer for the container. required: false privileged: default: false description: - Give extended privileges to the container. required: false api_version: aliases: - docker_api_version default: auto description: - 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 C(DOCKER_API_VERSION) will be used instead. If the environment variable is not set, the default value will be used. type: str client_cert: aliases: - tls_client_cert - cert_path description: - Path to the client's TLS certificate file. - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set, the file C(cert.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used. type: path cpuset_cpus: default: null description: - CPUs in which to allow execution C(1,3) or C(1-3). required: false cpuset_mems: default: null description: - Memory nodes (MEMs) in which to allow execution C(0-3) or C(0,1) required: false dns_servers: default: null description: - List of custom DNS servers. required: false docker_host: aliases: - docker_url default: unix://var/run/docker.sock description: - 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, C(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection, the module will automatically replace C(tcp) in the connection URL with C(https). - If the value is not specified in the task, the value of environment variable C(DOCKER_HOST) will be used instead. If the environment variable is not set, the default value will be used. type: str interactive: default: false description: - Keep stdin open after a container is launched, even if not attached. required: false kill_signal: default: null description: - Override default signal used to kill a running container. required: false log_options: default: null description: - Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/ for details. required: false mac_address: default: null description: - Container MAC address (e.g. 92:d0:c6:0a:29:33) required: false memory_swap: default: 0 description: - Total memory limit (memory + swap, format:<number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g. required: false ssl_version: description: - 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 C(DOCKER_SSL_VERSION) will be used instead. type: str stop_signal: default: null description: - Override default signal used to stop the container. required: false blkio_weight: default: null description: - Block IO (relative weight), between 10 and 1000. required: false capabilities: default: null description: - List of capabilities to add to the container. required: false ignore_image: default: false description: - When C(state) is I(present) or I(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 C(ignore_image) to I(True). required: false version_added: '2.2' version_added_collection: ansible.builtin keep_volumes: default: true description: - Retain volumes associated with a removed container. required: false network_mode: choices: - bridge - container:<name|id> - host - none default: null description: - Connect the container to a network. required: false stop_timeout: default: null description: - Number of seconds to wait for the container to stop before sending SIGKILL. required: false tls_hostname: description: - 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 C(DOCKER_TLS_HOSTNAME) will be used instead. If the environment variable is not set, the default value will be used. - The current default value is C(localhost). This default is deprecated and will change in community.docker 2.0.0 to be a value computed from I(docker_host). Explicitly specify C(localhost) to make sure this value will still be used, and to disable the deprecation message which will be shown otherwise. type: str volumes_from: default: null description: - List of container names or Ids to get volumes from. required: false exposed_ports: aliases: - exposed default: null description: - 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. required: false kernel_memory: default: 0 description: - 'Kernel memory limit (format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g. Minimum is 4M.' required: false oom_score_adj: default: 0 description: - An integer value containing the score given to the container in order to tune OOM killer preferences. required: false version_added: '2.2' version_added_collection: ansible.builtin security_opts: default: null description: - List of security options in the form of C("label:user:User") required: false volume_driver: default: none description: - The container volume driver. required: false purge_networks: default: false description: - Remove the container from ALL networks not included in C(networks) parameter. - Any default networks such as I(bridge), if not found in C(networks), will be removed as well. required: false version_added: '2.2' version_added_collection: ansible.builtin restart_policy: choices: - always - false - on-failure - unless-stopped default: on-failure description: - Container restart policy. Place quotes around I(no) option. required: false use_ssh_client: default: false description: - For SSH transports, use the C(ssh) CLI tool instead of paramiko. - Requires Docker SDK for Python 4.4.0 or newer. type: bool version_added: 1.5.0 version_added_collection: community.docker validate_certs: aliases: - tls_verify default: false description: - 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 C(DOCKER_TLS_VERIFY) will be used instead. If the environment variable is not set, the default value will be used. type: bool published_ports: aliases: - ports default: null description: - List of ports to publish from the container to the host. - 'Use docker CLI 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.' - Container ports must be exposed either in the Dockerfile or via the C(expose) option. - A value of all will publish all exposed container ports to random host ports, ignoring any other mappings. - If C(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 C(networks) is the one that will be used. required: false restart_retries: default: 0 description: - Use with restart policy to control maximum number of restart attempts. required: false memory_swappiness: default: 0 description: - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. required: false dns_search_domains: default: null description: - List of custom DNS search domains. required: false memory_reservation: default: 0 description: - 'Memory soft limit (format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g' required: false trust_image_content: default: false description: - If true, skip image verification. required: false
docker_container: description: - 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 C(state) is I(absent) - If detached is I(False), will include Output attribute containing any output from container run. returned: always 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/": {} }, ... }' type: dict