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.
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:
requests
pywin32 (when using named pipes on Windows 32)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
backports.ssl_match_hostname (when using TLS on Python 2)
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.
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:
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
Configuration:
Variable: ansible_docker_ca_cert
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.
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
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 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:
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.
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:
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Configuration:
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.
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:
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.
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:
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.
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
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 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)
Does not work with TCP TLS sockets! This is caused by the inability to send close_notify without closing the connection with Python’s SSLSockets. See https://github.com/ansible-collections/community.docker/issues/605 for more information.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
Uses Docker Compose to start, shutdown and scale services. This module requires docker-compose < 2.0.0.
Configuration can be read from a docker-compose.yml or docker-compose.yaml file or inline using the definition option.
Configuration can be read from a docker-compose.yml or docker-compose.yaml file or inline using the definition option.
See the examples for more details.
Supports check mode.
This module was called docker_service before Ansible 2.8. The usage did not change.
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.
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"
build
boolean
Use with state present to always build images prior to starting the application.
Use with state=present to always build images prior to starting the application.
Same as running docker-compose build with the pull option.
Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents.
-Use the nocache option to ignore the image cache when performing the build.
-If an existing image is replaced, services using the image will be recreated unless recreate is never.
Use the nocache option to ignore the image cache when performing the build.
If an existing image is replaced, services using the image will be recreated unless recreate=never.
Choices:
false ← (default)
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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 file describing one or more services, networks and volumes.
-Mutually exclusive with project_src and files.
+Mutually exclusive with project_src and files.
When state is present specify whether or not to include linked services.
When state is present specify whether or not to include linked services.
Choices:
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.
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
added in community.docker 1.9.0
By default environment files are loaded from a .env file located directly under the project_src directory.
env_file can be used to specify the path of a custom environment file instead.
-The path is relative to the project_src directory.
+By default environment files are loaded from a .env file located directly under the project_src directory.
env_file can be used to specify the path of a custom environment file instead.
The path is relative to the project_src directory.
Requires docker-compose version 1.25.0 or greater.
Note: docker-compose versions <=1.28 load the env file from the current working directory of the docker-compose command rather than project_src.
Note: docker-compose versions <=1.28 load the env file from the current working directory of the docker-compose command rather than project_src.
List of Compose file names relative to project_src. Overrides docker-compose.yml or docker-compose.yaml.
List of Compose file names relative to project_src. Overrides docker-compose.yml or docker-compose.yaml.
Files are loaded and merged in the order given.
nocache
boolean
Use with the build option to ignore the cache during the image build process.
+Use with the build option to ignore the cache during the image build process.
Choices:
project_name
string
Provide a project name. If not provided, the project name is taken from the basename of project_src.
-Required when definition is provided.
+Provide a project name. If not provided, the project name is taken from the basename of project_src.
Required when definition is provided.
Path to a directory containing a docker-compose.yml or docker-compose.yaml file.
Mutually exclusive with definition.
-Required when no definition is provided.
+Mutually exclusive with definition.
Required when no definition is provided.
Use with state present to always pull images prior to starting the application.
Use with state=present to always pull images prior to starting the application.
Same as running docker-compose pull.
When a new image is pulled, services using the image will be recreated unless recreate is never.
When a new image is pulled, services using the image will be recreated unless recreate=never.
Choices:
By default containers will be recreated when their configuration differs from the service definition.
-Setting to never ignores configuration differences and leaves existing containers unchanged.
Setting to always forces recreation of all existing containers.
Setting to never ignores configuration differences and leaves existing containers unchanged.
Setting to always forces recreation of all existing containers.
Choices:
remove_images
string
Use with state absent to remove all images or only local images.
Use with state=absent to remove all images or only local images.
Choices:
remove_volumes
boolean
Use with state absent to remove data volumes.
restarted
boolean
Use with state present to restart all containers defined in the Compose file.
If services is defined, only the containers listed there will be restarted.
+Use with state=present to restart all containers defined in the Compose file.
If services is defined, only the containers listed there will be restarted.
Choices:
scale
dictionary
When state is present scale services. 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.
When state is present scale services. 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.
When state is present run docker-compose up resp. docker-compose stop (with stopped) resp. docker-compose restart (with restarted) on a subset of services.
If empty, which is the default, the operation will be performed on all services defined in the Compose file (or inline definition).
+When state is present run docker-compose up resp. docker-compose stop (with stopped) resp. docker-compose restart (with restarted) on a subset of services.
If empty, which is the default, the operation will be performed on all services defined in the Compose file (or inline definition).
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Desired state of the project.
-Specifying present is the same as running docker-compose up resp. docker-compose stop (with stopped) resp. docker-compose restart (with restarted).
Specifying absent is the same as running docker-compose down.
Specifying present is the same as running docker-compose up resp. docker-compose stop (with stopped) resp. docker-compose restart (with restarted).
Specifying absent is the same as running docker-compose down.
Choices:
stopped
boolean
Use with state present to stop all containers defined in the Compose file.
If services is defined, only the containers listed there will be stopped.
+Use with state=present to stop all containers defined in the Compose file.
If services is defined, only the containers listed there will be stopped.
Requires docker-compose version 1.17.0 or greater for full support. For older versions, the services will first be started and then stopped when the service is supposed to be created as stopped.
Choices:
Timeout in seconds for container shutdown when attached or when containers are already running.
-By default compose will use a 10s timeout unless default_grace_period is defined for a particular service in the project_src.
By default docker-compose will use a 10 seconds timeout unless default_grace_period is defined for a particular service in the project_src.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
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.
This module uses the Docker SDK for Python to communicate with the Docker daemon.
complex
Provides the actions to be taken on each service as determined by compose.
-Returned: when in check mode or debug is true
Returned: when in check mode or debug=true
Create and remove Docker configs in a Swarm environment. Similar to docker config create and docker config rm.
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.
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 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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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 value of the config.
-Mutually exclusive with data_src. One of data and data_src is required if state=present.
+Mutually exclusive with data_src. One of data and data_src is required if state=present.
If set to true, the data is assumed to be Base64 encoded and will be decoded before being used.
To use binary data, it is better to keep it Base64 encoded and let it be decoded by this option.
+If set to true, the data is assumed to be Base64 encoded and will be decoded before being used.
To use binary data, it is better to keep it Base64 encoded and let it be decoded by this option.
Choices:
false ← (default)
The file on the target from which to read the config.
-Mutually exclusive with data. One of data and data_src is required if state=present.
+Mutually exclusive with data. One of data and data_src is required if state=present.
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.
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.
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:
labels
dictionary
A map of key:value meta data, where both the key and value are expected to be a string.
+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.
boolean
added in community.docker 2.2.0
If set to true, configs are created with an increasing version number appended to their name.
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:
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Set to present, if the config should exist, and absent, if it should not.
Set to golang to use a Go template in data or a Go template file in data_src.
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.
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.
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:
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.
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.
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 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:
When using rolling_versions, the number of old versions of the config to keep.
+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 to 0 or 1 to keep only the current one.
Set to -1 to keep everything or 0 or 1 to keep only the current one.
Default: 5
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
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.
This module uses the Docker SDK for Python to communicate with the Docker daemon.
string
The ID assigned by Docker to the config object.
-Returned: success and state is present
Returned: success and state=present
Sample: "hzehrmyjigmcp2gb6nlhmjqcv"
The name of the created config object.
-Returned: success and state is present
Returned: success and state=present
Sample: "awesome_config"
Copy a file into a Docker container.
Similar to docker cp.
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.
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.
Note
@@ -199,7 +199,7 @@ seeDocker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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 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.
+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.
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.
+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.
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
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 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:
The group ID to use when writing the file to disk.
-If provided, owner_id must also be provided.
+If provided, owner_id must also be 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.
integer
The owner ID to use when writing the file to disk.
-If provided, group_id must also be provided.
+If provided, group_id must also be 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.
path
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
string
The actual path in the container.
-Can only be different from container_path when follow=true.
+Can only be different from container_path when follow=true.
Returned: success
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
The command to execute.
Since this is a list of arguments, no quoting is needed.
-Exactly one of argv or command must be specified.
+Exactly one of argv or command must be specified.
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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.
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:
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.
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"
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 }}".
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 }}".
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Set the stdin of the command directly to the specified value.
-Can only be used if detach=false.
+Can only be used if detach=false.
If set to true, appends a newline to stdin.
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.
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.
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:
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.
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.
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 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)
Does not support check_mode.
Does not work with TCP TLS sockets when using stdin. This is caused by the inability to send close_notify without closing the connection with Python’s SSLSockets. See https://github.com/ansible-collections/community.docker/issues/605 for more information.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Does not work with TCP TLS sockets when using stdin. This is caused by the inability to send close_notify without closing the connection with Python’s SSLSockets. See https://github.com/ansible-collections/community.docker/issues/605 for more information.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
The execution ID of the command.
-Returned: success and detach=true
+Returned: success and detach=true
Sample: "249d9e3075655baf705ed8f40488c5e9434049cf3431976f1bfdb73741c574c5"
integer
The exit code of the command.
-Returned: success and detach=false
+Returned: success and detach=false
Sample: 0
string
The standard error output of the container command.
-Returned: success and detach=false
+Returned: success and detach=false
The standard output of the container command.
-Returned: success and detach=false
+Returned: success and detach=false
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
ssl_version
string
-Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
dictionary
Facts representing the current state of the container. Matches the docker inspection output.
-Will be none if container does not exist.
Will be none if container does not exist.
Returned: always
Sample: "{ \"AppArmorProfile\": \"\", \"Args\": [], \"Config\": { \"AttachStderr\": false, \"AttachStdin\": false, \"AttachStdout\": false, \"Cmd\": [ \"/usr/bin/supervisord\" ], \"Domainname\": \"\", \"Entrypoint\": null, \"Env\": [ \"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\" ], \"ExposedPorts\": { \"443/tcp\": {}, \"80/tcp\": {} }, \"Hostname\": \"8e47bf643eb9\", \"Image\": \"lnmp_nginx:v1\", \"Labels\": {}, \"OnBuild\": null, \"OpenStdin\": false, \"StdinOnce\": false, \"Tty\": false, \"User\": \"\", \"Volumes\": { \"/tmp/lnmp/nginx-sites/logs/\": {} }, ... }"
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
boolean
Enable auto-removal of the container on daemon side when the container’s process exits.
-If container_default_behavior is set to compatibility, this option has a default of false.
If container_default_behavior=compatibility, this option has a default of false.
Choices:
false
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
cleanup
boolean
Use with detach=false to remove the container after successful execution.
+Use with detach=false to remove the container after successful execution.
Choices:
false ← (default)
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.
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.
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 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 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.
+See command_handling for differences in how strings and lists are handled.
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.
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:
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.
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.
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.
This affects the auto_remove, detach, init, interactive, memory, paused, privileged, read_only and tty 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.
This affects the auto_remove, detach, init, interactive, memory, paused, privileged, read_only, and tty options.
Choices:
Limit CPU CFS (Completely Fair Scheduler) period.
-See cpus for an easier to use alternative.
+See cpus for an easier to use alternative.
Limit CPU CFS (Completely Fair Scheduler) quota.
-See cpus for an easier to use alternative.
+See cpus for an easier to use alternative.
Specify how much of the available CPU resources a container can use.
-A value of 1.5 means that at most one and a half CPU (core) will be used.
A value of 1.5 means that at most one and a half CPU (core) will be used.
CPUs in which to allow execution 1,3 or 1-3.
CPUs in which to allow execution 1,3 or 1-3.
Memory nodes (MEMs) in which to allow execution 0-3 or 0,1.
Memory nodes (MEMs) in which to allow execution 0-3 or 0,1.
Define the default host IP to use.
Must be an empty string, an IPv4 address, or an IPv6 address.
-With Docker 20.10.2 or newer, this should be set to an empty string ("") to avoid the port bindings without an explicit IP address to only bind to IPv4. See https://github.com/ansible-collections/community.docker/issues/70 for details.
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.
With Docker 20.10.2 or newer, this should be set to an empty string ("") to avoid the port bindings without an explicit IP address to only bind to IPv4. See https://github.com/ansible-collections/community.docker/issues/70 for details.
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.
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).
-If container_default_behavior is set to compatibility, this option has a default of true.
If container_default_behavior=compatibility, this option has a default of true.
Choices:
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).
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.
integer
Number or devices to request.
-Set to -1 to request all available devices.
Set to -1 to request all available devices.
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).
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.
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.
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"
list / elements=string
Command that overwrites the default ENTRYPOINT of the image.
See command_handling for differences in how strings and lists are handled.
+See command_handling for differences in how strings and lists are handled.
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 }}".
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 }}".
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.
-interval, timeout and start_period are specified as durations. They accept duration as a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
healthcheck.interval, healthcheck.timeout and healthcheck.start_period are specified as durations. They accept 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.
Time between running the check.
-The default used by the Docker daemon is 30s.
The default used by the Docker daemon is 30s.
Consecutive number of failures needed to report unhealthy.
-The default used by the Docker daemon is 3.
The default used by the Docker daemon is 3.
Start period for the container to initialize before starting health-retries countdown.
-The default used by the Docker daemon is 0s.
The default used by the Docker daemon is 0s.
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.
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.
Maximum time to allow one check to run.
-The default used by the Docker daemon is 30s.
The default used by the Docker daemon is 30s.
ignore_image
boolean
When state is present or started, the module compares the configuration of an existing container to requested configuration. The evaluation includes the image version. If the image version in the registry does not match the container, the container will be recreated. You can stop this behavior by setting ignore_image to true.
Warning: This option is ignored if image: ignore or *: ignore is specified in the comparisons option.
This option is deprecated since community.docker 3.2.0 and will be removed in community.docker 4.0.0. Use image: ignore in comparisons instead of ignore_image=true.
When state is present or started, the module compares the configuration of an existing container to requested configuration. The evaluation includes the image version. If the image version in the registry does not match the container, the container will be recreated. You can stop this behavior by setting ignore_image to true.
Warning: This option is ignored if image: ignore or *: ignore is specified in the comparisons option.
This option is deprecated since community.docker 3.2.0 and will be removed in community.docker 4.0.0. Use image: ignore in comparisons instead of ignore_image=true.
Choices:
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.
+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.
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 via 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.
This affects the env, env_file, exposed_ports, labels, and volumes options.
+The default, desired-image, will use the image that is provided to the module via 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.
This affects the env, env_file, exposed_ports, labels, and volumes options.
Choices:
"desired-image" ← (default)
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 comparisons strict.
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.
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 comparisons strict.
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)
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 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.
This is ignored if image: ignore is set in comparisons.
If set to recreate 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.
Choices:
Run an init inside the container that forwards signals and reaps processes.
-If container_default_behavior is set to compatibility, this option has a default of false.
If container_default_behavior=compatibility, this option has a default of false.
Choices:
Keep stdin open after a container is launched, even if not attached.
-If container_default_behavior is set to compatibility, this option has a default of false.
If container_default_behavior=compatibility, this option has a default of false.
Choices:
Set the IPC mode for the container.
-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.
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.
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.
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.
log_driver
string
-Specify the logging driver. Docker uses json-file by default.
See here for possible choices.
+Specify the logging driver. Docker uses json-file by default.
See the Docker logging configuration documentation for possible choices.
Dictionary of options specific to the chosen log_driver.
+Dictionary of options specific to the chosen log_driver.
See https://docs.docker.com/engine/admin/logging/overview/ for details.
-log_driver needs to be specified for log_options to take effect, even if using the default json-file driver.
log_driver needs to be specified for log_options to take effect, even if using the default json-file driver.
Container MAC address (for example, 92:d0:c6:0a:29:33).
Container MAC address (for example, 92:d0:c6:0a:29:33).
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 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.
-If container_default_behavior is set to compatibility, this option has a default of "0".
If container_default_behavior=compatibility, this option has a default of "0".
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).
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).
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.
mounts
list / elements=dictionary
Specification for mounts to be added to the container. More powerful alternative to volumes.
+Specification for mounts to be added to the container. More powerful alternative to volumes.
labels
dictionary
User-defined name and labels for the volume. Only valid for the volume type.
User-defined name and labels for the volume. Only valid for the volume type.
False if the volume should be populated with the data from the target. Only valid for the volume type.
The default value is false.
False if the volume should be populated with the data from the target. Only valid for the volume type.
The default value is false.
Choices:
propagation
string
Propagation mode. Only valid for the bind type.
Mount source.
For example, this can be a volume name or a host path.
-If not supplied when type=volume an anonymous volume will be created.
+If not supplied when mounts[].type=volume an anonymous volume will be created.
The size for the tmpfs mount in bytes 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).
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.
string
The mount type.
-Note that npipe is only supported by Docker for Windows.
Note that npipe is only supported by Docker for Windows.
Choices:
volume_driver
string
Specify the volume driver. Only valid for the volume type.
Specify the volume driver. Only valid for the volume type.
See here for details.
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 is 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.
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.
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 is set to false, this will not remove the default network if networks is specified. This is different from the behavior of docker run .... 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.
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 docker run .... 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.
networks_cli_compatible
boolean
If networks_cli_compatible is set to true (default), this module will behave as docker run --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 is set to false and networks are provided to the module via the networks option, the module behaves differently than docker run --network: docker run --network other will create a container with network other attached, but the default network not attached. This module with networks: {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.
If networks_cli_compatible=true (default), this module will behave as docker run --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 via the networks option, the module behaves differently than docker run --network: docker run --network other 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:
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.
Only effective when log_driver is set to json-file, journald, or local.
Choices:
Use with the started state to pause running processes inside the container.
-If container_default_behavior is set to compatibility, this option has a default of false.
If container_default_behavior=compatibility, this option has a default of false.
Choices:
Set PIDs limit for the container. It accepts an integer value.
-Set -1 for unlimited PIDs.
Set -1 for unlimited PIDs.
Platform for the container in the format os[/arch[/variant]].
Please note that inspecting the container does not always return the exact platform string used to create the container. This can cause idempotency to break for this module. Use the comparisons option with platform: ignore to prevent accidental recreation of the container due to this.
Please note that inspecting the container does not always return the exact platform string used to create the container. This can cause idempotency to break for this module. Use the comparisons option with platform: ignore to prevent accidental recreation of the container due to this.
Give extended privileges to the container.
-If container_default_behavior is set to compatibility, this option has a default of false.
If container_default_behavior=compatibility, this option has a default of false.
Choices:
false
Publish all ports to the host.
-Any specified port bindings from published_ports will remain intact when true.
Any specified port bindings from published_ports will remain intact when true.
Choices:
false
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.
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 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.
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.
purge_networks
boolean
Remove the container from ALL networks not included in networks parameter.
-Any default networks such as bridge, if not found in networks, will be removed as well.
This option is deprecated since community.docker 3.2.0 and will be removed in community.docker 4.0.0. Use networks: strict in comparisons instead of purge_networks=true and make sure that networks is specified. If you want to remove all networks, specify networks: [].
Remove the container from ALL networks not included in networks parameter.
Any default networks such as bridge, if not found in networks, will be removed as well.
This option is deprecated since community.docker 3.2.0 and will be removed in community.docker 4.0.0. Use networks: strict in comparisons instead of purge_networks=true and make sure that networks is specified. If you want to remove all networks, specify networks as [].
Choices:
Mount the container’s root file system as read-only.
-If container_default_behavior is set to compatibility, this option has a default of false.
If container_default_behavior=compatibility, this option has a default of false.
Choices:
Container restart policy.
-Place quotes around no option.
Place quotes around no option.
Choices:
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.
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.
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
+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.
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:
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.
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.
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:
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.
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.
Allocate a pseudo-TTY.
-If container_default_behavior is set to compatibility, this option has a default of false.
If container_default_behavior=compatibility, this option has a default of false.
Choices:
ulimits
list / elements=string
List of ulimit options. A ulimit is specified as nofile:262144:262144.
List of ulimit options. A ulimit is specified as nofile:262144:262144.
userns_mode
string
Set the user namespace mode for the container. Currently, the only valid value are host and the empty string.
Set the user namespace mode for the container. Currently, the only valid value are host and the empty string ("").
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 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:
Note
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.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
dictionary
Facts representing the current state of the container. Matches the docker inspection output.
-Empty if state is absent.
If detach=false, will include Output attribute containing any output from container run.
Returned: success; or when state=started and detach=false, and when waiting for the container result did not fail
+Empty if state=absent.
If detach=false, will include Output attribute containing any output from container run.
Returned: success; or when state=started and detach=false, and when waiting for the container result did not fail
Sample: "{ \"AppArmorProfile\": \"\", \"Args\": [], \"Config\": { \"AttachStderr\": false, \"AttachStdin\": false, \"AttachStdout\": false, \"Cmd\": [ \"/usr/bin/supervisord\" ], \"Domainname\": \"\", \"Entrypoint\": null, \"Env\": [ \"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\" ], \"ExposedPorts\": { \"443/tcp\": {}, \"80/tcp\": {} }, \"Hostname\": \"8e47bf643eb9\", \"Image\": \"lnmp_nginx:v1\", \"Labels\": {}, \"OnBuild\": null, \"OpenStdin\": false, \"StdinOnce\": false, \"Tty\": false, \"User\": \"\", \"Volumes\": { \"/tmp/lnmp/nginx-sites/logs/\": {} }, ... }"
In case a container is started without detaching, this contains the exit code of the process in the container.
Before community.docker 1.1.0, this was only returned when non-zero.
-Returned: when state=started and detach=false, and when waiting for the container result did not fail
+Returned: when state=started and detach=false, and when waiting for the container result did not fail
Sample: 0
requests
pywin32 (when using named pipes on Windows 32)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
backports.ssl_match_hostname (when using TLS on Python 2)
<image name>.
stack_<stack name>: contains the containers that belong to the stack <stack name>.
service_<service name>: contains the containers that belong to the service <service name>
<docker_host>: contains the containers which belong to the Docker daemon docker_host. Useful if you run this plugin against multiple Docker daemons.
<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.
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)
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
Whether to pass all Docker daemon configuration from the inventory plugin to the connection plugin.
-Only used when connection_type=docker-api.
+Only used when connection_type=docker-api.
Choices:
Which connection type to use the containers.
-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.
Alternatively, docker-cli selects the docker connection plugin, and docker-api (default) selects the docker_api connection plugin.
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.
Note that the docker_api connection plugin does not work with TCP TLS sockets! See https://github.com/ansible-collections/community.docker/issues/605 for more information.
+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.
Alternatively, docker-cli selects the community.docker.docker connection plugin, and docker-api (default) selects the community.docker.docker_api connection plugin.
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.
Note that the community.docker.docker_api does not work with TCP TLS sockets! See https://github.com/ansible-collections/community.docker/issues/605 for more information.
Choices:
The IP address to assign to ansible_host when the container’s SSH port is mapped to interface ‘0.0.0.0’.
-Only used if connection_type is ssh.
Only used if connection_type is ssh.
Default: "127.0.0.1"
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.
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"
plugin
string / required
The name of this plugin, it should always be set to community.docker.docker_containers for this plugin to recognize it as it’s own.
The port containers use for SSH.
-Only used if connection_type is ssh.
Only used if connection_type is ssh.
Default: 22
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
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.
If this is false, these values can only be used during constructed, groups, and keyed_groups.
The docker inventory script always added these variables, so for compatibility set this to true.
If this is false, these values can only be used during compose, groups, and keyed_groups.
The docker inventory script always added these variables, so for compatibility set this to true.
Choices:
false ← (default)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
ssl_version
string
-Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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:
verbose_output
boolean
When set to true and networks, volumes, images, containers or disk_usage is set to true then output will contain verbose information about objects matching the full output of API method. For details see the documentation of your version of Docker API at https://docs.docker.com/engine/api/.
The verbose output in this module contains only subset of information returned by _info module for each type of the objects.
+When set to true and networks, volumes, images, containers, or disk_usage is set to true then output will contain verbose information about objects matching the full output of API method. For details see the documentation of your version of Docker API at https://docs.docker.com/engine/api/.
The verbose output in this module contains only subset of information returned by this module for each type of the objects.
Choices:
false ← (default)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
can_talk_to_docker
boolean
Will be true if the module can talk to the docker daemon.
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 docker container ls output unless verbose_output=true. See description for verbose_output.
Returned: When containers is true
List of dict objects containing the basic information about each container. Keys matches the docker container ls output unless verbose_output=true. See description for verbose_output.
Returned: When containers=true
Information on summary disk usage by images, containers and volumes on docker host unless verbose_output=true. See description for verbose_output.
-Returned: When disk_usage is true
Information on summary disk usage by images, containers and volumes on docker host unless verbose_output=true. See description for verbose_output.
Returned: When disk_usage=true
images
list / elements=dictionary
List of dict objects containing the basic information about each image. Keys matches the docker image ls output unless verbose_output=true. See description for verbose_output.
Returned: When images is true
List of dict objects containing the basic information about each image. Keys matches the docker image ls output unless verbose_output=true. See description for verbose_output.
Returned: When images=true
List of dict objects containing the basic information about each network. Keys matches the docker network ls output unless verbose_output=true. See description for verbose_output.
Returned: When networks is true
List of dict objects containing the basic information about each network. Keys matches the docker network ls output unless verbose_output=true. See description for verbose_output.
Returned: When networks=true
List of dict objects containing the basic information about each volume. Keys matches the docker volume ls output unless verbose_output=true. See description for verbose_output.
Returned: When volumes is true
List of dict objects containing the basic information about each volume. Keys matches the docker volume ls output unless verbose_output=true. See description for verbose_output.
Returned: When volumes=true
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 module will not attempt to pull images from registries. Use community.docker.docker_image with source set to pull to ensure an image is pulled.
The module will not attempt to pull images from registries. Use community.docker.docker_image with source=pull to ensure an image is pulled.
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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.
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.
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
This module was called docker_image_facts before Ansible 2.8. The usage did not change.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
ssl_version
string
-Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
Does not support check_mode.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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.
Use with state=present to archive an image to a .tar file.
CPUs in which to allow execution.
-For example, 0-3 or 0,1.
For example, 0-3 or 0,1.
Total memory (memory + swap).
-Use -1 to disable swap.
Use -1 to disable swap.
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 path).
+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).
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.
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
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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.
+Use with state=absent to un-tag and remove all images matching the specified name.
Choices:
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.
Use with state=present to build, load or pull an image (depending on the value of the source option) when the image already exists.
Choices:
force_tag
boolean
Use with state present to force tagging an image.
Use with state=present to force tagging an image.
Choices:
load_path
path
Use with state present to load an image from a .tar file.
Set source to load if you want to load the image.
Use with state=present to load an image from a .tar file.
Set source=load if you want to load the image.
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) are only supported for state=absent, for state=present with source=load, and for state=present with source=local.
+Note that image IDs (hashes) are only supported for state=absent, for state=present with source=load, and for state=present with source=local.
push
boolean
Push the image to the registry. Specify the registry as part of the name or repository parameter.
+Push the image to the registry. Specify the registry as part of the name or repository parameter.
Choices:
repository
string
Use with state present to tag the image.
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).
+Use with state=present to tag the image.
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).
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.
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:
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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:
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.
+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.
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.
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:
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.
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.
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 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)
Building images is done using Docker daemon’s API. It is not possible to use BuildKit / buildx this way.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
string
The plaintext password for the registry account.
-Required when state is present.
Required when state=present.
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
This controls the current state of the user. present will login in a user, absent will log them out.
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.
@@ -348,7 +348,7 @@ seeinteger
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.
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.
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:
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.
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.
The username for the registry account.
-Required when state is present.
Required when state=present.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
dictionary
Results from the login.
-Returned: when state=present
+Returned: when state=present
Sample: {"serveraddress": "localhost:5000", "username": "testuser"}
ansible_port, ansible_user and ansible_ssh_private_key.
-The plugin stores the Docker Machine ‘env’ output variables in dm_ prefixed host variables.
The plugin stores the Docker Machine ‘env’ output variables in dm_ prefixed host variables.
string
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.
+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:
running_required
boolean
When true, hosts which Docker Machine indicates are in a state other than running will be skipped.
When true, hosts which Docker Machine indicates are in a state other than running will be skipped.
Choices:
verbose_output
boolean
When true, include all available nodes metadata (for exmaple Image, Region, Size) as a JSON object named docker_machine_node_attributes.
When true, include all available nodes metadata (for exmaple Image, Region, Size) as a JSON object named docker_machine_node_attributes.
Choices:
false
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
dictionary
Facts representing the current state of the network. Matches the docker inspection output.
-Will be none if network does not exist.
Will be none if network does not exist.
Returned: always
Sample: {"Attachable": false, "ConfigFrom": {"Network": ""}, "ConfigOnly": false, "Containers": {}, "Created": "2018-12-07T01:47:51.250835114-06:00", "Driver": "bridge", "EnableIPv6": false, "IPAM": {"Config": [{"Gateway": "192.168.96.1", "Subnet": "192.168.96.0/20"}], "Driver": "default", "Options": null}, "Id": "0856968545f22026c41c2c7c3d448319d3b4a6a03a40b148b3ac4031696d1c0a", "Ingress": false, "Internal": false, "Labels": {}, "Name": "ansible-test-f2700bba", "Options": {}, "Scope": "local"}
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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
-With state absent forces disconnecting all containers from the network prior to deleting the network. With state present will disconnect all containers, delete the network and re-create the network.
With state absent forces disconnecting all containers from the network prior to deleting the network. With state present will disconnect all containers, 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:
ipam_config
list / elements=dictionary
List of IPAM config blocks. Consult Docker docs for valid options and values. Note that iprange is spelled differently here (we use the notation from the Docker SDK for Python).
+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).
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
absent deletes the network. If a network has connected containers, it cannot be deleted. Use the force option to disconnect all containers and delete the network.
present creates the network, if it does not already exist with the specified parameters, and connects the list of containers provided via 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.
absent deletes the network. If a network has connected containers, it cannot be deleted. Use the force option to disconnect all containers and delete the network.
present creates the network, if it does not already exist with the specified parameters, and connects the list of containers provided via 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:
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.
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.
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:
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.
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.
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 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)
Note
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.
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.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
If self=true then this parameter is ignored.
If true, queries the node (that is, the docker daemon) the module communicates with.
If true then name is ignored.
If false then query depends on name presence and value.
If true, queries the node (that is, the docker daemon) the module communicates with.
If true then name is ignored.
If false then query depends on name presence and value.
Choices:
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
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.
This module uses the Docker SDK for Python to communicate with the Docker daemon.
list / elements=dictionary
Facts representing the current state of the nodes. Matches the docker node inspect 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.
+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.
Returned: always
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
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.
+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.
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.
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)
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.
-If labels_state is replace and labels is not provided or empty then all labels assigned to node are removed and labels_to_remove is ignored.
If the label is both on the labels_to_remove and labels, then value provided in labels remains assigned to the node.
If labels_state=replace and labels is not provided or empty then all labels assigned to node are removed and labels_to_remove is ignored.
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
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.
This module uses the Docker SDK for Python to communicate with the Docker daemon.
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
ssl_version
string
-Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
absent remove the plugin.
present install the plugin, if it does not already exist.
enable enable the plugin.
disable disable the plugin.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
list / elements=string
List of actions performed during task execution.
-Returned: when state!=absent
+Returned: when state is not absent
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
ssl_version
string
-Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
The module always returned changed=false before community.docker 3.5.1.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
integer
Amount of reclaimed disk space from builder cache pruning in bytes.
-Returned: builder_cache is true
Returned: builder_cache=true
Sample: 0
list / elements=string
List of IDs of deleted containers.
-Returned: containers is true
Returned: containers=true
Sample: []
integer
Amount of reclaimed disk space from container pruning in bytes.
-Returned: containers is true
Returned: containers=true
Sample: 0
list / elements=string
integer
Amount of reclaimed disk space from image pruning in bytes.
-Returned: images is true
Returned: images=true
Sample: 0
list / elements=string
list / elements=string
integer
Amount of reclaimed disk space from volumes pruning in bytes.
-Returned: volumes is true
Returned: volumes=true
Sample: 0
Create and remove Docker secrets in a Swarm environment. Similar to docker secret create and docker secret rm.
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.
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 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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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 value of the secret.
-Mutually exclusive with data_src. One of data and data_src is required if state=present.
+Mutually exclusive with data_src. One of data and data_src is required if state=present.
If set to true, the data is assumed to be Base64 encoded and will be decoded before being used.
To use binary data, it is better to keep it Base64 encoded and let it be decoded by this option.
+If set to true, the data is assumed to be Base64 encoded and will be decoded before being used.
To use binary data, it is better to keep it Base64 encoded and let it be decoded by this option.
Choices:
false ← (default)
The file on the target from which to read the secret.
-Mutually exclusive with data. One of data and data_src is required if state=present.
+Mutually exclusive with data. One of data and data_src is required if state=present.
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.
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.
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:
If set to true, secrets are created with an increasing version number appended to their name.
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:
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Set to present, if the secret should exist, and absent, if it should not.
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.
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.
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:
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.
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.
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 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:
When using rolling_versions, the number of old versions of the secret to keep.
+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.
Set to -1 to keep everything or to 0 or 1 to keep only the current one.
Default: 5
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
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.
This module uses the Docker SDK for Python to communicate with the Docker daemon.
string
The ID assigned by Docker to the secret object.
-Returned: success and state is present
Returned: success and state=present
Sample: "hzehrmyjigmcp2gb6nlhmjqcv"
The name of the created secret object.
-Returned: success and state is present
Returned: success and state=present
Sample: "awesome_secret"
absent_retries
integer
If >0 and state is 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.
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.
Default: 0
absent_retries_interval
integer
Interval in seconds between consecutive absent_retries.
+Interval in seconds between consecutive absent_retries.
Default: 1
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
ssl_version
string
-Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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:
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 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.
For details see the documentation of your version of Docker API at https://docs.docker.com/engine/api/.
-The verbose output in this module contains only subset of information returned by _info module for each type of the objects.
+The verbose output in this module contains only subset of information returned by this info module for each type of the objects.
Choices:
false ← (default)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
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.
This module uses the Docker SDK for Python to communicate with the Docker daemon.
can_talk_to_docker
boolean
Will be true if the module can talk to the docker daemon.
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.
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.
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 docker node ls output unless verbose_output=true. See description for verbose_output.
Returned: When nodes is true
List of dict objects containing the basic information about each volume. Keys matches the docker node ls output unless verbose_output=true. See description for verbose_output.
Returned: When nodes=true
List of dict objects containing the basic information about each volume. Keys matches the docker service ls output unless verbose_output=true. See description for verbose_output.
Returned: When services is true
List of dict objects containing the basic information about each volume. Keys matches the docker service ls output unless verbose_output=true. See description for verbose_output.
Returned: When services=true
Contains the key needed to unlock the swarm.
-Returned: When unlock_key is true.
Returned: When unlock_key=true.
List of dict objects containing the basic information about each volume. Keys matches the docker service ps output unless verbose_output=true. See description for verbose_output.
Returned: When tasks is true
List of dict objects containing the basic information about each volume. Keys matches the docker service ps output unless verbose_output=true. See description for verbose_output.
Returned: When tasks=true
Reads inventories from the Docker swarm API.
Uses a YAML configuration file 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 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.
Socket of a Docker swarm manager node (tcp, unix).
Use unix://var/run/docker.sock to connect via local socket.
Use unix://var/run/docker.sock to connect via local socket.
include_host_uri
boolean
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 via API. The port always defaults to 2376.
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 via API. The port always defaults to 2376.
Choices:
include_host_uri_port
integer
Override the detected port number included in ansible_host_uri
+Override the detected port number included in ansible_host_uri.
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 it’s own.
The name of this plugin, it should always be set to community.docker.docker_swarm for this plugin to recognize it as it’s own.
Choices:
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
+Provide a valid SSL version number. Default value determined by SSL Python module.
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.
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
verbose_output
boolean
-Toggle to (not) include all available nodes metadata (for example Platform, Architecture, OS, EngineVersion)
Toggle to (not) include all available nodes metadata (for example Platform, Architecture, OS, EngineVersion).
Choices:
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.
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.
+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’s not considered for idempotency checking.
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.
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"
boolean
If set, generate a key and use it to lock data stored on the managers.
-Docker default value is false.
Docker default value is false.
community.docker.docker_swarm_info can be used to retrieve the unlock key.
Choices:
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
Docker default value is 0.
Requires API version >= 1.30.
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.
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.
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 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.
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.
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.
Port to use for data path traffic.
-This needs to be a port number like 9789.
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.
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 default value is 5 seconds, which corresponds to a value of 5000000000.
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.
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"
integer
Amount of ticks (in seconds) needed without a leader to trigger a new election.
-Docker default value is 10 seconds.
Docker default value is 10 seconds.
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.
Amount of ticks (in seconds) between each heartbeat.
-Docker default value is 1 seconds.
Docker default value is 1 seconds.
Swarm token used to join a swarm cluster.
-Used with state=join.
+Used with state=join.
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.
integer
Number of snapshots to keep beyond the current snapshot.
-Docker default value is 0.
Docker default value is 0.
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.
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’s not considered for idempotency checking.
Default: "0.0.0.0:2377"
integer
Automatic expiry for nodes certificates, given in nanoseconds.
-Docker default value is 90 days, which corresponds to a value of 7776000000000000.
Docker default value is 90 days, which corresponds to a value of 7776000000000000.
Remote address of one or more manager nodes of an existing Swarm to connect to.
-Used with state=join.
+Used with state=join.
Number of logs entries between snapshot.
-Docker default value is 10000.
Docker default value is 10000.
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Set to present, to create/update a new cluster.
Set to join, to join an existing cluster.
Set to absent, to leave an existing cluster.
Set to remove, to remove an absent node from the cluster. Note that removing requires Docker SDK for Python >= 2.4.0.
Set to present, to create/update a new cluster.
Set to join, to join an existing cluster.
Set to absent, to leave an existing cluster.
Set to remove, to remove an absent node from the cluster. Note that removing requires Docker SDK for Python >= 2.4.0.
community.docker.docker_node can be used to demote a manager before removal.
Choices:
Maximum number of tasks history stored.
-Docker default value is 5.
Docker default value is 5.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
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.
This module uses the Docker SDK for Python to communicate with the Docker daemon.
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!
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"
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!
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"
UnlockKey
string
-The swarm unlock-key if autolock_managers is true.
Returned: on success if autolock_managers is true and swarm is initialised, or if autolock_managers has changed.
The swarm unlock-key if autolock_managers=true.
Returned: on success if autolock_managers=true and swarm is initialised, or if autolock_managers has changed.
Sample: "SWMKEY-1-xxx"
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
ssl_version
string
-Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
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.
This module uses the Docker SDK for Python to communicate with the Docker daemon.
dictionary
A dictionary representing the current state of the service. Matches the docker service inspect output.
Will be none if service does not exist.
Will be none if service does not exist.
Returned: always
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
filename
string
Name of the file containing the config. Defaults to the config_name if not specified.
+Name of the file containing the config. Defaults to the configs[].config_name if not specified.
mode
integer
File access mode inside the container. Must be an octal number (like 0644 or 0444).
File access mode inside the container. Must be an octal number (like 0644 or 0444).
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.
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"
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.
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 docker service create.
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.
+If variable also present in env, then env value will override.
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.
-interval, timeout and start_period are specified as durations. They accept duration as a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
healthcheck.interval, healthcheck.timeout, and healthcheck.start_period are specified as durations. They accept 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.
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.
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.
cpus
float
Service CPU limit. 0 equals no limit.
Service CPU limit. 0 equals no limit.
Corresponds to the --limit-cpu option of docker service create.
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.
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 docker service create.
dictionary
Volume driver configuration.
-Can only be used when type is volume.
Can only be used when mounts[].type=volume.
Disable copying of data from a container when a volume is created.
-Can only be used when type is volume.
Can only be used when mounts[].type=volume.
Choices:
The propagation mode to use.
-Can only be used when type is bind.
Can only be used when mounts[].type=bind.
Choices:
Mount source (for example a volume name or a host path).
-Must be specified if type is not tmpfs.
Must be specified if mounts[].type is not tmpfs.
File mode of the tmpfs in octal.
-Can only be used when type is tmpfs.
Can only be used when mounts[].type=tmpfs.
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).
Can only be used when type is tmpfs.
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).
Can only be used when mounts[].type=tmpfs.
List of the service networks names or dictionaries.
-When passed dictionaries valid sub-options are name, which is required, and aliases and options.
+When passed dictionaries valid sub-options are name, which is required, and aliases and options.
Prior to API version 1.29, updating and removing networks is not supported. If changes are made the service will then be removed and recreated.
Corresponds to the --network option of docker service create.
replicas
integer
-Number of containers instantiated in the service. Valid only if mode is replicated.
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.
Number of containers instantiated in the service. Valid only if mode=replicated.
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 docker service create.
Default: -1
cpus
float
Service CPU reservation. 0 equals no reservation.
Service CPU reservation. 0 equals no reservation.
Corresponds to the --reserve-cpu option of docker service create.
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.
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 docker service create.
string
Delay between restarts.
-Accepts a a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Accepts a a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Corresponds to the --restart-delay option of docker service create.
string
Restart policy evaluation window.
-Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Corresponds to the --restart-window option of docker service create.
string
Delay between task rollbacks.
-Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Corresponds to the --rollback-delay option of docker service create.
Requires API version >= 1.28.
string
Duration after each task rollback to monitor for failure.
-Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Corresponds to the --rollback-monitor option of docker service create.
Requires API version >= 1.28.
filename
string
-Name of the file containing the secret. Defaults to the secret_name if not specified.
+Name of the file containing the secret. Defaults to the secrets[].secret_name if not specified.
Corresponds to the target key of docker service create --secret.
mode
integer
File access mode inside the container. Must be an octal number (like 0644 or 0444).
File access mode inside the container. Must be an octal number (like 0644 or 0444).
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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:
Time to wait before force killing a container.
-Accepts a duration as a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Accepts a duration as a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Corresponds to the --stop-grace-period option of docker service create.
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.
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.
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:
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.
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.
Rolling update delay.
-Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Corresponds to the --update-delay option of docker service create.
Time to monitor updated tasks for failures.
-Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Accepts a string in a format that look like: 5h34m56s, 1m30s etc. The supported units are us, ms, s, m and h.
Corresponds to the --update-monitor option of docker service create.
string
Sets the username or UID used for the specified command.
-Before Ansible 2.8, the default value for this option was root.
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 docker service create.
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 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)
Note
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.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
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.
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.
This module uses the Docker SDK for Python to communicate with the Docker daemon.
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.
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.
Returned: always
Sample: {"args": ["3600"], "cap_add": null, "cap_drop": ["ALL"], "command": ["sleep"], "configs": null, "constraints": ["node.role == manager", "engine.labels.operatingsystem == ubuntu 14.04"], "container_labels": null, "dns": null, "dns_options": null, "dns_search": null, "endpoint_mode": null, "env": ["ENVVAR1=envvar1", "ENVVAR2=envvar2"], "force_update": null, "groups": null, "healthcheck": {"interval": 90000000000, "retries": 3, "start_period": 30000000000, "test": ["CMD", "curl", "--fail", "http://nginx.host.com"], "timeout": 10000000000}, "healthcheck_disabled": false, "hostname": null, "hosts": null, "image": "alpine:latest@sha256:b3dbf31b77fd99d9c08f780ce6f5282aba076d70a513a8be859d8d3a4d0c92b8", "labels": {"com.example.department": "Finance", "com.example.description": "Accounting webapp"}, "limit_cpu": 0.5, "limit_memory": 52428800, "log_driver": "fluentd", "log_driver_options": {"fluentd-address": "127.0.0.1:24224", "fluentd-async-connect": "true", "tag": "myservice"}, "mode": "replicated", "mounts": [{"driver_config": null, "labels": null, "no_copy": null, "propagation": null, "readonly": false, "source": "/tmp/", "target": "/remote_tmp/", "tmpfs_mode": null, "tmpfs_size": null, "type": "bind"}], "networks": null, "placement_preferences": [{"spread": "node.labels.mylabel"}], "publish": null, "read_only": null, "replicas": 1, "replicas_max_per_node": 1, "reserve_cpu": 0.25, "reserve_memory": 20971520, "restart_policy": "on-failure", "restart_policy_attempts": 3, "restart_policy_delay": 5000000000, "restart_policy_window": 120000000000, "secrets": null, "stop_grace_period": null, "stop_signal": null, "tty": null, "update_delay": 10000000000, "update_failure_action": null, "update_max_failure_ratio": null, "update_monitor": null, "update_order": "stop-first", "update_parallelism": 2, "user": null, "working_dir": null}
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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"
ssl_version
string
-Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
dictionary
Volume inspection results for the affected volume.
-Will be none if volume does not exist.
Will be none if volume does not exist.
Returned: success
Sample: {"CreatedAt": "2018-12-09T17:43:44+01:00", "Driver": "local", "Labels": null, "Mountpoint": "/var/lib/docker/volumes/ansible-test-bd3f6172/_data", "Name": "ansible-test-bd3f6172", "Options": {}, "Scope": "local"}
Docker API >= 1.25
backports.ssl_match_hostname (when using TLS on Python 2)
paramiko (when using SSH with use_ssh_client=false)
paramiko (when using SSH with use_ssh_client=false)
pyOpenSSL (when using TLS)
pywin32 (when using named pipes on Windows 32)
requests
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.
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"
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 ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.
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.
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.
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 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.
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.
Specify the type of volume. Docker provides the local driver, but 3rd party drivers can also be used.
Default: "local"
recreate
string
Controls when a volume will be recreated when state is 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.
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:
ssl_version
string
Provide a valid SSL version number. Default value determined by ssl.py module.
-If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
Provide a valid SSL version number. Default value determined by SSL Python module.
+If the value is not specified in the task, the value of environment variable DOCKER_SSL_VERSION will be used instead.
absent deletes the volume.
present creates the volume, if it does not already exist.
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.
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.
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:
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.
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.
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 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)
Note
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
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.
--+ + +-
- DOCKER_HOST
- -
The URL or Unix socket path used to connect to the Docker API.
-- DOCKER_API_VERSION
The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported +
+
+ +- +DOCKER_HOST
+The URL or Unix socket path used to connect to the Docker API.
++
-- +DOCKER_API_VERSION
+- -
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.
-- DOCKER_TIMEOUT
- -
The maximum amount of time in seconds to wait on a response from the API.
-- DOCKER_CERT_PATH
- -
Path to the directory containing the client certificate, client key and CA certificate.
-- DOCKER_SSL_VERSION
- -
Provide a valid SSL version number.
-- DOCKER_TLS
- -
Secure the connection to the API by using TLS without verifying the authenticity of the Docker Host.
-- DOCKER_TLS_VERIFY
- -
Secure the connection to the API by using TLS and verify the authenticity of the Docker Host.
-
The maximum amount of time in seconds to wait on a response from the API.
+Path to the directory containing the client certificate, client key and CA certificate.
+Provide a valid SSL version number.
+Secure the connection to the API by using TLS without verifying the authenticity of the Docker Host.
+When verifying the authenticity of the Docker Host, uses this hostname to compare to the host’s certificate.
+Secure the connection to the API by using TLS and verify the authenticity of the Docker Host.
+