+ + +
+ +
+

community.docker.docker_image_pull module – Pull Docker images from registries

+
+

Note

+

This module is part of the community.docker collection (version 3.6.0).

+

It is not included in ansible-core. +To check whether it is installed, run ansible-galaxy collection list.

+

To install it, use: ansible-galaxy collection install community.docker. +You need further requirements to be able to use this module, +see Requirements for details.

+

To use it in a playbook, specify: community.docker.docker_image_pull.

+
+

New in community.docker 3.6.0

+ +
+

Synopsis

+
    +

  • Pulls a Docker image from a registry.

    • +
+
+
+

Requirements

+

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

+
    +

  • Docker API >= 1.25

    • +

  • backports.ssl_match_hostname (when using TLS on Python 2)

    • +

  • paramiko (when using SSH with use_ssh_client=false)

    • +

  • pyOpenSSL (when using TLS)

    • +

  • pywin32 (when using named pipes on Windows 32)

    • +

  • requests

    • +
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

api_version

+

aliases: docker_api_version

+

string

+

The version of the Docker API running on the Docker Host.

+

Defaults to the latest version of the API supported by this collection and the docker daemon.

+

If the value is not specified in the task, the value of environment variable DOCKER_API_VERSION will be used instead. If the environment variable is not set, the default value will be used.

+

Default: "auto"

+
+
+
+

ca_cert

+

aliases: tls_ca_cert, cacert_path

+

path

+

Use a CA certificate when performing server verification by providing the path to a CA certificate file.

+

If the value is not specified in the task and the environment variable DOCKER_CERT_PATH is set, the file ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.

+
+
+
+

client_cert

+

aliases: tls_client_cert, cert_path

+

path

+

Path to the client’s TLS certificate file.

+

If the value is not specified in the task and the environment variable DOCKER_CERT_PATH is set, the file cert.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.

+
+
+
+

client_key

+

aliases: tls_client_key, key_path

+

path

+

Path to the client’s TLS key file.

+

If the value is not specified in the task and the environment variable DOCKER_CERT_PATH is set, the file key.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.

+
+

debug

+

boolean

+

Debug mode

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+
+

docker_host

+

aliases: docker_url

+

string

+

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.

+

If the value is not specified in the task, the value of environment variable DOCKER_HOST will be used instead. If the environment variable is not set, the default value will be used.

+

Default: "unix://var/run/docker.sock"

+
+

name

+

string / required

+

Image name. Name format must be one of name, repository/name, or registry_server:port/name. - The name can optionally include the tag by appending :tag_name, or it can contain a digest by appending @hash:digest.

+
+

platform

+

string

+

Ask for this specific platform when pulling.

+
+

pull

+

string

+

Determines when to pull an image.

+

If always, will always pull the image.

+

If not_present, will only pull the image if no image of the name exists on the current Docker daemon, or if platform does not match.

+

Choices:

+
    +

  • "always" ← (default)

    • +

  • "not_present"

    • +
+
+

ssl_version

+

string

+

Provide a valid SSL version number. Default value determined by SSL Python module.

+

If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.

+
+

tag

+

string

+

Used to select an image when pulling. Defaults to latest.

+

If name parameter format is name:tag or image@hash:digest, then tag will be ignored.

+

Default: "latest"

+
+

timeout

+

integer

+

The maximum amount of time in seconds to wait on a response from the API.

+

If the value is not specified in the task, the value of environment variable DOCKER_TIMEOUT will be used instead. If the environment variable is not set, the default value will be used.

+

Default: 60

+
+

tls

+

boolean

+

Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if validate_certs is set to true as well, it will take precedence.

+

If the value is not specified in the task, the value of environment variable DOCKER_TLS will be used instead. If the environment variable is not set, the default value will be used.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

tls_hostname

+

string

+

When verifying the authenticity of the Docker Host server, provide the expected name of the server.

+

If the value is not specified in the task, the value of environment variable DOCKER_TLS_HOSTNAME will be used instead. If the environment variable is not set, the default value will be used.

+

Note that this option had a default value localhost in older versions. It was removed in community.docker 3.0.0.

+
+

use_ssh_client

+

boolean

+

added in community.docker 1.5.0

+

For SSH transports, use the ssh CLI tool instead of paramiko.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+
+

validate_certs

+

aliases: tls_verify

+

boolean

+

Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.

+

If the value is not specified in the task, the value of environment variable DOCKER_TLS_VERIFY will be used instead. If the environment variable is not set, the default value will be used.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+
+
+

Attributes

+ + + + + + + + + + + + + + + + + + + + + +

Attribute

Support

Description

+

action_group

+

Action groups: community.docker.docker, docker

+

Use group/docker or group/community.docker.docker in module_defaults to set defaults for this module.

+
+

check_mode

+

Support: partial

+

When trying to pull an image with pull=always, the module assumes this is always changed in check mode.

+

When check mode is combined with diff mode, the pulled image’s ID is always shown as unknown in the diff.

+

Can run in check_mode and return changed status prediction without modifying target.

+
+

diff_mode

+

Support: full

+

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

+
+
+
+

Notes

+
+

Note

+ +
+
+
+

Examples

+
- name: Pull an image
+  community.docker.docker_image_pull:
+    name: pacur/centos-7
+    # Select platform for pulling. If not specified, will pull whatever docker prefers.
+    platform: amd64
+
+
+
+
+

Return Values

+

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

+ + + + + + + + + + + +

Key

Description

+

image

+

dictionary

+

Image inspection results for the affected image.

+

Returned: success

+

Sample: {}

+
+
+

Authors

+
    +

  • Felix Fontein (@felixfontein)

    • +
+
+ +
+
+ + +
+