/ home / ansible / ansible.builtin / v2.3.3.0-1 / module / docker_container

ansible.builtin.docker_container (v2.3.3.0-1) — module

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 community

Install Ansible via `pip`

Install with pip install ansible==2.3.3.0.post1

Description

Manage the life cycle of docker containers.

Supports check mode. Run with --check and --diff to view config difference and list of actions to be taken.

Requirements

python >= 2.6
docker-py >= 1.7.0
Docker API >= 1.20

Usage examples

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

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

Inputs

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

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

Outputs

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

Install Ansible via pip

Description

Requirements

Usage examples

Inputs

Outputs

Install Ansible via `pip`