docker_image_facts - Inspect docker images

New in version 2.1.0.

Synopsis

  • Provide one or more image names, and the module will inspect each, returning an array of inspection results.

Requirements

The below requirements are needed on the host that executes this module.

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

Parameters

Parameter Choices/Defaults Comments
api_version Default:
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
cacert_path Default:
None
Use a CA certificate when performing server verification by providing the path to a CA certificate file.

aliases: tls_ca_cert
cert_path Default:
None
Path to the client's TLS certificate file.

aliases: tls_client_cert
docker_host Default:
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
key_path Default:
None
Path to the client's TLS key file.

aliases: tls_client_key
name
required
 Default:
None
An image name or a list of image names. Name format will be name[:tag] or repository/name[:tag], where tag is optional. If a tag is not provided, 'latest' will be used.
ssl_version Default:
1.0
Provide a valid SSL version number. Default value determined by docker-py, currently 1.0.
timeout Default:
60
The maximum amount of time in seconds to wait on a response from the API.
tls Default:
no
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server.
tls_hostname Default:
localhost
When verifying the authenticity of the Docker Host server, provide the expected name of the server.
tls_verify Default:
no
Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.

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.

Examples

- name: Inspect a single image
  docker_image_facts:
    name: pacur/centos-7

- name: Inspect multiple images
  docker_image_facts:
    name:
      - pacur/centos-7
      - sinatra

Return Values

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

Key Returned Description
images
dict
 always
Facts for the selected images.

Sample:
[{'Container': 'e83a452b8fb89d78a25a6739457050131ca5c863629a47639530d9ad2008d610', 'Name': 'registry:2', 'Author': '', 'GraphDriver': {'Data': None, 'Name': 'aufs'}, 'Architecture': 'amd64', 'VirtualSize': 165808884, 'ContainerConfig': {'Cmd': ['/bin/sh', '-c', '#(nop) CMD ["/etc/docker/registry/config.yml"]'], 'Env': ['PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'], 'StdinOnce': False, 'Hostname': 'e5c68db50333', 'WorkingDir': '', 'Entrypoint': ['/bin/registry'], 'Volumes': {'/var/lib/registry': {}}, 'OnBuild': [], 'OpenStdin': False, 'Tty': False, 'Domainname': '', 'Image': 'c72dce2618dc8f7b794d2b2c2b1e64e0205ead5befc294f8111da23bd6a2c799', 'Labels': {}, 'ExposedPorts': {'5000/tcp': {}}, 'User': '', 'AttachStdin': False, 'AttachStderr': False, 'AttachStdout': False}, 'Os': 'linux', 'RepoTags': ['registry:2'], 'Comment': '', 'DockerVersion': '1.9.1', 'Parent': 'f0b1f729f784b755e7bf9c8c2e65d8a0a35a533769c2588f02895f6781ac0805', 'Config': {'Cmd': ['/etc/docker/registry/config.yml'], 'Env': ['PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'], 'StdinOnce': False, 'Hostname': 'e5c68db50333', 'WorkingDir': '', 'Entrypoint': ['/bin/registry'], 'Volumes': {'/var/lib/registry': {}}, 'OnBuild': [], 'OpenStdin': False, 'Tty': False, 'Domainname': '', 'Image': 'c72dce2618dc8f7b794d2b2c2b1e64e0205ead5befc294f8111da23bd6a2c799', 'Labels': {}, 'ExposedPorts': {'5000/tcp': {}}, 'User': '', 'AttachStdin': False, 'AttachStderr': False, 'AttachStdout': False}, 'Created': '2016-03-08T21:08:15.399680378Z', 'RepoDigests': [], 'Id': '53773d8552f07b730f3e19979e32499519807d67b344141d965463a950a66e08', 'Size': 0}]


Status

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

Author

  • Chris Houseknecht (@chouseknecht)
  • James Tanner (@jctanner)

Hint

If you notice any issues in this documentation you can edit this document to improve it.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.5/modules/docker_image_facts_module.html