/ home / community / community.docker / 3.8.1 / module / docker_image_load

community.docker.docker_image_load (3.8.1) — module

Load docker image(s) from archives

| "added in version" 1.3.0 of community.docker"

Authors: Felix Fontein (@felixfontein)

Install collection

Install with ansible-galaxy collection install community.docker:==3.8.1

Add to requirements.yml

  collections:
    - name: community.docker
      version: 3.8.1

Description

Load one or multiple Docker images from a C(.tar) archive, and return information on the loaded image(s).

Requirements

Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with O(use_ssh_client=false))
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests

Usage examples

Scanned by Steampunk Spotter

- name: Load all image(s) from the given tar file
  community.docker.docker_image_load:
    path: /path/to/images.tar
  register: result

Scanned by Steampunk Spotter

- name: Print the loaded image names
  ansible.builtin.debug:
    msg: "Loaded the following images: {{ result.image_names | join(', ') }}"

Inputs

tls:
default: false
description:
- Secure the connection to the API by using TLS without verifying the authenticity
of the Docker host server. Note that if O(validate_certs) is set to V(true) as well,
it will take precedence.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS)
will be used instead. If the environment variable is not set, the default value
will be used.
type: bool

path:
description:
- The path to the C(.tar) archive to load Docker image(s) from.
required: true
type: path

debug:
default: false
description:
- Debug mode
type: bool

ca_path:
aliases:
- ca_cert
- tls_ca_cert
- cacert_path
description:
- 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 E(DOCKER_CERT_PATH)
is set, the file C(ca.pem) from the directory specified in the environment variable
E(DOCKER_CERT_PATH) will be used.
- This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker
3.6.0. The old name has been added as an alias and can still be used.
type: path

timeout:
default: 60
description:
- 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 E(DOCKER_TIMEOUT)
will be used instead. If the environment variable is not set, the default value
will be used.
type: int

client_key:
aliases:
- tls_client_key
- key_path
description:
- Path to the client's TLS key file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
is set, the file C(key.pem) from the directory specified in the environment variable
E(DOCKER_CERT_PATH) will be used.
type: path

api_version:
aliases:
- docker_api_version
default: auto
description:
- 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 E(DOCKER_API_VERSION)
will be used instead. If the environment variable is not set, the default value
will be used.
type: str

client_cert:
aliases:
- tls_client_cert
- cert_path
description:
- Path to the client's TLS certificate file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
is set, the file C(cert.pem) from the directory specified in the environment variable
E(DOCKER_CERT_PATH) will be used.
type: path

docker_host:
aliases:
- docker_url
default: unix:///var/run/docker.sock
description:
- 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, V(tcp://192.0.2.23:2376).
If TLS is used to encrypt the connection, the module will automatically replace
C(tcp) in the connection URL with C(https).
- If the value is not specified in the task, the value of environment variable E(DOCKER_HOST)
will be used instead. If the environment variable is not set, the default value
will be used.
type: str

ssl_version:
description:
- Provide a valid SSL version number. Default value determined by L(SSL Python module,
https://docs.python.org/3/library/ssl.html).
- If the value is not specified in the task, the value of environment variable E(DOCKER_SSL_VERSION)
will be used instead.
type: str

tls_hostname:
description:
- 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 E(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 V(localhost) in older versions. It was
removed in community.docker 3.0.0.
type: str

use_ssh_client:
default: false
description:
- For SSH transports, use the C(ssh) CLI tool instead of paramiko.
type: bool
version_added: 1.5.0
version_added_collection: community.docker

validate_certs:
aliases:
- tls_verify
default: false
description:
- 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 E(DOCKER_TLS_VERIFY)
will be used instead. If the environment variable is not set, the default value
will be used.
type: bool

Outputs

image_names:
  description: List of image names and IDs loaded from the archive.
  elements: str
  returned: success
  sample:
  - hello-world:latest
  - sha256:e004c2cc521c95383aebb1fb5893719aa7a8eae2e7a71f316a4410784edb00a9
  type: list
images:
  description: Image inspection results for the loaded images.
  elements: dict
  returned: success
  sample: []
  type: list