ansible-collections/community.docker
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.docker.git synced 2026-03-15 11:53:31 +00:00
Code Packages Projects Releases Wiki Activity

Use semantic markup (#645)

Browse Source 
* Use semantic markup.

* Linting.

* Define docsite targets.

* Forgot one env var.

* Add array stubs.
This commit is contained in:
Felix Fontein 2023-06-22 07:01:31 +02:00 committed by GitHub
parent f94beeb027
commit 024bdec919
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
34 changed files with 571 additions and 547 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/docsite/config.yml Normal file
View File

@ -0,0 +1,15 @@
---
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
# The following `.. envvar::` directives are defined in the extra docsite docs:
envvar_directives:
- DOCKER_HOST
- DOCKER_API_VERSION
- DOCKER_TIMEOUT
- DOCKER_CERT_PATH
- DOCKER_SSL_VERSION
- DOCKER_TLS
- DOCKER_TLS_HOSTNAME
- DOCKER_TLS_VERIFY

41
docs/docsite/rst/scenario_guide.rst
View File

@ -86,27 +86,38 @@ You can also control how the plugins and modules connect to the Docker API by se
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.
.. envvar:: DOCKER_HOST
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.
The URL or Unix socket path used to connect to the Docker API.
DOCKER_TIMEOUT
The maximum amount of time in seconds to wait on a response from the API.
.. envvar:: DOCKER_API_VERSION
DOCKER_CERT_PATH
Path to the directory containing the client certificate, client key and CA certificate.
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_SSL_VERSION
Provide a valid SSL version number.
.. envvar:: DOCKER_TIMEOUT
DOCKER_TLS
Secure the connection to the API by using TLS without verifying the authenticity of the Docker Host.
The maximum amount of time in seconds to wait on a response from the API.
DOCKER_TLS_VERIFY
Secure the connection to the API by using TLS and verify the authenticity of the Docker Host.
.. envvar:: DOCKER_CERT_PATH
Path to the directory containing the client certificate, client key and CA certificate.
.. envvar:: DOCKER_SSL_VERSION
Provide a valid SSL version number.
.. envvar:: DOCKER_TLS
Secure the connection to the API by using TLS without verifying the authenticity of the Docker Host.
.. envvar:: DOCKER_TLS_HOSTNAME
When verifying the authenticity of the Docker Host, uses this hostname to compare to the host's certificate.
.. envvar:: DOCKER_TLS_VERIFY
Secure the connection to the API by using TLS and verify the authenticity of the Docker Host.
Plain Docker daemon: images, networks, volumes, and containers

3
plugins/connection/docker.py
View File

@ -20,8 +20,7 @@ description:
- Run commands or put/fetch files to an existing docker container.
- Uses the Docker CLI to execute commands in the container. If you prefer
to directly connect to the Docker daemon, use the
R(community.docker.docker_api,ansible_collections.community.docker.docker_api_connection)
connection plugin.
P(community.docker.docker_api#connection) connection plugin.
options:
remote_addr:
description:

3
plugins/connection/docker_api.py
View File

@ -15,8 +15,7 @@ description:
- Run commands or put/fetch files to an existing docker container.
- Uses the L(requests library,https://pypi.org/project/requests/) to interact
directly with the Docker daemon instead of using the Docker CLI. Use the
R(community.docker.docker,ansible_collections.community.docker.docker_connection)
connection plugin if you want to use the Docker CLI.
P(community.docker.docker#connection) connection plugin if you want to use the Docker CLI.
notes:
- Does B(not work with TCP TLS sockets)! This is caused by the inability to send C(close_notify) without closing the connection
with Python's C(SSLSocket)s. See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.

84
plugins/doc_fragments/docker.py
View File

@ -16,9 +16,9 @@ options:
docker_host:
description:
- The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the
TCP connection string. For example, C(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection,
TCP connection string. For example, V(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection,
the module will automatically replace C(tcp) in the connection URL with C(https).
- If the value is not specified in the task, the value of environment variable C(DOCKER_HOST) will be used
- If the value is not specified in the task, the value of environment variable E(DOCKER_HOST) will be used
instead. If the environment variable is not set, the default value will be used.
type: str
default: unix://var/run/docker.sock
@ -26,15 +26,15 @@ options:
tls_hostname:
description:
- When verifying the authenticity of the Docker Host server, provide the expected name of the server.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TLS_HOSTNAME) will
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME) will
be used instead. If the environment variable is not set, the default value will be used.
- Note that this option had a default value C(localhost) in older versions. It was removed in community.docker 3.0.0.
- Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0.
type: str
api_version:
description:
- 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 C(DOCKER_API_VERSION) will be
- If the value is not specified in the task, the value of environment variable E(DOCKER_API_VERSION) will be
used instead. If the environment variable is not set, the default value will be used.
type: str
default: auto
@ -42,42 +42,42 @@ options:
timeout:
description:
- The maximum amount of time in seconds to wait on a response from the API.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TIMEOUT) will be used
- If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT) will be used
instead. If the environment variable is not set, the default value will be used.
type: int
default: 60
ca_cert:
description:
- Use a CA certificate when performing server verification by providing the path to a CA certificate file.
- If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set,
the file C(ca.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [ tls_ca_cert, cacert_path ]
client_cert:
description:
- Path to the client's TLS certificate file.
- If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set,
the file C(cert.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
the file C(cert.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [ tls_client_cert, cert_path ]
client_key:
description:
- Path to the client's TLS key file.
- If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set,
the file C(key.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
the file C(key.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [ tls_client_key, key_path ]
ssl_version:
description:
- 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 C(DOCKER_SSL_VERSION) will be
- Provide a valid SSL version number. Default value determined by L(SSL Python module, https://docs.python.org/3/library/ssl.html).
- If the value is not specified in the task, the value of environment variable E(DOCKER_SSL_VERSION) will be
used instead.
type: str
tls:
description:
- Secure the connection to the API by using TLS without verifying the authenticity of the Docker host
server. Note that if I(validate_certs) is set to C(true) as well, it will take precedence.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TLS) will be used
server. Note that if O(validate_certs) is set to V(true) as well, it will take precedence.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used
instead. If the environment variable is not set, the default value will be used.
type: bool
default: false
@ -91,7 +91,7 @@ options:
validate_certs:
description:
- Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TLS_VERIFY) will be
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_VERIFY) will be
used instead. If the environment variable is not set, the default value will be used.
type: bool
default: false
@ -104,14 +104,14 @@ options:
notes:
- Connect to the Docker daemon by providing parameters with each task or by defining environment variables.
You can define C(DOCKER_HOST), C(DOCKER_TLS_HOSTNAME), C(DOCKER_API_VERSION), C(DOCKER_CERT_PATH), C(DOCKER_SSL_VERSION),
C(DOCKER_TLS), C(DOCKER_TLS_VERIFY) and C(DOCKER_TIMEOUT). If you are using docker machine, run the script shipped
You can define E(DOCKER_HOST), E(DOCKER_TLS_HOSTNAME), E(DOCKER_API_VERSION), E(DOCKER_CERT_PATH), E(DOCKER_SSL_VERSION),
E(DOCKER_TLS), E(DOCKER_TLS_VERIFY) and E(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
U(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 C(docker[tls]) with M(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 C($HOME/.docker/config.json) if the C(DOCKER_CONFIG) environment variable is not specified,
In general, it will use C($HOME/.docker/config.json) if the E(DOCKER_CONFIG) environment variable is not specified,
and use C($DOCKER_CONFIG/config.json) otherwise.
'''
@ -189,9 +189,9 @@ options:
docker_host:
description:
- The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the
TCP connection string. For example, C(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection,
TCP connection string. For example, V(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection,
the module will automatically replace C(tcp) in the connection URL with C(https).
- If the value is not specified in the task, the value of environment variable C(DOCKER_HOST) will be used
- If the value is not specified in the task, the value of environment variable E(DOCKER_HOST) will be used
instead. If the environment variable is not set, the default value will be used.
type: str
default: unix://var/run/docker.sock
@ -199,15 +199,15 @@ options:
tls_hostname:
description:
- When verifying the authenticity of the Docker Host server, provide the expected name of the server.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TLS_HOSTNAME) will
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME) will
be used instead. If the environment variable is not set, the default value will be used.
- Note that this option had a default value C(localhost) in older versions. It was removed in community.docker 3.0.0.
- Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0.
type: str
api_version:
description:
- The version of the Docker API running on the Docker Host.
- Defaults to the latest version of the API supported by this collection and the docker daemon.
- If the value is not specified in the task, the value of environment variable C(DOCKER_API_VERSION) will be
- If the value is not specified in the task, the value of environment variable E(DOCKER_API_VERSION) will be
used instead. If the environment variable is not set, the default value will be used.
type: str
default: auto
@ -215,42 +215,42 @@ options:
timeout:
description:
- The maximum amount of time in seconds to wait on a response from the API.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TIMEOUT) will be used
- If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT) will be used
instead. If the environment variable is not set, the default value will be used.
type: int
default: 60
ca_cert:
description:
- Use a CA certificate when performing server verification by providing the path to a CA certificate file.
- If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set,
the file C(ca.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [ tls_ca_cert, cacert_path ]
client_cert:
description:
- Path to the client's TLS certificate file.
- If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set,
the file C(cert.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
the file C(cert.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [ tls_client_cert, cert_path ]
client_key:
description:
- Path to the client's TLS key file.
- If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set,
the file C(key.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
the file C(key.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [ tls_client_key, key_path ]
ssl_version:
description:
- 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 C(DOCKER_SSL_VERSION) will be
- Provide a valid SSL version number. Default value determined by L(SSL Python module, https://docs.python.org/3/library/ssl.html).
- If the value is not specified in the task, the value of environment variable E(DOCKER_SSL_VERSION) will be
used instead.
type: str
tls:
description:
- Secure the connection to the API by using TLS without verifying the authenticity of the Docker host
server. Note that if I(validate_certs) is set to C(true) as well, it will take precedence.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TLS) will be used
server. Note that if O(validate_certs) is set to V(true) as well, it will take precedence.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used
instead. If the environment variable is not set, the default value will be used.
type: bool
default: false
@ -263,7 +263,7 @@ options:
validate_certs:
description:
- Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TLS_VERIFY) will be
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_VERIFY) will be
used instead. If the environment variable is not set, the default value will be used.
type: bool
default: false
@ -276,14 +276,12 @@ options:
notes:
- Connect to the Docker daemon by providing parameters with each task or by defining environment variables.
You can define C(DOCKER_HOST), C(DOCKER_TLS_HOSTNAME), C(DOCKER_API_VERSION), C(DOCKER_CERT_PATH), C(DOCKER_SSL_VERSION),
C(DOCKER_TLS), C(DOCKER_TLS_VERIFY) and C(DOCKER_TIMEOUT). If you are using docker machine, run the script shipped
You can define E(DOCKER_HOST), E(DOCKER_TLS_HOSTNAME), E(DOCKER_API_VERSION), E(DOCKER_CERT_PATH), E(DOCKER_SSL_VERSION),
E(DOCKER_TLS), E(DOCKER_TLS_VERIFY) and E(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
U(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 C(docker[tls]) with M(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 C($HOME/.docker/config.json) if the C(DOCKER_CONFIG) environment variable is not specified,
# In general, it will use C($HOME/.docker/config.json) if the E(DOCKER_CONFIG) environment variable is not specified,
# and use C($DOCKER_CONFIG/config.json) otherwise.
- This module does B(not) use the L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) to
communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this
@ -291,7 +289,7 @@ notes:
requirements:
- requests
- pywin32 (when using named pipes on Windows 32)
- paramiko (when using SSH with I(use_ssh_client=false))
- paramiko (when using SSH with O(use_ssh_client=false))
- pyOpenSSL (when using TLS)
- backports.ssl_match_hostname (when using TLS on Python 2)
'''

35
plugins/inventory/docker_containers.py
View File

@ -27,7 +27,7 @@ description:
options:
plugin:
description:
- The name of this plugin, it should always be set to C(community.docker.docker_containers)
- The name of this plugin, it should always be set to V(community.docker.docker_containers)
for this plugin to recognize it as it's own.
type: str
required: true
@ -36,17 +36,14 @@ options:
connection_type:
description:
- Which connection type to use the containers.
- One way to connect to containers is to use SSH (C(ssh)). For this, the options I(default_ip) and
I(private_ssh_port) are used. This requires that a SSH daemon is running inside the containers.
- Alternatively, C(docker-cli) selects the
R(docker connection plugin,ansible_collections.community.docker.docker_connection),
and C(docker-api) (default) selects the
R(docker_api connection plugin,ansible_collections.community.docker.docker_api_connection).
- When C(docker-api) is used, all Docker daemon configuration values are passed from the inventory plugin
to the connection plugin. This can be controlled with I(configure_docker_daemon).
- Note that the R(docker_api connection plugin,ansible_collections.community.docker.docker_api_connection)
does B(not work with TCP TLS sockets)! See U(https://github.com/ansible-collections/community.docker/issues/605)
for more information.
- One way to connect to containers is to use SSH (V(ssh)). For this, the options O(default_ip) and
O(private_ssh_port) are used. This requires that a SSH daemon is running inside the containers.
- Alternatively, V(docker-cli) selects the P(community.docker.docker#connection) connection plugin,
and V(docker-api) (default) selects the P(community.docker.docker_api#connection) connection plugin.
- When V(docker-api) is used, all Docker daemon configuration values are passed from the inventory plugin
to the connection plugin. This can be controlled with O(configure_docker_daemon).
- Note that the P(community.docker.docker_api#connection) does B(not work with TCP TLS sockets)!
See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.
type: str
default: docker-api
choices:
@ -57,7 +54,7 @@ options:
configure_docker_daemon:
description:
- Whether to pass all Docker daemon configuration from the inventory plugin to the connection plugin.
- Only used when I(connection_type=docker-api).
- Only used when O(connection_type=docker-api).
type: bool
default: true
version_added: 1.8.0
@ -67,8 +64,8 @@ options:
- Toggle to (not) include all available inspection metadata.
- Note that all top-level keys will be transformed to the format C(docker_xxx).
For example, C(HostConfig) is converted to C(docker_hostconfig).
- If this is C(false), these values can only be used during I(constructed), I(groups), and I(keyed_groups).
- The C(docker) inventory script always added these variables, so for compatibility set this to C(true).
- If this is V(false), these values can only be used during O(compose), O(groups), and O(keyed_groups).
- The C(docker) inventory script always added these variables, so for compatibility set this to V(true).
type: bool
default: false
@ -76,14 +73,14 @@ options:
description:
- 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 I(connection_type) is C(ssh).
- Only used if O(connection_type) is V(ssh).
type: str
default: 127.0.0.1
private_ssh_port:
description:
- The port containers use for SSH.
- Only used if I(connection_type) is C(ssh).
- Only used if O(connection_type) is V(ssh).
type: int
default: 22
@ -96,11 +93,11 @@ options:
- "C(image_<image name>): contains the containers that have the image C(<image name>)."
- "C(stack_<stack name>): contains the containers that belong to the stack C(<stack name>)."
- "C(service_<service name>): contains the containers that belong to the service C(<service name>)"
- "C(<docker_host>): contains the containers which belong to the Docker daemon I(docker_host).
- "C(<docker_host>): contains the containers which belong to the Docker daemon O(docker_host).
Useful if you run this plugin against multiple Docker daemons."
- "C(running): contains all containers that are running."
- "C(stopped): contains all containers that are not running."
- If this is not set to C(true), you should use keyed groups to add the containers to groups.
- If this is not set to V(true), you should use keyed groups to add the containers to groups.
See the examples for how to do that.
type: bool
default: false

18
plugins/inventory/docker_machine.py
View File

@ -18,7 +18,7 @@ DOCUMENTATION = '''
- Get inventory hosts from Docker Machine.
- Uses a YAML configuration file that ends with docker_machine.(yml|yaml).
- The plugin sets standard host variables C(ansible_host), C(ansible_port), C(ansible_user) and C(ansible_ssh_private_key).
- The plugin stores the Docker Machine 'env' output variables in I(dm_) prefixed host variables.
- The plugin stores the Docker Machine 'env' output variables in C(dm_) prefixed host variables.
options:
plugin:
@ -28,12 +28,12 @@ DOCUMENTATION = '''
daemon_env:
description:
- Whether docker daemon connection environment variables should be fetched, and how to behave if they cannot be fetched.
- With C(require) and C(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 C(require).
- With C(optional) and C(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 C(optional).
- With C(skip), do not attempt to fetch the docker daemon connection environment variables.
- If fetched successfully, the variables will be prefixed with I(dm_) and stored as host variables.
- With V(require) and V(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 V(require).
- With V(optional) and V(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 V(optional).
- With V(skip), do not attempt to fetch the docker daemon connection environment variables.
- If fetched successfully, the variables will be prefixed with C(dm_) and stored as host variables.
type: str
choices:
- require
@ -44,12 +44,12 @@ DOCUMENTATION = '''
default: require
running_required:
description:
- When C(true), hosts which Docker Machine indicates are in a state other than C(running) will be skipped.
- When V(true), hosts which Docker Machine indicates are in a state other than C(running) will be skipped.
type: bool
default: true
verbose_output:
description:
- When C(true), include all available nodes metadata (for exmaple C(Image), C(Region), C(Size)) as a JSON object
- When V(true), include all available nodes metadata (for exmaple C(Image), C(Region), C(Size)) as a JSON object
named C(docker_machine_node_attributes).
type: bool
default: true

26
plugins/inventory/docker_swarm.py
View File

@ -21,12 +21,12 @@ DOCUMENTATION = '''
description:
- Reads inventories from the Docker swarm API.
- Uses a YAML configuration file docker_swarm.[yml|yaml].
- "The plugin returns following groups of swarm nodes: I(all) - all hosts; I(workers) - all worker nodes;
I(managers) - all manager nodes; I(leader) - the swarm leader node;
I(nonleaders) - all nodes except the swarm leader."
- "The plugin returns following groups of swarm nodes: C(all) - all hosts; C(workers) - all worker nodes;
C(managers) - all manager nodes; C(leader) - the swarm leader node;
C(nonleaders) - all nodes except the swarm leader."
options:
plugin:
description: The name of this plugin, it should always be set to C(community.docker.docker_swarm)
description: The name of this plugin, it should always be set to V(community.docker.docker_swarm)
for this plugin to recognize it as it's own.
type: str
required: true
@ -34,13 +34,13 @@ DOCUMENTATION = '''
docker_host:
description:
- Socket of a Docker swarm manager node (C(tcp), C(unix)).
- "Use C(unix://var/run/docker.sock) to connect via local socket."
- "Use V(unix://var/run/docker.sock) to connect via local socket."
type: str
required: true
aliases: [ docker_url ]
verbose_output:
description: Toggle to (not) include all available nodes metadata (for example C(Platform), C(Architecture), C(OS),
C(EngineVersion))
C(EngineVersion)).
type: bool
default: true
tls:
@ -71,7 +71,9 @@ DOCUMENTATION = '''
the server.
type: str
ssl_version:
description: Provide a valid SSL version number. Default value determined by ssl.py module.
description:
- Provide a valid SSL version number. Default value determined
by L(SSL Python module, https://docs.python.org/3/library/ssl.html).
type: str
api_version:
description:
@ -82,7 +84,7 @@ DOCUMENTATION = '''
timeout:
description:
- The maximum amount of time in seconds to wait on a response from the API.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TIMEOUT)
- If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT).
will be used instead. If the environment variable is not set, the default value will be used.
type: int
default: 60
@ -96,13 +98,13 @@ DOCUMENTATION = '''
version_added: 1.5.0
include_host_uri:
description: Toggle to return the additional attribute C(ansible_host_uri) which contains the URI of the
swarm leader in format of C(tcp://172.16.0.1:2376). This value may be used without additional
modification as value of option I(docker_host) in Docker Swarm modules when connecting via API.
The port always defaults to C(2376).
swarm leader in format of V(tcp://172.16.0.1:2376). This value may be used without additional
modification as value of option O(docker_host) in Docker Swarm modules when connecting via API.
The port always defaults to V(2376).
type: bool
default: false
include_host_uri_port:
description: Override the detected port number included in I(ansible_host_uri)
description: Override the detected port number included in C(ansible_host_uri).
type: int
'''

8
plugins/modules/current_container_facts.py
View File

@ -58,10 +58,10 @@ ansible_facts:
description:
- The detected container environment.
- Contains an empty string if no container was detected, or a non-empty string identifying the container environment.
- C(docker) indicates that the module ran inside a regular Docker container.
- C(azure_pipelines) indicates that the module ran on Azure Pipelines. This seems to no longer be reported.
- C(github_actions) indicates that the module ran inside a Docker container on GitHub Actions. It is supported since community.docker 2.4.0.
- C(podman) indicates that the module ran inside a regular Podman container. It is supported since community.docker 3.3.0.
- V(docker) indicates that the module ran inside a regular Docker container.
- V(azure_pipelines) indicates that the module ran on Azure Pipelines. This seems to no longer be reported.
- V(github_actions) indicates that the module ran inside a Docker container on GitHub Actions. It is supported since community.docker 2.4.0.
- V(podman) indicates that the module ran inside a regular Podman container. It is supported since community.docker 3.3.0.
returned: always
type: str
choices:

70
plugins/modules/docker_compose.py
View File

@ -18,7 +18,7 @@ author: "Chris Houseknecht (@chouseknecht)"
description:
- Uses Docker Compose to start, shutdown and scale services. B(This module requires docker-compose < 2.0.0.)
- Configuration can be read from a C(docker-compose.yml) or C(docker-compose.yaml) file or inline using the I(definition) option.
- Configuration can be read from a C(docker-compose.yml) or C(docker-compose.yaml) file or inline using the O(definition) option.
- See the examples for more details.
- Supports check mode.
- This module was called C(docker_service) before Ansible 2.8. The usage did not change.
@ -39,27 +39,27 @@ options:
project_src:
description:
- Path to a directory containing a C(docker-compose.yml) or C(docker-compose.yaml) file.
- Mutually exclusive with I(definition).
- Required when no I(definition) is provided.
- Mutually exclusive with O(definition).
- Required when no O(definition) is provided.
type: path
project_name:
description:
- Provide a project name. If not provided, the project name is taken from the basename of I(project_src).
- Required when I(definition) is provided.
- Provide a project name. If not provided, the project name is taken from the basename of O(project_src).
- Required when O(definition) is provided.
type: str
env_file:
description:
- By default environment files are loaded from a C(.env) file located directly under the I(project_src) directory.
- I(env_file) can be used to specify the path of a custom environment file instead.
- The path is relative to the I(project_src) directory.
- By default environment files are loaded from a C(.env) file located directly under the O(project_src) directory.
- O(env_file) can be used to specify the path of a custom environment file instead.
- The path is relative to the O(project_src) directory.
- Requires C(docker-compose) version 1.25.0 or greater.
- "Note: C(docker-compose) versions C(<=1.28) load the env file from the current working directory of the
C(docker-compose) command rather than I(project_src)."
C(docker-compose) command rather than O(project_src)."
type: path
version_added: 1.9.0
files:
description:
- List of Compose file names relative to I(project_src). Overrides C(docker-compose.yml) or C(docker-compose.yaml).
- List of Compose file names relative to O(project_src). Overrides C(docker-compose.yml) or C(docker-compose.yaml).
- Files are loaded and merged in the order given.
type: list
elements: path
@ -74,9 +74,9 @@ options:
state:
description:
- Desired state of the project.
- Specifying C(present) is the same as running C(docker-compose up) resp. C(docker-compose stop) (with I(stopped)) resp. C(docker-compose restart)
(with I(restarted)).
- Specifying C(absent) is the same as running C(docker-compose down).
- Specifying V(present) is the same as running C(docker-compose up) resp. C(docker-compose stop) (with V(stopped)) resp. C(docker-compose restart)
(with V(restarted)).
- Specifying V(absent) is the same as running C(docker-compose down).
type: str
default: present
choices:
@ -84,25 +84,25 @@ options:
- present
services:
description:
- When I(state) is C(present) run C(docker-compose up) resp. C(docker-compose stop) (with I(stopped)) resp. C(docker-compose restart) (with I(restarted))
- When O(state) is V(present) run C(docker-compose up) resp. C(docker-compose stop) (with V(stopped)) resp. C(docker-compose restart) (with V(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 I(definition)).
- If empty, which is the default, the operation will be performed on all services defined in the Compose file (or inline O(definition)).
type: list
elements: str
scale:
description:
- When I(state) is C(present) scale services. Provide a dictionary of key/value pairs where the key
- When O(state) is V(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.
type: dict
dependencies:
description:
- When I(state) is C(present) specify whether or not to include linked services.
- When O(state) is V(present) specify whether or not to include linked services.
type: bool
default: true
definition:
description:
- Compose file describing one or more services, networks and volumes.
- Mutually exclusive with I(project_src) and I(files).
- Mutually exclusive with O(project_src) and O(files).
type: dict
hostname_check:
description:
@ -112,8 +112,8 @@ options:
recreate:
description:
- By default containers will be recreated when their configuration differs from the service definition.
- Setting to C(never) ignores configuration differences and leaves existing containers unchanged.
- Setting to C(always) forces recreation of all existing containers.
- Setting to V(never) ignores configuration differences and leaves existing containers unchanged.
- Setting to V(always) forces recreation of all existing containers.
type: str
default: smart
choices:
@ -122,49 +122,49 @@ options:
- smart
build:
description:
- Use with I(state) C(present) to always build images prior to starting the application.
- Use with O(state=present) to always build images prior to starting the application.
- Same as running C(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 I(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 I(recreate) is C(never).
- Use the O(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 O(recreate=never).
type: bool
default: false
pull:
description:
- Use with I(state) C(present) to always pull images prior to starting the application.
- Use with O(state=present) to always pull images prior to starting the application.
- Same as running C(docker-compose pull).
- When a new image is pulled, services using the image will be recreated unless I(recreate) is C(never).
- When a new image is pulled, services using the image will be recreated unless O(recreate=never).
type: bool
default: false
nocache:
description:
- Use with the I(build) option to ignore the cache during the image build process.
- Use with the O(build) option to ignore the cache during the image build process.
type: bool
default: false
remove_images:
description:
- Use with I(state) C(absent) to remove all images or only local images.
- Use with O(state=absent) to remove all images or only local images.
type: str
choices:
- 'all'
- 'local'
remove_volumes:
description:
- Use with I(state) C(absent) to remove data volumes.
- Use with O(state=absent) to remove data volumes.
type: bool
default: false
stopped:
description:
- Use with I(state) C(present) to stop all containers defined in the Compose file.
- If I(services) is defined, only the containers listed there will be stopped.
- Use with O(state=present) to stop all containers defined in the Compose file.
- If O(services) is defined, only the containers listed there will be stopped.
- Requires C(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.
type: bool
default: false
restarted:
description:
- Use with I(state) C(present) to restart all containers defined in the Compose file.
- If I(services) is defined, only the containers listed there will be restarted.
- Use with O(state=present) to restart all containers defined in the Compose file.
- If O(services) is defined, only the containers listed there will be restarted.
type: bool
default: false
remove_orphans:
@ -175,8 +175,8 @@ options:
timeout:
description:
- Timeout in seconds for container shutdown when attached or when containers are already running.
- By default C(compose) will use a C(10s) timeout unless C(default_grace_period) is defined for a
particular service in the I(project_src).
- By default C(docker-compose) will use a V(10) seconds timeout unless C(default_grace_period) is defined for a
particular service in the O(project_src).
type: int
default: null
use_ssh_client:
@ -440,7 +440,7 @@ services:
actions:
description: Provides the actions to be taken on each service as determined by compose.
returned: when in check mode or I(debug) is C(true)
returned: when in check mode or O(debug=true)
type: complex
contains:
service_name:

30
plugins/modules/docker_config.py
View File

@ -18,7 +18,7 @@ description:
- Create and remove Docker configs in a Swarm environment. Similar to C(docker config create) and C(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 I(force) option is set.
unless the O(force) option is set.
- Updates to configs are performed by removing the config and creating it again.
extends_documentation_fragment:
@ -37,45 +37,45 @@ options:
data:
description:
- The value of the config.
- Mutually exclusive with I(data_src). One of I(data) and I(data_src) is required if I(state=present).
- Mutually exclusive with O(data_src). One of O(data) and O(data_src) is required if O(state=present).
type: str
data_is_b64:
description:
- If set to C(true), the data is assumed to be Base64 encoded and will be
- If set to V(true), the data is assumed to be Base64 encoded and will be
decoded before being used.
- To use binary I(data), it is better to keep it Base64 encoded and let it
- To use binary O(data), it is better to keep it Base64 encoded and let it
be decoded by this option.
type: bool
default: false
data_src:
description:
- The file on the target from which to read the config.
- Mutually exclusive with I(data). One of I(data) and I(data_src) is required if I(state=present).
- Mutually exclusive with O(data). One of O(data) and O(data_src) is required if O(state=present).
type: path
version_added: 1.10.0
labels:
description:
- "A map of key:value meta data, where both the I(key) and I(value) are expected to be a string."
- "A map of key:value meta data, where both the C(key) and C(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.
type: dict
force:
description:
- Use with state C(present) to always remove and recreate an existing config.
- If C(true), an existing config will be replaced, even if it has not been changed.
- Use with O(state=present) to always remove and recreate an existing config.
- If V(true), an existing config will be replaced, even if it has not been changed.
type: bool
default: false
rolling_versions:
description:
- If set to C(true), configs are created with an increasing version number appended to their name.
- If set to V(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 C(ansible_version).
type: bool
default: false
version_added: 2.2.0
versions_to_keep:
description:
- When using I(rolling_versions), the number of old versions of the config to keep.
- When using O(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 C(-1) to keep everything or to C(0) or C(1) to keep only the current one.
- Set to V(-1) to keep everything or V(0) or V(1) to keep only the current one.
type: int
default: 5
version_added: 2.2.0
@ -86,7 +86,7 @@ options:
required: true
state:
description:
- Set to C(present), if the config should exist, and C(absent), if it should not.
- Set to V(present), if the config should exist, and V(absent), if it should not.
type: str
default: present
choices:
@ -94,7 +94,7 @@ options:
- present
template_driver:
description:
- Set to C(golang) to use a Go template in I(data) or a Go template file in I(data_src).
- Set to V(golang) to use a Go template in O(data) or a Go template file in O(data_src).
type: str
choices:
- golang
@ -183,13 +183,13 @@ RETURN = '''
config_id:
description:
- The ID assigned by Docker to the config object.
returned: success and I(state) is C(present)
returned: success and O(state=present)
type: str
sample: 'hzehrmyjigmcp2gb6nlhmjqcv'
config_name:
description:
- The name of the created config object.
returned: success and I(state) is C(present)
returned: success and O(state=present)
type: str
sample: 'awesome_config'
version_added: 2.2.0

312
plugins/modules/docker_container.py
View File

@ -20,11 +20,11 @@ description:
notes:
- 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 I(comparisons) option to
a new one created. This can cause unexpected data loss and downtime. You can use the O(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 I(image)). Therefore, always specify B(all) options relevant to the container.
- When I(restart) is set to C(true), the module will only restart the container if no config changes are detected.
new container (except O(image)). Therefore, always specify B(all) options relevant to the container.
- When O(restart) is set to V(true), the module will only restart the container if no config changes are detected.
extends_documentation_fragment:
- community.docker.docker.api_documentation
@ -43,7 +43,7 @@ options:
auto_remove:
description:
- Enable auto-removal of the container on daemon side when the container's process exits.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
blkio_weight:
description:
@ -76,14 +76,14 @@ options:
version_added: 1.1.0
cleanup:
description:
- Use with I(detach=false) to remove the container after successful execution.
- Use with O(detach=false) to remove the container after successful execution.
type: bool
default: false
command:
description:
- 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 I(command_handling) for differences in how strings and lists are handled.
- See O(command_handling) for differences in how strings and lists are handled.
type: raw
comparisons:
description:
@ -91,30 +91,30 @@ options:
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 I(networks).
- Must be a dictionary specifying for an option one of the keys C(strict), C(ignore)
and C(allow_more_present).
- If C(strict) is specified, values are tested for equality, and changes always
result in updating or restarting. If C(ignore) is specified, changes are ignored.
- C(allow_more_present) is allowed only for lists, sets and dicts. If it is
Docker daemon can be specified, as well as O(networks).
- Must be a dictionary specifying for an option one of the keys V(strict), V(ignore)
and V(allow_more_present).
- If V(strict) is specified, values are tested for equality, and changes always
result in updating or restarting. If V(ignore) is specified, changes are ignored.
- V(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 C(*) can be used to set one of the default values C(strict)
or C(ignore) to I(all) comparisons which are not explicitly set to other values.
- The wildcard option C(*) can be used to set one of the default values V(strict)
or V(ignore) to I(all) comparisons which are not explicitly set to other values.
- See the examples for details.
type: dict
container_default_behavior:
description:
- 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 C(no_defaults). To restore the old behavior, set it to
C(compatibility), which will ensure that the default values are used when the values
- The default value is now V(no_defaults). To restore the old behavior, set it to
V(compatibility), which will ensure that the default values are used when the values
are not explicitly specified by the user.
- This affects the I(auto_remove), I(detach), I(init), I(interactive), I(memory),
I(paused), I(privileged), I(read_only) and I(tty) options.
- This affects the O(auto_remove), O(detach), O(init), O(interactive), O(memory),
O(paused), O(privileged), O(read_only), and O(tty) options.
type: str
choices:
- compatibility
@ -122,15 +122,15 @@ options:
default: no_defaults
command_handling:
description:
- The default behavior for I(command) (when provided as a list) and I(entrypoint) is to
- The default behavior for O(command) (when provided as a list) and O(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 I(command) to an empty list of string, and setting I(entrypoint) to an empty
- Also, setting O(command) to an empty list of string, and setting O(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 C(compatibility), which was the default until community.docker 3.0.0, the
- When this is set to V(compatibility), which was the default until community.docker 3.0.0, the
current behavior will be kept.
- When this is set to C(correct), these options are kept as lists, and an empty value or empty
- When this is set to V(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.
type: str
@ -142,25 +142,25 @@ options:
cpu_period:
description:
- Limit CPU CFS (Completely Fair Scheduler) period.
- See I(cpus) for an easier to use alternative.
- See O(cpus) for an easier to use alternative.
type: int
cpu_quota:
description:
- Limit CPU CFS (Completely Fair Scheduler) quota.
- See I(cpus) for an easier to use alternative.
- See O(cpus) for an easier to use alternative.
type: int
cpus:
description:
- Specify how much of the available CPU resources a container can use.
- A value of C(1.5) means that at most one and a half CPU (core) will be used.
- A value of V(1.5) means that at most one and a half CPU (core) will be used.
type: float
cpuset_cpus:
description:
- CPUs in which to allow execution C(1,3) or C(1-3).
- CPUs in which to allow execution V(1,3) or V(1-3).
type: str
cpuset_mems:
description:
- Memory nodes (MEMs) in which to allow execution C(0-3) or C(0,1).
- Memory nodes (MEMs) in which to allow execution V(0-3) or V(0,1).
type: str
cpu_shares:
description:
@ -170,19 +170,19 @@ options:
description:
- 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 (C("")) to avoid the
- With Docker 20.10.2 or newer, this should be set to an empty string (V("")) to avoid the
port bindings without an explicit IP address to only bind to IPv4.
See U(https://github.com/ansible-collections/community.docker/issues/70) for details.
- By default, the module will try to auto-detect this value from the C(bridge) network's
C(com.docker.network.bridge.host_binding_ipv4) option. If it cannot auto-detect it, it
will fall back to C(0.0.0.0).
will fall back to V(0.0.0.0).
type: str
version_added: 1.2.0
detach:
description:
- 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 I(container_default_behavior) is set to C(compatibility), this option has a default of C(true).
- If O(container_default_behavior=compatibility), this option has a default of V(true).
type: bool
devices:
description:
@ -204,8 +204,8 @@ options:
rate:
description:
- "Device read limit in format C(<number>[<unit>])."
- "Number is a positive integer. Unit can be one of C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- "Number is a positive integer. Unit can be one of V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- "Omitting the unit defaults to bytes."
type: str
required: true
@ -223,8 +223,8 @@ options:
rate:
description:
- "Device read limit in format C(<number>[<unit>])."
- "Number is a positive integer. Unit can be one of C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- "Number is a positive integer. Unit can be one of V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- "Omitting the unit defaults to bytes."
type: str
required: true
@ -281,7 +281,7 @@ options:
count:
description:
- Number or devices to request.
- Set to C(-1) to request all available devices.
- Set to V(-1) to request all available devices.
type: int
device_ids:
description:
@ -319,19 +319,19 @@ options:
env:
description:
- 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 C("true")) in order to avoid data loss.
- Please note that if you are passing values in with Jinja2 templates, like C("{{ value }}"), you need to add C(| string) to prevent Ansible to
convert strings such as C("true") back to booleans. The correct way is to use C("{{ value | string }}").
- Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example V("true")) in order to avoid data loss.
- Please note that if you are passing values in with Jinja2 templates, like V("{{ value }}"), you need to add V(| string) to prevent Ansible to
convert strings such as V("true") back to booleans. The correct way is to use V("{{ value | string }}").
type: dict
env_file:
description:
- Path to a file, present on the target, containing environment variables I(FOO=BAR).
- If variable also present in I(env), then the I(env) value will override.
- Path to a file, present on the target, containing environment variables C(FOO=BAR).
- If variable also present in O(env), then the O(env) value will override.
type: path
entrypoint:
description:
- Command that overwrites the default C(ENTRYPOINT) of the image.
- See I(command_handling) for differences in how strings and lists are handled.
- See O(command_handling) for differences in how strings and lists are handled.
type: list
elements: str
etc_hosts:
@ -367,34 +367,35 @@ options:
- Configure a check that is run to determine whether or not containers for this service are "healthy".
- "See the docs for the L(HEALTHCHECK Dockerfile instruction,https://docs.docker.com/engine/reference/builder/#healthcheck)
for details on how healthchecks work."
- "I(interval), I(timeout) and I(start_period) are specified as durations. They accept duration as a string in a format
that look like: C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
- "O(healthcheck.interval), O(healthcheck.timeout) and O(healthcheck.start_period) are specified as durations.
They accept duration as a string in a format that look like: V(5h34m56s), V(1m30s), and so on.
The supported units are V(us), V(ms), V(s), V(m) and V(h)."
type: dict
suboptions:
test:
description:
- 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 C(NONE), C(CMD) or C(CMD-SHELL).
- Must be either a string or a list. If it is a list, the first item must be one of V(NONE), V(CMD) or V(CMD-SHELL).
type: raw
interval:
description:
- Time between running the check.
- The default used by the Docker daemon is C(30s).
- The default used by the Docker daemon is V(30s).
type: str
timeout:
description:
- Maximum time to allow one check to run.
- The default used by the Docker daemon is C(30s).
- The default used by the Docker daemon is V(30s).
type: str
retries:
description:
- Consecutive number of failures needed to report unhealthy.
- The default used by the Docker daemon is C(3).
- The default used by the Docker daemon is V(3).
type: int
start_period:
description:
- Start period for the container to initialize before starting health-retries countdown.
- The default used by the Docker daemon is C(0s).
- The default used by the Docker daemon is V(0s).
type: str
hostname:
description:
@ -402,30 +403,30 @@ options:
type: str
ignore_image:
description:
- When I(state) is C(present) or C(started), the module compares the configuration of an existing
- When O(state) is V(present) or V(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 I(ignore_image) to C(true).
stop this behavior by setting O(ignore_image) to V(true).
- "B(Warning:) This option is ignored if C(image: ignore) or C(*: ignore) is specified in the
I(comparisons) option."
O(comparisons) option."
- "This option is deprecated since community.docker 3.2.0 and will be removed in community.docker 4.0.0.
Use C(image: ignore) in I(comparisons) instead of I(ignore_image=true)."
Use C(image: ignore) in O(comparisons) instead of O(ignore_image=true)."
type: bool
default: false
image:
description:
- 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, C(latest) will be used.
will be pulled from the registry. If no tag is included, V(latest) will be used.
- Can also be an image ID. If this is the case, the image is assumed to be available locally.
The I(pull) option is ignored for this case.
The O(pull) option is ignored for this case.
type: str
image_comparison:
description:
- Determines which image to use for idempotency checks that depend on image parameters.
- The default, C(desired-image), will use the image that is provided to the module via the I(image) parameter.
- C(current-image) will use the image that the container is currently using, if the container exists. It
- The default, V(desired-image), will use the image that is provided to the module via the O(image) parameter.
- V(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 I(env), I(env_file), I(exposed_ports), I(labels), and I(volumes) options.
- This affects the O(env), O(env_file), O(exposed_ports), O(labels), and O(volumes) options.
type: str
choices:
- desired-image
@ -435,13 +436,13 @@ options:
image_label_mismatch:
description:
- How to handle labels inherited from the image that are not set explicitly.
- When C(ignore), labels that are present in the image but not specified in I(labels) will be
ignored. This is useful to avoid having to specify the image labels in I(labels) while keeping
labels I(comparisons) C(strict).
- When C(fail), if there are labels present in the image which are not set from I(labels), the
- When V(ignore), labels that are present in the image but not specified in O(labels) will be
ignored. This is useful to avoid having to specify the image labels in O(labels) while keeping
labels O(comparisons) V(strict).
- When V(fail), if there are labels present in the image which are not set from O(labels), the
module will fail. This prevents introducing unexpected labels from the base image.
- "B(Warning:) This option is ignored unless C(labels: strict) or C(*: strict) is specified in
the I(comparisons) option."
the O(comparisons) option."
type: str
choices:
- 'ignore'
@ -452,9 +453,9 @@ options:
description:
- 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 C(image: ignore) is set in I(comparisons)."
- If set to C(recreate) the container will be recreated.
- If set to C(ignore) the container will not be recreated because of this. It might still get recreated for other reasons.
- "This is ignored if C(image: ignore) is set in O(comparisons)."
- If set to V(recreate) the container will be recreated.
- If set to V(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.
type: str
choices:
@ -465,17 +466,17 @@ options:
init:
description:
- Run an init inside the container that forwards signals and reaps processes.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
interactive:
description:
- Keep stdin open after a container is launched, even if not attached.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
ipc_mode:
description:
- Set the IPC mode for the container.
- Can be one of C(container:<name|id>) to reuse another container's IPC namespace or C(host) to use
- Can be one of V(container:<name|id>) to reuse another container's IPC namespace or V(host) to use
the host's IPC namespace within the container.
type: str
keep_volumes:
@ -490,8 +491,8 @@ options:
kernel_memory:
description:
- "Kernel memory limit in format C(<number>[<unit>]). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte). Minimum is C(4M)."
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte). Minimum is V(4M)."
- Omitting the unit defaults to bytes.
type: str
labels:
@ -506,42 +507,43 @@ options:
elements: str
log_driver:
description:
- Specify the logging driver. Docker uses C(json-file) by default.
- See L(here,https://docs.docker.com/config/containers/logging/configure/) for possible choices.
- Specify the logging driver. Docker uses V(json-file) by default.
- See L(the Docker logging configuration documentation,https://docs.docker.com/config/containers/logging/configure/)
for possible choices.
type: str
log_options:
description:
- Dictionary of options specific to the chosen I(log_driver).
- Dictionary of options specific to the chosen O(log_driver).
- See U(https://docs.docker.com/engine/admin/logging/overview/) for details.
- I(log_driver) needs to be specified for I(log_options) to take effect, even if using the default C(json-file) driver.
- O(log_driver) needs to be specified for O(log_options) to take effect, even if using the default V(json-file) driver.
type: dict
aliases:
- log_opt
mac_address:
description:
- Container MAC address (for example, C(92:d0:c6:0a:29:33)).
- Container MAC address (for example, V(92:d0:c6:0a:29:33)).
type: str
memory:
description:
- "Memory limit in format C(<number>[<unit>]). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- Omitting the unit defaults to bytes.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C("0").
- If O(container_default_behavior=compatibility), this option has a default of V("0").
type: str
memory_reservation:
description:
- "Memory soft limit in format C(<number>[<unit>]). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- Omitting the unit defaults to bytes.
type: str
memory_swap:
description:
- "Total memory limit (memory + swap) in format C(<number>[<unit>]), or
the special values C(unlimited) or C(-1) for unlimited swap usage.
Number is a positive integer. Unit can be C(B) (byte), C(K) (kibibyte, 1024B),
C(M) (mebibyte), C(G) (gibibyte), C(T) (tebibyte), or C(P) (pebibyte)."
the special values V(unlimited) or V(-1) for unlimited swap usage.
Number is a positive integer. Unit can be V(B) (byte), V(K) (kibibyte, 1024B),
V(M) (mebibyte), V(G) (gibibyte), V(T) (tebibyte), or V(P) (pebibyte)."
- Omitting the unit defaults to bytes.
type: str
memory_swappiness:
@ -554,7 +556,7 @@ options:
type: list
elements: dict
description:
- Specification for mounts to be added to the container. More powerful alternative to I(volumes).
- Specification for mounts to be added to the container. More powerful alternative to O(volumes).
suboptions:
target:
description:
@ -565,12 +567,12 @@ options:
description:
- Mount source.
- For example, this can be a volume name or a host path.
- If not supplied when I(type=volume) an anonymous volume will be created.
- If not supplied when O(mounts[].type=volume) an anonymous volume will be created.
type: str
type:
description:
- The mount type.
- Note that C(npipe) is only supported by Docker for Windows.
- Note that V(npipe) is only supported by Docker for Windows.
type: str
choices:
- bind
@ -593,7 +595,7 @@ options:
- delegated
propagation:
description:
- Propagation mode. Only valid for the C(bind) type.
- Propagation mode. Only valid for the V(bind) type.
type: str
choices:
- private
@ -604,16 +606,16 @@ options:
- rslave
no_copy:
description:
- False if the volume should be populated with the data from the target. Only valid for the C(volume) type.
- The default value is C(false).
- False if the volume should be populated with the data from the target. Only valid for the V(volume) type.
- The default value is V(false).
type: bool
labels:
description:
- User-defined name and labels for the volume. Only valid for the C(volume) type.
- User-defined name and labels for the volume. Only valid for the V(volume) type.
type: dict
volume_driver:
description:
- Specify the volume driver. Only valid for the C(volume) type.
- Specify the volume driver. Only valid for the V(volume) type.
- See L(here,https://docs.docker.com/storage/volumes/#use-a-volume-driver) for details.
type: str
volume_options:
@ -624,8 +626,8 @@ options:
tmpfs_size:
description:
- "The size for the tmpfs mount in bytes in format <number>[<unit>]."
- "Number is a positive integer. Unit can be one of C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- "Number is a positive integer. Unit can be one of V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- "Omitting the unit defaults to bytes."
type: str
tmpfs_mode:
@ -640,24 +642,24 @@ options:
required: true
network_mode:
description:
- Connect the container to a network. Choices are C(bridge), C(host), C(none), C(container:<name|id>), C(<network_name>) or C(default).
- "Since community.docker 2.0.0, if I(networks_cli_compatible) is C(true) and I(networks) contains at least one network,
the default value for I(network_mode) is the name of the first network in the I(networks) list. You can prevent this
by explicitly specifying a value for I(network_mode), like the default value C(default) which will be used by Docker if
I(network_mode) is not specified."
- Connect the container to a network. Choices are V(bridge), V(host), V(none), C(container:<name|id>), C(<network_name>) or V(default).
- "Since community.docker 2.0.0, if O(networks_cli_compatible=true) and O(networks) contains at least one network,
the default value for O(network_mode) is the name of the first network in the O(networks) list. You can prevent this
by explicitly specifying a value for O(network_mode), like the default value V(default) which will be used by Docker if
O(network_mode) is not specified."
type: str
userns_mode:
description:
- Set the user namespace mode for the container. Currently, the only valid value are C(host) and the empty string.
- Set the user namespace mode for the container. Currently, the only valid value are V(host) and the empty string (V("")).
type: str
networks:
description:
- 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 C(networks: strict) in the I(comparisons) option."
- "If I(networks_cli_compatible) is set to C(false), this will not remove the default network if I(networks) is specified.
This is different from the behavior of C(docker run ...). You need to explicitly use C(networks: strict) in I(comparisons)
to enforce the removal of the default network (and all other networks not explicitly mentioned in I(networks)) in that case."
- "To remove a container from one or more networks, use C(networks: strict) in the O(comparisons) option."
- "If O(networks_cli_compatible=false), this will not remove the default network if O(networks) is specified.
This is different from the behavior of C(docker run ...). You need to explicitly use C(networks: strict) in O(comparisons)
to enforce the removal of the default network (and all other networks not explicitly mentioned in O(networks)) in that case."
type: list
elements: dict
suboptions:
@ -687,15 +689,15 @@ options:
elements: str
networks_cli_compatible:
description:
- "If I(networks_cli_compatible) is set to C(true) (default), this module will behave as
C(docker run --network) and will B(not) add the default network if I(networks) is
specified. If I(networks) is not specified, the default network will be attached."
- "When I(networks_cli_compatible) is set to C(false) and networks are provided to the module
via the I(networks) option, the module behaves differently than C(docker run --network):
- "If O(networks_cli_compatible=true) (default), this module will behave as
C(docker run --network) and will B(not) add the default network if O(networks) is
specified. If O(networks) is not specified, the default network will be attached."
- "When O(networks_cli_compatible=false) and networks are provided to the module
via the O(networks) option, the module behaves differently than C(docker run --network):
C(docker run --network other) will create a container with network C(other) attached,
but the default network not attached. This module with I(networks: {name: other}) will
but the default network not attached. This module with O(networks) set to C({name: other}) will
create a container with both C(default) and C(other) attached. If C(networks: strict)
or C(*: strict) is set in I(comparisons), the C(default) network will be removed afterwards."
or C(*: strict) is set in O(comparisons), the C(default) network will be removed afterwards."
type: bool
default: true
oom_killer:
@ -710,13 +712,13 @@ options:
output_logs:
description:
- If set to true, output of the container command will be printed.
- Only effective when I(log_driver) is set to C(json-file), C(journald), or C(local).
- Only effective when O(log_driver) is set to V(json-file), V(journald), or V(local).
type: bool
default: false
paused:
description:
- Use with the started state to pause running processes inside the container.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
pid_mode:
description:
@ -725,31 +727,31 @@ options:
pids_limit:
description:
- Set PIDs limit for the container. It accepts an integer value.
- Set C(-1) for unlimited PIDs.
- Set V(-1) for unlimited PIDs.
type: int
platform:
description:
- Platform for the container in the format C(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 I(comparisons) option
create the container. This can cause idempotency to break for this module. Use the O(comparisons) option
with C(platform: ignore) to prevent accidental recreation of the container due to this."
type: str
version_added: 3.0.0
privileged:
description:
- Give extended privileges to the container.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
publish_all_ports:
description:
- Publish all ports to the host.
- Any specified port bindings from I(published_ports) will remain intact when C(true).
- Any specified port bindings from O(published_ports) will remain intact when V(true).
type: bool
version_added: 1.8.0
published_ports:
description:
- List of ports to publish from the container to the host.
- "Use docker CLI syntax: C(8000), C(9000:8000), or C(0.0.0.0:9000:8000), where 8000 is a
- "Use docker CLI syntax: V(8000), V(9000:8000), or V(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.
@ -757,16 +759,16 @@ options:
to the first port of the destination range, but to a free port in that range. This is the
same behavior as for C(docker) command line utility.
- "Bind addresses must be either IPv4 or IPv6 addresses. Hostnames are B(not) allowed. This
is different from the C(docker) command line utility. Use the R(dig lookup,ansible_collections.community.general.dig_lookup)
is different from the C(docker) command line utility. Use the P(community.general.dig#lookup) lookup
to resolve hostnames."
- If I(networks) parameter is provided, will inspect each network to see if there exists
- If O(networks) parameter is provided, will inspect each network to see if there exists
a bridge network with optional parameter C(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 C(com.docker.network.bridge.host_binding_ipv4).
Note that the first bridge network with a C(com.docker.network.bridge.host_binding_ipv4)
value encountered in the list of I(networks) is the one that will be used.
- The value C(all) was allowed in earlier versions of this module. Support for it was removed in
community.docker 3.0.0. Use the I(publish_all_ports) option instead.
value encountered in the list of O(networks) is the one that will be used.
- The value V(all) was allowed in earlier versions of this module. Support for it was removed in
community.docker 3.0.0. Use the O(publish_all_ports) option instead.
type: list
elements: str
aliases:
@ -781,17 +783,17 @@ options:
default: false
purge_networks:
description:
- Remove the container from ALL networks not included in I(networks) parameter.
- Any default networks such as C(bridge), if not found in I(networks), will be removed as well.
- Remove the container from ALL networks not included in O(networks) parameter.
- Any default networks such as C(bridge), if not found in O(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 C(networks: strict) in I(comparisons) instead of I(purge_networks=true) and make sure that
I(networks) is specified. If you want to remove all networks, specify I(networks: [])."
Use C(networks: strict) in O(comparisons) instead of O(purge_networks=true) and make sure that
O(networks) is specified. If you want to remove all networks, specify O(networks) as C([])."
type: bool
default: false
read_only:
description:
- Mount the container's root file system as read-only.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
recreate:
description:
@ -816,7 +818,7 @@ options:
restart_policy:
description:
- Container restart policy.
- Place quotes around C(no) option.
- Place quotes around V(no) option.
type: str
choices:
- 'no'
@ -834,9 +836,9 @@ options:
shm_size:
description:
- "Size of C(/dev/shm) in format C(<number>[<unit>]). Number is positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses C(64M).
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses V(64M).
type: str
security_opts:
description:
@ -845,22 +847,22 @@ options:
elements: str
state:
description:
- 'C(absent) - A container matching the specified name will be stopped and removed. Use I(force_kill) to kill the container
rather than stopping it. Use I(keep_volumes) to retain anonymous volumes associated with the removed container.'
- 'C(present) - Asserts the existence of a container matching the name and any provided configuration parameters. If no
- 'V(absent) - A container matching the specified name will be stopped and removed. Use O(force_kill) to kill the container
rather than stopping it. Use O(keep_volumes) to retain anonymous volumes associated with the removed container.'
- 'V(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.'
- 'C(started) - Asserts that the container is first C(present), and then if the container is not running moves it to a running
state. Use I(restart) to force a matching container to be stopped and restarted.'
- 'C(stopped) - Asserts that the container is first C(present), and then if the container is running moves it to a stopped
- 'V(started) - Asserts that the container is first V(present), and then if the container is not running moves it to a running
state. Use O(restart) to force a matching container to be stopped and restarted.'
- 'V(stopped) - Asserts that the container is first V(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 I(comparisons) option. To avoid that the
image version will be taken into account, you can also use the C(image: ignore) in the I(comparisons) option."
- Use the I(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 I(state) is
C(stopped), please use the I(force_kill) option. Use I(keep_volumes) to retain anonymous volumes associated with a removed container.
- Use I(keep_volumes) to retain anonymous volumes associated with a removed container.
- "To control what will be taken into account when comparing configuration, see the O(comparisons) option. To avoid that the
image version will be taken into account, you can also use the V(image: ignore) in the O(comparisons) option."
- Use the O(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 O(state) is
V(stopped), please use the O(force_kill) option. Use O(keep_volumes) to retain anonymous volumes associated with a removed container.
- Use O(keep_volumes) to retain anonymous volumes associated with a removed container.
type: str
default: started
choices:
@ -896,11 +898,11 @@ options:
tty:
description:
- Allocate a pseudo-TTY.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
ulimits:
description:
- "List of ulimit options. A ulimit is specified as C(nofile:262144:262144)."
- "List of ulimit options. A ulimit is specified as V(nofile:262144:262144)."
type: list
elements: str
sysctls:
@ -920,12 +922,12 @@ options:
description:
- List of volumes to mount within the container.
- "Use docker CLI-style syntax: C(/host:/container[:mode])"
- "Mount modes can be a comma-separated list of various modes such as C(ro), C(rw), C(consistent),
C(delegated), C(cached), C(rprivate), C(private), C(rshared), C(shared), C(rslave), C(slave), and
C(nocopy). Note that the docker daemon might not support all modes and combinations of such modes."
- SELinux hosts can additionally use C(z) or C(Z) to use a shared or private label for the volume.
- "Note that Ansible 2.7 and earlier only supported one mode, which had to be one of C(ro), C(rw),
C(z), and C(Z)."
- "Mount modes can be a comma-separated list of various modes such as V(ro), V(rw), V(consistent),
V(delegated), V(cached), V(rprivate), V(private), V(rshared), V(shared), V(rslave), V(slave), and
V(nocopy). Note that the docker daemon might not support all modes and combinations of such modes."
- SELinux hosts can additionally use V(z) or V(Z) to use a shared or private label for the volume.
- "Note that Ansible 2.7 and earlier only supported one mode, which had to be one of V(ro), V(rw),
V(z), and V(Z)."
type: list
elements: str
volume_driver:
@ -1225,9 +1227,9 @@ RETURN = '''
container:
description:
- Facts representing the current state of the container. Matches the docker inspection output.
- Empty if I(state) is C(absent).
- If I(detach=false), will include C(Output) attribute containing any output from container run.
returned: success; or when I(state=started) and I(detach=false), and when waiting for the container result did not fail
- Empty if O(state=absent).
- If O(detach=false), will include C(Output) attribute containing any output from container run.
returned: success; or when O(state=started) and O(detach=false), and when waiting for the container result did not fail
type: dict
sample: '{
"AppArmorProfile": "",
@ -1265,7 +1267,7 @@ status:
description:
- 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 I(state=started) and I(detach=false), and when waiting for the container result did not fail
returned: when O(state=started) and O(detach=false), and when waiting for the container result did not fail
type: int
sample: 0
'''

22
plugins/modules/docker_container_copy_into.py
View File

@ -19,7 +19,7 @@ version_added: 3.4.0
description:
- Copy a file into a Docker container.
- Similar to C(docker cp).
- To copy files in a non-running container, you must provide the I(owner_id) and I(group_id) options.
- To copy files in a non-running container, you must provide the O(owner_id) and O(group_id) options.
This is also necessary if the container does not contain a C(/bin/sh) shell with an C(id) tool.
attributes:
@ -41,19 +41,19 @@ options:
path:
description:
- Path to a file on the managed node.
- Mutually exclusive with I(content). One of I(content) and I(path) is required.
- Mutually exclusive with O(content). One of O(content) and O(path) is required.
type: path
content:
description:
- The file's content.
- If you plan to provide binary data, provide it pre-encoded to base64, and set I(content_is_b64=true).
- Mutually exclusive with I(path). One of I(content) and I(path) is required.
- If you plan to provide binary data, provide it pre-encoded to base64, and set O(content_is_b64=true).
- Mutually exclusive with O(path). One of O(content) and O(path) is required.
type: str
content_is_b64:
description:
- If set to C(true), the content in I(content) is assumed to be Base64 encoded and
- If set to V(true), the content in O(content) is assumed to be Base64 encoded and
will be decoded before being used.
- To use binary I(content), it is better to keep it Base64 encoded and let it
- To use binary O(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.
type: bool
@ -77,7 +77,7 @@ options:
owner_id:
description:
- The owner ID to use when writing the file to disk.
- If provided, I(group_id) must also be provided.
- If provided, O(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 C(/bin/sh) is present in the container and the C(id) binary or shell builtin is available.
Also the container must be running.
@ -85,7 +85,7 @@ options:
group_id:
description:
- The group ID to use when writing the file to disk.
- If provided, I(owner_id) must also be provided.
- If provided, O(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 C(/bin/sh) is present in the container and the C(id) binary or shell builtin is available.
Also the container must be running.
@ -97,8 +97,8 @@ options:
type: int
force:
description:
- If set to C(true), force writing the file (without performing any idempotency checks).
- If set to C(false), only write the file if it does not exist on the target. If a filesystem object exists at
- If set to V(true), force writing the file (without performing any idempotency checks).
- If set to V(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
@ -138,7 +138,7 @@ RETURN = '''
container_path:
description:
- The actual path in the container.
- Can only be different from I(container_path) when I(follow=true).
- Can only be different from O(container_path) when O(follow=true).
type: str
returned: success
'''

30
plugins/modules/docker_container_exec.py
View File

@ -42,21 +42,21 @@ options:
description:
- The command to execute.
- Since this is a list of arguments, no quoting is needed.
- Exactly one of I(argv) or I(command) must be specified.
- Exactly one of O(argv) or O(command) must be specified.
command:
type: str
description:
- The command to execute.
- Exactly one of I(argv) or I(command) must be specified.
- Exactly one of O(argv) or O(command) must be specified.
chdir:
type: str
description:
- The directory to run the command in.
detach:
description:
- Whether to run the command synchronously (I(detach=false), default) or asynchronously (I(detach=true)).
- If set to C(true), I(stdin) cannot be provided, and the return values C(stdout), C(stderr) and
C(rc) are not returned.
- Whether to run the command synchronously (O(detach=false), default) or asynchronously (O(detach=true)).
- If set to V(true), O(stdin) cannot be provided, and the return values RV(stdout), RV(stderr), and
RV(rc) are not returned.
type: bool
default: false
version_added: 2.1.0
@ -68,12 +68,12 @@ options:
type: str
description:
- Set the stdin of the command directly to the specified value.
- Can only be used if I(detach=false).
- Can only be used if O(detach=false).
stdin_add_newline:
type: bool
default: true
description:
- If set to C(true), appends a newline to I(stdin).
- If set to V(true), appends a newline to O(stdin).
strip_empty_ends:
type: bool
default: true
@ -87,15 +87,15 @@ options:
env:
description:
- 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 C("true")) in order to avoid data loss.
- Please note that if you are passing values in with Jinja2 templates, like C("{{ value }}"), you need to add C(| string) to prevent Ansible to
convert strings such as C("true") back to booleans. The correct way is to use C("{{ value | string }}").
- Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example V("true")) in order to avoid data loss.
- Please note that if you are passing values in with Jinja2 templates, like V("{{ value }}"), you need to add V(| string) to prevent Ansible to
convert strings such as V("true") back to booleans. The correct way is to use V("{{ value | string }}").
type: dict
version_added: 2.1.0
notes:
- Does not support C(check_mode).
- Does B(not work with TCP TLS sockets) when using I(stdin). This is caused by the inability to send C(close_notify) without closing the connection
- Does B(not work with TCP TLS sockets) when using O(stdin). This is caused by the inability to send C(close_notify) without closing the connection
with Python's C(SSLSocket)s. See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.
author:
- "Felix Fontein (@felixfontein)"
@ -134,23 +134,23 @@ EXAMPLES = '''
RETURN = '''
stdout:
type: str
returned: success and I(detach=false)
returned: success and O(detach=false)
description:
- The standard output of the container command.
stderr:
type: str
returned: success and I(detach=false)
returned: success and O(detach=false)
description:
- The standard error output of the container command.
rc:
type: int
returned: success and I(detach=false)
returned: success and O(detach=false)
sample: 0
description:
- The exit code of the command.
exec_id:
type: str
returned: success and I(detach=true)
returned: success and O(detach=true)
sample: 249d9e3075655baf705ed8f40488c5e9434049cf3431976f1bfdb73741c574c5
description:
- The execution ID of the command.

2
plugins/modules/docker_container_info.py
View File

@ -66,7 +66,7 @@ exists:
container:
description:
- Facts representing the current state of the container. Matches the docker inspection output.
- Will be C(none) if container does not exist.
- Will be V(none) if container does not exist.
returned: always
type: dict
sample: '{

34
plugins/modules/docker_host_info.py
View File

@ -108,10 +108,10 @@ options:
default: false
verbose_output:
description:
- When set to C(true) and I(networks), I(volumes), I(images), I(containers) or I(disk_usage) is set to C(true)
- When set to V(true) and O(networks), O(volumes), O(images), O(containers), or O(disk_usage) is set to V(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 U(https://docs.docker.com/engine/api/).
- The verbose output in this module contains only subset of information returned by I(_info) module
- The verbose output in this module contains only subset of information returned by this module
for each type of the objects.
type: bool
default: false
@ -169,7 +169,7 @@ EXAMPLES = '''
RETURN = '''
can_talk_to_docker:
description:
- Will be C(true) if the module can talk to the docker daemon.
- Will be V(true) if the module can talk to the docker daemon.
returned: both on success and on error
type: bool
@ -181,40 +181,40 @@ host_info:
volumes:
description:
- List of dict objects containing the basic information about each volume.
Keys matches the C(docker volume ls) output unless I(verbose_output=true).
See description for I(verbose_output).
returned: When I(volumes) is C(true)
Keys matches the C(docker volume ls) output unless O(verbose_output=true).
See description for O(verbose_output).
returned: When O(volumes=true)
type: list
elements: dict
networks:
description:
- List of dict objects containing the basic information about each network.
Keys matches the C(docker network ls) output unless I(verbose_output=true).
See description for I(verbose_output).
returned: When I(networks) is C(true)
Keys matches the C(docker network ls) output unless O(verbose_output=true).
See description for O(verbose_output).
returned: When O(networks=true)
type: list
elements: dict
containers:
description:
- List of dict objects containing the basic information about each container.
Keys matches the C(docker container ls) output unless I(verbose_output=true).
See description for I(verbose_output).
returned: When I(containers) is C(true)
Keys matches the C(docker container ls) output unless O(verbose_output=true).
See description for O(verbose_output).
returned: When O(containers=true)
type: list
elements: dict
images:
description:
- List of dict objects containing the basic information about each image.
Keys matches the C(docker image ls) output unless I(verbose_output=true).
See description for I(verbose_output).
returned: When I(images) is C(true)
Keys matches the C(docker image ls) output unless O(verbose_output=true).
See description for O(verbose_output).
returned: When O(images=true)
type: list
elements: dict
disk_usage:
description:
- Information on summary disk usage by images, containers and volumes on docker host
unless I(verbose_output=true). See description for I(verbose_output).
returned: When I(disk_usage) is C(true)
unless O(verbose_output=true). See description for O(verbose_output).
returned: When O(disk_usage=true)
type: dict
'''

54
plugins/modules/docker_image.py
View File

@ -38,12 +38,12 @@ options:
source:
description:
- "Determines where the module will try to retrieve the image from."
- "Use C(build) to build the image from a C(Dockerfile). I(build.path) must
- "Use V(build) to build the image from a C(Dockerfile). O(build.path) must
be specified when this value is used."
- "Use C(load) to load the image from a C(.tar) file. I(load_path) must
- "Use V(load) to load the image from a C(.tar) file. O(load_path) must
be specified when this value is used."
- "Use C(pull) to pull the image from a registry."
- "Use C(local) to make sure that the image is already available on the local
- "Use V(pull) to pull the image from a registry."
- "Use V(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."
type: str
choices:
@ -63,8 +63,8 @@ options:
elements: str
dockerfile:
description:
- Use with state C(present) and source C(build) to provide an alternate name for the Dockerfile to use when building an image.
- This can also include a relative path (relative to I(path)).
- Use with O(state=present) and O(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 O(build.path)).
type: str
http_timeout:
description:
@ -117,7 +117,7 @@ options:
memswap:
description:
- Total memory (memory + swap).
- Use C(-1) to disable swap.
- Use V(-1) to disable swap.
type: int
cpushares:
description:
@ -126,11 +126,11 @@ options:
cpusetcpus:
description:
- CPUs in which to allow execution.
- For example, C(0-3) or C(0,1).
- For example, V(0-3) or V(0,1).
type: str
use_config_proxy:
description:
- If set to C(true) and a proxy configuration is specified in the docker client configuration
- If set to V(true) and a proxy configuration is specified in the docker client configuration
(by default C($HOME/.docker/config.json)), the corresponding environment variables will
be set in the container being built.
type: bool
@ -146,35 +146,35 @@ options:
version_added: 1.1.0
archive_path:
description:
- Use with state C(present) to archive an image to a .tar file.
- Use with O(state=present) to archive an image to a C(.tar) file.
type: path
load_path:
description:
- Use with state C(present) to load an image from a .tar file.
- Set I(source) to C(load) if you want to load the image.
- Use with O(state=present) to load an image from a C(.tar) file.
- Set O(source=load) if you want to load the image.
type: path
force_source:
description:
- Use with state C(present) to build, load or pull an image (depending on the
value of the I(source) option) when the image already exists.
- Use with O(state=present) to build, load or pull an image (depending on the
value of the O(source) option) when the image already exists.
type: bool
default: false
force_absent:
description:
- Use with state I(absent) to un-tag and remove all images matching the specified name.
- Use with O(state=absent) to un-tag and remove all images matching the specified name.
type: bool
default: false
force_tag:
description:
- Use with state C(present) to force tagging an image.
- Use with O(state=present) to force tagging an image.
type: bool
default: false
name:
description:
- "Image name. Name format will be one of: C(name), C(repository/name), C(registry_server:port/name).
When pushing or pulling an image the name can optionally include the tag by appending C(:tag_name)."
- Note that image IDs (hashes) are only supported for I(state=absent), for I(state=present) with I(source=load),
and for I(state=present) with I(source=local).
- Note that image IDs (hashes) are only supported for O(state=absent), for O(state=present) with O(source=load),
and for O(state=present) with O(source=local).
type: str
required: true
pull:
@ -191,23 +191,23 @@ options:
type: str
push:
description:
- Push the image to the registry. Specify the registry as part of the I(name) or I(repository) parameter.
- Push the image to the registry. Specify the registry as part of the O(name) or O(repository) parameter.
type: bool
default: false
repository:
description:
- Use with state C(present) to tag the image.
- Expects format C(repository:tag). If no tag is provided, will use the value of the I(tag) parameter or C(latest).
- If I(push=true), I(repository) must either include a registry, or will be assumed to belong to the default
- Use with O(state=present) to tag the image.
- Expects format C(repository:tag). If no tag is provided, will use the value of the O(tag) parameter or V(latest).
- If O(push=true), O(repository) must either include a registry, or will be assumed to belong to the default
registry (Docker Hub).
type: str
state:
description:
- Make assertions about the state of an image.
- When C(absent) an image will be removed. Use the force option to un-tag and remove all images
- When V(absent) an image will be removed. Use the force option to un-tag and remove all images
matching the provided name.
- When C(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 I(source) option.
- When V(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 O(source) option.
type: str
default: present
choices:
@ -216,8 +216,8 @@ options:
tag:
description:
- Used to select an image when pulling. Will be added to the image when pushing, tagging or building. Defaults to
I(latest).
- If I(name) parameter format is I(name:tag), then tag value from I(name) will take precedence.
V(latest).
- If O(name) parameter format is C(name:tag), then tag value from O(name) will take precedence.
type: str
default: latest

6
plugins/modules/docker_image_info.py
View File

@ -19,8 +19,8 @@ description:
- 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 M(community.docker.docker_image) with I(source) set to C(pull)
to ensure an image is pulled.
- The module will not attempt to pull images from registries. Use M(community.docker.docker_image) with
O(community.docker.docker_image#module:source=pull) to ensure an image is pulled.
notes:
- This module was called C(docker_image_facts) before Ansible 2.8. The usage did not change.
@ -35,7 +35,7 @@ options:
name:
description:
- An image name or a list of image names. Name format will be C(name[:tag]) or C(repository/name[:tag]),
where C(tag) is optional. If a tag is not provided, C(latest) will be used. Instead of image names, also
where C(tag) is optional. If a tag is not provided, V(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.
type: list

8
plugins/modules/docker_login.py
View File

@ -46,12 +46,12 @@ options:
username:
description:
- The username for the registry account.
- Required when I(state) is C(present).
- Required when O(state=present).
type: str
password:
description:
- The plaintext password for the registry account.
- Required when I(state) is C(present).
- Required when O(state=present).
type: str
reauthorize:
description:
@ -69,7 +69,7 @@ options:
- dockercfg_path
state:
description:
- This controls the current state of the user. C(present) will login in a user, C(absent) will log them out.
- This controls the current state of the user. V(present) will login in a user, V(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.
@ -112,7 +112,7 @@ EXAMPLES = '''
RETURN = '''
login_results:
description: Results from the login.
returned: when I(state=present)
returned: when O(state=present)
type: dict
sample: {
"serveraddress": "localhost:5000",

18
plugins/modules/docker_network.py
View File

@ -61,8 +61,8 @@ options:
force:
description:
- With state C(absent) forces disconnecting all containers from the
network prior to deleting the network. With state C(present) will
- With state V(absent) forces disconnecting all containers from the
network prior to deleting the network. With state V(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
@ -73,7 +73,7 @@ options:
appends:
description:
- By default the connected list is canonical, meaning containers not on the list are removed from the network.
- Use I(appends) to leave existing containers connected.
- Use O(appends) to leave existing containers connected.
type: bool
default: false
aliases:
@ -98,7 +98,7 @@ options:
description:
- List of IPAM config blocks. Consult
L(Docker docs,https://docs.docker.com/compose/compose-file/compose-file-v2/#ipam) for valid options and values.
Note that I(iprange) is spelled differently here (we use the notation from the Docker SDK for Python).
Note that O(ipam_config[].iprange) is spelled differently here (we use the notation from the Docker SDK for Python).
type: list
elements: dict
suboptions:
@ -121,14 +121,14 @@ options:
state:
description:
- C(absent) deletes the network. If a network has connected containers, it
cannot be deleted. Use the I(force) option to disconnect all containers
- V(absent) deletes the network. If a network has connected containers, it
cannot be deleted. Use the O(force) option to disconnect all containers
and delete the network.
- C(present) creates the network, if it does not already exist with the
- V(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
I(appends) option to leave existing containers connected. Use the I(force)
O(appends) option to leave existing containers connected. Use the O(force)
options to force re-creation of the network.
type: str
default: present
@ -163,7 +163,7 @@ options:
notes:
- 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 (I(connected), and even for these, it does not consider specific
It does not try to reconnect containers, except the ones listed in (O(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 M(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

2
plugins/modules/docker_network_info.py
View File

@ -66,7 +66,7 @@ exists:
network:
description:
- Facts representing the current state of the network. Matches the docker inspection output.
- Will be C(none) if network does not exist.
- Will be V(none) if network does not exist.
returned: always
type: dict
sample: {

20
plugins/modules/docker_node.py
View File

@ -39,19 +39,19 @@ options:
labels:
description:
- 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 I(hostname).
- Label operations in this module apply to the docker swarm node specified by O(hostname).
Use M(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
I(labels_state) and I(labels_to_remove) parameters values. See description below.
O(labels_state) and O(labels_to_remove) parameters values. See description below.
type: dict
labels_state:
description:
- It defines the operation on the labels assigned to node and labels specified in I(labels) option.
- Set to C(merge) to combine labels provided in I(labels) with those already assigned to the node.
- It defines the operation on the labels assigned to node and labels specified in O(labels) option.
- Set to V(merge) to combine labels provided in O(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 I(labels) will remain unchanged.
If I(labels) is empty then no changes will be made.
- Set to C(replace) to replace all assigned labels with provided ones. If I(labels) is empty then
to the node, it will update their values. The labels not specified in O(labels) will remain unchanged.
If O(labels) is empty then no changes will be made.
- Set to V(replace) to replace all assigned labels with provided ones. If O(labels) is empty then
all labels assigned to the node will be removed.
type: str
default: 'merge'
@ -63,10 +63,10 @@ options:
- 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 I(labels_to_remove) and I(labels), then value provided in I(labels) remains
- If the label is both on the O(labels_to_remove) and O(labels), then value provided in O(labels) remains
assigned to the node.
- If I(labels_state) is C(replace) and I(labels) is not provided or empty then all labels assigned to
node are removed and I(labels_to_remove) is ignored.
- If O(labels_state=replace) and O(labels) is not provided or empty then all labels assigned to
node are removed and O(labels_to_remove) is ignored.
type: list
elements: str
availability:

12
plugins/modules/docker_node_info.py
View File

@ -33,14 +33,14 @@ options:
- The list of nodes names to inspect.
- If empty then return information of all nodes in Swarm cluster.
- When identifying the node use either the hostname of the node (as registered in Swarm) or node ID.
- If I(self) is C(true) then this parameter is ignored.
- If O(self=true) then this parameter is ignored.
type: list
elements: str
self:
description:
- If C(true), queries the node (that is, the docker daemon) the module communicates with.
- If C(true) then I(name) is ignored.
- If C(false) then query depends on I(name) presence and value.
- If V(true), queries the node (that is, the docker daemon) the module communicates with.
- If V(true) then O(name) is ignored.
- If V(false) then query depends on O(name) presence and value.
type: bool
default: false
@ -79,8 +79,8 @@ RETURN = '''
nodes:
description:
- Facts representing the current state of the nodes. Matches the C(docker node inspect) output.
- Can contain multiple entries if more than one node provided in I(name), or I(name) is not provided.
- If I(name) contains a list of nodes, the output will provide information on all nodes registered
- Can contain multiple entries if more than one node provided in O(name), or O(name) is not provided.
- If O(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

10
plugins/modules/docker_plugin.py
View File

@ -38,10 +38,10 @@ options:
state:
description:
- C(absent) remove the plugin.
- C(present) install the plugin, if it does not already exist.
- C(enable) enable the plugin.
- C(disable) disable the plugin.
- V(absent) remove the plugin.
- V(present) install the plugin, if it does not already exist.
- V(enable) enable the plugin.
- V(disable) disable the plugin.
default: present
choices:
- absent
@ -121,7 +121,7 @@ plugin:
actions:
description:
- List of actions performed during task execution.
returned: when I(state!=absent)
returned: when O(state) is not V(absent)
type: list
'''

16
plugins/modules/docker_prune.py
View File

@ -124,14 +124,14 @@ RETURN = '''
containers:
description:
- List of IDs of deleted containers.
returned: I(containers) is C(true)
returned: O(containers=true)
type: list
elements: str
sample: []
containers_space_reclaimed:
description:
- Amount of reclaimed disk space from container pruning in bytes.
returned: I(containers) is C(true)
returned: O(containers=true)
type: int
sample: 0
@ -139,14 +139,14 @@ containers_space_reclaimed:
images:
description:
- List of IDs of deleted images.
returned: I(images) is C(true)
returned: O(images=true)
type: list
elements: str
sample: []
images_space_reclaimed:
description:
- Amount of reclaimed disk space from image pruning in bytes.
returned: I(images) is C(true)
returned: O(images=true)
type: int
sample: 0
@ -154,7 +154,7 @@ images_space_reclaimed:
networks:
description:
- List of IDs of deleted networks.
returned: I(networks) is C(true)
returned: O(networks=true)
type: list
elements: str
sample: []
@ -163,14 +163,14 @@ networks:
volumes:
description:
- List of IDs of deleted volumes.
returned: I(volumes) is C(true)
returned: O(volumes=true)
type: list
elements: str
sample: []
volumes_space_reclaimed:
description:
- Amount of reclaimed disk space from volumes pruning in bytes.
returned: I(volumes) is C(true)
returned: O(volumes=true)
type: int
sample: 0
@ -178,7 +178,7 @@ volumes_space_reclaimed:
builder_cache_space_reclaimed:
description:
- Amount of reclaimed disk space from builder cache pruning in bytes.
returned: I(builder_cache) is C(true)
returned: O(builder_cache=true)
type: int
sample: 0
'''

26
plugins/modules/docker_secret.py
View File

@ -18,7 +18,7 @@ description:
- Create and remove Docker secrets in a Swarm environment. Similar to C(docker secret create) and C(docker secret rm).
- Adds to the metadata of new secrets C(ansible_key), an encrypted hash representation of the data, which is then used
in future runs to test if a secret has changed. If C(ansible_key) is not present, then a secret will not be updated
unless the I(force) option is set.
unless the O(force) option is set.
- Updates to secrets are performed by removing the secret and creating it again.
extends_documentation_fragment:
@ -37,20 +37,20 @@ options:
data:
description:
- The value of the secret.
- Mutually exclusive with I(data_src). One of I(data) and I(data_src) is required if I(state=present).
- Mutually exclusive with O(data_src). One of O(data) and O(data_src) is required if O(state=present).
type: str
data_is_b64:
description:
- If set to C(true), the data is assumed to be Base64 encoded and will be
- If set to V(true), the data is assumed to be Base64 encoded and will be
decoded before being used.
- To use binary I(data), it is better to keep it Base64 encoded and let it
- To use binary O(data), it is better to keep it Base64 encoded and let it
be decoded by this option.
type: bool
default: false
data_src:
description:
- The file on the target from which to read the secret.
- Mutually exclusive with I(data). One of I(data) and I(data_src) is required if I(state=present).
- Mutually exclusive with O(data). One of O(data) and O(data_src) is required if O(state=present).
type: path
version_added: 1.10.0
labels:
@ -60,22 +60,22 @@ options:
type: dict
force:
description:
- Use with state C(present) to always remove and recreate an existing secret.
- If C(true), an existing secret will be replaced, even if it has not changed.
- Use with O(state=present) to always remove and recreate an existing secret.
- If V(true), an existing secret will be replaced, even if it has not changed.
type: bool
default: false
rolling_versions:
description:
- If set to C(true), secrets are created with an increasing version number appended to their name.
- If set to V(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 C(ansible_version).
type: bool
default: false
version_added: 2.2.0
versions_to_keep:
description:
- When using I(rolling_versions), the number of old versions of the secret to keep.
- When using O(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 C(-1) to keep everything or to C(0) or C(1) to keep only the current one.
- Set to V(-1) to keep everything or to V(0) or V(1) to keep only the current one.
type: int
default: 5
version_added: 2.2.0
@ -86,7 +86,7 @@ options:
required: true
state:
description:
- Set to C(present), if the secret should exist, and C(absent), if it should not.
- Set to V(present), if the secret should exist, and V(absent), if it should not.
type: str
default: present
choices:
@ -175,13 +175,13 @@ RETURN = '''
secret_id:
description:
- The ID assigned by Docker to the secret object.
returned: success and I(state) is C(present)
returned: success and O(state=present)
type: str
sample: 'hzehrmyjigmcp2gb6nlhmjqcv'
secret_name:
description:
- The name of the created secret object.
returned: success and I(state) is C(present)
returned: success and O(state=present)
type: str
sample: 'awesome_secret'
version_added: 2.2.0

6
plugins/modules/docker_stack.py
View File

@ -68,8 +68,8 @@ options:
choices: ["always", "changed", "never"]
absent_retries:
description:
- If C(>0) and I(state) is C(absent) the module will retry up to
I(absent_retries) times to delete the stack until all the
- If larger than V(0) and O(state=absent) the module will retry up to
O(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.
@ -77,7 +77,7 @@ options:
default: 0
absent_retries_interval:
description:
- Interval in seconds between consecutive I(absent_retries).
- Interval in seconds between consecutive O(absent_retries).
type: int
default: 1

66
plugins/modules/docker_swarm.py
View File

@ -32,11 +32,11 @@ options:
description:
- Externally reachable address advertised to other nodes.
- This can either be an address/port combination
in the form C(192.168.1.1:4567), or an interface followed by a
port number, like C(eth0:4567).
in the form V(192.168.1.1:4567), or an interface followed by a
port number, like V(eth0:4567).
- If the port number is omitted,
the port number from the listen address is used.
- If I(advertise_addr) is not specified, it will be automatically
- If O(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.
@ -60,8 +60,8 @@ options:
description:
- Listen address used for inter-manager communication.
- This can either be an address/port combination in the form
C(192.168.1.1:4567), or an interface followed by a port number,
like C(eth0:4567).
V(192.168.1.1:4567), or an interface followed by a port number,
like V(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
@ -70,16 +70,16 @@ options:
default: 0.0.0.0:2377
force:
description:
- Use with state C(present) to force creating a new Swarm, even if already part of one.
- Use with state C(absent) to Leave the swarm even if this node is a manager.
- Use with state V(present) to force creating a new Swarm, even if already part of one.
- Use with state V(absent) to Leave the swarm even if this node is a manager.
type: bool
default: false
state:
description:
- Set to C(present), to create/update a new cluster.
- Set to C(join), to join an existing cluster.
- Set to C(absent), to leave an existing cluster.
- Set to C(remove), to remove an absent node from the cluster.
- Set to V(present), to create/update a new cluster.
- Set to V(join), to join an existing cluster.
- Set to V(absent), to leave an existing cluster.
- Set to V(remove), to remove an absent node from the cluster.
Note that removing requires Docker SDK for Python >= 2.4.0.
- M(community.docker.docker_node) can be used to demote a manager before removal.
type: str
@ -92,35 +92,35 @@ options:
node_id:
description:
- Swarm id of the node to remove.
- Used with I(state=remove).
- Used with O(state=remove).
type: str
join_token:
description:
- Swarm token used to join a swarm cluster.
- Used with I(state=join).
- Used with O(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.
type: str
remote_addrs:
description:
- Remote address of one or more manager nodes of an existing Swarm to connect to.
- Used with I(state=join).
- Used with O(state=join).
type: list
elements: str
task_history_retention_limit:
description:
- Maximum number of tasks history stored.
- Docker default value is C(5).
- Docker default value is V(5).
type: int
snapshot_interval:
description:
- Number of logs entries between snapshot.
- Docker default value is C(10000).
- Docker default value is V(10000).
type: int
keep_old_snapshots:
description:
- Number of snapshots to keep beyond the current snapshot.
- Docker default value is C(0).
- Docker default value is V(0).
type: int
log_entries_for_slow_followers:
description:
@ -129,23 +129,23 @@ options:
heartbeat_tick:
description:
- Amount of ticks (in seconds) between each heartbeat.
- Docker default value is C(1) seconds.
- Docker default value is V(1) seconds.
type: int
election_tick:
description:
- Amount of ticks (in seconds) needed without a leader to trigger a new election.
- Docker default value is C(10) seconds.
- Docker default value is V(10) seconds.
type: int
dispatcher_heartbeat_period:
description:
- 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 C(5000000000).
- Docker default value is 5 seconds, which corresponds to a value of V(5000000000).
# DefaultHeartBeatPeriod in https://github.com/moby/moby/blob/master/vendor/github.com/moby/swarmkit/v2/manager/dispatcher/dispatcher.go#L32
type: int
node_cert_expiry:
description:
- Automatic expiry for nodes certificates, given in nanoseconds.
- Docker default value is 90 days, which corresponds to a value of C(7776000000000000).
- Docker default value is 90 days, which corresponds to a value of V(7776000000000000).
# DefaultNodeCertExpiration in https://github.com/moby/moby/blob/master/vendor/github.com/moby/swarmkit/v2/ca/certificates.go#L56
type: int
name:
@ -175,13 +175,13 @@ options:
description:
- 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 C(0).
- Docker default value is V(0).
- Requires API version >= 1.30.
type: int
autolock_managers:
description:
- If set, generate a key and use it to lock data stored on the managers.
- Docker default value is C(false).
- Docker default value is V(false).
- M(community.docker.docker_swarm_info) can be used to retrieve the unlock key.
type: bool
rotate_worker_token:
@ -195,8 +195,8 @@ options:
data_path_addr:
description:
- Address or interface to use for data path traffic.
- This can either be an address in the form C(192.168.1.1), or an interface,
like C(eth0).
- This can either be an address in the form V(192.168.1.1), or an interface,
like V(eth0).
- Only used when swarm is initialised or joined. Because of this it is not
considered for idempotency checking.
type: str
@ -204,7 +204,7 @@ options:
data_path_port:
description:
- Port to use for data path traffic.
- This needs to be a port number like C(9789).
- This needs to be a port number like V(9789).
- Only used when swarm is initialised. Because of this it is not
considered for idempotency checking.
type: int
@ -276,8 +276,8 @@ swarm_facts:
Worker:
description:
- Token to join the cluster as a new *worker* node.
- "B(Note:) if this value has been specified as I(join_token), the value here will not
be the token, but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). If you pass I(join_token),
- "B(Note:) if this value has been specified as O(join_token), the value here will not
be the token, but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). If you pass O(join_token),
make sure your playbook/role does not depend on this return value!"
returned: success
type: str
@ -285,16 +285,16 @@ swarm_facts:
Manager:
description:
- Token to join the cluster as a new *manager* node.
- "B(Note:) if this value has been specified as I(join_token), the value here will not
be the token, but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). If you pass I(join_token),
- "B(Note:) if this value has been specified as O(join_token), the value here will not
be the token, but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). If you pass O(join_token),
make sure your playbook/role does not depend on this return value!"
returned: success
type: str
example: SWMTKN-1--xxxxx
UnlockKey:
description: The swarm unlock-key if I(autolock_managers) is C(true).
returned: on success if I(autolock_managers) is C(true)
and swarm is initialised, or if I(autolock_managers) has changed.
description: The swarm unlock-key if O(autolock_managers=true).
returned: on success if O(autolock_managers=true)
and swarm is initialised, or if O(autolock_managers) has changed.
type: str
example: SWMKEY-1-xxx

32
plugins/modules/docker_swarm_info.py
View File

@ -77,10 +77,10 @@ options:
default: false
verbose_output:
description:
- When set to C(true) and I(nodes), I(services) or I(tasks) is set to C(true), then the module output will
- When set to V(true) and O(nodes), O(services), or O(tasks) is set to V(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 U(https://docs.docker.com/engine/api/).
- The verbose output in this module contains only subset of information returned by I(_info) module
- The verbose output in this module contains only subset of information returned by this info module
for each type of the objects.
type: bool
default: false
@ -139,21 +139,21 @@ EXAMPLES = '''
RETURN = '''
can_talk_to_docker:
description:
- Will be C(true) if the module can talk to the docker daemon.
- Will be V(true) if the module can talk to the docker daemon.
returned: both on success and on error
type: bool
docker_swarm_active:
description:
- Will be C(true) if the module can talk to the docker daemon,
- Will be V(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
type: bool
docker_swarm_manager:
description:
- Will be C(true) if the module can talk to the docker daemon,
- Will be V(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 C(true), the module will not fail.
- Only if this one is V(true), the module will not fail.
returned: both on success and on error
type: bool
swarm_facts:
@ -165,30 +165,30 @@ swarm_facts:
swarm_unlock_key:
description:
- Contains the key needed to unlock the swarm.
returned: When I(unlock_key) is C(true).
returned: When O(unlock_key=true).
type: str
nodes:
description:
- List of dict objects containing the basic information about each volume.
Keys matches the C(docker node ls) output unless I(verbose_output=true).
See description for I(verbose_output).
returned: When I(nodes) is C(true)
Keys matches the C(docker node ls) output unless O(verbose_output=true).
See description for O(verbose_output).
returned: When O(nodes=true)
type: list
elements: dict
services:
description:
- List of dict objects containing the basic information about each volume.
Keys matches the C(docker service ls) output unless I(verbose_output=true).
See description for I(verbose_output).
returned: When I(services) is C(true)
Keys matches the C(docker service ls) output unless O(verbose_output=true).
See description for O(verbose_output).
returned: When O(services=true)
type: list
elements: dict
tasks:
description:
- List of dict objects containing the basic information about each volume.
Keys matches the C(docker service ps) output unless I(verbose_output=true).
See description for I(verbose_output).
returned: When I(tasks) is C(true)
Keys matches the C(docker service ps) output unless O(verbose_output=true).
See description for O(verbose_output).
returned: When O(tasks=true)
type: list
elements: dict

89
plugins/modules/docker_swarm_service.py
View File

@ -64,7 +64,7 @@ options:
required: true
filename:
description:
- Name of the file containing the config. Defaults to the I(config_name) if not specified.
- Name of the file containing the config. Defaults to the O(configs[].config_name) if not specified.
type: str
uid:
description:
@ -76,7 +76,7 @@ options:
type: str
mode:
description:
- File access mode inside the container. Must be an octal number (like C(0644) or C(0444)).
- File access mode inside the container. Must be an octal number (like V(0644) or V(0444)).
type: int
container_labels:
description:
@ -114,7 +114,7 @@ options:
- List or dictionary of the service environment variables.
- If passed a list each items need to be in the format of C(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 C("true"))
booleans or other types by the YAML parser must be quoted (for example V("true"))
in order to avoid data loss.
- Corresponds to the C(--env) option of C(docker service create).
type: raw
@ -123,7 +123,7 @@ options:
- List of paths to files, present on the target, containing environment variables C(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 I(env), then I(env) value will override.
- If variable also present in O(env), then O(env) value will override.
type: list
elements: path
force_update:
@ -143,14 +143,15 @@ options:
- Configure a check that is run to determine whether or not containers for this service are "healthy".
See the docs for the L(HEALTHCHECK Dockerfile instruction,https://docs.docker.com/engine/reference/builder/#healthcheck)
for details on how healthchecks work.
- "I(interval), I(timeout) and I(start_period) are specified as durations. They accept duration as a string in a format
that look like: C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
- "O(healthcheck.interval), O(healthcheck.timeout), and O(healthcheck.start_period) are specified as durations.
They accept duration as a string in a format that look like: V(5h34m56s), V(1m30s), and so on.
The supported units are V(us), V(ms), V(s), V(m) and V(h)."
type: dict
suboptions:
test:
description:
- 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 C(NONE), C(CMD) or C(CMD-SHELL).
- Must be either a string or a list. If it is a list, the first item must be one of V(NONE), V(CMD) or V(CMD-SHELL).
type: raw
interval:
description:
@ -201,15 +202,15 @@ options:
suboptions:
cpus:
description:
- Service CPU limit. C(0) equals no limit.
- Service CPU limit. V(0) equals no limit.
- Corresponds to the C(--limit-cpu) option of C(docker service create).
type: float
memory:
description:
- "Service memory limit in format C(<number>[<unit>]). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- C(0) equals no limit.
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- V(0) equals no limit.
- Omitting the unit defaults to bytes.
- Corresponds to the C(--limit-memory) option of C(docker service create).
type: str
@ -249,7 +250,7 @@ options:
source:
description:
- Mount source (for example a volume name or a host path).
- Must be specified if I(type) is not C(tmpfs).
- Must be specified if O(mounts[].type) is not V(tmpfs).
type: str
target:
description:
@ -259,7 +260,7 @@ options:
type:
description:
- The mount type.
- Note that C(npipe) is only supported by Docker for Windows. Also note that C(npipe) was added in Ansible 2.9.
- Note that V(npipe) is only supported by Docker for Windows. Also note that V(npipe) was added in Ansible 2.9.
type: str
default: bind
choices:
@ -278,7 +279,7 @@ options:
propagation:
description:
- The propagation mode to use.
- Can only be used when I(type) is C(bind).
- Can only be used when O(mounts[].type=bind).
type: str
choices:
- shared
@ -290,12 +291,12 @@ options:
no_copy:
description:
- Disable copying of data from a container when a volume is created.
- Can only be used when I(type) is C(volume).
- Can only be used when O(mounts[].type=volume).
type: bool
driver_config:
description:
- Volume driver configuration.
- Can only be used when I(type) is C(volume).
- Can only be used when O(mounts[].type=volume).
suboptions:
name:
description:
@ -309,14 +310,14 @@ options:
tmpfs_size:
description:
- "Size of the tmpfs mount in format C(<number>[<unit>]). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- Can only be used when I(type) is C(tmpfs).
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- Can only be used when O(mounts[].type=tmpfs).
type: str
tmpfs_mode:
description:
- File mode of the tmpfs in octal.
- Can only be used when I(type) is C(tmpfs).
- Can only be used when O(mounts[].type=tmpfs).
type: int
name:
description:
@ -327,8 +328,8 @@ options:
networks:
description:
- List of the service networks names or dictionaries.
- When passed dictionaries valid sub-options are I(name), which is required, and
I(aliases) and I(options).
- When passed dictionaries valid sub-options are C(name), which is required, and
C(aliases) and C(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 C(--network) option of C(docker service create).
@ -399,9 +400,9 @@ options:
type: bool
replicas:
description:
- Number of containers instantiated in the service. Valid only if I(mode) is C(replicated).
- If set to C(-1), and service is not present, service replicas will be set to C(1).
- If set to C(-1), and service is present, service replicas will be unchanged.
- Number of containers instantiated in the service. Valid only if O(mode=replicated).
- If set to V(-1), and service is not present, service replicas will be set to V(1).
- If set to V(-1), and service is present, service replicas will be unchanged.
- Corresponds to the C(--replicas) option of C(docker service create).
type: int
default: -1
@ -411,15 +412,15 @@ options:
suboptions:
cpus:
description:
- Service CPU reservation. C(0) equals no reservation.
- Service CPU reservation. V(0) equals no reservation.
- Corresponds to the C(--reserve-cpu) option of C(docker service create).
type: float
memory:
description:
- "Service memory reservation in format C(<number>[<unit>]). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- C(0) equals no reservation.
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- V(0) equals no reservation.
- Omitting the unit defaults to bytes.
- Corresponds to the C(--reserve-memory) option of C(docker service create).
type: str
@ -447,7 +448,7 @@ options:
description:
- Delay between restarts.
- "Accepts a a string in a format that look like:
C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h)."
- Corresponds to the C(--restart-delay) option of C(docker service create).
type: str
max_attempts:
@ -459,7 +460,7 @@ options:
description:
- Restart policy evaluation window.
- "Accepts a string in a format that look like:
C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h)."
- Corresponds to the C(--restart-window) option of C(docker service create).
type: str
type: dict
@ -477,7 +478,7 @@ options:
description:
- Delay between task rollbacks.
- "Accepts a string in a format that look like:
C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h)."
- Corresponds to the C(--rollback-delay) option of C(docker service create).
- Requires API version >= 1.28.
type: str
@ -494,7 +495,7 @@ options:
description:
- Duration after each task rollback to monitor for failure.
- "Accepts a string in a format that look like:
C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h)."
- Corresponds to the C(--rollback-monitor) option of C(docker service create).
- Requires API version >= 1.28.
type: str
@ -529,7 +530,7 @@ options:
required: true
filename:
description:
- Name of the file containing the secret. Defaults to the I(secret_name) if not specified.
- Name of the file containing the secret. Defaults to the O(secrets[].secret_name) if not specified.
- Corresponds to the C(target) key of C(docker service create --secret).
type: str
uid:
@ -542,12 +543,12 @@ options:
type: str
mode:
description:
- File access mode inside the container. Must be an octal number (like C(0644) or C(0444)).
- File access mode inside the container. Must be an octal number (like V(0644) or V(0444)).
type: int
state:
description:
- C(absent) - A service matching the specified name will be removed and have its tasks stopped.
- C(present) - Asserts the existence of a service matching the name and provided configuration parameters.
- V(absent) - A service matching the specified name will be removed and have its tasks stopped.
- V(present) - Asserts the existence of a service matching the name and provided configuration parameters.
Unspecified configuration parameters will be set to docker defaults.
type: str
default: present
@ -558,7 +559,7 @@ options:
description:
- Time to wait before force killing a container.
- "Accepts a duration as a string in a format that look like:
C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h)."
- Corresponds to the C(--stop-grace-period) option of C(docker service create).
type: str
stop_signal:
@ -584,14 +585,14 @@ options:
description:
- Rolling update delay.
- "Accepts a string in a format that look like:
C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h)."
- Corresponds to the C(--update-delay) option of C(docker service create).
type: str
failure_action:
description:
- Action to take in case of container failure.
- Corresponds to the C(--update-failure-action) option of C(docker service create).
- Usage of I(rollback) requires API version >= 1.29.
- Usage of V(rollback) requires API version >= 1.29.
type: str
choices:
- continue
@ -601,7 +602,7 @@ options:
description:
- Time to monitor updated tasks for failures.
- "Accepts a string in a format that look like:
C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h)."
- Corresponds to the C(--update-monitor) option of C(docker service create).
type: str
max_failure_ratio:
@ -619,7 +620,7 @@ options:
user:
description:
- Sets the username or UID used for the specified command.
- Before Ansible 2.8, the default value for this option was C(root).
- Before Ansible 2.8, the default value for this option was V(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 C(--user) option of C(docker service create).
type: str
@ -648,7 +649,7 @@ requirements:
- "Docker API >= 1.25"
notes:
- "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 C(force_update: true) to trigger the swarm to resolve a new image."
When using older versions use O(force_update=true) to trigger the swarm to resolve a new image."
'''
RETURN = '''
@ -661,7 +662,7 @@ swarm_service:
- 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 C(ansible_swarm_service),
while the module actually returned a variable called C(ansible_docker_service). The variable
was renamed to C(swarm_service) in both code and documentation for Ansible 2.7.9 and Ansible 2.8.0.
was renamed to RV(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 C(ansible_docker_service) can still be used.
sample: '{
"args": [

2
plugins/modules/docker_swarm_service_info.py
View File

@ -58,7 +58,7 @@ exists:
service:
description:
- A dictionary representing the current state of the service. Matches the C(docker service inspect) output.
- Will be C(none) if service does not exist.
- Will be V(none) if service does not exist.
returned: always
type: dict
'''

14
plugins/modules/docker_volume.py
View File

@ -38,7 +38,7 @@ options:
driver:
description:
- Specify the type of volume. Docker provides the C(local) driver, but 3rd party drivers can also be used.
- Specify the type of volume. Docker provides the V(local) driver, but 3rd party drivers can also be used.
type: str
default: local
@ -56,13 +56,13 @@ options:
recreate:
description:
- Controls when a volume will be recreated when I(state) is C(present). Please
- Controls when a volume will be recreated when O(state=present). Please
note that recreating an existing volume will cause B(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 C(always) forces the volume to be always recreated.
- The value C(never) makes sure the volume will not be recreated.
- The value C(options-changed) makes sure the volume will be recreated if the volume
- The value V(always) forces the volume to be always recreated.
- The value V(never) makes sure the volume will not be recreated.
- The value V(options-changed) makes sure the volume will be recreated if the volume
already exist and the driver, driver options or labels differ.
type: str
default: never
@ -73,8 +73,8 @@ options:
state:
description:
- C(absent) deletes the volume.
- C(present) creates the volume, if it does not already exist.
- V(absent) deletes the volume.
- V(present) creates the volume, if it does not already exist.
type: str
default: present
choices:

2
plugins/modules/docker_volume_info.py
View File

@ -63,7 +63,7 @@ exists:
volume:
description:
- Volume inspection results for the affected volume.
- Will be C(none) if volume does not exist.
- Will be V(none) if volume does not exist.
returned: success
type: dict
sample: '{

2
tests/sanity/extra/extra-docs.py
View File

@ -17,7 +17,7 @@ def main():
suffix = ':{env}'.format(env=env["ANSIBLE_COLLECTIONS_PATH"]) if 'ANSIBLE_COLLECTIONS_PATH' in env else ''
env['ANSIBLE_COLLECTIONS_PATH'] = '{root}{suffix}'.format(root=os.path.dirname(os.path.dirname(os.path.dirname(os.getcwd()))), suffix=suffix)
p = subprocess.run(
['antsibull-docs', 'lint-collection-docs', '--plugin-docs', '--disallow-semantic-markup', '--skip-rstcheck', '.'],
['antsibull-docs', 'lint-collection-docs', '--plugin-docs', '--skip-rstcheck', '.'],
env=env,
check=False,
)