Documentation

docker_image - manage docker images

New in version 1.5.

Synopsis

Create, check and remove docker images

Requirements (on host that executes module)

  • python >= 2.6
  • docker-py
  • requests

Options

parameter required default choices comments
docker_api_version
(added in 2.0)
 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 docker host to issue commands to
      dockerfile
      (added in 2.0)
      		 no Dockerfile
        Dockerfile to use
        name
        		 yes
          Image name to work with
          nocache
          		 no
            Do not use cache with building
            path
            		 no
              Path to directory with Dockerfile
              state
              		 no present
              • present
              • absent
              • build
              Set the state of the image
              tag
              		 no latest
                Image tag to work with
                timeout
                		 no 600
                  Set image operation timeout
                  tls_ca_cert
                  (added in 2.0)
                  		 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 2.0)
                    		 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 2.0)
                      		 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 2.0)
                        		 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.
                          use_tls
                          (added in 2.0)
                          		 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.

                          Examples

                          Build docker image if required. Path should contains Dockerfile to build image:

- hosts: web
  become: yes
  tasks:
  - name: check or build image
    docker_image: path="/path/to/build/dir" name="my/app" state=present

Build new version of image:

- hosts: web
  become: yes
  tasks:
  - name: check or build image
    docker_image: path="/path/to/build/dir" name="my/app" state=build

Remove image from local docker storage:

- hosts: web
  become: yes
  tasks:
  - name: remove image
    docker_image: name="my/app" state=absent

                          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.