Documentation

docker - manage docker containers

New in version 1.4.

Synopsis

Manage the life cycle of docker containers.

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
                                                                                                      

                                                                                                      This is a Core Module

                                                                                                      For more information on what this means please read Core Modules

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