Documentation

docker_container - manage docker containers

New in version 2.1.

Synopsis

  • 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 (on host that executes module)

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

Options

parameter required default choices comments
api_version
no default provided by docker-py
The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by docker-py.

aliases: docker_api_version
blkio_weight
no
Block IO (relative weight), between 10 and 1000.
cacert_path
no
Use a CA certificate when performing server verification by providing the path to a CA certificate file.

aliases: tls_ca_cert
capabilities
no
List of capabilities to add to the container.
cert_path
no
Path to the client's TLS certificate file.

aliases: tls_client_cert
cleanup
(added in 2.2)
no
Use with detach to remove the container after successful execution.
command
no
Command to execute when the container starts.
cpu_period
no
Limit CPU CFS (Completely Fair Scheduler) period
cpu_quota
no
Limit CPU CFS (Completely Fair Scheduler) quota
cpu_shares
no
CPU shares (relative weight).
cpuset_cpus
no
CPUs in which to allow execution 1,3 or 1-3.
cpuset_mems
no
Memory nodes (MEMs) in which to allow execution 0-3 or 0,1
detach
no True
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).
devices
no
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_search_domains
no
List of custom DNS search domains.
dns_servers
no
List of custom DNS servers.
docker_host
no 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 replace 'tcp' in the connection URL with 'https'.

aliases: docker_url
entrypoint
no
Command that overwrites the default ENTRYPOINT of the image.
env
no
Dictionary of key,value pairs.
env_file
(added in 2.2)
no
Path to a file containing environment variables FOO=BAR.
If variable also present in env, then env value will override.
Requires docker-py >= 1.4.0.
etc_hosts
no
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.
exposed_ports
no
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.

aliases: exposed
force_kill
no
Use the kill command when stopping a running container.
groups
no
List of additional group names and/or IDs that the container process will run as.
hostname
no
Container hostname.
ignore_image
(added in 2.2)
no
When state is present or 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 ignore_image to True.
image
no
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.
interactive
no
Keep stdin open after a container is launched, even if not attached.
ipc_mode
no
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.
keep_volumes
no True
Retain volumes associated with a removed container.
kernel_memory
no
Kernel memory limit (format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g. Minimum is 4M.
key_path
no
Path to the client's TLS key file.

aliases: tls_client_key
kill_signal
no
Override default signal used to kill a running container.
labels
no
Dictionary of key value pairs.
links
no
List of name aliases for linked containers in the format container_name:alias
log_driver
no
  • none
  • json-file
  • syslog
  • journald
  • gelf
  • fluentd
  • awslogs
  • splunk
Specify the logging driver. Docker uses json-file by default.
log_options
no
Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/ for details.
mac_address
no
Container MAC address (e.g. 92:d0:c6:0a:29:33)
memory
no
Memory limit (format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g
memory_reservation
no
Memory soft limit (format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g
memory_swap
no
Total memory limit (memory + swap, format:<number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g.
memory_swappiness
no
Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
name
yes
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
no
  • bridge
  • container:
  • host
  • none
Connect the container to a network.
networks
(added in 2.2)
no
List of networks the container belongs to.
Each network is a dict with keys name, ipv4_address, ipv6_address, links, aliases.
For each network name is required, all other keys are optional.
If included, links or 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 purge_networks option.
oom_killer
no
Whether or not to disable OOM Killer for the container.
oom_score_adj
(added in 2.2)
no
An integer value containing the score given to the container in order to tune OOM killer preferences.
paused
no
Use with the started state to pause running processes inside the container.
pid_mode
no
Set the PID namespace mode for the container. Currently only supports 'host'.
privileged
no
Give extended privileges to the container.
published_ports
no
List of ports to publish from the container to the host.
Use docker CLI 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.
Container ports must be exposed either in the Dockerfile or via the expose option.
A value of all will 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 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 networks is the one that will be used.

aliases: ports
pull
no
If true, always pull the latest version of an image. Otherwise, will only pull an image when missing.
purge_networks
(added in 2.2)
no
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
no
Mount the container's root file system as read-only.
recreate
no
Use with present and started states to force the re-creation of an existing container.
restart
no
Use with started state to force a matching container to be stopped and restarted.
restart_policy
no on-failure
  • always
  • False
  • on-failure
  • unless-stopped
Container restart policy. Place quotes around no option.
restart_retries
no
Use with restart policy to control maximum number of restart attempts.
security_opts
no
List of security options in the form of "label:user:User"
shm_size
no
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`.
ssl_version
no 1.0
Provide a valid SSL version number. Default value determined by docker-py, currently 1.0.
state
no started
  • absent
  • present
  • stopped
  • started
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.
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.
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.
stopped - Asserts that the container is first 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.
stop_signal
no
Override default signal used to stop the container.
stop_timeout
no
Number of seconds to wait for the container to stop before sending SIGKILL.
timeout
no 60
The maximum amount of time in seconds to wait on a response from the API.
tls
no
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server.
tls_hostname
no localhost
When verifying the authenticity of the Docker Host server, provide the expected name of the server.
tls_verify
no
Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
trust_image_content
no
If true, skip image verification.
tty
no
Allocate a pseudo-TTY.
ulimits
no
List of ulimit options. A ulimit is specified as nofile:262144:262144
user
no
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 ]
uts
no
Set the UTS namespace mode for the container.
volume_driver
no none
The container volume driver.
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.
SELinux hosts can additionally use z or Z to use a shared or private label for the volume.
volumes_from
no
List of container names or Ids to get volumes from.

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

- 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

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name description returned type sample
docker_container ["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.'] always dict { "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/": {} }, ... }


Notes

Note

  • 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_VERIFY and DOCKER_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://docker-py.readthedocs.org/en/stable/machine/ for more details.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Support

This module is community maintained without core committer oversight.

For more information on what this means please read Module Support

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