+ + +
+ +
+

community.docker.docker_compose_v2_pull module – Pull a Docker compose project

+
+

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_compose_v2_pull.

+
+

New in community.docker 3.6.0

+ +
+

Synopsis

+
    +

  • Uses Docker Compose to pull images for a project.

    • +
+
+
+

Requirements

+

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

+
    +

  • Docker CLI with Docker compose plugin 2.18.0 or later

    • +
+
+
+

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_path

+

aliases: ca_cert, 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.

+
+

cli_context

+

string

+

The Docker CLI context to use.

+
+
+
+

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.

+
+

docker_cli

+

path

+

Path to the Docker CLI. If not provided, will search for Docker CLI on the PATH.

+
+
+

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"

+
+

env_files

+

list / elements=path

+

By default environment files are loaded from a .env file located directly under the project_src directory.

+

env_files can be used to specify the path of one or multiple custom environment files instead.

+

The path is relative to the project_src directory.

+
+

policy

+

string

+

Whether to pull images before running. This is used when docker compose up is ran.

+

always ensures that the images are always pulled, even when already present on the Docker daemon.

+

missing only pulls them when they are not present on the Docker daemon. This is only supported since Docker Compose 2.22.0.

+

Choices:

+
    +

  • "always" ← (default)

    • +

  • "missing"

    • +
+
+

profiles

+

list / elements=string

+

List of profiles to enable when starting services.

+

Equivalent to docker compose --profile.

+
+

project_name

+

string

+

Provide a project name. If not provided, the project name is taken from the basename of project_src.

+
+

project_src

+

path / required

+

Path to a directory containing a docker-compose.yml or docker-compose.yaml file.

+
+

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.

+
+
+

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: full

+

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

+
+

diff_mode

+

Support: none

+

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

+
+
+
+

Notes

+
+

Note

+
    +

  • The Docker compose CLI plugin has no stable output format (see for example https://github.com/docker/compose/issues/10872), +and for the main operations also no machine friendly output format. The module tries to accomodate this with various +version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin.

    +

    Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions +will change over time. New releases of the Docker compose CLI plugin can break this module at any time.

    +
    • +

  • 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_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://docs.docker.com/machine/reference/env/ for more details.

    • +

  • This module does not use the Docker SDK for Python to communicate with the Docker daemon. It directly calls the Docker CLI program.

    • +
+
+
+
+

See Also

+
+

See also

+
+
community.docker.docker_compose

Manage multi-container Docker applications with Docker Compose V1.

+
+
+
+
+
+

Examples

+
# Examples use the django example at https://docs.docker.com/compose/django. Follow it to create the
+# flask directory
+
+- name: Run using a project directory
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Tear down existing services
+      community.docker.docker_compose_v2:
+        project_src: flask
+        state: absent
+
+    - name: Create and start services
+      community.docker.docker_compose_v2:
+        project_src: flask
+      register: output
+
+    - name: Show results
+      ansible.builtin.debug:
+        var: output
+
+    - name: Run `docker-compose up` again
+      community.docker.docker_compose_v2:
+        project_src: flask
+      register: output
+
+    - name: Show results
+      ansible.builtin.debug:
+        var: output
+
+    - ansible.builtin.assert:
+        that: not output.changed
+
+    - name: Stop all services
+      community.docker.docker_compose_v2:
+        project_src: flask
+        state: stopped
+      register: output
+
+    - name: Show results
+      ansible.builtin.debug:
+        var: output
+
+    - name: Verify that web and db services are not running
+      ansible.builtin.assert:
+        that:
+          - "not output.services.web.flask_web_1.state.running"
+          - "not output.services.db.flask_db_1.state.running"
+
+    - name: Restart services
+      community.docker.docker_compose_v2:
+        project_src: flask
+        state: restarted
+      register: output
+
+    - name: Show results
+      ansible.builtin.debug:
+        var: output
+
+    - name: Verify that web and db services are running
+      ansible.builtin.assert:
+        that:
+          - "output.services.web.flask_web_1.state.running"
+          - "output.services.db.flask_db_1.state.running"
+
+
+
+
+

Return Values

+

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

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

Key

Description

+

actions

+

list / elements=dictionary

+

A list of actions that have been applied.

+

Returned: success

+
+

id

+

string

+

The ID of the resource that was changed.

+

Returned: success

+

Sample: "container"

+
+

status

+

string

+

The status change that happened.

+

Returned: success

+

Can only return:

+
    +

  • "Starting"

    • +

  • "Exiting"

    • +

  • "Restarting"

    • +

  • "Creating"

    • +

  • "Stopping"

    • +

  • "Killing"

    • +

  • "Removing"

    • +

  • "Recreating"

    • +

  • "Pulling"

    • +
+

Sample: "Creating"

+
+

what

+

string

+

What kind of resource was changed.

+

Returned: success

+

Can only return:

+
    +

  • "container"

    • +

  • "image"

    • +

  • "network"

    • +

  • "service"

    • +

  • "unknown"

    • +

  • "volume"

    • +
+

Sample: "container"

+
+

containers

+

list / elements=dictionary

+

A list of containers associated to the service.

+

Returned: success

+
+

Command

+

any

+

The container’s command.

+

Returned: success

+
+

CreatedAt

+

string

+

The timestamp when the container was created.

+

Returned: success

+

Sample: "2024-01-02 12:20:41 +0100 CET"

+
+

ExitCode

+

integer

+

The container’s exit code.

+

Returned: success

+
+

Health

+

any

+

The container’s health check.

+

Returned: success

+
+

ID

+

string

+

The container’s ID.

+

Returned: success

+

Sample: "44a7d607219a60b7db0a4817fb3205dce46e91df2cb4b78a6100b6e27b0d3135"

+
+

Image

+

string

+

The container’s image.

+

Returned: success

+
+

Labels

+

dictionary

+

Labels for this container.

+

Returned: success

+
+

LocalVolumes

+

string

+

The local volumes count.

+

Returned: success

+
+

Mounts

+

string

+

Mounts.

+

Returned: success

+
+

Name

+

string

+

The container’s primary name.

+

Returned: success

+
+

Names

+

list / elements=string

+

List of names of the container.

+

Returned: success

+
+

Networks

+

list / elements=string

+

List of networks attached to this container.

+

Returned: success

+
+

Ports

+

string

+

List of port assignments as a string.

+

Returned: success

+
+

Publishers

+

list / elements=dictionary

+

List of port assigments.

+

Returned: success

+
+

Protocol

+

string

+

The protocol.

+

Returned: success

+

Can only return:

+
    +

  • "tcp"

    • +

  • "udp"

    • +
+
+

PublishedPort

+

integer

+

The port that is published.

+

Returned: success

+
+

TargetPort

+

integer

+

The container’s port the published port maps to.

+

Returned: success

+
+

URL

+

string

+

Interface the port is bound to.

+

Returned: success

+
+

RunningFor

+

string

+

Amount of time the container runs.

+

Returned: success

+
+

Service

+

string

+

The name of the service.

+

Returned: success

+
+

Size

+

string

+

The container’s size.

+

Returned: success

+

Sample: "0B"

+
+

State

+

string

+

The container’s state.

+

Returned: success

+

Sample: "running"

+
+

Status

+

string

+

The container’s status.

+

Returned: success

+

Sample: "Up About a minute"

+
+

images

+

list / elements=dictionary

+

A list of images associated to the service.

+

Returned: success

+
+

ContainerName

+

string

+

Name of the conainer this image is used by.

+

Returned: success

+
+

ID

+

string

+

The image’s ID.

+

Returned: success

+

Sample: "sha256:c8bccc0af9571ec0d006a43acb5a8d08c4ce42b6cc7194dd6eb167976f501ef1"

+
+

Repository

+

string

+

The repository where this image belongs to.

+

Returned: success

+
+

Size

+

integer

+

The image’s size in bytes.

+

Returned: success

+
+

Tag

+

string

+

The tag of the image.

+

Returned: success

+
+
+

Authors

+
    +

  • Felix Fontein (@felixfontein)

    • +
+
+ +
+
+ + +
+