docker_container - fix handling of exposed port ranges. So far, the module used an undocumented feature of Docker that was removed from Docker 29.0.0, that allowed to pass the range to the deamon and let handle it. Now the module explodes ranges into a list of all contained ports, same as the Docker CLI does. For backwards compatibility with Docker < 29.0.0, it also explodes ranges returned by the API for existing containers so that comparison should only indicate a difference if the ranges actually change (https://github.com/ansible-collections/community.docker/pull/1192).
docker_image, docker_image_export - idempotency for archiving images depends on whether the image IDs used by the image storage backend correspond to the IDs used in the tarball’s manifest.json files. The new default backend in Docker 29 apparently uses image IDs that no longer correspond, whence idempotency no longer works (https://github.com/ansible-collections/community.docker/pull/1199).
The main changes are that the collection dropped support for some ansible-core
+versions that are End of Life, and thus dropped support for Python 2.7.
+This allowed to modernize the Python code, in particular with type hints.
+Also all module and plugin utils are now private to the collection, which
+makes it easier to refactor code. All these changes should have no effect on
+end-users.
docker_compose_v2_run - the module has a conflict between the type of parameter it expects and the one it tries to sanitize. Fix removes the label sanitization step because they are already validated by the parameter definition (https://github.com/ansible-collections/community.docker/pull/1034).
docker_image_build - work around bug resp. very unexpected behavior in Docker buildx that overwrites all image names in --output parameters if --tag is provided, which the module did by default in the past. The module now only supplies --tag if outputs is empty. If outputs has entries, it will add an additional entry with type=image if no entry of type=image contains the image name specified by the name and tag options (https://github.com/ansible-collections/community.docker/issues/1001, https://github.com/ansible-collections/community.docker/pull/1006).
The collection deprecates support for all ansible-core versions that are currently End of Life, according to the ansible-core support matrix. This means that the next major release of the collection will no longer support ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14.
docker_container - when creating a container, directly pass all networks to connect to to the Docker Daemon for API version 1.44 and newer. This makes creation more efficient and works around a bug in Docker Daemon that does not use the specified MAC address in at least some cases, though only for creation (https://github.com/ansible-collections/community.docker/pull/933).
docker_container - when specifying a MAC address for a container’s network, and the network is attached after container creation (for example, due to idempotency checks), the MAC address is at least in some cases ignored by the Docker Daemon (https://github.com/ansible-collections/community.docker/pull/933).
Please note that the fix for requests 2.32.0 included in community.docker 3.10.1 only
+fixes problems with the vendored Docker SDK for Python code. Modules and plugins that
+use Docker SDK for Python can still fail due to the SDK currently being incompatible
+with requests 2.32.0.
+
If you still experience problems with requests 2.32.0, such as error messages like
+NotsupportedURLschemehttp+docker, please restrict requests to <2.32.0.
various modules and plugins - the ssl_version option has been deprecated and will be removed from community.docker 4.0.0. It has already been removed from Docker SDK for Python 7.0.0, and was only necessary in the past to work around SSL/TLS issues (https://github.com/ansible-collections/community.docker/pull/853).
The EE requirements now include PyYAML, since the docker_compose_v2* modules depend on it when the definition option is used. This should not have a noticable effect on generated EEs since ansible-core itself depends on PyYAML as well, and ansible-builder explicitly ignores this dependency (https://github.com/ansible-collections/community.docker/pull/832).
The collection now includes a bunch of new docker_image_* modules that move features out of the
+rather complex docker_image module. These new modules are easier to use and can better declare whether
+they support check mode, diff mode, or none of them.
+
This version also features modules that support the Docker CLI plugins buildx and compose.
+The docker_image_build module uses the dockerbuildx command under the hood, and the docker_compose_v2
+and docker_compose_v2_pull modules uses the dockercompose command. All these modules use the Docker CLI
+instead of directly talking to the API. The modules support mostly the same interface as the API based modules,
+so the main difference is that instead of some Python requirements, they depend on the Docker CLI tool docker.
The community.docker collection now depends on the community.library_inventory_filtering_v1 collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ansible-galaxycollectioninstall, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugins (https://github.com/ansible-collections/community.docker/pull/698).
The ca_cert option available to almost all modules and plugins has been renamed to ca_path. The name ca_path is also used for similar options in ansible-core and other collections. The old name has been added as an alias and can still be used (https://github.com/ansible-collections/community.docker/pull/744).
+
The docker_stack* modules now use the common CLI-based module code added for the docker_image_build and docker_compose_v2 modules. This means that the modules now have various more configuration options with respect to talking to the Docker Daemon, and now also are part of the community.docker.docker and docker module default groups (https://github.com/ansible-collections/community.docker/pull/745).
+
docker_container - add networks[].mac_address option for Docker API 1.44+. Note that Docker API 1.44 no longer uses the global mac_address option, this new option is the only way to set the MAC address for a container (https://github.com/ansible-collections/community.docker/pull/763).
docker_container - the default ignore for the image_name_mismatch parameter has been deprecated and will switch to recreate in community.docker 4.0.0. A deprecation warning will be printed in situations where the default value is used and where a behavior would change once the default changes (https://github.com/ansible-collections/community.docker/pull/703).
modules and plugins using the Docker SDK for Python - remove ssl_version from the parameters passed to Docker SDK for Python 7.0.0+. Explicitly fail with a nicer error message if it was explicitly set in this case (https://github.com/ansible-collections/community.docker/pull/715).
+
modules and plugins using the Docker SDK for Python - remove tls_hostname from the parameters passed to Docker SDK for Python 7.0.0+. Explicitly fail with a nicer error message if it was explicitly set in this case (https://github.com/ansible-collections/community.docker/pull/721).
From this version on, community.docker is using the new Ansible semantic markup
+in its documentation. If you look at documentation with the ansible-doc CLI tool
+from ansible-core before 2.15, please note that it does not render the markup
+correctly. You should be still able to read it in most cases, but you need
+ansible-core 2.15 or later to see it as it is intended. Alternatively you can
+look at the devel docsite
+for the rendered HTML version of the documentation of the latest release.
Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/docker/.
docker_image - when using archive_path, detect whether changes are necessary based on the image ID (hash). If the existing tar archive matches the source, do nothing. Previously, each task execution re-created the archive (https://github.com/ansible-collections/community.docker/pull/500).
docker_container - the purge_networks option is deprecated and will be removed in community.docker 4.0.0. Use networks:strict in comparisons instead, and make sure to provide networks, with value [] if all networks should be removed (https://github.com/ansible-collections/community.docker/pull/487).
The collection now contains vendored code from the Docker SDK for Python to talk to the Docker daemon. Modules and plugins using this code no longer need the Docker SDK for Python installed on the machine the module or plugin is running on (https://github.com/ansible-collections/community.docker/pull/398).
+
docker_api connection plugin - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/414).
+
docker_container - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/422).
docker_container_exec - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/401).
+
docker_container_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/402).
+
docker_containers inventory plugin - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/413).
+
docker_host_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/403).
+
docker_image - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/404).
+
docker_image_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/405).
+
docker_image_load - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/406).
+
docker_login - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/407).
+
docker_network - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/408).
+
docker_network_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/409).
+
docker_plugin - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/429).
+
docker_prune - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/410).
+
docker_volume - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/411).
+
docker_volume_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/412).
All software licenses are now in the LICENSES/ directory of the collection root. Moreover, SPDX-License-Identifier: is used to declare the applicable license for every file that is not automatically generated (https://github.com/ansible-collections/community.docker/pull/430).
+
Remove vendored copy of distutils.version in favor of vendored copy included with ansible-core 2.12+. For ansible-core 2.11, uses distutils.version for Python < 3.12. There is no support for ansible-core 2.11 with Python 3.12+ (https://github.com/ansible-collections/community.docker/pull/271).
modules and plugins communicating directly with the Docker daemon - improve default TLS version selection for Python 3.6 and newer. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (https://github.com/ansible-collections/community.docker/pull/434).
modules and plugins communicating directly with the Docker daemon - when connecting by SSH and not using use_ssh_client=true, reject unknown host keys instead of accepting them. This is only a breaking change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (https://github.com/ansible-collections/community.docker/pull/434).
docker_container - the default of command_handling was changed from compatibility to correct. Older versions were warning for every invocation of the module when this would result in a change of behavior (https://github.com/ansible-collections/community.docker/pull/399).
modules and plugins communicating directly with the Docker daemon - when connecting by SSH and not using use_ssh_client=true, reject unknown host keys instead of accepting them. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (https://github.com/ansible-collections/community.docker/pull/434).
docker_image - when composing the build context, trim trailing whitespace from .dockerignore entries. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (https://github.com/ansible-collections/community.docker/pull/434).
modules and plugins communicating directly with the Docker daemon - do not create a subshell for SSH connections when using use_ssh_client=true. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (https://github.com/ansible-collections/community.docker/pull/434).
+
modules and plugins communicating directly with the Docker daemon - fix ProxyCommand handling for SSH connections when not using use_ssh_client=true. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (https://github.com/ansible-collections/community.docker/pull/434).
+
modules and plugins communicating directly with the Docker daemon - fix parsing of IPv6 addresses with a port in docker_host. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (https://github.com/ansible-collections/community.docker/pull/434).
Bugfix and deprecation release. The next 2.x.y releases will only be bugfix releases, the next expect minor/major release will be 3.0.0 with some major changes.
Support for Docker API version 1.20 to 1.24 has been deprecated and will be removed in community.docker 3.0.0. The first Docker version supporting API version 1.25 was Docker 1.13, released in January 2017. This affects the modules docker_container, docker_container_exec, docker_container_info, docker_compose, docker_login, docker_image, docker_image_info, docker_image_load, docker_host_info, docker_network, docker_network_info, docker_node_info, docker_swarm_info, docker_swarm_service, docker_swarm_service_info, docker_volume_info, and docker_volume, whose minimally supported API version is between 1.20 and 1.24 (https://github.com/ansible-collections/community.docker/pull/396).
+
Support for Python 2.6 is deprecated and will be removed in the next major release (community.docker 3.0.0). Some modules might still work with Python 2.6, but we will no longer try to ensure compatibility (https://github.com/ansible-collections/community.docker/pull/388).
Docker SDK for Python based modules and plugins - if the API version is specified as an option, use that one to validate API version requirements of module/plugin options instead of the latest API version supported by the Docker daemon. This also avoids one unnecessary API call per module/plugin (https://github.com/ansible-collections/community.docker/pull/389).
Support for Ansible 2.9 and ansible-base 2.10 is deprecated, and will be removed in the next major release (community.docker 3.0.0). Some modules might still work with these versions afterwards, but we will no longer keep compatibility code that was needed to support them (https://github.com/ansible-collections/community.docker/pull/361).
docker connection plugin - the plugin supports new ways to define the timeout. These are the ANSIBLE_DOCKER_TIMEOUT environment variable, the timeout setting in the docker_connection section of ansible.cfg, and the ansible_docker_timeout variable (https://github.com/ansible-collections/community.docker/pull/297).
docker_api connection plugin - the plugin supports new ways to define the timeout. These are the ANSIBLE_DOCKER_TIMEOUT environment variable, the timeout setting in the docker_connection section of ansible.cfg, and the ansible_docker_timeout variable (https://github.com/ansible-collections/community.docker/pull/308).
docker_swarm_service - add support for setting capabilities with the cap_add and cap_drop parameters. Usage is the same as with the capabilities and cap_drop parameters for docker_container (https://github.com/ansible-collections/community.docker/pull/294).
Various modules and plugins - use vendored version of distutils.version included in ansible-core 2.12 if available. This avoids breakage when distutils is removed from the standard library of Python 3.12. Note that ansible-core 2.11, ansible-base 2.10 and Ansible 2.9 are right now not compatible with Python 3.12, hence this fix does not target these ansible-core/-base/2.9 versions (https://github.com/ansible-collections/community.docker/pull/258).
docker_container - added publish_all_ports option to publish all exposed ports to random ports except those explicitly bound with published_ports (this was already added in community.docker 1.8.0) (https://github.com/ansible-collections/community.docker/pull/162).
+
docker_container - added new command_handling option with current deprecated default value compatibility which allows to control how the module handles shell quoting when interpreting lists, and how the module handles empty lists/strings. The default will switch to correct in community.docker 3.0.0 (https://github.com/ansible-collections/community.docker/pull/186).
docker_container - the new command_handling’s default value, compatibility, is deprecated and will change to correct in community.docker 3.0.0. A deprecation warning is emitted by the module in cases where the behavior will change. Please note that ansible-core will output a deprecation warning only once, so if it is shown for an earlier task, there could be more tasks with this warning where it is not shown (https://github.com/ansible-collections/community.docker/pull/186).
docker_containers inventory plugin - when connection_type=docker-api, now pass Docker daemon connection options from inventory plugin to connection plugin. This can be disabled by setting configure_docker_daemon=false (https://github.com/ansible-collections/community.docker/pull/157).
docker_container - allow memory_swap:-1 to set memory swap limit to unlimited. This is useful when the user cannot set memory swap limits due to cgroup limitations or other reasons, as by default Docker will try to set swap usage to two times the value of memory (https://github.com/ansible-collections/community.docker/pull/138).
docker_* modules and plugins, except docker_swarm connection plugin and docker_compose and docker_stack*`modules-thecurrentdefault``localhost for tls_hostname is deprecated. In community.docker 2.0.0 it will be computed from docker_host instead (https://github.com/ansible-collections/community.docker/pull/134).
docker_swarm - if join_token is specified, a returned join token with the same value will be replaced by VALUE_SPECIFIED_IN_NO_LOG_PARAMETER. Make sure that you do not blindly use the join tokens from the return value of this module when the module is invoked with join_token specified! This breaking change appears in a minor release since it is necessary to fix a security issue (https://github.com/ansible-collections/community.docker/pull/103).
The community.docker continues the work on the Ansible docker modules and plugins from their state in community.general 1.2.0. The changes listed here are thus relative to the modules and plugins community.general.docker*.
+
All deprecation removals planned for community.general 2.0.0 have been applied. All deprecation removals scheduled for community.general 3.0.0 have been re-scheduled for community.docker 2.0.0.
docker_swarm_service - the restart_policy, restart_policy_attempts, restart_policy_delay and restart_policy_window options has been removed. Use the corresponding suboptions in restart_config instead (https://github.com/ansible-collections/community.docker/pull/1).
+
docker_swarm_service - the update_delay, update_parallelism, update_failure_action, update_monitor, update_max_failure_ratio and update_order options has been removed. Use the corresponding suboptions in update_config instead (https://github.com/ansible-collections/community.docker/pull/1).
Return facts about whether the module runs in a Docker or podman container.
+
This module attempts a best-effort detection. There might be special cases where it does not work; if you encounter one, make sure that this is still a problem with the latest community.docker release, and if it is, please file an issue.
---
+-name:Get facts on current container
+community.docker.current_container_facts:
+
+-name:Print information on current container when running in a container
+ansible.builtin.debug:
+msg:"ContainerIDis{{ansible_module_container_id}}"
+when:ansible_module_running_in_container
+
Facts returned by this module are added/updated in the hostvars host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.
+
+
+
Key
+
Description
+
+
+
+
+
ansible_module_container_id
+
string
+
+
The detected container ID.
+
Contains an empty string if no container was detected.
+
Returned: always
+
+
+
+
ansible_module_container_type
+
string
+
+
The detected container environment.
+
Contains an empty string if no container was detected, or a non-empty string identifying the container environment.
+
docker indicates that the module ran inside a regular Docker container.
+
azure_pipelines indicates that the module ran on Azure Pipelines. This seems to no longer be reported.
+
github_actions indicates that the module ran inside a Docker container on GitHub Actions. It is supported since community.docker 2.4.0.
+
podman indicates that the module ran inside a regular Podman container. It is supported since community.docker 3.3.0.
+
Returned: always
+
Can only return:
+
+
""
+
"docker"
+
"azure_pipelines"
+
"github_actions"
+
"podman"
+
+
+
+
+
ansible_module_running_in_container
+
boolean
+
+
Whether the module was able to detect that it runs in a container or not.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.docker.
+You need further requirements to be able to use this connection plugin,
+see Requirements for details.
+
To use it in a playbook, specify: community.docker.docker_api.
Run commands or put/fetch files to an existing docker container.
+
Uses the requests library to interact directly with the Docker daemon instead of using the Docker CLI. Use the community.docker.docker connection plugin if you want to use the Docker CLI.
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"
+
Configuration:
+
+
Variable: ansible_docker_api_version
+
+
+
+
+
+
+
+
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still be used.
+
Configuration:
+
+
Variable: ansible_docker_ca_cert
+
Variable: ansible_docker_ca_path
+
added in community.docker 3.6.0
+
+
+
+
+
+
+
+
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.
+
Configuration:
+
+
Variable: ansible_docker_client_cert
+
+
+
+
+
+
+
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.
+
Configuration:
+
+
Variable: ansible_docker_client_key
+
+
+
+
+
container_timeout
+
integer
+
+
Controls how long we can wait to access reading output from the container once execution started.
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"
+
Configuration:
+
+
Variable: ansible_docker_docker_host
+
+
+
+
+
extra_env
+
dictionary
+
added in community.docker 3.12.0
+
+
Provide extra environment variables to set when running commands in the Docker container.
+
This option can currently only be provided as Ansible variables due to limitations of ansible-core’s configuration manager.
+
Configuration:
+
+
Variable: ansible_docker_extra_env
+
+
+
+
+
privileged
+
boolean
+
added in community.docker 3.12.0
+
+
Whether commands should be run with extended privileges.
+
Note that this allows command to potentially break out of the container. Use with care!
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
+
Configuration:
+
+
Variable: ansible_docker_timeout
+
+
+
+
+
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
+
+
Configuration:
+
+
Variable: ansible_docker_tls
+
+
+
+
+
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.
+
Configuration:
+
+
Variable: ansible_docker_tls_hostname
+
+
+
+
+
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
+
+
Configuration:
+
+
Variable: ansible_docker_validate_certs
+
+
+
+
+
working_dir
+
string
+
added in community.docker 3.12.0
+
+
The directory inside the container to run commands in.
Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
+For example, a variable that is lower in the list will override a variable that is higher up.
+The entry types are also ordered by precedence from low to high priority order.
+For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
This module has been removed
+in version 4.0.0 of community.docker.
+This module uses docker-compose v1, which is End of Life since July 2022. Please migrate to community.docker.docker_compose_v2.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/pr/1248/docker_compose_v2_exec_module.html b/pr/1248/docker_compose_v2_exec_module.html
new file mode 100644
index 00000000..8bd68d17
--- /dev/null
+++ b/pr/1248/docker_compose_v2_exec_module.html
@@ -0,0 +1,720 @@
+
+
+
+
+
+
+
+
+
+ community.docker.docker_compose_v2_exec module – Run command in a container of a Compose service — Community.Docker Collection documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_exec.
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"
+
+
+
+
argv
+
list / elements=string
+
+
The command to execute.
+
Since this is a list of arguments, no quoting is needed.
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.
+
+
+
+
chdir
+
string
+
+
The directory to run the command in.
+
+
+
+
check_files_existing
+
boolean
+
added in community.docker 3.9.0
+
+
If set to false, the module will not check whether one of the files compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml exists in project_src if files is not provided.
+
This can be useful if environment files with COMPOSE_FILE are used to configure a different filename. The module currently does not check for COMPOSE_FILE in environment files or the current environment.
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.
If provided, PyYAML must be available to this module, and project_name must be specified.
+
Note that a temporary directory will be created and deleted afterwards when using this option.
+
+
+
+
detach
+
boolean
+
+
Whether to run the command synchronously (detach=false, default) or asynchronously (detach=true).
+
If set to true, stdin cannot be provided, and the return values stdout, stderr, and rc are not returned.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
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.
+
Mutually exclusive with cli_context. If neither docker_host nor cli_context are provided, the value unix:///var/run/docker.sock is used.
+
+
+
+
env
+
dictionary
+
+
Dictionary of environment variables with their respective values to be passed to the command ran inside the container.
+
Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example "true") in order to avoid data loss.
+
Please note that if you are passing values in with Jinja2 templates, like "{{value}}", you need to add |string to prevent Ansible to convert strings such as "true" back to booleans. The correct way is to use "{{value|string}}".
+
+
+
+
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.
+
+
+
+
files
+
list / elements=path
+
added in community.docker 3.7.0
+
+
List of Compose file names relative to project_src to be used instead of the main Compose file (compose.yml, compose.yaml, docker-compose.yml, or docker-compose.yaml).
Strip empty lines from the end of stdout/stderr in result.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
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.
+
+
+
+
tty
+
boolean
+
+
Whether to allocate a TTY.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
user
+
string
+
+
If specified, the user to execute this command with.
+
+
+
+
+
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.
If you need to evaluate environment variables of the container in command or argv, you need to pass the command through a shell, like command=/bin/sh-c"echo$ENV_VARIABLE". The same needs to be done in case you want to use glob patterns or other shell features such as redirects.
+
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.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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.
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"
+
+
+
+
assume_yes
+
boolean
+
added in community.docker 4.5.0
+
+
When assume_yes=true, pass -y/--yes to assume “yes” as answer to all prompts and run non-interactively.
+
Right now a prompt is asked whenever a non-matching volume should be re-created. assume_yes=false results in the question being answered by “no”, which will simply re-use the existing volume.
+
This option is only available on Docker Compose 2.32.0 or newer.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
build
+
string
+
+
Whether to build images before starting containers. This is used when dockercomposeup is run.
+
always always builds before starting containers. This is equivalent to the --build option of dockercomposeup.
+
never never builds before starting containers. This is equivalent to the --no-build option of dockercomposeup.
+
policy uses the policy as defined in the Compose file.
+
Choices:
+
+
"always"
+
"never"
+
"policy"← (default)
+
+
+
+
+
+
+
+
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.
+
+
+
+
check_files_existing
+
boolean
+
added in community.docker 3.9.0
+
+
If set to false, the module will not check whether one of the files compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml exists in project_src if files is not provided.
+
This can be useful if environment files with COMPOSE_FILE are used to configure a different filename. The module currently does not check for COMPOSE_FILE in environment files or the current environment.
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.
+
+
+
+
definition
+
dictionary
+
added in community.docker 3.9.0
+
+
Compose file describing one or more services, networks and volumes.
If provided, PyYAML must be available to this module, and project_name must be specified.
+
Note that a temporary directory will be created and deleted afterwards when using this option.
+
+
+
+
dependencies
+
boolean
+
+
When state is present or restarted, specify whether or not to include linked services.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
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.
+
Mutually exclusive with cli_context. If neither docker_host nor cli_context are provided, the value unix:///var/run/docker.sock is used.
+
+
+
+
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.
+
+
+
+
files
+
list / elements=path
+
added in community.docker 3.7.0
+
+
List of Compose file names relative to project_src to be used instead of the main Compose file (compose.yml, compose.yaml, docker-compose.yml, or docker-compose.yaml).
Note that Docker Compose 2.31.0 is the first Compose 2.x version to emit build events. For older versions, the behavior is always as if ignore_build_events=true.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
profiles
+
list / elements=string
+
+
List of profiles to enable when starting services.
+
Equivalent to dockercompose--profile.
+
+
+
+
project_name
+
string
+
+
Provide a project name. If not provided, the project name is taken from the basename of project_src.
Whether to recreate instead of reuse anonymous volumes from previous containers.
+
true is equivalent to the --renew-anon-volumes option of dockercomposeup.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
scale
+
dictionary
+
added in community.docker 3.7.0
+
+
Define how to scale services when running dockercomposeup.
+
Provide a dictionary of key/value pairs where the key is the name of the service and the value is an integer count for the number of containers.
+
+
+
+
services
+
list / elements=string
+
+
Specifies a subset of services to be targeted.
+
+
+
+
state
+
string
+
+
Desired state of the project.
+
present is equivalent to running dockercomposeup.
+
stopped is equivalent to running dockercomposestop.
+
absent is equivalent to running dockercomposedown.
+
restarted is equivalent to running dockercomposerestart.
+
Choices:
+
+
"absent"
+
"stopped"
+
"restarted"
+
"present"← (default)
+
+
+
+
+
timeout
+
integer
+
+
Timeout in seconds for container shutdown when attached or when containers are already running.
+
+
+
+
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
+
+
+
+
+
wait
+
boolean
+
added in community.docker 3.8.0
+
+
When running dockercomposeup, pass --wait to wait for services to be running/healthy.
+
A timeout can be set with the wait_timeout option.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
wait_timeout
+
integer
+
added in community.docker 3.8.0
+
+
When wait=true, wait at most this amount of seconds.
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.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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.
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.
+
+
+
+
check_files_existing
+
boolean
+
added in community.docker 3.9.0
+
+
If set to false, the module will not check whether one of the files compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml exists in project_src if files is not provided.
+
This can be useful if environment files with COMPOSE_FILE are used to configure a different filename. The module currently does not check for COMPOSE_FILE in environment files or the current environment.
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.
+
+
+
+
definition
+
dictionary
+
added in community.docker 3.9.0
+
+
Compose file describing one or more services, networks and volumes.
If provided, PyYAML must be available to this module, and project_name must be specified.
+
Note that a temporary directory will be created and deleted afterwards when using this option.
+
+
+
+
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.
+
Mutually exclusive with cli_context. If neither docker_host nor cli_context are provided, the value unix:///var/run/docker.sock is used.
+
+
+
+
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.
+
+
+
+
files
+
list / elements=path
+
added in community.docker 3.7.0
+
+
List of Compose file names relative to project_src to be used instead of the main Compose file (compose.yml, compose.yaml, docker-compose.yml, or docker-compose.yaml).
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.
Use group/docker or group/community.docker.docker in module_defaults to set defaults for this module.
+
+
+
+
check_mode
+
+
Support: full
+
If policy=always, the module will always indicate a change. Docker Compose does not give any information whether pulling would update the image or not.
+
+
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.
+
+
+
+
idempotent
+
+
Support: full
+
+
When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.
+
This assumes that the system controlled/queried by the module has not changed in a relevant way.
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.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_run.
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"
+
+
+
+
argv
+
list / elements=string
+
+
The command to execute.
+
Since this is a list of arguments, no quoting is needed.
Note that building can insert information into stdout or stderr.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
+
+
+
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.
+
+
+
+
cap_add
+
list / elements=string
+
+
Linux capabilities to add to the container.
+
+
+
+
cap_drop
+
list / elements=string
+
+
Linux capabilities to drop from the container.
+
+
+
+
chdir
+
string
+
+
The directory to run the command in.
+
+
+
+
check_files_existing
+
boolean
+
added in community.docker 3.9.0
+
+
If set to false, the module will not check whether one of the files compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml exists in project_src if files is not provided.
+
This can be useful if environment files with COMPOSE_FILE are used to configure a different filename. The module currently does not check for COMPOSE_FILE in environment files or the current environment.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
cleanup
+
boolean
+
+
Automatically remove th econtainer when it exits.
+
Corresponds to the --rm option of dockercomposerun.
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.
If provided, PyYAML must be available to this module, and project_name must be specified.
+
Note that a temporary directory will be created and deleted afterwards when using this option.
+
+
+
+
detach
+
boolean
+
+
Whether to run the command synchronously (detach=false, default) or asynchronously (detach=true).
+
If set to true, stdin cannot be provided, and the return values stdout, stderr, and rc are not returned. Instead, the return value container_id is provided.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
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.
+
Mutually exclusive with cli_context. If neither docker_host nor cli_context are provided, the value unix:///var/run/docker.sock is used.
+
+
+
+
entrypoint
+
string
+
+
Override the entrypoint of the container image.
+
+
+
+
env
+
dictionary
+
+
Dictionary of environment variables with their respective values to be passed to the command ran inside the container.
+
Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example "true") in order to avoid data loss.
+
Please note that if you are passing values in with Jinja2 templates, like "{{value}}", you need to add |string to prevent Ansible to convert strings such as "true" back to booleans. The correct way is to use "{{value|string}}".
+
+
+
+
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.
+
+
+
+
files
+
list / elements=path
+
added in community.docker 3.7.0
+
+
List of Compose file names relative to project_src to be used instead of the main Compose file (compose.yml, compose.yaml, docker-compose.yml, or docker-compose.yaml).
Strip empty lines from the end of stdout/stderr in result.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
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.
+
+
+
+
tty
+
boolean
+
+
Whether to allocate a TTY.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
use_aliases
+
boolean
+
+
Use the service’s network useAliases in the network(s) the container connects to.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
user
+
string
+
+
If specified, the user to execute this command with.
+
+
+
+
+
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.
If you need to evaluate environment variables of the container in command or argv, you need to pass the command through a shell, like command=/bin/sh-c"echo$ENV_VARIABLE". The same needs to be done in case you want to use glob patterns or other shell features such as redirects.
+
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.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_config.
Create and remove Docker configs in a Swarm environment. Similar to dockerconfigcreate and dockerconfigrm.
+
Adds to the metadata of new configs ansible_key, an encrypted hash representation of the data, which is then used in future runs to test if a config has changed. If ansible_key is not present, then a config will not be updated unless the force option is set.
+
Updates to configs are performed by removing the config and creating it again.
The below requirements are needed on the host that executes this module.
+
+
Docker API >= 1.30
+
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). This module does not work with docker-py.
The version of the Docker API running on the Docker Host.
+
Defaults to the latest version of the API supported by Docker SDK for Python 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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
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"
+
+
+
+
force
+
boolean
+
+
Use with state=present to always remove and recreate an existing config.
+
If true, an existing config will be replaced, even if it has not been changed.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
labels
+
dictionary
+
+
A map of key:value meta data, where both the key and value are expected to be a string.
+
If new meta data is provided, or existing meta data is modified, the config will be updated by removing it and creating it again.
+
+
+
+
name
+
string / required
+
+
The name of the config.
+
+
+
+
rolling_versions
+
boolean
+
added in community.docker 2.2.0
+
+
If set to true, configs are created with an increasing version number appended to their name.
+
Adds a label containing the version number to the managed configs with the name ansible_version.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
state
+
string
+
+
Set to present, if the config should exist, and absent, if it should not.
+
Choices:
+
+
"absent"
+
"present"← (default)
+
+
+
+
+
template_driver
+
string
+
added in community.docker 2.5.0
+
+
Set to golang to use a Go template in data or a Go template file in data_src.
+
Choices:
+
+
"golang"
+
+
+
+
+
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.
+
Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error.
+
+
+
+
use_ssh_client
+
boolean
+
added in community.docker 1.5.0
+
+
For SSH transports, use the ssh CLI tool instead of paramiko.
+
Requires Docker SDK for Python 4.4.0 or newer.
+
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
+
+
+
+
+
versions_to_keep
+
integer
+
added in community.docker 2.2.0
+
+
When using rolling_versions, the number of old versions of the config to keep.
+
Extraneous old configs are deleted after the new one is created.
+
Set to -1 to keep everything or 0 or 1 to keep only the current one.
When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls] with ansible.builtin.pip.
+
Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/.docker/config.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.
---
+-name:Create config foo (from a file on the control machine)
+community.docker.docker_config:
+name:foo
+# If the file is JSON or binary, Ansible might modify it (because
+# it is first decoded and later re-encoded). Base64-encoding the
+# file directly after reading it prevents this to happen.
+data:"{{lookup('file','/path/to/config/file')|b64encode}}"
+data_is_b64:true
+state:present
+
+-name:Create config foo (from a file on the target machine)
+community.docker.docker_config:
+name:foo
+data_src:/path/to/config/file
+state:present
+
+-name:Change the config data
+community.docker.docker_config:
+name:foo
+data:Goodnight everyone!
+labels:
+bar:baz
+one:'1'
+state:present
+
+-name:Add a new label
+community.docker.docker_config:
+name:foo
+data:Goodnight everyone!
+labels:
+bar:baz
+one:'1'
+# Adding a new label will cause a remove/create of the config
+two:'2'
+state:present
+
+-name:No change
+community.docker.docker_config:
+name:foo
+data:Goodnight everyone!
+labels:
+bar:baz
+one:'1'
+# Even though 'two' is missing, there is no change to the existing config
+state:present
+
+-name:Update an existing label
+community.docker.docker_config:
+name:foo
+data:Goodnight everyone!
+labels:
+bar:monkey# Changing a label will cause a remove/create of the config
+one:'1'
+state:present
+
+-name:Force the (re-)creation of the config
+community.docker.docker_config:
+name:foo
+data:Goodnight everyone!
+force:true
+state:present
+
+-name:Remove config foo
+community.docker.docker_config:
+name:foo
+state:absent
+
Run commands or put/fetch files to an existing docker container.
+
Uses the Docker CLI to execute commands in the container. If you prefer to directly connect to the Docker daemon, use the community.docker.docker_api connection plugin.
Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
+For example, a variable that is lower in the list will override a variable that is higher up.
+The entry types are also ordered by precedence from low to high priority order.
+For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_container_copy_into.
To copy files in a non-running container, you must provide the owner_id and group_id options. This is also necessary if the container does not contain a /bin/sh shell with an id tool.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
+
+
+
+
container
+
string / required
+
+
The name of the container to copy files to.
+
+
+
+
container_path
+
string / required
+
+
Path to a file inside the Docker container.
+
Must be an absolute path.
+
+
+
+
content
+
string
+
+
The file’s content.
+
If you plan to provide binary data, provide it pre-encoded to base64, and set content_is_b64=true.
+
Mutually exclusive with path. One of content and path is required.
+
+
+
+
content_is_b64
+
boolean
+
+
If set to true, the content in content is assumed to be Base64 encoded and will be decoded before being used.
+
To use binary content, it is better to keep it Base64 encoded and let it be decoded by this option. Otherwise you risk the data to be interpreted as UTF-8 and corrupted.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
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"
+
+
+
+
follow
+
boolean
+
+
This flag indicates that filesystem links in the Docker container, if they exist, should be followed.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
force
+
boolean
+
+
If set to true, force writing the file (without performing any idempotency checks).
+
If set to false, only write the file if it does not exist on the target. If a filesystem object exists at the destination, the module will not do any change.
+
If this option is not specified, the module will be idempotent. To verify idempotency, it will try to get information on the filesystem object in the container, and if everything seems to match will download the file from the container to compare it to the file to upload.
+
Choices:
+
+
false
+
true
+
+
+
+
+
group_id
+
integer
+
+
The group ID to use when writing the file to disk.
If not provided, the module will try to determine the user and group ID for the current user in the container. This will only work if /bin/sh is present in the container and the id binary or shell builtin is available. Also the container must be running.
+
+
+
+
local_follow
+
boolean
+
+
This flag indicates that filesystem links in the source tree (where the module is executed), if they exist, should be followed.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
mode
+
any
+
+
The file mode to use when writing the file to disk.
+
Will use the file’s mode from the source system if this option is not provided.
+
This option is parsed depending on how mode_parse is set.
"legacy"(default):
+Parses the value of mode as an integer.
+
Note that if you provide an octal number as a string to mode, it will be parsed as a decimal number. If you provide an octal integer directly, though, it will work as expected.
+
This has been the default behavior of the module since it was added to community.docker.
+
+
"modern":
+Parses the value of mode as an octal string, or takes the integer value if an integer has been provided.
If not provided, the module will try to determine the user and group ID for the current user in the container. This will only work if /bin/sh is present in the container and the id binary or shell builtin is available. Also the container must be running.
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+-name:Copy a file into the container
+community.docker.docker_container_copy_into:
+container:mydata
+path:/home/user/data.txt
+container_path:/data/input.txt
+
+-name:Copy a file into the container with owner, group, and mode set
+community.docker.docker_container_copy_into:
+container:mydata
+path:/home/user/bin/runme.o
+container_path:/bin/runme
+owner_id:0# root
+group_id:0# root
+mode:"0755"# readable and executable by all users, writable by root
+mode_parse:modern# ensure that strings passed for 'mode' are passed as octal numbers
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_container_exec.
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"
+
+
+
+
argv
+
list / elements=string
+
+
The command to execute.
+
Since this is a list of arguments, no quoting is needed.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still be used.
+
+
+
+
chdir
+
string
+
+
The directory to run the command in.
+
+
+
+
+
+
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.
The name of the container to execute the command in.
+
+
+
+
debug
+
boolean
+
+
Debug mode
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
detach
+
boolean
+
added in community.docker 2.1.0
+
+
Whether to run the command synchronously (detach=false, default) or asynchronously (detach=true).
+
If set to true, stdin cannot be provided, and the return values stdout, stderr, and rc are not returned.
+
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"
+
+
+
+
env
+
dictionary
+
added in community.docker 2.1.0
+
+
Dictionary of environment variables with their respective values to be passed to the command ran inside the container.
+
Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example "true") in order to avoid data loss.
+
Please note that if you are passing values in with Jinja2 templates, like "{{value}}", you need to add |string to prevent Ansible to convert strings such as "true" back to booleans. The correct way is to use "{{value|string}}".
+
+
+
+
stdin
+
string
+
+
Set the stdin of the command directly to the specified value.
Strip empty lines from the end of stdout/stderr in result.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
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.
+
+
+
+
tty
+
boolean
+
+
Whether to allocate a TTY.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
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
+
+
+
+
+
user
+
string
+
+
If specified, the user to execute this command with.
+
+
+
+
+
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.
If you need to evaluate environment variables of the container in command or argv, you need to pass the command through a shell, like command=/bin/sh-c"echo$ENV_VARIABLE". The same needs to be done in case you want to use glob patterns or other shell features such as redirects.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_container_info.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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
+
+
The name of the container to inspect.
+
When identifying an existing container name may be a name or a long or short container ID.
+
+
+
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_container.
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"
+
+
+
+
auto_remove
+
boolean
+
+
Enable auto-removal of the container on daemon side when the container’s process exits.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still be used.
+
+
+
+
cap_drop
+
list / elements=string
+
+
List of capabilities to drop from the container.
+
+
+
+
capabilities
+
list / elements=string
+
+
List of capabilities to add to the container.
+
This is equivalent to dockerrun--cap-add, or the docker-compose option cap_add.
+
+
+
+
cgroup_parent
+
string
+
added in community.docker 1.1.0
+
+
Specify the parent cgroup for the container.
+
+
+
+
cgroupns_mode
+
string
+
added in community.docker 3.0.0
+
+
Specify the cgroup namespace mode for the container.
+
The Docker CLI calls this simply cgroupns.
+
Choices:
+
+
"host"
+
"private"
+
+
+
+
+
cleanup
+
boolean
+
+
Use with detach=false to remove the container after successful execution.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
+
+
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.
+
+
+
+
command
+
any
+
+
Command to execute when the container starts. A command may be either a string or a list.
+
Prior to version 2.4, strings were split on commas.
+
See command_handling for differences in how strings and lists are handled.
+
+
+
+
command_handling
+
string
+
added in community.docker 1.9.0
+
+
The default behavior for command (when provided as a list) and entrypoint is to convert them to strings without considering shell quoting rules. (For comparing idempotency, the resulting string is split considering shell quoting rules).
+
Also, setting command to an empty list of string, and setting entrypoint to an empty list will be handled as if these options are not specified. This is different from idempotency handling for other container-config related options.
+
When this is set to compatibility, which was the default until community.docker 3.0.0, the current behavior will be kept.
+
When this is set to correct, these options are kept as lists, and an empty value or empty list will be handled correctly for idempotency checks. This has been the default since community.docker 3.0.0.
+
Choices:
+
+
"compatibility"
+
"correct"← (default)
+
+
+
+
+
comparisons
+
dictionary
+
+
Allows to specify how properties of existing containers are compared with module options to decide whether the container should be recreated / updated or not.
+
Only options which correspond to the state of a container as handled by the Docker daemon can be specified, as well as networks.
+
Must be a dictionary specifying for an option one of the keys strict, ignore and allow_more_present.
+
If strict is specified, values are tested for equality, and changes always result in updating or restarting. If ignore is specified, changes are ignored.
+
allow_more_present is allowed only for lists, sets and dicts. If it is specified for lists or sets, the container will only be updated or restarted if the module option contains a value which is not present in the container’s options. If the option is specified for a dict, the container will only be updated or restarted if the module option contains a key which is not present in the container’s option, or if the value of a key present differs.
+
The wildcard option * can be used to set one of the default values strict or ignore to all comparisons which are not explicitly set to other values.
+
See the examples for details.
+
+
+
+
container_default_behavior
+
string
+
+
In older versions of this module, various module options used to have default values. This caused problems with containers which use different values for these options.
+
The default value is now no_defaults. To restore the old behavior, set it to compatibility, which will ensure that the default values are used when the values are not explicitly specified by the user.
By default, the module will try to auto-detect this value from the bridge network’s com.docker.network.bridge.host_binding_ipv4 option. If it cannot auto-detect it, it will fall back to 0.0.0.0.
+
+
+
+
detach
+
boolean
+
+
Enable detached mode to leave the container running in background.
+
If disabled, the task will reflect the status of the container run (failed if the command failed).
List of device and write rate (bytes per second) to device.
+
+
+
+
path
+
string / required
+
+
Device path in the container.
+
+
+
+
rate
+
string / required
+
+
Device read limit in format <number>[<unit>].
+
Number is a positive integer. Unit can be one of B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
Omitting the unit defaults to bytes.
+
+
+
+
device_write_iops
+
list / elements=dictionary
+
+
List of device and write rate (IO per second) to device.
+
+
+
+
path
+
string / required
+
+
Device path in the container.
+
+
+
+
rate
+
integer / required
+
+
Device read limit.
+
Must be a positive integer.
+
+
+
+
devices
+
list / elements=string
+
+
List of host device bindings to add to the container.
+
Each binding is a mapping expressed in the format <path_on_host>:<path_in_container>:<cgroup_permissions>.
+
+
+
+
dns_opts
+
list / elements=string
+
+
List of DNS options.
+
+
+
+
dns_search_domains
+
list / elements=string
+
+
List of custom DNS search domains.
+
+
+
+
dns_servers
+
list / elements=string
+
+
List of custom DNS servers.
+
+
+
+
+
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"
+
+
+
+
domainname
+
string
+
+
Container domainname.
+
+
+
+
entrypoint
+
list / elements=string
+
+
Command that overwrites the default ENTRYPOINT of the image.
+
See command_handling for differences in how strings and lists are handled.
+
+
+
+
env
+
dictionary
+
+
Dictionary of key,value pairs.
+
Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example "true") in order to avoid data loss.
+
Please note that if you are passing values in with Jinja2 templates, like "{{value}}", you need to add |string to prevent Ansible to convert strings such as "true" back to booleans. The correct way is to use "{{value|string}}".
+
+
+
+
env_file
+
path
+
+
Path to a file, present on the target, containing environment variables FOO=BAR.
+
If variable also present in env, then the env value will override.
+
+
+
+
etc_hosts
+
dictionary
+
+
Dict of host-to-IP mappings, where each host name is a key in the dictionary. Each host name will be added to the container’s /etc/hosts file.
+
Instead of an IP address, the special value host-gateway can also be used, which resolves to the host’s gateway IP and allows containers to connect to services running on the host.
+
+
+
+
+
+
exposed_ports
+
aliases: exposed, expose
+
list / elements=string
+
+
List of additional container ports which informs Docker that the container listens on the specified network ports at runtime.
+
If the port is already exposed using EXPOSE in a Dockerfile, it does not need to be exposed again.
+
+
+
+
+
force_kill
+
aliases: forcekill
+
boolean
+
+
Use the kill command when stopping a running container.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
groups
+
list / elements=string
+
+
List of additional group names and/or IDs that the container process will run as.
+
+
+
+
healthcheck
+
dictionary
+
+
Configure a check that is run to determine whether or not containers for this service are “healthy”.
Consecutive number of failures needed to report unhealthy.
+
The default used by the Docker daemon is 3.
+
+
+
+
start_interval
+
string
+
added in community.docker 3.10.0
+
+
Time between health checks during the start period. This option requires Docker Engine version 25.0 or later.
+
The default used by the Docker daemon is 5s.
+
+
+
+
start_period
+
string
+
+
Start period for the container to initialize before starting health-retries countdown.
+
The default used by the Docker daemon is 0s.
+
+
+
+
test
+
any
+
+
Command to run to check health.
+
Must be either a string or a list. If it is a list, the first item must be one of NONE, CMD or CMD-SHELL.
+
+
+
+
test_cli_compatible
+
boolean
+
added in community.docker 3.10.0
+
+
If set to true, omitting healthcheck.test while providing healthcheck does not disable healthchecks, but simply overwrites the image’s values by the ones specified in healthcheck. This is the behavior used by the Docker CLI.
+
If set to false, omitting healthcheck.test will disable the container’s health check. This is the classical behavior of the module and currently the default behavior.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
timeout
+
string
+
+
Maximum time to allow one check to run.
+
The default used by the Docker daemon is 30s.
+
+
+
+
healthy_wait_timeout
+
float
+
added in community.docker 3.11.0
+
+
When waiting for the container to become healthy if state=healthy, this option controls how long the module waits until the container state becomes healthy.
+
The timeout is specified in seconds. The default, 300, is 5 minutes.
+
Set this to 0 or a negative value to wait indefinitely. Note that depending on the container this can result in the module not terminating.
+
Default:300.0
+
+
+
+
hostname
+
string
+
+
The container’s hostname.
+
+
+
+
image
+
string
+
+
Repository path and tag used to create the container. If an image is not found or pull is true, the image will be pulled from the registry. If no tag is included, latest will be used.
+
Can also be an image ID. If this is the case, the image is assumed to be available locally. The pull option is ignored for this case.
+
+
+
+
image_comparison
+
string
+
added in community.docker 3.0.0
+
+
Determines which image to use for idempotency checks that depend on image parameters.
+
The default, desired-image, will use the image that is provided to the module with the image parameter.
+
current-image will use the image that the container is currently using, if the container exists. It falls back to the image that is provided in case the container does not yet exist.
How to handle labels inherited from the image that are not set explicitly.
+
When ignore, labels that are present in the image but not specified in labels will be ignored. This is useful to avoid having to specify the image labels in labels while keeping labels comparisonsstrict.
+
When fail, if there are labels present in the image which are not set from labels, the module will fail. This prevents introducing unexpected labels from the base image.
+
Warning: This option is ignored unless labels:strict or *:strict is specified in the comparisons option.
+
Choices:
+
+
"ignore"← (default)
+
"fail"
+
+
+
+
+
image_name_mismatch
+
string
+
added in community.docker 3.2.0
+
+
Determines what the module does if the image matches, but the image name in the container’s configuration does not match the image name provided to the module.
+
This is ignored if image:ignore is set in comparisons.
+
If set to recreate (default) the container will be recreated.
+
If set to ignore the container will not be recreated because of this. It might still get recreated for other reasons. This has been the default behavior of the module for a long time, but might not be what users expect.
+
The default changed from ignore to recreate in community.docker 4.0.0.
+
Choices:
+
+
"recreate"← (default)
+
"ignore"
+
+
+
+
+
init
+
boolean
+
+
Run an init inside the container that forwards signals and reaps processes.
Can be one of container:<name|id> to reuse another container’s IPC namespace or host to use the host’s IPC namespace within the container.
+
+
+
+
keep_volumes
+
boolean
+
+
Retain anonymous volumes associated with a removed container.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
kernel_memory
+
string
+
+
Kernel memory limit in format <number>[<unit>]. Number is a positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte). Minimum is 4M.
+
Omitting the unit defaults to bytes.
+
+
+
+
kill_signal
+
string
+
+
Override default signal used to kill a running container.
+
+
+
+
labels
+
dictionary
+
+
Dictionary of key value pairs.
+
+
+
+
links
+
list / elements=string
+
+
List of name aliases for linked containers in the format container_name:alias.
+
Setting this will force container to be restarted.
+
+
+
+
log_driver
+
string
+
+
Specify the logging driver. Docker uses json-file by default.
Memory limit in format <number>[<unit>]. Number is a positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
Memory soft limit in format <number>[<unit>]. Number is a positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
Omitting the unit defaults to bytes.
+
+
+
+
memory_swap
+
string
+
+
Total memory limit (memory + swap) in format <number>[<unit>], or the special values unlimited or -1 for unlimited swap usage. Number is a positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
Omitting the unit defaults to bytes.
+
+
+
+
memory_swappiness
+
integer
+
+
Tune a container’s memory swappiness behavior. Accepts an integer between 0 and 100.
+
If not set, the value will be remain the same if container exists and will be inherited from the host machine if it is (re-)created.
+
+
+
+
mounts
+
list / elements=dictionary
+
+
Specification for mounts to be added to the container. More powerful alternative to volumes.
Dictionary of options specific to the chosen volume_driver. See here for details.
+
+
+
+
name
+
string / required
+
+
Assign a name to a new container or match an existing container.
+
When identifying an existing container name may be a name or a long or short container ID.
+
+
+
+
network_mode
+
string
+
+
Connect the container to a network. Choices are bridge, host, none, container:<name|id>, <network_name> or default.
+
Since community.docker 2.0.0, if networks_cli_compatible=true and networks contains at least one network, the default value for network_mode is the name of the first network in the networks list. You can prevent this by explicitly specifying a value for network_mode, like the default value default which will be used by Docker if network_mode is not specified.
+
+
+
+
networks
+
list / elements=dictionary
+
+
List of networks the container belongs to.
+
For examples of the data structure and usage see EXAMPLES below.
+
To remove a container from one or more networks, use networks:strict in the comparisons option.
+
If networks_cli_compatible=false, this will not remove the default network if networks is specified. This is different from the behavior of dockerrun.... You need to explicitly use networks:strict in comparisons to enforce the removal of the default network (and all other networks not explicitly mentioned in networks) in that case.
+
+
+
+
aliases
+
list / elements=string
+
+
List of aliases for this container in this network. These names can be used in the network to reach this container.
+
+
+
+
driver_opts
+
dictionary
+
added in community.docker 5.0.0
+
+
Dictionary of driver options for this network endpoint.
+
Allows setting endpoint-specific driver options like com.docker.network.endpoint.ifname to set a custom network interface name.
+
Requires Docker API version 1.32 or newer.
+
+
+
+
gw_priority
+
integer
+
added in community.docker 5.0.0
+
+
Gateway priority for this network endpoint.
+
When a container is connected to multiple networks, this controls which network’s gateway is used as the default gateway.
+
Higher values indicate higher priority.
+
Requires Docker API version 1.48 or newer.
+
+
+
+
ipv4_address
+
string
+
+
The container’s IPv4 address in this network.
+
+
+
+
ipv6_address
+
string
+
+
The container’s IPv6 address in this network.
+
+
+
+
links
+
list / elements=string
+
+
A list of containers to link to.
+
+
+
+
mac_address
+
string
+
added in community.docker 3.6.0
+
+
Endpoint MAC address (for example, 92:d0:c6:0a:29:33).
+
This is only available for Docker API version 1.44 and later.
+
Please note that when a container is attached to a network after creation, this is currently ignored by the Docker Daemon at least in some cases. When passed on creation, this seems to work better.
+
+
+
+
name
+
string / required
+
+
The network’s name.
+
+
+
+
networks_cli_compatible
+
boolean
+
+
If networks_cli_compatible=true (default), this module will behave as dockerrun--network and will not add the default network if networks is specified. If networks is not specified, the default network will be attached.
+
When networks_cli_compatible=false and networks are provided to the module with the networks option, the module behaves differently than dockerrun--network: dockerrun--networkother will create a container with network other attached, but the default network not attached. This module with networks set to {name:other} will create a container with both default and other attached. If networks:strict or *:strict is set in comparisons, the default network will be removed afterwards.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
oom_killer
+
boolean
+
+
Whether or not to disable OOM Killer for the container.
+
Choices:
+
+
false
+
true
+
+
+
+
+
oom_score_adj
+
integer
+
+
An integer value containing the score given to the container in order to tune OOM killer preferences.
+
+
+
+
output_logs
+
boolean
+
+
If set to true, output of the container command will be printed.
+
Only effective when log_driver is set to json-file, journald, or local.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
paused
+
boolean
+
+
Use with the started state to pause running processes inside the container.
Set PIDs limit for the container. It accepts an integer value.
+
Set -1 for unlimited PIDs.
+
+
+
+
platform
+
string
+
added in community.docker 3.0.0
+
+
Platform for the container in the format os[/arch[/variant]].
+
Note that since community.docker 3.5.0, the module uses both the image’s metadata and the Docker daemon’s information to normalize platform strings similarly to how Docker itself is doing this. If you notice idempotency problems, please verify whether this is still a problem with the latest release of community.docker, and if it is, create an issue in the community.docker GitHub repository. For older community.docker versions, you can use the comparisons option with platform:ignore to prevent accidental recreation of the container due to this.
Any specified port bindings from published_ports will remain intact when true.
+
Choices:
+
+
false
+
true
+
+
+
+
+
+
published_ports
+
aliases: ports
+
list / elements=string
+
+
List of ports to publish from the container to the host.
+
Use docker CLI syntax: 8000, 9000:8000, or 0.0.0.0:9000:8000, where 8000 is a container port, 9000 is a host port, and 0.0.0.0 is a host interface.
+
Port ranges can be used for source and destination ports. If two ranges with different lengths are specified, the shorter range will be used. Since community.general 0.2.0, if the source port range has length 1, the port will not be assigned to the first port of the destination range, but to a free port in that range. This is the same behavior as for docker command line utility.
+
Bind addresses must be either IPv4 or IPv6 addresses. Hostnames are not allowed. This is different from the docker command line utility. Use the community.general.dig lookup to resolve hostnames.
+
If networks parameter is provided, will inspect each network to see if there exists a bridge network with optional parameter com.docker.network.bridge.host_binding_ipv4. If such a network is found, then published ports where no host IP address is specified will be bound to the host IP pointed to by com.docker.network.bridge.host_binding_ipv4. Note that the first bridge network with a com.docker.network.bridge.host_binding_ipv4 value encountered in the list of networks is the one that will be used.
+
The value all was allowed in earlier versions of this module. Support for it was removed in community.docker 3.0.0. Use the publish_all_ports option instead.
+
+
+
+
pull
+
any
+
+
If set to never, will never try to pull an image. Will fail if the image is not available on the Docker daemon.
+
If set to missing or false, only pull the image if it is not available on the Docker daemon. This is the default behavior.
+
If set to always or true, always try to pull the latest version of the image.
+
Note: images are only pulled when specified by name. If the image is specified as a image ID (hash), it cannot be pulled, and this option is ignored.
+
Note: the values never, missing, and always are only available since community.docker 3.8.0. Earlier versions only support true and false.
Since the Docker daemon does not expose any functionality to test whether a pull will result in a changed image, the module by default acts like pull=always only results in a change when the image is not present.
+
If set to image_not_present (default), only report changes in check mode when the image is not present.
+
If set to always, always report changes in check mode.
+
Choices:
+
+
"image_not_present"← (default)
+
"always"
+
+
+
+
+
read_only
+
boolean
+
+
Mount the container’s root file system as read-only.
Use with present and started states to force the re-creation of an existing container.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
removal_wait_timeout
+
float
+
+
When removing an existing container, the docker daemon API call exists after the container is scheduled for removal. Removal usually is very fast, but it can happen that during high I/O load, removal can take longer. By default, the module will wait until the container has been removed before trying to (re-)create it, however long this takes.
+
By setting this option, the module will wait at most this many seconds for the container to be removed. If the container is still in the removal phase after this many seconds, the module will fail.
+
+
+
+
restart
+
boolean
+
+
Use with started state to force a matching container to be stopped and restarted.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
restart_policy
+
string
+
+
Container restart policy.
+
Place quotes around no option.
+
Choices:
+
+
"no"
+
"on-failure"
+
"always"
+
"unless-stopped"
+
+
+
+
+
restart_retries
+
integer
+
+
Use with restart policy to control maximum number of restart attempts.
+
+
+
+
runtime
+
string
+
+
Runtime to use for the container.
+
+
+
+
security_opts
+
list / elements=string
+
+
List of security options in the form of "label:user:User".
+
+
+
+
shm_size
+
string
+
+
Size of /dev/shm in format <number>[<unit>]. Number is positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses 64M.
+
+
+
+
state
+
string
+
+
absent - A container matching the specified name will be stopped and removed. Use force_kill to kill the container rather than stopping it. Use keep_volumes to retain anonymous volumes associated with the removed container.
+
present - Asserts the existence of a container matching the name and any provided configuration parameters. If no container matches the name, a container will be created. If a container matches the name but the provided configuration does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and re-created with the requested config.
+
started - Asserts that the container is first present, and then if the container is not running moves it to a running state. Use restart to force a matching container to be stopped and restarted.
+
healthy - Asserts that the container is present and started, and is actually healthy as well. This means that the conditions defined in healthcheck respectively in the image’s HEALTHCHECK (Docker reference for HEALTHCHECK) are satisfied. The time waited can be controlled with healthy_wait_timeout. This state has been added in community.docker 3.11.0.
+
stopped - Asserts that the container is first present, and then if the container is running moves it to a stopped state.
+
To control what will be taken into account when comparing configuration, see the comparisons option. To avoid that the image version will be taken into account, you can also use the image:ignore in the comparisons option.
+
Use the recreate option to always force re-creation of a matching container, even if it is running.
+
If the container should be killed instead of stopped in case it needs to be stopped for recreation, or because state is stopped, please use the force_kill option. Use keep_volumes to retain anonymous volumes associated with a removed container.
+
Use keep_volumes to retain anonymous volumes associated with a removed container.
+
Choices:
+
+
"absent"
+
"present"
+
"healthy"
+
"stopped"
+
"started"← (default)
+
+
+
+
+
stop_signal
+
string
+
+
Override default signal used to stop the container.
+
+
+
+
stop_timeout
+
integer
+
+
Number of seconds to wait for the container to stop before sending SIGKILL. When the container is created by this module, its StopTimeout configuration will be set to this value.
+
When the container is stopped, will be used as a timeout for stopping the container. In case the container has a custom StopTimeout configuration, the behavior depends on the version of the docker daemon. New versions of the docker daemon will always use the container’s configured StopTimeout value if it has been configured.
+
+
+
+
storage_opts
+
dictionary
+
added in community.docker 1.3.0
+
+
Storage driver options for this container as a key-value mapping.
+
+
+
+
sysctls
+
dictionary
+
+
Dictionary of key,value pairs.
+
+
+
+
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.
List of ulimit options. A ulimit is specified as nofile:262144:262144.
+
+
+
+
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
+
+
+
+
+
user
+
string
+
+
Sets the username or UID used and optionally the groupname or GID for the specified command.
+
Can be of the forms user, user:group, uid, uid:gid, user:gid or uid:group.
+
+
+
+
userns_mode
+
string
+
+
Set the user namespace mode for the container. Currently, the only valid value are host and the empty string ("").
+
+
+
+
uts
+
string
+
+
Set the UTS namespace mode for the container.
+
+
+
+
+
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
+
+
+
+
+
volume_driver
+
string
+
+
The container volume driver.
+
+
+
+
volumes
+
list / elements=string
+
+
List of volumes to mount within the container.
+
Use docker CLI-style syntax: /host:/container[:mode].
+
Mount modes can be a comma-separated list of various modes such as ro, rw, consistent, delegated, cached, rprivate, private, rshared, shared, rslave, slave, and nocopy. Note that the docker daemon might not support all modes and combinations of such modes.
+
SELinux hosts can additionally use z or Z to use a shared or private label for the volume.
+
Note that Ansible 2.7 and earlier only supported one mode, which had to be one of ro, rw, z, and Z.
+
+
+
+
volumes_from
+
list / elements=string
+
+
List of container names or IDs to get volumes from.
For most config changes, the container needs to be recreated. This means that the existing container has to be destroyed and a new one created. This can cause unexpected data loss and downtime. You can use the comparisons option to prevent this.
+
If the module needs to recreate the container, it will only use the options provided to the module to create the new container (except image). Therefore, always specify all options relevant to the container.
+
When restart is set to true, the module will only restart the container if no config changes are detected.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+-name:Create a data container
+community.docker.docker_container:
+name:mydata
+image:busybox
+volumes:
+-/data
+
+-name:Re-create a redis container
+community.docker.docker_container:
+name:myredis
+image:redis
+command:redis-server --appendonly yes
+state:present
+recreate:true
+exposed_ports:
+-6379
+volumes_from:
+-mydata
+
+-name:Restart a container
+community.docker.docker_container:
+name:myapplication
+image:someuser/appimage
+state:started
+restart:true
+links:
+-"myredis:aliasedredis"
+devices:
+-"/dev/sda:/dev/xvda:rwm"
+ports:
+# Publish container port 9000 as host port 8080
+-"8080:9000"
+# Publish container UDP port 9001 as host port 8081 on interface 127.0.0.1
+-"127.0.0.1:8081:9001/udp"
+# Publish container port 9002 as a random host port
+-"9002"
+# Publish container port 9003 as a free host port in range 8000-8100
+# (the host port will be selected by the Docker daemon)
+-"8000-8100:9003"
+# Publish container ports 9010-9020 to host ports 7000-7010
+-"7000-7010:9010-9020"
+env:
+SECRET_KEY:"ssssh"
+# Values which might be parsed as numbers, booleans or other types by the YAML parser need to be quoted
+BOOLEAN_KEY:"yes"
+
+-name:Container present
+community.docker.docker_container:
+name:mycontainer
+state:present
+image:ubuntu:14.04
+command:sleep infinity
+
+-name:Stop a container
+community.docker.docker_container:
+name:mycontainer
+state:stopped
+
+-name:Start 4 load-balanced containers
+community.docker.docker_container:
+name:"container{{item}}"
+recreate:true
+image:someuser/anotherappimage
+command:sleep 1d
+with_sequence:count=4
+
+-name:Remove container
+community.docker.docker_container:
+name:ohno
+state:absent
+
+-name:Syslogging output
+community.docker.docker_container:
+name:myservice
+image:busybox
+log_driver:syslog
+log_options:
+syslog-address:tcp://my-syslog-server:514
+syslog-facility:daemon
+# NOTE: in Docker 1.13+ the "syslog-tag" option was renamed to "tag" for
+# older docker installs, use "syslog-tag" instead
+tag:myservice
+
+-name:Create db container and connect to network
+community.docker.docker_container:
+name:db_test
+image:"postgres:latest"
+networks:
+-name:"{{docker_network_name}}"
+
+-name:Start container, connect to network and link
+community.docker.docker_container:
+name:sleeper
+image:ubuntu:14.04
+networks:
+-name:TestingNet
+ipv4_address:"172.16.1.100"
+aliases:
+-sleepyzz
+links:
+-db_test:db
+-name:TestingNet2
+
+-name:Start a container with a command
+community.docker.docker_container:
+name:sleepy
+image:ubuntu:14.04
+command:["sleep","infinity"]
+
+-name:Add container to networks
+community.docker.docker_container:
+name:sleepy
+networks:
+-name:TestingNet
+ipv4_address:172.16.1.18
+links:
+-sleeper
+-name:TestingNet2
+ipv4_address:172.16.10.20
+
+-name:Update network with aliases
+community.docker.docker_container:
+name:sleepy
+networks:
+-name:TestingNet
+aliases:
+-sleepyz
+-zzzz
+
+-name:Remove container from one network
+community.docker.docker_container:
+name:sleepy
+networks:
+-name:TestingNet2
+comparisons:
+networks:strict
+
+-name:Remove container from all networks
+community.docker.docker_container:
+name:sleepy
+comparisons:
+networks:strict
+
+-name:Start a container and use an env file
+community.docker.docker_container:
+name:agent
+image:jenkinsci/ssh-slave
+env_file:/var/tmp/jenkins/agent.env
+
+-name:Create a container with limited capabilities
+community.docker.docker_container:
+name:sleepy
+image:ubuntu:16.04
+command:sleep infinity
+capabilities:
+-sys_time
+cap_drop:
+-all
+
+-name:Finer container restart/update control
+community.docker.docker_container:
+name:test
+image:ubuntu:18.04
+env:
+arg1:"true"
+arg2:"whatever"
+volumes:
+-/tmp:/tmp
+comparisons:
+image:ignore# do not restart containers with older versions of the image
+env:strict# we want precisely this environment
+volumes:allow_more_present# if there are more volumes, that's ok, as long as `/tmp:/tmp` is there
+
+-name:Finer container restart/update control II
+community.docker.docker_container:
+name:test
+image:ubuntu:18.04
+env:
+arg1:"true"
+arg2:"whatever"
+comparisons:
+'*':ignore# by default, ignore *all* options (including image)
+env:strict# except for environment variables; there, we want to be strict
+
+-name:Start container with healthstatus
+community.docker.docker_container:
+name:nginx-proxy
+image:nginx:1.13
+state:started
+healthcheck:
+# Check if nginx server is healthy by curl'ing the server.
+# If this fails or timeouts, the healthcheck fails.
+test:["CMD","curl","--fail","http://nginx.host.com"]
+interval:1m30s
+timeout:10s
+retries:3
+start_period:30s
+start_interval:10s
+
+-name:Remove healthcheck from container
+community.docker.docker_container:
+name:nginx-proxy
+image:nginx:1.13
+state:started
+healthcheck:
+# The "NONE" check needs to be specified
+test:["NONE"]
+
+-name:Create a tmpfs with a size and mode
+community.docker.docker_container:
+name:tmpfs test
+image:ubuntu:22.04
+state:started
+mounts:
+-type:tmpfs
+target:/cache
+tmpfs_mode:"1700"# only readable to the owner
+tmpfs_size:"16G"
+
+-name:Start container with block device read limit
+community.docker.docker_container:
+name:test
+image:ubuntu:18.04
+state:started
+device_read_bps:
+# Limit read rate for /dev/sda to 20 mebibytes per second
+-path:/dev/sda
+rate:20M
+device_read_iops:
+# Limit read rate for /dev/sdb to 300 IO per second
+-path:/dev/sdb
+rate:300
+
+-name:Start container with GPUs
+community.docker.docker_container:
+name:test
+image:ubuntu:18.04
+state:started
+device_requests:
+# Add some specific devices to this container
+-device_ids:
+-'0'
+-'GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a'
+# Add nVidia GPUs to this container
+-driver:nvidia
+count:-1# this means we want all
+capabilities:
+# We have one OR condition: 'gpu' AND 'utility'
+--gpu
+-utility
+# See https://github.com/NVIDIA/nvidia-container-runtime#supported-driver-capabilities
+# for a list of capabilities supported by the nvidia driver
+
+-name:Start container with storage options
+community.docker.docker_container:
+name:test
+image:ubuntu:18.04
+state:started
+storage_opts:
+# Limit root filesystem to 12 MB - note that this requires special storage backends
+# (https://fabianlee.org/2020/01/15/docker-use-overlay2-with-an-xfs-backing-filesystem-to-limit-rootfs-size/)
+size:12m
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.docker.
+You need further requirements to be able to use this inventory plugin,
+see Requirements for details.
+
To use it in a playbook, specify: community.docker.docker_containers.
Add the same groups as the docker inventory script does. These are the following:
+
<containerid>: contains the container of this ID.
+
<containername>: contains the container that has this name.
+
<containershortid>: contains the containers that have this short ID (first 13 letters of ID).
+
image_<imagename>: contains the containers that have the image <imagename>.
+
stack_<stackname>: contains the containers that belong to the stack <stackname>.
+
service_<servicename>: contains the containers that belong to the service <servicename>.
+
<docker_host>: contains the containers which belong to the Docker daemon docker_host. Useful if you run this plugin against multiple Docker daemons.
+
running: contains all containers that are running.
+
stopped: contains all containers that are not running.
+
If this is not set to true, you should use keyed groups to add the containers to groups. See the examples for how to do that.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
+
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
+
+
+
+
compose
+
dictionary
+
+
Create vars from jinja2 expressions.
+
Default:{}
+
+
+
+
configure_docker_daemon
+
boolean
+
added in community.docker 1.8.0
+
+
Whether to pass all Docker daemon configuration from the inventory plugin to the connection plugin.
One way to connect to containers is to use SSH (ssh). For this, the options default_ip and private_ssh_port are used. This requires that a SSH daemon is running inside the containers.
When docker-api is used, all Docker daemon configuration values are passed from the inventory plugin to the connection plugin. This can be controlled with configure_docker_daemon.
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"
+
+
+
+
filters
+
list / elements=dictionary
+
added in community.docker 3.5.0
+
+
A list of include/exclude filters that allows to select/deselect hosts for this inventory.
+
Filters are processed sequentially until the first filter where filters[].exclude or filters[].include matches is found. In case filters[].exclude matches, the host is excluded, and in case filters[].include matches, the host is included. In case no filter matches, the host is included.
+
+
+
+
exclude
+
string
+
+
A Jinja2 condition. If it matches for a host, that host is excluded.
If yes make invalid entries a fatal error, otherwise skip and continue.
+
Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
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_extra_vars
+
boolean
+
added in ansible-core 2.11
+
+
Merge extra vars into the available variables for composition (highest precedence).
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
+
+
+
+
+
verbose_output
+
boolean
+
+
Toggle to (not) include all available inspection metadata.
+
Note that all top-level keys will be transformed to the format docker_xxx. For example, HostConfig is converted to docker_hostconfig.
The docker inventory script always added these variables, so for compatibility set this to true.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
+
+
Note
+
Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
+For example, a variable that is lower in the list will override a variable that is higher up.
+The entry types are also ordered by precedence from low to high priority order.
+For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+# Minimal example using local Docker daemon
+plugin:community.docker.docker_containers
+docker_host:unix:///var/run/docker.sock
+
+---
+# Minimal example using remote Docker daemon
+plugin:community.docker.docker_containers
+docker_host:tcp://my-docker-host:2375
+
+---
+# Example using remote Docker daemon with unverified TLS
+plugin:community.docker.docker_containers
+docker_host:tcp://my-docker-host:2376
+tls:true
+
+---
+# Example using remote Docker daemon with verified TLS and client certificate verification
+plugin:community.docker.docker_containers
+docker_host:tcp://my-docker-host:2376
+validate_certs:true
+ca_path:/somewhere/ca.pem
+client_key:/somewhere/key.pem
+client_cert:/somewhere/cert.pem
+
+---
+# Example using constructed features to create groups
+plugin:community.docker.docker_containers
+docker_host:tcp://my-docker-host:2375
+strict:false
+keyed_groups:
+# Add containers with primary network foo to a network_foo group
+-prefix:network
+key:'docker_hostconfig.NetworkMode'
+# Add Linux hosts to an os_linux group
+-prefix:os
+key:docker_platform
+
+---
+# Example using SSH connection with an explicit fallback for when port 22 has not been
+# exported: use container name as ansible_ssh_host and 22 as ansible_ssh_port
+plugin:community.docker.docker_containers
+connection_type:ssh
+compose:
+ansible_ssh_host:ansible_ssh_host | default(docker_name[1:], true)
+ansible_ssh_port:ansible_ssh_port | default(22, true)
+
+---
+# Only consider containers which have a label 'foo', or whose name starts with 'a'
+plugin:community.docker.docker_containers
+filters:
+# Accept all containers which have a label called 'foo'
+-include:>-
+"foo" in docker_config.Labels
+# Next accept all containers whose inventory_hostname starts with 'a'
+-include:>-
+inventory_hostname.startswith("a")
+# Exclude all containers that did not match any of the above filters
+-exclude:true
+
This includes some generic information, as well as a contexts[].config dictionary that can be used for module defaults for all community.docker modules that use the community.docker.docker module defaults group.
The module will fail if this context does not exist. If you simply want to query whether a context exists, do not specify this parameter and use Jinja2 to search the resulting list for a context of the given name instead.
---
+-name:Get infos on contexts
+community.docker.docker_context_info:
+register:result
+
+-name:Show all contexts
+ansible.builtin.debug:
+msg:"{{result.contexts}}"
+
+-name:Get current context
+community.docker.docker_context_info:
+only_current:true
+register:docker_current_context
+
+-name:Run community.docker modules with current context
+module_defaults:
+group/community.docker.docker:"{{docker_current_context.contexts[0].config}}"
+block:
+-name:Task using the current context
+community.docker.docker_container:
+image:ubuntu:latest
+name:ubuntu
+state:started
+
In case the context is for Docker, contains option values to configure the community.docker modules to use this context.
+
Note that the exact values returned here and their values might change over time if incompatibilities to existing modules are found. The goal is that this configuration works fine with all modules in this collection, but we do not have the capabilities to test all possible configuration options at the moment.
+
Returned: success
+
Sample:{}
+
+
+
+
ca_path
+
boolean
+
+
The CA certificate used to validate the Docker daemon’s certificate.
+
Returned: success, context is for Docker, TLS config is present, and CA cert is present
+
Sample:"/path/to/ca-cert.pem"
+
+
+
+
client_cert
+
boolean
+
+
The client certificate to authenticate with to the Docker daemon.
+
Returned: success, context is for Docker, TLS config is present, and client cert info is present
+
Sample:"/path/to/client-cert.pem"
+
+
+
+
client_key
+
boolean
+
+
The client certificate’s key to authenticate with to the Docker daemon.
+
Returned: success, context is for Docker, TLS config is present, and client cert info is present
+
Sample:"/path/to/client-key.pem"
+
+
+
+
docker_host
+
string
+
+
The Docker daemon to connect to.
+
Returned: success and context is for Docker
+
Sample:"unix:///var/run/docker.sock"
+
+
+
+
tls
+
boolean
+
+
Whether the Docker context should use an unvalidated TLS connection.
+
Returned: success and context is for Docker
+
Sample:false
+
+
+
+
validate_certs
+
boolean
+
+
Whether the Docker context should use a validated TLS connection.
+
Returned: success, context is for Docker, and TLS config is present
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_host_info.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
+
+
+
+
containers
+
boolean
+
+
Whether to list containers.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
containers_all
+
boolean
+
added in community.docker 3.4.0
+
+
By default, only running containers are returned.
+
This corresponds to the --all option to dockercontainerlist.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
containers_filters
+
dictionary
+
+
A dictionary of filter values used for selecting containers to list.
+
For example, until:24h.
+
label is a special case of filter which can be a string <key> matching when a label is present, a string <key>=<value> matching when a label has a particular value, or a list of strings <key>/<key>=<value.
Summary information on used disk space by all Docker layers.
+
The output is a sum of images, volumes, containers and build cache.
+
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"
+
+
+
+
images
+
boolean
+
+
Whether to list images.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
images_filters
+
dictionary
+
+
A dictionary of filter values used for selecting images to list.
+
For example, dangling:true.
+
label is a special case of filter which can be a string <key> matching when a label is present, a string <key>=<value> matching when a label has a particular value, or a list of strings <key>/<key>=<value.
A dictionary of filter values used for selecting networks to list.
+
label is a special case of filter which can be a string <key> matching when a label is present, a string <key>=<value> matching when a label has a particular value, or a list of strings <key>/<key>=<value.
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.
The verbose output in this module contains only subset of information returned by this module for each type of the objects.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
volumes
+
boolean
+
+
Whether to list volumes.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
volumes_filters
+
dictionary
+
+
A dictionary of filter values used for selecting volumes to list.
+
label is a special case of filter which can be a string <key> matching when a label is present, a string <key>=<value> matching when a label has a particular value, or a list of strings <key>/<key>=<value.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+-name:Get info on docker host
+community.docker.docker_host_info:
+register:result
+
+-name:Get info on docker host and list images
+community.docker.docker_host_info:
+images:true
+register:result
+
+-name:Get info on docker host and list images matching the filter
+community.docker.docker_host_info:
+images:true
+images_filters:
+label:"mylabel"
+register:result
+
+-name:Get info on docker host and verbose list images
+community.docker.docker_host_info:
+images:true
+verbose_output:true
+register:result
+
+-name:Get info on docker host and used disk space
+community.docker.docker_host_info:
+disk_usage:true
+register:result
+
+-name:Get info on docker host and list containers matching the filter
+community.docker.docker_host_info:
+containers:true
+containers_filters:
+label:
+-key1=value1
+-key2=value2
+register:result
+
+-name:Show host information
+ansible.builtin.debug:
+var:result.host_info
+
Common return values are documented here, the following are the fields unique to this module:
+
+
+
Key
+
Description
+
+
+
+
+
can_talk_to_docker
+
boolean
+
+
Will be true if the module can talk to the docker daemon.
+
Returned: both on success and on error
+
+
+
+
containers
+
list / elements=dictionary
+
+
List of dict objects containing the basic information about each container. Keys matches the dockercontainerls output unless verbose_output=true. See description for verbose_output.
Facts representing the basic state of the docker host. Matches the dockersysteminfo output.
+
Returned: always
+
+
+
+
images
+
list / elements=dictionary
+
+
List of dict objects containing the basic information about each image. Keys matches the dockerimagels output unless verbose_output=true. See description for verbose_output.
List of dict objects containing the basic information about each network. Keys matches the dockernetworkls output unless verbose_output=true. See description for verbose_output.
List of dict objects containing the basic information about each volume. Keys matches the dockervolumels output unless verbose_output=true. See description for verbose_output.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_build.
This module allows you to build Docker images using Docker’s buildx plugin (BuildKit).
+
Note that the module is not idempotent in the sense of classical Ansible modules. The only idempotence check is whether the built image already exists. This check can be disabled with the rebuild option.
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"
+
+
+
+
args
+
dictionary
+
+
Provide a dictionary of key:value build arguments that map to Dockerfile ARG directive.
+
Docker expects the value to be a string. For convenience any non-string values will be converted to strings.
+
+
+
+
+
+
+
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.
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.
+
Mutually exclusive with cli_context. If neither docker_host nor cli_context are provided, the value unix:///var/run/docker.sock is used.
+
+
+
+
dockerfile
+
string
+
+
Provide an alternate name for the Dockerfile to use when building an image.
+
This can also include a relative path (relative to path).
+
+
+
+
etc_hosts
+
dictionary
+
+
Extra hosts to add to /etc/hosts in building containers, as a mapping of hostname to IP address.
+
Instead of an IP address, the special value host-gateway can also be used, which resolves to the host’s gateway IP and allows building containers to connect to services running on the host.
+
+
+
+
labels
+
dictionary
+
+
Dictionary of key value pairs.
+
+
+
+
name
+
string / required
+
+
Image name. Name format will be one of: name, repository/name, registry_server:port/name. When pushing or pulling an image the name can optionally include the tag by appending :tag_name.
+
Note that image IDs (hashes) and names with digest cannot be used.
+
+
+
+
network
+
string
+
+
The network to use for RUN build instructions.
+
+
+
+
nocache
+
boolean
+
+
Do not use cache when building an image.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
outputs
+
list / elements=dictionary
+
added in community.docker 3.10.0
+
+
Output destinations.
+
You can provide a list of exporters to export the built image in various places. Note that not all exporters might be supported by the build driver used.
+
Note that depending on how this option is used, no image with name name and tag tag might be created, which can cause the basic idempotency this module offers to not work.
+
Providing an empty list to this option is equivalent to not specifying it at all. The default behavior is a single entry with outputs[].type=image.
+
Note that since community.docker 4.2.0, an entry for name/tag is added if outputs has at least one entry and no entry has type outputs[].type=image and includes name/tag in outputs[].name. This is because the module would otherwise pass --tagname:image to the buildx plugin, which for some reason overwrites all images in outputs by the name:image provided in name/tag.
+
+
+
+
context
+
string
+
+
Name for the Docker context where to import the result.
"docker":
+This export type writes the single-platform result image as a Docker image specification tarball on the client. Tarballs created by this exporter are also OCI compatible.
+
The destination can be provided in outputs[].dest. If not specified, the tar will be loaded automatically to the local image store.
+
The Docker context where to import the result can be provided in outputs[].context.
+
+
"image":
+This exporter writes the build result as an image or a manifest list. When using this driver, the image will appear in dockerimages.
+
The image name can be provided in outputs[].name. If it is not provided, name and tag will be used.
+
Optionally, image can be automatically pushed to a registry by setting outputs[].push=true.
+
+
"local":
+This export type writes all result files to a directory on the client. The new files will be owned by the current user. On multi-platform builds, all results will be put in subdirectories by their platform.
"tar":
+This export type export type writes all result files as a single tarball on the client. On multi-platform builds, all results will be put in subdirectories by their platform.
Size of /dev/shm in format <number>[<unit>]. Number is positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses 64M.
If name‘s format is name:tag, then the tag value from name will take precedence.
+
Default:"latest"
+
+
+
+
target
+
string
+
+
When building an image specifies an intermediate build stage by name as a final stage for the resulting image.
+
+
+
+
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.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_export.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
force
+
boolean
+
+
Export the image even if the .tar file already exists and seems to contain the right image.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
+
names
+
aliases: name
+
list / elements=string / required
+
+
One or more image names. Name format will be one of: name, repository/name, registry_server:port/name. When pushing or pulling an image the name can optionally include the tag by appending :tag_name.
If name‘s format is name:tag, then the tag value from name will take precedence.
+
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.
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.
+
+
+
+
idempotent
+
+
Support: partial
+
Whether the module is idempotent depends on the storage API used for images, which determines how the image ID is computed. The idempotency check needs that the image ID equals the ID stored in archive’s manifest.json. This seemed to have worked fine with the default storage backend up to Docker 28, but seems to have changed in Docker 29.
+
+
When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.
+
This assumes that the system controlled/queried by the module has not changed in a relevant way.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_info.
Provide one or more image names, and the module will inspect each, returning an array of inspection results.
+
If an image does not exist locally, it will not appear in the results. If you want to check whether an image exists locally, you can call the module with the image name, then check whether the result list is empty (image does not exist) or has one element (the image exists locally).
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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
+
list / elements=string
+
+
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. Instead of image names, also image IDs can be used.
+
If no name is provided, a list of all images will be returned.
+
+
+
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_load.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
path
+
path / required
+
+
The path to the .tar archive to load Docker image(s) from.
+
+
+
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+-name:Load all image(s) from the given tar file
+community.docker.docker_image_load:
+path:/path/to/images.tar
+register:result
+
+-name:Print the loaded image names
+ansible.builtin.debug:
+msg:"Loadedthefollowingimages:{{result.image_names|join(', ')}}"
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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.
Build, load or pull an image, making the image available for creating containers. Also supports tagging an image, pushing an image, and archiving an image to a .tar file.
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"
+
+
+
+
archive_path
+
path
+
+
Use with state=present to archive an image to a .tar file.
+
+
+
+
build
+
dictionary
+
+
Specifies options used for building images.
+
+
+
+
args
+
dictionary
+
+
Provide a dictionary of key:value build arguments that map to Dockerfile ARG directive.
+
Docker expects the value to be a string. For convenience any non-string values will be converted to strings.
+
+
+
+
cache_from
+
list / elements=string
+
+
List of image names to consider as cache source.
+
+
+
+
container_limits
+
dictionary
+
+
A dictionary of limits applied to each container created by the build process.
+
+
+
+
cpusetcpus
+
string
+
+
CPUs in which to allow execution.
+
For example, 0-3 or 0,1.
+
+
+
+
cpushares
+
integer
+
+
CPU shares (relative weight).
+
+
+
+
memory
+
string
+
+
Memory limit for build in format <number>[<unit>]. Number is a positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
Omitting the unit defaults to bytes.
+
Before community.docker 3.6.0, no units were allowed.
+
+
+
+
memswap
+
string
+
+
Total memory limit (memory + swap) for build in format <number>[<unit>], or the special values unlimited or -1 for unlimited swap usage. Number is a positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
Omitting the unit defaults to bytes.
+
Before community.docker 3.6.0, no units were allowed, and neither was the special value unlimited.
+
+
+
+
dockerfile
+
string
+
+
Use with state=present and source=build to provide an alternate name for the Dockerfile to use when building an image.
+
This can also include a relative path (relative to build.path).
+
+
+
+
etc_hosts
+
dictionary
+
+
Extra hosts to add to /etc/hosts in building containers, as a mapping of hostname to IP address.
+
Instead of an IP address, the special value host-gateway can also be used, which resolves to the host’s gateway IP and allows building containers to connect to services running on the host.
+
+
+
+
http_timeout
+
integer
+
+
Timeout for HTTP requests during the image build operation. Provide a positive integer value for the number of seconds.
+
+
+
+
labels
+
dictionary
+
added in community.docker 3.6.0
+
+
Dictionary of key value pairs.
+
+
+
+
network
+
string
+
+
The network to use for RUN build instructions.
+
+
+
+
nocache
+
boolean
+
+
Do not use cache when building an image.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
path
+
path / required
+
+
Use with state ‘present’ to build an image. Will be the path to a directory containing the context and Dockerfile for building an image.
+
+
+
+
platform
+
string
+
added in community.docker 1.1.0
+
+
Platform in the format os[/arch[/variant]].
+
+
+
+
pull
+
boolean
+
+
When building an image downloads any updates to the FROM image in Dockerfile.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
rm
+
boolean
+
+
Remove intermediate containers after build.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
shm_size
+
string
+
added in community.docker 3.6.0
+
+
Size of /dev/shm in format <number>[<unit>]. Number is positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses 64M.
+
+
+
+
target
+
string
+
+
When building an image specifies an intermediate build stage by name as a final stage for the resulting image.
+
+
+
+
use_config_proxy
+
boolean
+
+
If set to true and a proxy configuration is specified in the docker client configuration (by default $HOME/.docker/config.json), the corresponding environment variables will be set in the container being built.
+
Choices:
+
+
false
+
true
+
+
+
+
+
+
+
+
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
force_absent
+
boolean
+
+
Use with state=absent to un-tag and remove all images matching the specified name.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
force_source
+
boolean
+
+
Use with state=present to build, load or pull an image (depending on the value of the source option) when the image already exists.
Image name. Name format will be one of: name, repository/name, registry_server:port/name. When pushing or pulling an image the name can optionally include the tag by appending :tag_name.
Expects format repository:tag. If no tag is provided, will use the value of the tag parameter or latest.
+
If push=true, repository must either include a registry, or will be assumed to belong to the default registry (Docker Hub).
+
+
+
+
source
+
string
+
+
Determines where the module will try to retrieve the image from.
+
Use build to build the image from a Dockerfile. build.path must be specified when this value is used.
+
Use load to load the image from a .tar file. load_path must be specified when this value is used.
+
Use pull to pull the image from a registry.
+
Use local to make sure that the image is already available on the local docker daemon. This means that the module does not try to build, pull or load the image.
+
Choices:
+
+
"build"
+
"load"
+
"pull"
+
"local"
+
+
+
+
+
state
+
string
+
+
Make assertions about the state of an image.
+
When absent an image will be removed. Use the force option to un-tag and remove all images matching the provided name.
+
When present check if an image exists using the provided name and tag. If the image is not found or the force option is used, the image will either be pulled, built or loaded, depending on the source option.
+
Choices:
+
+
"absent"
+
"present"← (default)
+
+
+
+
+
tag
+
string
+
+
Used to select an image when pulling. Will be added to the image when pushing, tagging or building. Defaults to latest.
+
If name parameter format is name:tag, then tag value from name will take precedence.
+
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.
Building images is done using Docker daemon’s API. It is not possible to use BuildKit / buildx this way. Use community.docker.docker_image_build to build images with BuildKit.
+
Exporting images is generally not idempotent. It depends on whether the image ID equals the IDs found in the generated tarball’s manifest.json. This was the case with the default storage backend up to Docker 28, but seems to have changed in Docker 29.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+-name:Pull an image
+community.docker.docker_image:
+name:pacur/centos-7
+source:pull
+# Select platform for pulling. If not specified, will pull whatever docker prefers.
+pull:
+platform:amd64
+
+-name:Tag and push to docker hub
+community.docker.docker_image:
+name:pacur/centos-7:56
+repository:dcoppenhagan/myimage:7.56
+push:true
+source:local
+
+-name:Tag and push to local registry
+community.docker.docker_image:
+# Image will be centos:7
+name:centos
+# Will be pushed to localhost:5000/centos:7
+repository:localhost:5000/centos
+tag:7
+push:true
+source:local
+
+-name:Add tag latest to image
+community.docker.docker_image:
+name:myimage:7.1.2
+repository:myimage:latest
+# As 'latest' usually already is present, we need to enable overwriting of existing tags:
+force_tag:true
+source:local
+
+-name:Remove image
+community.docker.docker_image:
+state:absent
+name:registry.ansible.com/chouseknecht/sinatra
+tag:v1
+
+-name:Build an image and push it to a private repo
+community.docker.docker_image:
+build:
+path:./sinatra
+name:registry.ansible.com/chouseknecht/sinatra
+tag:v1
+push:true
+source:build
+
+-name:Archive image
+community.docker.docker_image:
+name:registry.ansible.com/chouseknecht/sinatra
+tag:v1
+archive_path:my_sinatra.tar
+source:local
+
+-name:Load image from archive and push to a private registry
+community.docker.docker_image:
+name:localhost:5000/myimages/sinatra
+tag:v1
+push:true
+load_path:my_sinatra.tar
+source:load
+
+-name:Build image and with build args
+community.docker.docker_image:
+name:myimage
+build:
+path:/path/to/build/dir
+args:
+log_volume:/var/log/myapp
+listen_port:8080
+source:build
+
+-name:Build image using cache source
+community.docker.docker_image:
+name:myimage:latest
+build:
+path:/path/to/build/dir
+# Use as cache source for building myimage
+cache_from:
+-nginx:latest
+-alpine:3.8
+source:build
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+-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
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_push.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
+
+
+
+
tag
+
string
+
+
Select which image to push. 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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_remove.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
force
+
boolean
+
+
Un-tag and remove all images matching the specified name.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
name
+
string / required
+
+
Image name. Name format will be one of: name, repository/name, registry_server:port/name. When pushing or pulling an image the name can optionally include the tag by appending :tag_name.
If name‘s format is name:tag, then the tag value from name will take precedence.
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_tag.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
existing_images
+
string
+
+
Defines the behavior if the image to be tagged already exists and is another image than the one identified by name and tag.
+
If set to keep, the tagged image is kept.
+
If set to overwrite, the tagged image is overwritten by the specified one.
+
Choices:
+
+
"keep"
+
"overwrite"← (default)
+
+
+
+
+
name
+
string / required
+
+
Image name. Name format will be one of: name, repository/name, registry_server:port/name. When pushing or pulling an image the name can optionally include the tag by appending :tag_name.
+
Note that image IDs (hashes) can also be used.
+
+
+
+
repository
+
list / elements=string / required
+
+
List of new image names to tag the image as.
+
Expects format repository:tag. If no tag is provided, will use the value of the tag parameter if present, or latest.
If name‘s format is name:tag, then the tag value from name will take precedence.
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+-name:Tag Python 3.12 image with two new names
+community.docker.docker_image_tag:
+name:python:3.12
+repository:
+-python-3:3.12
+-local-registry:5000/python-3/3.12:latest
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_login.
Provides functionality similar to the dockerlogin command.
+
Authenticate with a docker registry and add the credentials to your local Docker config file respectively the credentials store associated to the registry. Adding the credentials to the config files resp. the credential store allows future connections to the registry using tools such as Ansible’s Docker modules, the Docker CLI and Docker SDK for Python without needing to provide credentials.
+
Running in check mode will perform the authentication without updating the config file.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
+
+
+
+
+
config_path
+
aliases: dockercfg_path
+
path
+
+
Custom path to the Docker CLI configuration file.
+
Default:"~/.docker/config.json"
+
+
+
+
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.
Refresh existing authentication found in the configuration file.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
+
+
registry_url
+
aliases: registry, url
+
string
+
+
The registry URL.
+
Default:"https://index.docker.io/v1/"
+
+
+
+
state
+
string
+
+
This controls the current state of the user. present will login in a user, absent will log them out.
+
To logout you only need the registry server, which defaults to DockerHub.
+
Before 2.1 you could ONLY log in.
+
Docker does not support ‘logout’ with a custom config file.
+
Choices:
+
+
"present"← (default)
+
"absent"
+
+
+
+
+
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.
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+-name:Log into DockerHub
+community.docker.docker_login:
+username:docker
+password:rekcod
+
+-name:Log into private registry and force re-authorization
+community.docker.docker_login:
+registry_url:your.private.registry.io
+username:yourself
+password:secrets3
+reauthorize:true
+
+-name:Log into DockerHub using a custom config file
+community.docker.docker_login:
+username:docker
+password:rekcod
+config_path:/tmp/.mydockercfg
+
+-name:Log out of DockerHub
+community.docker.docker_login:
+state:absent
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.docker.
+You need further requirements to be able to use this inventory plugin,
+see Requirements for details.
+
To use it in a playbook, specify: community.docker.docker_machine.
Whether docker daemon connection environment variables should be fetched, and how to behave if they cannot be fetched.
+
With require and require-silently, fetch them and skip any host for which they cannot be fetched. A warning will be issued for any skipped host if the choice is require.
+
With optional and optional-silently, fetch them and not skip hosts for which they cannot be fetched. A warning will be issued for hosts where they cannot be fetched if the choice is optional.
+
With skip, do not attempt to fetch the docker daemon connection environment variables.
+
If fetched successfully, the variables will be prefixed with dm_ and stored as host variables.
+
Choices:
+
+
"require"← (default)
+
"require-silently"
+
"optional"
+
"optional-silently"
+
"skip"
+
+
+
+
+
filters
+
list / elements=dictionary
+
added in community.docker 3.5.0
+
+
A list of include/exclude filters that allows to select/deselect hosts for this inventory.
+
Filters are processed sequentially until the first filter where filters[].exclude or filters[].include matches is found. In case filters[].exclude matches, the host is excluded, and in case filters[].include matches, the host is included. In case no filter matches, the host is included.
+
+
+
+
exclude
+
string
+
+
A Jinja2 condition. If it matches for a host, that host is excluded.
When true, include all available nodes metadata (for example Image, Region, Size) as a JSON object named docker_machine_node_attributes.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
+
+
Note
+
Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
+For example, a variable that is lower in the list will override a variable that is higher up.
+The entry types are also ordered by precedence from low to high priority order.
+For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
---
+# Minimal example
+plugin:community.docker.docker_machine
+
+---
+# Example using constructed features to create a group per Docker Machine driver
+# (https://docs.docker.com/machine/drivers/), for example:
+# $ docker-machine create --driver digitalocean ... mymachine
+# $ ansible-inventory -i ./path/to/docker-machine.yml --host=mymachine
+# {
+# ...
+# "digitalocean": {
+# "hosts": [
+# "mymachine"
+# ]
+# ...
+# }
+plugin:community.docker.docker_machine
+strict:false
+keyed_groups:
+-separator:''
+key:docker_machine_node_attributes.DriverName
+
+---
+# Example grouping hosts by Digital Machine tag
+plugin:community.docker.docker_machine
+strict:false
+keyed_groups:
+-prefix:tag
+key:'dm_tags'
+
+---
+# Example using compose to override the default SSH behaviour of asking the user to accept the remote host key
+plugin:community.docker.docker_machine
+compose:
+ansible_ssh_common_args:'"-oStrictHostKeyChecking=accept-new"'
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_network_info.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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
+
+
The name of the network to inspect.
+
When identifying an existing network name may be a name or a long or short network ID.
+
+
+
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_network.
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"
+
+
+
+
+
appends
+
aliases: incremental
+
boolean
+
+
By default the connected list is canonical, meaning containers not on the list are removed from the network.
+
Use appends to leave existing containers connected.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
attachable
+
boolean
+
+
If enabled, and the network is in the global scope, non-service containers on worker nodes will be able to connect to the network.
+
Choices:
+
+
false
+
true
+
+
+
+
+
+
+
+
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
+
+
+
+
config_from
+
string
+
added in community.docker 3.10.0
+
+
Specifies the config only network to use the config from.
+
+
+
+
config_only
+
boolean
+
added in community.docker 3.10.0
+
+
Sets that this is a config only network.
+
Choices:
+
+
false
+
true
+
+
+
+
+
+
connected
+
aliases: containers
+
list / elements=string
+
+
List of container names or container IDs to connect to a network.
+
Please note that the module only makes sure that these containers are connected to the network, but does not care about connection options. If you rely on specific IP addresses and so on, use the community.docker.docker_container module to ensure your containers are correctly connected to this network.
+
Default:[]
+
+
+
+
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"
+
+
+
+
driver
+
string
+
+
Specify the type of network. Docker provides bridge and overlay drivers, but 3rd party drivers can also be used.
+
Default:"bridge"
+
+
+
+
driver_options
+
dictionary
+
+
Dictionary of network settings. Consult docker docs for valid options and values.
+
Default:{}
+
+
+
+
enable_ipv4
+
boolean
+
added in community.docker 4.5.0
+
+
Enable IPv4 networking.
+
This is enabled by default, but can be explicitly disabled.
+
Requires Docker API 1.47 or newer.
+
Choices:
+
+
false
+
true
+
+
+
+
+
enable_ipv6
+
boolean
+
+
Enable IPv6 networking.
+
Choices:
+
+
false
+
true
+
+
+
+
+
force
+
boolean
+
+
With state present will disconnect all containers for existing networks, delete the network and re-create the network.
+
This option is required if you have changed the IPAM or driver options and want an existing network to be updated to use the new options.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
ingress
+
boolean
+
added in community.docker 4.2.0
+
+
Enable Swarm routing-mesh.
+
Choices:
+
+
false
+
true
+
+
+
+
+
internal
+
boolean
+
+
Restrict external access to the network.
+
Choices:
+
+
false
+
true
+
+
+
+
+
ipam_config
+
list / elements=dictionary
+
+
List of IPAM config blocks. Consult Docker docs for valid options and values. Note that ipam_config[].iprange is spelled differently here (we use the notation from the Docker SDK for Python).
+
+
+
+
aux_addresses
+
dictionary
+
+
Auxiliary IP addresses used by Network driver, as a mapping from hostname to IP.
+
+
+
+
gateway
+
string
+
+
IP gateway address.
+
+
+
+
iprange
+
string
+
+
IP address range in CIDR notation.
+
+
+
+
subnet
+
string
+
+
IP subset in CIDR notation.
+
+
+
+
ipam_driver
+
string
+
+
Specify an IPAM driver.
+
+
+
+
ipam_driver_options
+
dictionary
+
+
Dictionary of IPAM driver options.
+
+
+
+
labels
+
dictionary
+
+
Dictionary of labels.
+
Default:{}
+
+
+
+
+
name
+
aliases: network_name
+
string / required
+
+
Name of the network to operate on.
+
+
+
+
scope
+
string
+
+
Specify the network’s scope.
+
Choices:
+
+
"local"
+
"global"
+
"swarm"
+
+
+
+
+
state
+
string
+
+
absent deletes the network. If a network has connected containers, these will be detached from the network.
+
present creates the network, if it does not already exist with the specified parameters, and connects the list of containers provided by the connected parameter. Containers not on the list will be disconnected. An empty list will leave no containers connected to the network. Use the appends option to leave existing containers connected. Use the force options to force re-creation of the network.
+
Choices:
+
+
"absent"
+
"present"← (default)
+
+
+
+
+
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.
When network options are changed, the module disconnects all containers from the network, deletes the network, and re-creates the network. It does not try to reconnect containers, except the ones listed in (connected, and even for these, it does not consider specific connection options like fixed IP addresses or MAC addresses. If you need more control over how the containers are connected to the network, loop the community.docker.docker_container module to loop over your containers to make sure they are connected properly.
+
The module does not support Docker Swarm. This means that it will not try to disconnect or reconnect services. If services are connected to the network, deleting the network will fail. When network options are changed, the network has to be deleted and recreated, so this will fail as well.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_node_info.
The below requirements are needed on the host that executes this module.
+
+
Docker API >= 1.25
+
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). This module does not work with docker-py.
The version of the Docker API running on the Docker Host.
+
Defaults to the latest version of the API supported by Docker SDK for Python 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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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
+
list / elements=string
+
+
The name of the node to inspect.
+
The list of nodes names to inspect.
+
If empty then return information of all nodes in Swarm cluster.
+
When identifying the node use either the hostname of the node (as registered in Swarm) or node ID.
If false then query depends on name presence and value.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
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.
+
Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error.
+
+
+
+
use_ssh_client
+
boolean
+
added in community.docker 1.5.0
+
+
For SSH transports, use the ssh CLI tool instead of paramiko.
+
Requires Docker SDK for Python 4.4.0 or newer.
+
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.
When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls] with ansible.builtin.pip.
+
Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/.docker/config.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.
---
+-name:Get info on all nodes
+community.docker.docker_node_info:
+register:result
+
+-name:Get info on node
+community.docker.docker_node_info:
+name:mynode
+register:result
+
+-name:Get info on list of nodes
+community.docker.docker_node_info:
+name:
+-mynode1
+-mynode2
+register:result
+
+-name:Get info on host if it is Swarm Manager
+community.docker.docker_node_info:
+self:true
+register:result
+
Common return values are documented here, the following are the fields unique to this module:
+
+
+
Key
+
Description
+
+
+
+
+
nodes
+
list / elements=dictionary
+
+
Facts representing the current state of the nodes. Matches the dockernodeinspect output.
+
Can contain multiple entries if more than one node provided in name, or name is not provided.
+
If name contains a list of nodes, the output will provide information on all nodes registered at the swarm, including nodes that left the swarm but have not been removed from the cluster on swarm managers and nodes that are unreachable.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_node.
The below requirements are needed on the host that executes this module.
+
+
Docker API >= 1.25
+
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). This module does not work with docker-py.
The version of the Docker API running on the Docker Host.
+
Defaults to the latest version of the API supported by Docker SDK for Python 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"
+
+
+
+
availability
+
string
+
+
Node availability to assign. If not provided then node availability remains unchanged.
+
Choices:
+
+
"active"
+
"pause"
+
"drain"
+
+
+
+
+
+
+
+
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
hostname
+
string / required
+
+
The hostname or ID of node as registered in Swarm.
+
If more than one node is registered using the same hostname the ID must be used, otherwise module will fail.
+
+
+
+
labels
+
dictionary
+
+
User-defined key/value metadata that will be assigned as node attribute.
+
Label operations in this module apply to the docker swarm node specified by hostname. Use community.docker.docker_swarm module to add/modify/remove swarm cluster labels.
+
The actual state of labels assigned to the node when module completes its work depends on labels_state and labels_to_remove parameters values. See description below.
+
+
+
+
labels_state
+
string
+
+
It defines the operation on the labels assigned to node and labels specified in labels option.
+
Set to merge to combine labels provided in labels with those already assigned to the node. If no labels are assigned then it will add listed labels. For labels that are already assigned to the node, it will update their values. The labels not specified in labels will remain unchanged. If labels is empty then no changes will be made.
+
Set to replace to replace all assigned labels with provided ones. If labels is empty then all labels assigned to the node will be removed.
+
Choices:
+
+
"merge"← (default)
+
"replace"
+
+
+
+
+
labels_to_remove
+
list / elements=string
+
+
List of labels that will be removed from the node configuration. The list has to contain only label names, not their values.
+
If the label provided on the list is not assigned to the node, the entry is ignored.
+
If the label is both on the labels_to_remove and labels, then value provided in labels remains assigned to the node.
Node role to assign. If not provided then node role remains unchanged.
+
Choices:
+
+
"manager"
+
"worker"
+
+
+
+
+
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.
+
Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error.
+
+
+
+
use_ssh_client
+
boolean
+
added in community.docker 1.5.0
+
+
For SSH transports, use the ssh CLI tool instead of paramiko.
+
Requires Docker SDK for Python 4.4.0 or newer.
+
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.
When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls] with ansible.builtin.pip.
+
Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/.docker/config.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_plugin.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
enable_timeout
+
integer
+
+
Timeout in seconds.
+
Default:0
+
+
+
+
force_remove
+
boolean
+
+
Remove even if the plugin is enabled.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
plugin_name
+
string / required
+
+
Name of the plugin to operate on.
+
+
+
+
plugin_options
+
dictionary
+
+
Dictionary of plugin settings.
+
Default:{}
+
+
+
+
state
+
string
+
+
absent remove the plugin.
+
present install the plugin, if it does not already exist.
+
enable enable the plugin.
+
disable disable the plugin.
+
Choices:
+
+
"absent"
+
"present"← (default)
+
"enable"
+
"disable"
+
+
+
+
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_prune.
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"
+
+
+
+
builder_cache
+
boolean
+
+
Whether to prune the builder cache.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
builder_cache_all
+
boolean
+
added in community.docker 3.10.0
+
+
Whether to remove all types of build cache.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
builder_cache_filters
+
dictionary
+
added in community.docker 3.10.0
+
+
A dictionary of filter values used for selecting images to delete.
Amount of disk space to keep for cache in format <number>[<unit>].”.
+
Number is a positive integer. Unit can be one of B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
Omitting the unit defaults to bytes.
+
+
+
+
+
+
+
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
+
+
+
+
containers
+
boolean
+
+
Whether to prune containers.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
containers_filters
+
dictionary
+
+
A dictionary of filter values used for selecting containers to delete.
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"
+
+
+
+
images
+
boolean
+
+
Whether to prune images.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
images_filters
+
dictionary
+
+
A dictionary of filter values used for selecting images to delete.
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
+
+
+
+
+
volumes
+
boolean
+
+
Whether to prune volumes.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
volumes_filters
+
dictionary
+
+
A dictionary of filter values used for selecting volumes to delete.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
---
+-name:Prune containers older than 24h
+community.docker.docker_prune:
+containers:true
+containers_filters:
+# only consider containers created more than 24 hours ago
+until:24h
+
+-name:Prune containers with labels
+community.docker.docker_prune:
+containers:true
+containers_filters:
+# Prune containers whose "foo" label has value "bar", and
+# whose "bam" label has value "baz". If you only want to
+# compare one label, you can provide it as a string instead
+# of a list with one element.
+label:
+-foo=bar
+-bam=baz
+# Prune containers whose label "bar" does *not* have value
+# "baz". If you want to avoid more than one label, you can
+# provide a list of multiple label-value pairs.
+"label!":bar=baz
+
+-name:Prune everything
+community.docker.docker_prune:
+containers:true
+images:true
+networks:true
+volumes:true
+builder_cache:true
+
+-name:Prune everything (including non-dangling images)
+community.docker.docker_prune:
+containers:true
+images:true
+images_filters:
+dangling:false
+networks:true
+volumes:true
+builder_cache:true
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_secret.
Create and remove Docker secrets in a Swarm environment. Similar to dockersecretcreate and dockersecretrm.
+
Adds to the metadata of new secrets ansible_key, an encrypted hash representation of the data, which is then used in future runs to test if a secret has changed. If ansible_key is not present, then a secret will not be updated unless the force option is set.
+
Updates to secrets are performed by removing the secret and creating it again.
The below requirements are needed on the host that executes this module.
+
+
Docker API >= 1.25
+
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). This module does not work with docker-py.
The version of the Docker API running on the Docker Host.
+
Defaults to the latest version of the API supported by Docker SDK for Python 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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
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"
+
+
+
+
force
+
boolean
+
+
Use with state=present to always remove and recreate an existing secret.
+
If true, an existing secret will be replaced, even if it has not changed.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
labels
+
dictionary
+
+
A map of key:value meta data, where both key and value are expected to be strings.
+
If new meta data is provided, or existing meta data is modified, the secret will be updated by removing it and creating it again.
+
+
+
+
name
+
string / required
+
+
The name of the secret.
+
+
+
+
rolling_versions
+
boolean
+
added in community.docker 2.2.0
+
+
If set to true, secrets are created with an increasing version number appended to their name.
+
Adds a label containing the version number to the managed secrets with the name ansible_version.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
state
+
string
+
+
Set to present, if the secret should exist, and absent, if it should not.
+
Choices:
+
+
"absent"
+
"present"← (default)
+
+
+
+
+
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.
+
Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error.
+
+
+
+
use_ssh_client
+
boolean
+
added in community.docker 1.5.0
+
+
For SSH transports, use the ssh CLI tool instead of paramiko.
+
Requires Docker SDK for Python 4.4.0 or newer.
+
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
+
+
+
+
+
versions_to_keep
+
integer
+
added in community.docker 2.2.0
+
+
When using rolling_versions, the number of old versions of the secret to keep.
+
Extraneous old secrets are deleted after the new one is created.
+
Set to -1 to keep everything or to 0 or 1 to keep only the current one.
When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls] with ansible.builtin.pip.
+
Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/.docker/config.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.
---
+-name:Create secret foo (from a file on the control machine)
+community.docker.docker_secret:
+name:foo
+# If the file is JSON or binary, Ansible might modify it (because
+# it is first decoded and later re-encoded). Base64-encoding the
+# file directly after reading it prevents this to happen.
+data:"{{lookup('file','/path/to/secret/file')|b64encode}}"
+data_is_b64:true
+state:present
+
+-name:Create secret foo (from a file on the target machine)
+community.docker.docker_secret:
+name:foo
+data_src:/path/to/secret/file
+state:present
+
+-name:Change the secret data
+community.docker.docker_secret:
+name:foo
+data:Goodnight everyone!
+labels:
+bar:baz
+one:'1'
+state:present
+
+-name:Add a new label
+community.docker.docker_secret:
+name:foo
+data:Goodnight everyone!
+labels:
+bar:baz
+one:'1'
+# Adding a new label will cause a remove/create of the secret
+two:'2'
+state:present
+
+-name:No change
+community.docker.docker_secret:
+name:foo
+data:Goodnight everyone!
+labels:
+bar:baz
+one:'1'
+# Even though 'two' is missing, there is no change to the existing secret
+state:present
+
+-name:Update an existing label
+community.docker.docker_secret:
+name:foo
+data:Goodnight everyone!
+labels:
+bar:monkey# Changing a label will cause a remove/create of the secret
+one:'1'
+state:present
+
+-name:Force the removal/creation of the secret
+community.docker.docker_secret:
+name:foo
+data:Goodnight everyone!
+force:true
+state:present
+
+-name:Remove secret foo
+community.docker.docker_secret:
+name:foo
+state:absent
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_stack_info.
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
+
added in community.docker 3.6.0
+
+
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.
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
+
added in community.docker 3.6.0
+
+
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
+
added in community.docker 3.6.0
+
+
Path to the Docker CLI. If not provided, will search for Docker CLI on the PATH.
+
+
+
+
+
docker_host
+
aliases: docker_url
+
string
+
added in community.docker 3.6.0
+
+
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.
+
Mutually exclusive with cli_context. If neither docker_host nor cli_context are provided, the value unix:///var/run/docker.sock is used.
+
+
+
+
tls
+
boolean
+
added in community.docker 3.6.0
+
+
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
+
added in community.docker 3.6.0
+
+
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
+
added in community.docker 3.6.0
+
+
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.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_stack.
If larger than 0 and state=absent the module will retry up to absent_retries times to delete the stack until all the resources have been effectively deleted. If the last try still reports the stack as not completely removed the module will fail.
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
+
added in community.docker 3.6.0
+
+
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.
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
+
added in community.docker 3.6.0
+
+
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.
+
+
+
+
compose
+
list / elements=any
+
+
List of compose definitions. Any element may be a string referring to the path of the compose file on the target host or the YAML contents of a compose file nested as dictionary.
+
Default:[]
+
+
+
+
detach
+
boolean
+
added in community.docker 4.1.0
+
+
If false, the --detach=false option is added to the dockerstackdeploy command, allowing Docker to wait for tasks to converge before exiting.
+
If true (default), Docker exits immediately instead of waiting for tasks to converge.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
docker_cli
+
path
+
added in community.docker 3.6.0
+
+
Path to the Docker CLI. If not provided, will search for Docker CLI on the PATH.
+
+
+
+
+
docker_host
+
aliases: docker_url
+
string
+
added in community.docker 3.6.0
+
+
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.
+
Mutually exclusive with cli_context. If neither docker_host nor cli_context are provided, the value unix:///var/run/docker.sock is used.
+
+
+
+
name
+
string / required
+
+
Stack name.
+
+
+
+
prune
+
boolean
+
+
If true will add the --prune option to the dockerstackdeploy command. This will have docker remove the services not present in the current stack definition.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
resolve_image
+
string
+
+
If set will add the --resolve-image option to the dockerstackdeploy command. This will have docker query the registry to resolve image digest and supported platforms. If not set, docker use “always” by default.
+
Choices:
+
+
"always"
+
"changed"
+
"never"
+
+
+
+
+
state
+
string
+
+
Service state.
+
Choices:
+
+
"present"← (default)
+
"absent"
+
+
+
+
+
tls
+
boolean
+
added in community.docker 3.6.0
+
+
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
+
added in community.docker 3.6.0
+
+
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
+
added in community.docker 3.6.0
+
+
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
+
+
+
+
+
with_registry_auth
+
boolean
+
+
If true will add the --with-registry-auth option to the dockerstackdeploy command. This will have docker send registry authentication details to Swarm agents.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_stack_task_info.
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
+
added in community.docker 3.6.0
+
+
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.
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
+
added in community.docker 3.6.0
+
+
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
+
added in community.docker 3.6.0
+
+
Path to the Docker CLI. If not provided, will search for Docker CLI on the PATH.
+
+
+
+
+
docker_host
+
aliases: docker_url
+
string
+
added in community.docker 3.6.0
+
+
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.
+
Mutually exclusive with cli_context. If neither docker_host nor cli_context are provided, the value unix:///var/run/docker.sock is used.
+
+
+
+
name
+
string / required
+
+
Stack name.
+
+
+
+
tls
+
boolean
+
added in community.docker 3.6.0
+
+
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
+
added in community.docker 3.6.0
+
+
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
+
added in community.docker 3.6.0
+
+
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.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_swarm_info.
Returns lists of swarm objects names for the services - nodes, services, tasks.
+
The output differs depending on API version available on docker host.
+
Must be run on Swarm Manager node; otherwise module fails with error message. It does return boolean flags in on both error and success which indicate whether the docker daemon can be communicated with, whether it is in Swarm mode, and whether it is a Swarm Manager node.
The below requirements are needed on the host that executes this module.
+
+
Docker API >= 1.25
+
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). This module does not work with docker-py.
The version of the Docker API running on the Docker Host.
+
Defaults to the latest version of the API supported by Docker SDK for Python 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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
nodes
+
boolean
+
+
Whether to list swarm nodes.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
nodes_filters
+
dictionary
+
+
A dictionary of filter values used for selecting nodes to list.
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.
+
Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error.
+
+
+
+
unlock_key
+
boolean
+
+
Whether to retrieve the swarm unlock key.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
use_ssh_client
+
boolean
+
added in community.docker 1.5.0
+
+
For SSH transports, use the ssh CLI tool instead of paramiko.
+
Requires Docker SDK for Python 4.4.0 or newer.
+
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
+
+
+
+
+
verbose_output
+
boolean
+
+
When set to true and nodes, services, or tasks is set to true, then the module output will contain verbose information about objects matching the full output of API method.
When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls] with ansible.builtin.pip.
+
Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/.docker/config.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.
---
+-name:Get info on Docker Swarm
+community.docker.docker_swarm_info:
+ignore_errors:true
+register:result
+
+-name:Inform about basic flags
+ansible.builtin.debug:
+msg:|
+Was able to talk to docker daemon: {{result.can_talk_to_docker}}
+Docker in Swarm mode: {{result.docker_swarm_active}}
+This is a Manager node: {{result.docker_swarm_manager}}
+
+-name:Get info on Docker Swarm and list of registered nodes
+community.docker.docker_swarm_info:
+nodes:true
+register:result
+
+-name:Get info on Docker Swarm and extended list of registered nodes
+community.docker.docker_swarm_info:
+nodes:true
+verbose_output:true
+register:result
+
+-name:Get info on Docker Swarm and filtered list of registered nodes
+community.docker.docker_swarm_info:
+nodes:true
+nodes_filters:
+name:mynode
+register:result
+
+-name:Show swarm facts
+ansible.builtin.debug:
+var:result.swarm_facts
+
+-name:Get the swarm unlock key
+community.docker.docker_swarm_info:
+unlock_key:true
+register:result
+
+-name:Print swarm unlock key
+ansible.builtin.debug:
+var:result.swarm_unlock_key
+
Common return values are documented here, the following are the fields unique to this module:
+
+
+
Key
+
Description
+
+
+
+
+
can_talk_to_docker
+
boolean
+
+
Will be true if the module can talk to the docker daemon.
+
Returned: both on success and on error
+
+
+
+
docker_swarm_active
+
boolean
+
+
Will be true if the module can talk to the docker daemon, and the docker daemon is in Swarm mode.
+
Returned: both on success and on error
+
+
+
+
docker_swarm_manager
+
boolean
+
+
Will be true if the module can talk to the docker daemon, the docker daemon is in Swarm mode, and the current node is a manager node.
+
Only if this one is true, the module will not fail.
+
Returned: both on success and on error
+
+
+
+
nodes
+
list / elements=dictionary
+
+
List of dict objects containing the basic information about each volume. Keys matches the dockernodels output unless verbose_output=true. See description for verbose_output.
List of dict objects containing the basic information about each volume. Keys matches the dockerservicels output unless verbose_output=true. See description for verbose_output.
List of dict objects containing the basic information about each volume. Keys matches the dockerserviceps output unless verbose_output=true. See description for verbose_output.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.docker.
+You need further requirements to be able to use this inventory plugin,
+see Requirements for details.
+
To use it in a playbook, specify: community.docker.docker_swarm.
Uses a YAML configuration file that ends with docker_swarm.(yml|yaml).
+
The plugin returns following groups of swarm nodes: all - all hosts; workers - all worker nodes; managers - all manager nodes; leader - the swarm leader node; nonleaders - all nodes except the swarm leader.
The version of the Docker API running on the Docker Host.
+
Defaults to the latest version of the API supported by Docker SDK for Python.
+
+
+
+
+
+
+
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still be used.
+
+
+
+
+
+
client_cert
+
aliases: tls_client_cert, cert_path
+
path
+
+
Path to the client’s TLS certificate file.
+
+
+
+
+
+
client_key
+
aliases: tls_client_key, key_path
+
path
+
+
Path to the client’s TLS key file.
+
+
+
+
compose
+
dictionary
+
+
Create vars from jinja2 expressions.
+
Default:{}
+
+
+
+
+
docker_host
+
aliases: docker_url
+
string / required
+
+
Socket of a Docker swarm manager node (tcp, unix).
+
Use unix:///var/run/docker.sock to connect through a local socket.
+
+
+
+
filters
+
list / elements=dictionary
+
added in community.docker 3.5.0
+
+
A list of include/exclude filters that allows to select/deselect hosts for this inventory.
+
Filters are processed sequentially until the first filter where filters[].exclude or filters[].include matches is found. In case filters[].exclude matches, the host is excluded, and in case filters[].include matches, the host is included. In case no filter matches, the host is included.
+
+
+
+
exclude
+
string
+
+
A Jinja2 condition. If it matches for a host, that host is excluded.
Toggle to return the additional attribute ansible_host_uri which contains the URI of the swarm leader in format of tcp://172.16.0.1:2376. This value may be used without additional modification as value of option docker_host in Docker Swarm modules when connecting through the API. The port always defaults to 2376.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
include_host_uri_port
+
integer
+
+
Override the detected port number included in ansible_host_uri.
+
+
+
+
keyed_groups
+
list / elements=dictionary
+
+
Add hosts to group based on the values of a variable.
+
Default:[]
+
+
+
+
default_value
+
string
+
added in ansible-core 2.12
+
+
The default value when the host variable’s value is an empty string.
By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
+
This is because the default prefix is "" and the default separator is "_".
+
Set this option to false to omit the leading underscore (or other separator) if no prefix is given.
+
If the group name is derived from a mapping the separator is still used to concatenate the items.
+
To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
plugin
+
string / required
+
+
The name of this plugin, it should always be set to community.docker.docker_swarm for this plugin to recognize it as its own.
+
Choices:
+
+
"docker_swarm"
+
"community.docker.docker_swarm"
+
+
+
+
+
strict
+
boolean
+
+
If yes make invalid entries a fatal error, otherwise skip and continue.
+
Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
+
timeout
+
aliases: time_out
+
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
+
+
Connect using TLS without verifying the authenticity of the Docker host server.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
tls_hostname
+
string
+
+
When verifying the authenticity of the Docker host server, provide the expected name of the server.
+
+
+
+
use_extra_vars
+
boolean
+
added in ansible-core 2.11
+
+
Merge extra vars into the available variables for composition (highest precedence).
For SSH transports, use the ssh CLI tool instead of paramiko.
+
Requires Docker SDK for Python 4.4.0 or newer.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
+
validate_certs
+
aliases: tls_verify
+
boolean
+
+
Toggle if connecting using TLS with or without verifying the authenticity of the Docker host server.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
verbose_output
+
boolean
+
+
Toggle to (not) include all available nodes metadata (for example Platform, Architecture, OS, EngineVersion).
+
Choices:
+
+
false
+
true← (default)
+
+
+
+
+
+
+
Note
+
Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
+For example, a variable that is lower in the list will override a variable that is higher up.
+The entry types are also ordered by precedence from low to high priority order.
+For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
---
+# Minimal example using local docker
+plugin:community.docker.docker_swarm
+docker_host:unix:///var/run/docker.sock
+
+---
+# Minimal example using remote docker
+plugin:community.docker.docker_swarm
+docker_host:tcp://my-docker-host:2375
+
+---
+# Example using remote docker with unverified TLS
+plugin:community.docker.docker_swarm
+docker_host:tcp://my-docker-host:2376
+tls:true
+
+---
+# Example using remote docker with verified TLS and client certificate verification
+plugin:community.docker.docker_swarm
+docker_host:tcp://my-docker-host:2376
+validate_certs:true
+ca_path:/somewhere/ca.pem
+client_key:/somewhere/key.pem
+client_cert:/somewhere/cert.pem
+
+---
+# Example using constructed features to create groups and set ansible_host
+plugin:community.docker.docker_swarm
+docker_host:tcp://my-docker-host:2375
+strict:false
+keyed_groups:
+# add for example x86_64 hosts to an arch_x86_64 group
+-prefix:arch
+key:'Description.Platform.Architecture'
+# add for example linux hosts to an os_linux group
+-prefix:os
+key:'Description.Platform.OS'
+# create a group per node label
+# for exomple a node labeled w/ "production" ends up in group "label_production"
+# hint: labels containing special characters will be converted to safe names
+-key:'Spec.Labels'
+prefix:label
+
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_swarm.
The below requirements are needed on the host that executes this module.
+
+
Docker API >= 1.25
+
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). This module does not work with docker-py.
Externally reachable address advertised to other nodes.
+
This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567.
+
If the port number is omitted, the port number from the listen address is used.
+
If advertise_addr is not specified, it will be automatically detected when possible.
+
Only used when swarm is initialised or joined. Because of this it is not considered for idempotency checking.
+
+
+
+
+
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 Docker SDK for Python 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"
+
+
+
+
autolock_managers
+
boolean
+
+
If set, generate a key and use it to lock data stored on the managers.
An integer whose purpose is to force swarm to generate a new signing CA certificate and key, if none have been specified.
+
Docker default value is 0.
+
Requires API version >= 1.30.
+
+
+
+
+
+
+
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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.
+
+
+
+
data_path_addr
+
string
+
added in community.docker 2.5.0
+
+
Address or interface to use for data path traffic.
+
This can either be an address in the form 192.168.1.1, or an interface, like eth0.
+
Only used when swarm is initialised or joined. Because of this it is not considered for idempotency checking.
+
Requires API version >= 1.30.
+
+
+
+
data_path_port
+
integer
+
added in community.docker 3.1.0
+
+
Port to use for data path traffic.
+
This needs to be a port number like 9789.
+
Only used when swarm is initialised. Because of this it is not considered for idempotency checking.
+
Requires API version >= 1.40.
+
+
+
+
debug
+
boolean
+
+
Debug mode.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
default_addr_pool
+
list / elements=string
+
+
Default address pool in CIDR format.
+
Only used when swarm is initialised. Because of this it is not considered for idempotency checking.
+
Requires API version >= 1.39.
+
+
+
+
dispatcher_heartbeat_period
+
integer
+
+
The delay (in nanoseconds) for an agent to send a heartbeat to the dispatcher.
+
Docker default value is 5 seconds, which corresponds to a value of 5000000000.
+
+
+
+
+
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"
+
+
+
+
election_tick
+
integer
+
+
Amount of ticks (in seconds) needed without a leader to trigger a new election.
+
Docker default value is 10 seconds.
+
+
+
+
force
+
boolean
+
+
Use with state present to force creating a new Swarm, even if already part of one.
+
Use with state absent to Leave the swarm even if this node is a manager.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
heartbeat_tick
+
integer
+
+
Amount of ticks (in seconds) between each heartbeat.
If this value is specified, the corresponding value in the return values will be censored by Ansible. This is a side-effect of this value not being logged.
+
+
+
+
keep_old_snapshots
+
integer
+
+
Number of snapshots to keep beyond the current snapshot.
+
Docker default value is 0.
+
+
+
+
labels
+
dictionary
+
+
User-defined key/value metadata.
+
Label operations in this module apply to the docker swarm cluster. Use community.docker.docker_node module to add/modify/remove swarm node labels.
+
Requires API version >= 1.32.
+
+
+
+
listen_addr
+
string
+
+
Listen address used for inter-manager communication.
+
This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567.
+
If the port number is omitted, the default swarm listening port is used.
+
Only used when swarm is initialised or joined. Because of this it is not considered for idempotency checking.
+
Default:"0.0.0.0:2377"
+
+
+
+
log_entries_for_slow_followers
+
integer
+
+
Number of log entries to keep around to sync up slow followers after a snapshot is created.
+
+
+
+
name
+
string
+
+
The name of the swarm.
+
+
+
+
node_cert_expiry
+
integer
+
+
Automatic expiry for nodes certificates, given in nanoseconds.
+
Docker default value is 90 days, which corresponds to a value of 7776000000000000.
Only used when swarm is initialised. Because of this it is not considered for idempotency checking.
+
Requires API version >= 1.39.
+
+
+
+
task_history_retention_limit
+
integer
+
+
Maximum number of tasks history stored.
+
Docker default value is 5.
+
+
+
+
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.
+
Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error.
+
+
+
+
use_ssh_client
+
boolean
+
added in community.docker 1.5.0
+
+
For SSH transports, use the ssh CLI tool instead of paramiko.
+
Requires Docker SDK for Python 4.4.0 or newer.
+
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.
When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls] with ansible.builtin.pip.
+
Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/.docker/config.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.
---
+-name:Init a new swarm with default parameters
+community.docker.docker_swarm:
+state:present
+
+-name:Update swarm configuration
+community.docker.docker_swarm:
+state:present
+election_tick:5
+
+-name:Add nodes
+community.docker.docker_swarm:
+state:join
+advertise_addr:192.168.1.2
+join_token:SWMTKN-1--xxxxx
+remote_addrs:['192.168.1.1:2377']
+
+-name:Leave swarm for a node
+community.docker.docker_swarm:
+state:absent
+
+-name:Remove a swarm manager
+community.docker.docker_swarm:
+state:absent
+force:true
+
+-name:Remove node from swarm
+community.docker.docker_swarm:
+state:remove
+node_id:mynode
+
+-name:Init a new swarm with different data path interface
+community.docker.docker_swarm:
+state:present
+advertise_addr:eth0
+data_path_addr:ens10
+
+-name:Init a new swarm with a different data path port
+community.docker.docker_swarm:
+state:present
+data_path_port:9789
+
Common return values are documented here, the following are the fields unique to this module:
+
+
+
Key
+
Description
+
+
+
+
+
actions
+
list / elements=string
+
+
Provides the actions done on the swarm.
+
Returned: when action failed.
+
Sample:["Thisclusterisalreadyaswarmcluster"]
+
+
+
+
swarm_facts
+
dictionary
+
+
Information about swarm.
+
Returned: success
+
+
+
+
JoinTokens
+
dictionary
+
+
Tokens to connect to the Swarm.
+
Returned: success
+
+
+
+
Manager
+
string
+
+
Token to join the cluster as a new *manager* node.
+
Note: if this value has been specified as join_token, the value here will not be the token, but VALUE_SPECIFIED_IN_NO_LOG_PARAMETER. If you pass join_token, make sure your playbook/role does not depend on this return value!
+
Returned: success
+
Sample:"SWMTKN-1--xxxxx"
+
+
+
+
Worker
+
string
+
+
Token to join the cluster as a new *worker* node.
+
Note: if this value has been specified as join_token, the value here will not be the token, but VALUE_SPECIFIED_IN_NO_LOG_PARAMETER. If you pass join_token, make sure your playbook/role does not depend on this return value!
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_swarm_service_info.
The below requirements are needed on the host that executes this module.
+
+
Docker API >= 1.25
+
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). This module does not work with docker-py.
The version of the Docker API running on the Docker Host.
+
Defaults to the latest version of the API supported by Docker SDK for Python 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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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
+
+
The name of the service to inspect.
+
+
+
+
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.
+
Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error.
+
+
+
+
use_ssh_client
+
boolean
+
added in community.docker 1.5.0
+
+
For SSH transports, use the ssh CLI tool instead of paramiko.
+
Requires Docker SDK for Python 4.4.0 or newer.
+
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.
When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls] with ansible.builtin.pip.
+
Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/.docker/config.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_swarm_service.
The below requirements are needed on the host that executes this module.
+
+
Docker API >= 1.25
+
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). This module does not work with docker-py.
The version of the Docker API running on the Docker Host.
+
Defaults to the latest version of the API supported by Docker SDK for Python 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"
+
+
+
+
args
+
list / elements=string
+
+
List arguments to be passed to the container.
+
Corresponds to the ARG parameter of dockerservicecreate.
+
+
+
+
+
+
+
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still be used.
+
+
+
+
cap_add
+
list / elements=string
+
added in community.docker 2.2.0
+
+
List of capabilities to add to the container.
+
Requires API version >= 1.41.
+
+
+
+
cap_drop
+
list / elements=string
+
added in community.docker 2.2.0
+
+
List of capabilities to drop from the container.
+
Requires API version >= 1.41.
+
+
+
+
+
+
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.
+
+
+
+
command
+
any
+
+
Command to execute when the container starts.
+
A command may be either a string or a list or a list of strings.
+
Corresponds to the COMMAND parameter of dockerservicecreate.
+
+
+
+
configs
+
list / elements=dictionary
+
+
List of dictionaries describing the service configs.
+
Corresponds to the --config option of dockerservicecreate.
+
Requires API version >= 1.30.
+
+
+
+
config_id
+
string
+
+
Config’s ID.
+
+
+
+
config_name
+
string / required
+
+
Config’s name as defined at its creation.
+
+
+
+
filename
+
string
+
+
Name of the file containing the config. Defaults to the configs[].config_name if not specified.
+
+
+
+
gid
+
string
+
+
GID of the config file’s group.
+
+
+
+
mode
+
integer
+
+
File access mode inside the container. Must be an octal number (like 0644 or 0444).
+
+
+
+
uid
+
string
+
+
UID of the config file’s owner.
+
+
+
+
container_labels
+
dictionary
+
+
Dictionary of key value pairs.
+
Corresponds to the --container-label option of dockerservicecreate.
+
+
+
+
debug
+
boolean
+
+
Debug mode.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
dns
+
list / elements=string
+
+
List of custom DNS servers.
+
Corresponds to the --dns option of dockerservicecreate.
+
+
+
+
dns_options
+
list / elements=string
+
+
List of custom DNS options.
+
Corresponds to the --dns-option option of dockerservicecreate.
+
+
+
+
dns_search
+
list / elements=string
+
+
List of custom DNS search domains.
+
Corresponds to the --dns-search option of dockerservicecreate.
+
+
+
+
+
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"
+
+
+
+
endpoint_mode
+
string
+
+
Service endpoint mode.
+
Corresponds to the --endpoint-mode option of dockerservicecreate.
+
Choices:
+
+
"vip"
+
"dnsrr"
+
+
+
+
+
env
+
any
+
+
List or dictionary of the service environment variables.
+
If passed a list each items need to be in the format of KEY=VALUE.
+
If passed a dictionary values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example "true") in order to avoid data loss.
+
Corresponds to the --env option of dockerservicecreate.
+
+
+
+
env_files
+
list / elements=path
+
+
List of paths to files, present on the target, containing environment variables FOO=BAR.
+
The order of the list is significant in determining the value assigned to a variable that shows up more than once.
+
If variable also present in env, then env value will override.
+
+
+
+
force_update
+
boolean
+
+
Force update even if no changes require it.
+
Corresponds to the --force option of dockerserviceupdate.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
groups
+
list / elements=string
+
+
List of additional group names and/or IDs that the container process will run as.
+
Corresponds to the --group option of dockerserviceupdate.
+
+
+
+
healthcheck
+
dictionary
+
+
Configure a check that is run to determine whether or not containers for this service are “healthy”. See the docs for the HEALTHCHECK Dockerfile instruction for details on how healthchecks work.
Consecutive failures needed to report unhealthy. It accept integer value.
+
+
+
+
start_period
+
string
+
+
Start period for the container to initialize before starting health-retries countdown.
+
+
+
+
test
+
any
+
+
Command to run to check health.
+
Must be either a string or a list. If it is a list, the first item must be one of NONE, CMD or CMD-SHELL.
+
+
+
+
timeout
+
string
+
+
Maximum time to allow one check to run.
+
+
+
+
hostname
+
string
+
+
Container hostname.
+
Corresponds to the --hostname option of dockerservicecreate.
+
+
+
+
hosts
+
dictionary
+
+
Dict of host-to-IP mappings, where each host name is a key in the dictionary. Each host name will be added to the container’s /etc/hosts file.
+
Corresponds to the --host option of dockerservicecreate.
+
+
+
+
image
+
string
+
+
Service image path and tag.
+
Corresponds to the IMAGE parameter of dockerservicecreate.
+
+
+
+
init
+
boolean
+
+
Use an init inside each service container to forward signals and reap processes.
+
Corresponds to the --init option of dockerservicecreate.
+
Requires API version >= 1.37.
+
Choices:
+
+
false
+
true
+
+
+
+
+
labels
+
dictionary
+
+
Dictionary of key value pairs.
+
Corresponds to the --label option of dockerservicecreate.
+
+
+
+
limits
+
dictionary
+
+
Configures service resource limits.
+
+
+
+
cpus
+
float
+
+
Service CPU limit. 0 equals no limit.
+
Corresponds to the --limit-cpu option of dockerservicecreate.
+
+
+
+
memory
+
string
+
+
Service memory limit in format <number>[<unit>]. Number is a positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
0 equals no limit.
+
Omitting the unit defaults to bytes.
+
Corresponds to the --limit-memory option of dockerservicecreate.
+
+
+
+
logging
+
dictionary
+
+
Logging configuration for the service.
+
+
+
+
driver
+
string
+
+
Configure the logging driver for a service.
+
Corresponds to the --log-driver option of dockerservicecreate.
+
+
+
+
options
+
dictionary
+
+
Options for service logging driver.
+
Corresponds to the --log-opt option of dockerservicecreate.
+
+
+
+
mode
+
string
+
+
Service replication mode.
+
Service will be removed and recreated when changed.
+
Corresponds to the --mode option of dockerservicecreate.
+
The value replicated-job was added in community.docker 4.7.0, and requires API version >= 1.41 and Docker SDK for Python >= 6.0.0.
+
Choices:
+
+
"replicated"← (default)
+
"global"
+
"replicated-job"
+
+
+
+
+
mounts
+
list / elements=dictionary
+
+
List of dictionaries describing the service mounts.
+
Corresponds to the --mount option of dockerservicecreate.
Size of the tmpfs mount in format <number>[<unit>]. Number is a positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
If set to -1, and service is not present, service replicas will be set to 1.
+
If set to -1, and service is present, service replicas will be unchanged.
+
Corresponds to the --replicas option of dockerservicecreate.
+
Default:-1
+
+
+
+
reservations
+
dictionary
+
+
Configures service resource reservations.
+
+
+
+
cpus
+
float
+
+
Service CPU reservation. 0 equals no reservation.
+
Corresponds to the --reserve-cpu option of dockerservicecreate.
+
+
+
+
memory
+
string
+
+
Service memory reservation in format <number>[<unit>]. Number is a positive integer. Unit can be B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).
+
0 equals no reservation.
+
Omitting the unit defaults to bytes.
+
Corresponds to the --reserve-memory option of dockerservicecreate.
+
+
+
+
resolve_image
+
boolean
+
+
If the current image digest should be resolved from registry and updated if changed.
+
Requires API version >= 1.30.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
restart_config
+
dictionary
+
+
Configures if and how to restart containers when they exit.
+
+
+
+
condition
+
string
+
+
Restart condition of the service.
+
Corresponds to the --restart-condition option of dockerservicecreate.
+
Choices:
+
+
"none"
+
"on-failure"
+
"any"
+
+
+
+
+
delay
+
string
+
+
Delay between restarts.
+
Accepts a a string in a format that look like: 5h34m56s, 1m30s, and so on. The supported units are us, ms, s, m and h.
+
Corresponds to the --restart-delay option of dockerservicecreate.
+
+
+
+
max_attempts
+
integer
+
+
Maximum number of service restarts.
+
Corresponds to the --restart-condition option of dockerservicecreate.
+
+
+
+
window
+
string
+
+
Restart policy evaluation window.
+
Accepts a string in a format that look like: 5h34m56s, 1m30s, and so on. The supported units are us, ms, s, m and h.
+
Corresponds to the --restart-window option of dockerservicecreate.
+
+
+
+
rollback_config
+
dictionary
+
+
Configures how the service should be rolled back in case of a failing update.
+
+
+
+
delay
+
string
+
+
Delay between task rollbacks.
+
Accepts a string in a format that look like: 5h34m56s, 1m30s, and so on. The supported units are us, ms, s, m and h.
+
Corresponds to the --rollback-delay option of dockerservicecreate.
+
Requires API version >= 1.28.
+
+
+
+
failure_action
+
string
+
+
Action to take in case of rollback failure.
+
Corresponds to the --rollback-failure-action option of dockerservicecreate.
+
Requires API version >= 1.28.
+
Choices:
+
+
"continue"
+
"pause"
+
+
+
+
+
max_failure_ratio
+
float
+
+
Fraction of tasks that may fail during a rollback.
+
Corresponds to the --rollback-max-failure-ratio option of dockerservicecreate.
+
Requires API version >= 1.28.
+
+
+
+
monitor
+
string
+
+
Duration after each task rollback to monitor for failure.
+
Accepts a string in a format that look like: 5h34m56s, 1m30s, and so on. The supported units are us, ms, s, m and h.
+
Corresponds to the --rollback-monitor option of dockerservicecreate.
+
Requires API version >= 1.28.
+
+
+
+
order
+
string
+
+
Specifies the order of operations during rollbacks.
+
Corresponds to the --rollback-order option of dockerservicecreate.
+
Requires API version >= 1.29.
+
+
+
+
parallelism
+
integer
+
+
The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously.
+
Corresponds to the --rollback-parallelism option of dockerservicecreate.
+
Requires API version >= 1.28.
+
+
+
+
secrets
+
list / elements=dictionary
+
+
List of dictionaries describing the service secrets.
+
Corresponds to the --secret option of dockerservicecreate.
+
+
+
+
filename
+
string
+
+
Name of the file containing the secret. Defaults to the secrets[].secret_name if not specified.
+
Corresponds to the target key of dockerservicecreate--secret.
+
+
+
+
gid
+
string
+
+
GID of the secret file’s group.
+
+
+
+
mode
+
integer
+
+
File access mode inside the container. Must be an octal number (like 0644 or 0444).
+
+
+
+
secret_id
+
string
+
+
Secret’s ID.
+
+
+
+
secret_name
+
string / required
+
+
Secret’s name as defined at its creation.
+
+
+
+
uid
+
string
+
+
UID of the secret file’s owner.
+
+
+
+
state
+
string
+
+
absent - A service matching the specified name will be removed and have its tasks stopped.
+
present - Asserts the existence of a service matching the name and provided configuration parameters. Unspecified configuration parameters will be set to docker defaults.
+
Choices:
+
+
"present"← (default)
+
"absent"
+
+
+
+
+
stop_grace_period
+
string
+
+
Time to wait before force killing a container.
+
Accepts a duration as a string in a format that look like: 5h34m56s, 1m30s, and so on. The supported units are us, ms, s, m and h.
+
Corresponds to the --stop-grace-period option of dockerservicecreate.
+
+
+
+
stop_signal
+
string
+
+
Override default signal used to stop the container.
+
Corresponds to the --stop-signal option of dockerservicecreate.
+
+
+
+
sysctls
+
dictionary
+
added in community.docker 3.10.0
+
+
Dictionary of key, value pairs.
+
+
+
+
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.
+
Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error.
+
+
+
+
tty
+
boolean
+
+
Allocate a pseudo-TTY.
+
Corresponds to the --tty option of dockerservicecreate.
+
Choices:
+
+
false
+
true
+
+
+
+
+
update_config
+
dictionary
+
+
Configures how the service should be updated. Useful for configuring rolling updates.
+
+
+
+
delay
+
string
+
+
Rolling update delay.
+
Accepts a string in a format that look like: 5h34m56s, 1m30s, and so on. The supported units are us, ms, s, m and h.
+
Corresponds to the --update-delay option of dockerservicecreate.
+
+
+
+
failure_action
+
string
+
+
Action to take in case of container failure.
+
Corresponds to the --update-failure-action option of dockerservicecreate.
+
Usage of rollback requires API version >= 1.29.
+
Choices:
+
+
"continue"
+
"pause"
+
"rollback"
+
+
+
+
+
max_failure_ratio
+
float
+
+
Fraction of tasks that may fail during an update before the failure action is invoked.
+
Corresponds to the --update-max-failure-ratio option of dockerservicecreate.
+
+
+
+
monitor
+
string
+
+
Time to monitor updated tasks for failures.
+
Accepts a string in a format that look like: 5h34m56s, 1m30s, and so on. The supported units are us, ms, s, m and h.
+
Corresponds to the --update-monitor option of dockerservicecreate.
+
+
+
+
order
+
string
+
+
Specifies the order of operations when rolling out an updated task.
+
Corresponds to the --update-order option of dockerservicecreate.
+
Requires API version >= 1.29.
+
+
+
+
parallelism
+
integer
+
+
Rolling update parallelism.
+
Corresponds to the --update-parallelism option of dockerservicecreate.
+
+
+
+
use_ssh_client
+
boolean
+
added in community.docker 1.5.0
+
+
For SSH transports, use the ssh CLI tool instead of paramiko.
+
Requires Docker SDK for Python 4.4.0 or newer.
+
Choices:
+
+
false← (default)
+
true
+
+
+
+
+
user
+
string
+
+
Sets the username or UID used for the specified command.
+
Before Ansible 2.8, the default value for this option was root.
+
The default has been removed so that the user defined in the image is used if no user is specified here.
+
Corresponds to the --user option of dockerservicecreate.
+
+
+
+
+
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
+
+
+
+
+
working_dir
+
string
+
+
Path to the working directory.
+
Corresponds to the --workdir option of dockerservicecreate.
Images will only resolve to the latest digest when using Docker API >= 1.30 and Docker SDK for Python >= 3.2.0. When using older versions use force_update=true to trigger the swarm to resolve a new image.
When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls] with ansible.builtin.pip.
+
Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/.docker/config.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.
Common return values are documented here, the following are the fields unique to this module:
+
+
+
Key
+
Description
+
+
+
+
+
changes
+
list / elements=string
+
+
List of changed service attributes if a service has been altered, [] otherwise.
+
Returned: always
+
Sample:["container_labels","replicas"]
+
+
+
+
rebuilt
+
boolean
+
+
True if the service has been recreated (removed and created).
+
Returned: always
+
Sample:true
+
+
+
+
swarm_service
+
dictionary
+
+
Dictionary of variables representing the current state of the service. Matches the module parameters format.
+
Note that facts are not part of registered vars but accessible directly.
+
Note that before Ansible 2.7.9, the return variable was documented as ansible_swarm_service, while the module actually returned a variable called ansible_docker_service. The variable was renamed to swarm_service in both code and documentation for Ansible 2.7.9 and Ansible 2.8.0. In Ansible 2.7.x, the old name ansible_docker_service can still be used.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_volume_info.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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
+
aliases: volume_name
+
string / required
+
+
Name of the volume to inspect.
+
+
+
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
It is not included in ansible-core.
+To check whether it is installed, run ansible-galaxycollectionlist.
+
To install it, use: ansible-galaxycollectioninstallcommunity.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_volume.
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.
+
This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still 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"
+
+
+
+
driver
+
string
+
+
Specify the type of volume. Docker provides the local driver, but 3rd party drivers can also be used.
Dictionary of label key/values to set for the volume.
+
+
+
+
recreate
+
string
+
+
Controls when a volume will be recreated when state=present. Please note that recreating an existing volume will cause any data in the existing volume to be lost! The volume will be deleted and a new volume with the same name will be created.
+
The value always forces the volume to be always recreated.
+
The value never makes sure the volume will not be recreated.
+
The value options-changed makes sure the volume will be recreated if the volume already exist and the driver, driver options or labels differ.
+
Choices:
+
+
"always"
+
"never"← (default)
+
"options-changed"
+
+
+
+
+
state
+
string
+
+
absent deletes the volume.
+
present creates the volume, if it does not already exist.
+
Choices:
+
+
"absent"
+
"present"← (default)
+
+
+
+
+
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.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
Most of the modules and plugins in community.docker require the Docker SDK for Python. The SDK needs to be installed on the machines where the modules and plugins are executed, and for the Python version(s) with which the modules and plugins are executed. You can use the community.general.python_requirements_info module to make sure that the Docker SDK for Python is installed on the correct machine and for the Python version used by Ansible.
+
Note that plugins (inventory plugins and connection plugins) are always executed in the context of Ansible itself. If you use a plugin that requires the Docker SDK for Python, you need to install it on the machine running ansible or ansible-playbook and for the same Python interpreter used by Ansible. To see which Python is used, run ansible--version.
+
You can install the Docker SDK for Python for Python 3.6 or later as follows:
+
$ pipinstalldocker
+
+
+
For Python 2.7, you need to use a version between 2.0.0 and 4.4.4 since the Python package for Docker removed support for Python 2.7 on 5.0.0. You can install the specific version of the Docker SDK for Python as follows:
+
$ pipinstall'docker==4.4.4'
+
+
+
Note that the Docker SDK for Python was called docker-py on PyPi before version 2.0.0. Please avoid installing this really old version, and make sure to not install both docker and docker-py. Installing both will result in a broken installation. If this happens, Ansible will detect it and inform you about it. If that happens, you must uninstall both and reinstall the correct version. If in doubt, always install docker and never docker-py.
You can connect to a local or remote API using parameters passed to each task or by setting environment variables. The order of precedence is command line parameters and then environment variables. If neither a command line option nor an environment variable is found, Ansible uses the default value provided under Parameters.
Most plugins and modules can be configured by the following parameters:
+
+
+
docker_host
The URL or Unix socket path used to connect to the Docker API. Defaults to unix:///var/run/docker.sock. 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 to the API, then the module will automatically replace tcp in the connection URL with https.
+
+
api_version
The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by the Docker SDK for Python installed.
+
+
timeout
The maximum amount of time in seconds to wait on a response from the API. Defaults to 60 seconds.
+
+
tls
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Defaults to false.
+
+
validate_certs
Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. Default is false.
+
+
ca_path
Use a CA certificate when performing server verification by providing the path to a CA certificate file.
+
+
cert_path
Path to the client’s TLS certificate file.
+
+
key_path
Path to the client’s TLS key file.
+
+
tls_hostname
When verifying the authenticity of the Docker Host server, provide the expected name of the server. Defaults to localhost.
+
+
ssl_version
Provide a valid SSL version number. The default value is determined by the Docker SDK for Python.
+
This option is not available for the CLI based plugins. It is mainly needed for legacy systems and should be avoided.
To avoid having to specify common parameters for all the modules in every task, you can use the community.docker.dockermodule defaults group, or its short name docker.
+
+
Note
+
Module default groups only work for modules, not for plugins (connection and inventory plugins).
+
+
The following example shows how the module default group can be used in a playbook:
You can also control how the plugins and modules connect to the Docker API by setting the following environment variables.
+
For plugins, they have to be set for the environment Ansible itself runs in. For modules, they have to be set for the environment the modules are executed in. For modules running on remote machines, the environment variables have to be set on that machine for the user used to execute the modules with.
The docker inventory script is deprecated. Please use the inventory plugin instead. The inventory plugin has several compatibility options. If you need to collect Docker containers from multiple Docker daemons, you need to add every Docker daemon as an individual inventory source.
+
+
docker_host_info module
The community.docker.docker_host_info module allows you to retrieve information on a Docker daemon, such as all containers, images, volumes, networks and so on.
+
+
docker_login module
The community.docker.docker_login module allows you to log in and out of a remote registry, such as Docker Hub or a private registry. It provides similar functionality to the dockerlogin and dockerlogout CLI commands.
+
+
docker_prune module
The community.docker.docker_prune module allows you to prune no longer needed containers, images, volumes and so on. It provides similar functionality to the dockerprune CLI command.
The community.docker.docker_container module manages the container lifecycle by providing the ability to create, update, stop, start and destroy a Docker container.
These modules use the Docker CLI “compose” plugin (dockercompose), and thus needs access to the Docker CLI tool.
+No further requirements next to to the CLI tool and its Docker Compose plugin are needed.
The community.docker.docker_swarm module allows you to globally configure Docker Swarm manager nodes to join and leave swarms, and to change the Docker Swarm configuration.
The following index documents all environment variables declared by plugins in collections.
+Environment variables used by the ansible-core configuration are documented in Ansible Configuration Settings.
This connection plugin allows Ansible, running in a privileged container, to execute tasks on the container host instead of in the container itself.
+
This is useful for running Ansible in a pull model, while still keeping the Ansible control node containerized.
+
It relies on having privileged access to run nsenter in the host’s PID namespace, allowing it to enter the namespaces of the provided PID (default PID 1, or init/systemd).
Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
+For example, a variable that is lower in the list will override a variable that is higher up.
+The entry types are also ordered by precedence from low to high priority order.
+For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
The remote user is ignored; this plugin always runs as root.
+
This plugin requires the Ansible controller container to be launched in the following way: (1) The container image contains the nsenter program; (2) The container is launched in privileged mode; (3) The container is launched in the host’s PID namespace (--pidhost).
+ 
+