Documentation

docker - manage docker containers

New in version 1.4.

DEPRECATED

In 2.2 use docker_container and docker_image instead.

Synopsis

Requirements (on host that executes module)

  • python >= 2.6
  • docker-py >= 0.3.0
  • The docker server >= 0.10.0

Options

parameter required default choices comments
cap_add
(added in 2.0)
no
Add capabilities for the container. Requires docker-py >= 0.5.0.
cap_drop
(added in 2.0)
no
Drop capabilities for the container. Requires docker-py >= 0.5.0.
command
no
Command used to match and launch containers.
count
no 1
Number of matching containers that should be in the desired state.
cpu_set
(added in 2.0)
no
CPUs in which to allow execution. Requires docker-py >= 0.6.0.
cpu_shares
(added in 2.1)
no
CPU shares (relative weight). Requires docker-py >= 0.6.0.
detach
no True
Enable detached mode to leave the container running in background. If disabled, fail unless the process exits cleanly.
devices
(added in 2.1)
no
List of host devices to expose to container
dns
no
List of custom DNS servers for the container.
docker_api_version
(added in 1.8)
no docker-py default remote API version
Remote API version to use. This defaults to the current default as specified by docker-py.
docker_url
no ${DOCKER_HOST} or unix://var/run/docker.sock
URL of the host running the docker daemon. This will default to the env var DOCKER_HOST if unspecified.
docker_user
(added in 2.0)
no
Username or UID to use within the container
domainname
no
Container domain name.
email
no
Remote API email.
entrypoint
(added in 2.1)
no
Corresponds to ``--entrypoint`` option of ``docker run`` command and ``ENTRYPOINT`` directive of Dockerfile. Used to match and launch containers.
env
no
Pass a dict of environment variables to the container.
env_file
(added in 2.1)
no
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.
expose
(added in 1.5)
no
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.
extra_hosts
(added in 2.0)
no
Dict of custom host-to-IP mappings to be defined in the container
hostname
no
Container hostname.
image
yes
Container image used to match and launch containers.
insecure_registry
(added in 1.9)
no
Use insecure private registry by HTTP instead of HTTPS. Needed for docker-py >= 0.5.0.
labels
(added in 2.1)
no
Set container labels. Requires docker >= 1.6 and docker-py >= 1.2.0.
links
(added in 1.5)
no
List of other containers to link within this container with an optional
alias. Use docker CLI-style syntax: redis:myredis.
log_driver
(added in 2.0)
no json-file
  • json-file
  • none
  • syslog
  • journald
  • gelf
  • fluentd
  • awslogs
You can specify a different logging driver for the container than for the daemon. "json-file" Default logging driver for Docker. Writes JSON messages to file. docker logs command is available only for this logging driver. "none" disables any logging for the container. "syslog" Syslog logging driver for Docker. Writes log messages to syslog. docker logs command is not available for this logging driver. "journald" Journald logging driver for Docker. Writes log messages to "journald". "gelf" Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash. "fluentd" Fluentd logging driver for Docker. Writes log messages to "fluentd" (forward input). "awslogs" (added in 2.1) Awslogs logging driver for Docker. Writes log messages to AWS Cloudwatch Logs. If not defined explicitly, the Docker daemon's default ("json-file") will apply. Requires docker >= 1.6.0.
log_opt
(added in 2.0)
no
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.
lxc_conf
no
LXC configuration parameters, such as lxc.aa_profile:unconfined.
memory_limit
no
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.
name
(added in 1.5)
no
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".
net
(added in 1.8)
no
Network mode for the launched container: bridge, none, container:<name|id>
or host. Requires docker >= 0.11.
password
no
Remote API password.
pid
(added in 1.9)
no None
Set the PID namespace mode for the container (currently only supports 'host'). Requires docker-py >= 1.0.0 and docker >= 1.5.0
ports
(added in 1.5)
no
List containing private to public port mapping specification. Use docker 'CLI-style syntax: 8000, 9000:8000, or 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 expose option.
privileged
no
Whether the container should run in privileged mode or not.
publish_all_ports
(added in 1.5)
no
Publish all exposed ports to the host interfaces.
pull
(added in 1.9)
no missing
  • missing
  • always
Control when container images are updated from the docker_url registry. If "missing," images will be pulled only when missing from the host; if '"always," the registry will be checked for a newer version of the image' each time the task executes.
read_only
(added in 2.0)
no
Mount the container's root filesystem as read only
registry
(added in 1.8)
no DockerHub
Remote registry URL to pull images from.
restart_policy
(added in 1.9)
no
  • no
  • on-failure
  • always
  • unless-stopped
Container restart policy.
The 'unless-stopped' choice is only available starting in Ansible 2.1 and for Docker 1.9 and above.
restart_policy_retry
(added in 1.9)
no
Maximum number of times to restart a container. Leave as "0" for unlimited retries.
signal
(added in 2.0)
no KILL
With the state "killed", you can alter the signal sent to the container.
state
no started
  • present
  • started
  • reloaded
  • restarted
  • stopped
  • killed
  • absent
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.
stdin_open
(added in 1.6)
no
Keep stdin open after a container is launched.
stop_timeout
(added in 2.0)
no 10
How many seconds to wait for the container to stop before killing it.
timeout
(added in 2.1)
no 60
Docker daemon response timeout in seconds.
tls_ca_cert
(added in 1.9)
no ${DOCKER_CERT_PATH}/ca.pem
Path to a PEM-encoded certificate authority to secure the Docker connection. This has no effect if use_tls is encrypt.
tls_client_cert
(added in 1.9)
no ${DOCKER_CERT_PATH}/cert.pem
Path to the PEM-encoded certificate used to authenticate docker client. If specified tls_client_key must be valid
tls_client_key
(added in 1.9)
no ${DOCKER_CERT_PATH}/key.pem
Path to the PEM-encoded key used to authenticate docker client. If specified tls_client_cert must be valid
tls_hostname
(added in 1.9)
no Taken from docker_url
A hostname to check matches what's supplied in the docker server's certificate. If unspecified, the hostname is taken from the docker_url.
tty
(added in 1.6)
no
Allocate a pseudo-tty within the container.
ulimits
(added in 2.1)
no
ulimits, list ulimits with name, soft and optionally hard limit separated by colons. e.g. nofile:1024:2048 Requires docker-py >= 1.2.0 and docker >= 1.6.0
use_tls
(added in 1.9)
no
  • no
  • encrypt
  • verify
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.
username
no
Remote API username.
volumes
no
List of volumes to mount within the container
Use docker CLI-style syntax: /host:/container[:mode]
You can specify a read mode for the mount with either ro or rw. Starting at version 2.1, SELinux hosts can additionally use z or Z mount options to use a shared or private label for the volume.
volumes_from
no
List of names of containers to mount volumes from.

Examples

# 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

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.