mirror of
https://github.com/ansible-collections/community.docker.git
synced 2026-07-29 03:46:55 +00:00
Reformat documentation with 'andebox yaml-doc' (#1020)
* Reformat documentation with 'andebox yaml-doc'. * Revert unwanted changes. * Fix too long lines. * Fix broken quotes. * Forgot two line breaks.
This commit is contained in:
Felix Fontein
GitHub
@@ -11,14 +11,14 @@ __metaclass__ = type
|
||||
class ModuleDocFragment(object):
|
||||
|
||||
# Standard documentation fragment
|
||||
DOCUMENTATION = r'''
|
||||
DOCUMENTATION = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
check_mode:
|
||||
description: Can run in C(check_mode) and return changed status prediction without modifying target.
|
||||
diff_mode:
|
||||
description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
|
||||
'''
|
||||
check_mode:
|
||||
description: Can run in C(check_mode) and return changed status prediction without modifying target.
|
||||
diff_mode:
|
||||
description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
|
||||
"""
|
||||
|
||||
# Should be used together with the standard fragment
|
||||
INFO_MODULE = r'''
|
||||
@@ -45,23 +45,23 @@ attributes:
|
||||
- docker
|
||||
'''
|
||||
|
||||
CONN = r'''
|
||||
CONN = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
become:
|
||||
description: Is usable alongside C(become) keywords.
|
||||
connection:
|
||||
description: Uses the target's configured connection information to execute code on it.
|
||||
delegation:
|
||||
description: Can be used in conjunction with C(delegate_to) and related keywords.
|
||||
'''
|
||||
become:
|
||||
description: Is usable alongside C(become) keywords.
|
||||
connection:
|
||||
description: Uses the target's configured connection information to execute code on it.
|
||||
delegation:
|
||||
description: Can be used in conjunction with C(delegate_to) and related keywords.
|
||||
"""
|
||||
|
||||
FACTS = r'''
|
||||
FACTS = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
facts:
|
||||
description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
|
||||
'''
|
||||
facts:
|
||||
description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
|
||||
"""
|
||||
|
||||
# Should be used together with the standard fragment and the FACTS fragment
|
||||
FACTS_MODULE = r'''
|
||||
@@ -79,18 +79,18 @@ attributes:
|
||||
support: full
|
||||
'''
|
||||
|
||||
FILES = r'''
|
||||
FILES = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
safe_file_operations:
|
||||
description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
|
||||
'''
|
||||
safe_file_operations:
|
||||
description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
|
||||
"""
|
||||
|
||||
FLOW = r'''
|
||||
FLOW = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
action:
|
||||
description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
|
||||
async:
|
||||
description: Supports being used with the C(async) keyword.
|
||||
'''
|
||||
action:
|
||||
description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
|
||||
async:
|
||||
description: Supports being used with the C(async) keyword.
|
||||
"""
|
||||
|
||||
@@ -11,61 +11,58 @@ __metaclass__ = type
|
||||
class ModuleDocFragment(object):
|
||||
|
||||
# Docker doc fragment
|
||||
DOCUMENTATION = r'''
|
||||
DOCUMENTATION = r"""
|
||||
options:
|
||||
project_src:
|
||||
description:
|
||||
- Path to a directory containing a Compose file
|
||||
(C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)).
|
||||
- If O(files) is provided, will look for these files in this directory instead.
|
||||
- Mutually exclusive with O(definition). One of O(project_src) and O(definition) must be provided.
|
||||
type: path
|
||||
project_name:
|
||||
description:
|
||||
- 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
|
||||
files:
|
||||
description:
|
||||
- List of Compose file names relative to O(project_src) to be used instead of the main Compose file
|
||||
(C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)).
|
||||
- Files are loaded and merged in the order given.
|
||||
- Mutually exclusive with O(definition).
|
||||
type: list
|
||||
elements: path
|
||||
version_added: 3.7.0
|
||||
definition:
|
||||
description:
|
||||
- Compose file describing one or more services, networks and volumes.
|
||||
- Mutually exclusive with O(project_src) and O(files). One of O(project_src) and O(definition) must be provided.
|
||||
- If provided, PyYAML must be available to this module, and O(project_name) must be specified.
|
||||
- Note that a temporary directory will be created and deleted afterwards when using this option.
|
||||
type: dict
|
||||
version_added: 3.9.0
|
||||
env_files:
|
||||
description:
|
||||
- By default environment files are loaded from a C(.env) file located directly under the O(project_src) directory.
|
||||
- O(env_files) can be used to specify the path of one or multiple custom environment files instead.
|
||||
- The path is relative to the O(project_src) directory.
|
||||
type: list
|
||||
elements: path
|
||||
profiles:
|
||||
description:
|
||||
- List of profiles to enable when starting services.
|
||||
- Equivalent to C(docker compose --profile).
|
||||
type: list
|
||||
elements: str
|
||||
check_files_existing:
|
||||
description:
|
||||
- If set to V(false), the module will not check whether one of the files
|
||||
C(compose.yaml), C(compose.yml), C(docker-compose.yaml), or C(docker-compose.yml)
|
||||
exists in O(project_src) if O(files) is not provided.
|
||||
- This can be useful if environment files with C(COMPOSE_FILE) are used to configure a different
|
||||
filename. The module currently does not check for C(COMPOSE_FILE) in environment files or the
|
||||
current environment.
|
||||
type: bool
|
||||
default: true
|
||||
version_added: 3.9.0
|
||||
project_src:
|
||||
description:
|
||||
- Path to a directory containing a Compose file (C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)).
|
||||
- If O(files) is provided, will look for these files in this directory instead.
|
||||
- Mutually exclusive with O(definition). One of O(project_src) and O(definition) must be provided.
|
||||
type: path
|
||||
project_name:
|
||||
description:
|
||||
- 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
|
||||
files:
|
||||
description:
|
||||
- List of Compose file names relative to O(project_src) to be used instead of the main Compose file (C(compose.yml),
|
||||
C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)).
|
||||
- Files are loaded and merged in the order given.
|
||||
- Mutually exclusive with O(definition).
|
||||
type: list
|
||||
elements: path
|
||||
version_added: 3.7.0
|
||||
definition:
|
||||
description:
|
||||
- Compose file describing one or more services, networks and volumes.
|
||||
- Mutually exclusive with O(project_src) and O(files). One of O(project_src) and O(definition) must be provided.
|
||||
- If provided, PyYAML must be available to this module, and O(project_name) must be specified.
|
||||
- Note that a temporary directory will be created and deleted afterwards when using this option.
|
||||
type: dict
|
||||
version_added: 3.9.0
|
||||
env_files:
|
||||
description:
|
||||
- By default environment files are loaded from a C(.env) file located directly under the O(project_src) directory.
|
||||
- O(env_files) can be used to specify the path of one or multiple custom environment files instead.
|
||||
- The path is relative to the O(project_src) directory.
|
||||
type: list
|
||||
elements: path
|
||||
profiles:
|
||||
description:
|
||||
- List of profiles to enable when starting services.
|
||||
- Equivalent to C(docker compose --profile).
|
||||
type: list
|
||||
elements: str
|
||||
check_files_existing:
|
||||
description:
|
||||
- If set to V(false), the module will not check whether one of the files C(compose.yaml), C(compose.yml), C(docker-compose.yaml),
|
||||
or C(docker-compose.yml) exists in O(project_src) if O(files) is not provided.
|
||||
- This can be useful if environment files with C(COMPOSE_FILE) are used to configure a different filename. The module
|
||||
currently does not check for C(COMPOSE_FILE) in environment files or the current environment.
|
||||
type: bool
|
||||
default: true
|
||||
version_added: 3.9.0
|
||||
requirements:
|
||||
- "PyYAML if O(definition) is used"
|
||||
notes:
|
||||
@@ -73,10 +70,9 @@ notes:
|
||||
The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)),
|
||||
and for the main operations also no machine friendly output format. The module tries to accomodate this with various
|
||||
version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin.
|
||||
|
||||
Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions
|
||||
will change over time. New releases of the Docker compose CLI plugin can break this module at any time.
|
||||
'''
|
||||
"""
|
||||
|
||||
# The following needs to be kept in sync with the compose_v2 module utils
|
||||
MINIMUM_VERSION = r'''
|
||||
|
||||
@@ -11,107 +11,106 @@ __metaclass__ = type
|
||||
class ModuleDocFragment(object):
|
||||
|
||||
# Docker doc fragment
|
||||
DOCUMENTATION = r'''
|
||||
DOCUMENTATION = r"""
|
||||
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, V(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection,
|
||||
the module will automatically replace C(tcp) in the connection URL with C(https).
|
||||
- If the value is not specified in the task, the value of environment variable E(DOCKER_HOST) will be used
|
||||
instead. If the environment variable is not set, the default value will be used.
|
||||
type: str
|
||||
default: unix:///var/run/docker.sock
|
||||
aliases: [ docker_url ]
|
||||
tls_hostname:
|
||||
description:
|
||||
- When verifying the authenticity of the Docker Host server, provide the expected name of the server.
|
||||
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME) will
|
||||
be used instead. If the environment variable is not set, the default value will be used.
|
||||
- Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0.
|
||||
- B(Note:) this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for
|
||||
Python 7.0.0 or newer will lead to an error.
|
||||
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 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
|
||||
aliases: [ docker_api_version ]
|
||||
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 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_path:
|
||||
description:
|
||||
- Use a CA certificate when performing server verification by providing the path to a CA certificate file.
|
||||
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
|
||||
the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
|
||||
- This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has
|
||||
been added as an alias and can still be used.
|
||||
type: path
|
||||
aliases: [ ca_cert, 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 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 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 ]
|
||||
tls:
|
||||
description:
|
||||
- Secure the connection to the API by using TLS without verifying the authenticity of the Docker host
|
||||
server. Note that if O(validate_certs) is set to V(true) as well, it will take precedence.
|
||||
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used
|
||||
instead. If the environment variable is not set, the default value will be used.
|
||||
type: bool
|
||||
default: false
|
||||
use_ssh_client:
|
||||
description:
|
||||
- For SSH transports, use the C(ssh) CLI tool instead of paramiko.
|
||||
- Requires Docker SDK for Python 4.4.0 or newer.
|
||||
type: bool
|
||||
default: false
|
||||
version_added: 1.5.0
|
||||
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 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
|
||||
aliases: [ tls_verify ]
|
||||
debug:
|
||||
description:
|
||||
- Debug mode
|
||||
type: bool
|
||||
default: false
|
||||
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, V(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection, the module will automatically
|
||||
replace C(tcp) in the connection URL with C(https).
|
||||
- If the value is not specified in the task, the value of environment variable E(DOCKER_HOST) will be used instead.
|
||||
If the environment variable is not set, the default value will be used.
|
||||
type: str
|
||||
default: unix:///var/run/docker.sock
|
||||
aliases: [docker_url]
|
||||
tls_hostname:
|
||||
description:
|
||||
- When verifying the authenticity of the Docker Host server, provide the expected name of the server.
|
||||
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME) will be used instead.
|
||||
If the environment variable is not set, the default value will be used.
|
||||
- Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0.
|
||||
- B(Note:) this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python
|
||||
7.0.0 or newer will lead to an error.
|
||||
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 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
|
||||
aliases: [docker_api_version]
|
||||
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 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_path:
|
||||
description:
|
||||
- Use a CA certificate when performing server verification by providing the path to a CA certificate file.
|
||||
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, the file C(ca.pem)
|
||||
from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
|
||||
- This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has been added
|
||||
as an alias and can still be used.
|
||||
type: path
|
||||
aliases: [ca_cert, 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 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 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]
|
||||
tls:
|
||||
description:
|
||||
- Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that
|
||||
if O(validate_certs) is set to V(true) as well, it will take precedence.
|
||||
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used instead. If
|
||||
the environment variable is not set, the default value will be used.
|
||||
type: bool
|
||||
default: false
|
||||
use_ssh_client:
|
||||
description:
|
||||
- For SSH transports, use the C(ssh) CLI tool instead of paramiko.
|
||||
- Requires Docker SDK for Python 4.4.0 or newer.
|
||||
type: bool
|
||||
default: false
|
||||
version_added: 1.5.0
|
||||
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 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
|
||||
aliases: [tls_verify]
|
||||
debug:
|
||||
description:
|
||||
- Debug mode.
|
||||
type: bool
|
||||
default: false
|
||||
|
||||
notes:
|
||||
- Connect to the Docker daemon by providing parameters with each task or by defining environment variables.
|
||||
You can define E(DOCKER_HOST), E(DOCKER_TLS_HOSTNAME), E(DOCKER_API_VERSION), E(DOCKER_CERT_PATH),
|
||||
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).
|
||||
- Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define
|
||||
E(DOCKER_HOST), E(DOCKER_TLS_HOSTNAME), E(DOCKER_API_VERSION), E(DOCKER_CERT_PATH), 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 E(DOCKER_CONFIG) environment variable is not specified,
|
||||
and use C($DOCKER_CONFIG/config.json) otherwise.
|
||||
'''
|
||||
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.
|
||||
"""
|
||||
|
||||
# For plugins: allow to define common options with Ansible variables
|
||||
|
||||
|
||||
Reference in New Issue
Block a user