From 8572fe2095a9f62022086f265cb991588d0541cb Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 11 Jun 2023 15:08:13 +0200 Subject: [PATCH 1/5] Use semantic markup. --- docs/docsite/rst/scenario_guide.rst | 14 +- plugins/connection/docker.py | 3 +- plugins/connection/docker_api.py | 3 +- plugins/doc_fragments/docker.py | 84 +++-- plugins/inventory/docker_containers.py | 35 +- plugins/inventory/docker_machine.py | 18 +- plugins/inventory/docker_swarm.py | 26 +- plugins/modules/current_container_facts.py | 8 +- plugins/modules/docker_compose.py | 70 ++-- plugins/modules/docker_config.py | 30 +- plugins/modules/docker_container.py | 312 +++++++++--------- plugins/modules/docker_container_copy_into.py | 22 +- plugins/modules/docker_container_exec.py | 30 +- plugins/modules/docker_container_info.py | 2 +- plugins/modules/docker_host_info.py | 34 +- plugins/modules/docker_image.py | 54 +-- plugins/modules/docker_image_info.py | 6 +- plugins/modules/docker_login.py | 8 +- plugins/modules/docker_network.py | 18 +- plugins/modules/docker_network_info.py | 2 +- plugins/modules/docker_node.py | 20 +- plugins/modules/docker_node_info.py | 12 +- plugins/modules/docker_plugin.py | 10 +- plugins/modules/docker_prune.py | 16 +- plugins/modules/docker_secret.py | 26 +- plugins/modules/docker_stack.py | 6 +- plugins/modules/docker_swarm.py | 66 ++-- plugins/modules/docker_swarm_info.py | 32 +- plugins/modules/docker_swarm_service.py | 88 ++--- plugins/modules/docker_swarm_service_info.py | 2 +- plugins/modules/docker_volume.py | 14 +- plugins/modules/docker_volume_info.py | 2 +- tests/sanity/extra/extra-docs.py | 2 +- 33 files changed, 536 insertions(+), 539 deletions(-) diff --git a/docs/docsite/rst/scenario_guide.rst b/docs/docsite/rst/scenario_guide.rst index e4b84431f..310c9bb77 100644 --- a/docs/docsite/rst/scenario_guide.rst +++ b/docs/docsite/rst/scenario_guide.rst @@ -86,26 +86,26 @@ 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 + :envvar:`DOCKER_HOST` The URL or Unix socket path used to connect to the Docker API. - DOCKER_API_VERSION + :envvar:`DOCKER_API_VERSION` The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by Docker SDK for Python. - DOCKER_TIMEOUT + :envvar:`DOCKER_TIMEOUT` The maximum amount of time in seconds to wait on a response from the API. - DOCKER_CERT_PATH + :envvar:`DOCKER_CERT_PATH` Path to the directory containing the client certificate, client key and CA certificate. - DOCKER_SSL_VERSION + :envvar:`DOCKER_SSL_VERSION` Provide a valid SSL version number. - DOCKER_TLS + :envvar:`DOCKER_TLS` Secure the connection to the API by using TLS without verifying the authenticity of the Docker Host. - DOCKER_TLS_VERIFY + :envvar:`DOCKER_TLS_VERIFY` Secure the connection to the API by using TLS and verify the authenticity of the Docker Host. diff --git a/plugins/connection/docker.py b/plugins/connection/docker.py index ba2249299..68247dae2 100644 --- a/plugins/connection/docker.py +++ b/plugins/connection/docker.py @@ -20,8 +20,7 @@ - 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: diff --git a/plugins/connection/docker_api.py b/plugins/connection/docker_api.py index 24c95f55a..3b99281c3 100644 --- a/plugins/connection/docker_api.py +++ b/plugins/connection/docker_api.py @@ -15,8 +15,7 @@ - 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. diff --git a/plugins/doc_fragments/docker.py b/plugins/doc_fragments/docker.py index 4c537850e..dda297986 100644 --- a/plugins/doc_fragments/docker.py +++ b/plugins/doc_fragments/docker.py @@ -16,9 +16,9 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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) ''' diff --git a/plugins/inventory/docker_containers.py b/plugins/inventory/docker_containers.py index a82cda955..955b1b2eb 100644 --- a/plugins/inventory/docker_containers.py +++ b/plugins/inventory/docker_containers.py @@ -27,7 +27,7 @@ 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 @@ 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 @@ 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 @@ - 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 @@ 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 @@ - "C(image_): contains the containers that have the image C()." - "C(stack_): contains the containers that belong to the stack C()." - "C(service_): contains the containers that belong to the service C()" - - "C(): contains the containers which belong to the Docker daemon I(docker_host). + - "C(): 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 diff --git a/plugins/inventory/docker_machine.py b/plugins/inventory/docker_machine.py index 69d946100..9edf7c27e 100644 --- a/plugins/inventory/docker_machine.py +++ b/plugins/inventory/docker_machine.py @@ -18,7 +18,7 @@ - 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 @@ 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 @@ 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 diff --git a/plugins/inventory/docker_swarm.py b/plugins/inventory/docker_swarm.py index ebb1da15c..ab2e12122 100644 --- a/plugins/inventory/docker_swarm.py +++ b/plugins/inventory/docker_swarm.py @@ -21,12 +21,12 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 ''' diff --git a/plugins/modules/current_container_facts.py b/plugins/modules/current_container_facts.py index f2cde2b59..2daf60bb0 100644 --- a/plugins/modules/current_container_facts.py +++ b/plugins/modules/current_container_facts.py @@ -58,10 +58,10 @@ 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: diff --git a/plugins/modules/docker_compose.py b/plugins/modules/docker_compose.py index 01db6a22f..f9b930b91 100644 --- a/plugins/modules/docker_compose.py +++ b/plugins/modules/docker_compose.py @@ -18,7 +18,7 @@ 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 @@ 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 @@ 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 @@ - 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 @@ 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 @@ - 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 @@ 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 @@ 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: diff --git a/plugins/modules/docker_config.py b/plugins/modules/docker_config.py index 9f55e0f0d..86654e78b 100644 --- a/plugins/modules/docker_config.py +++ b/plugins/modules/docker_config.py @@ -18,7 +18,7 @@ - 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 @@ 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 @@ 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 @@ - 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 @@ 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 diff --git a/plugins/modules/docker_container.py b/plugins/modules/docker_container.py index 9d1ed416e..fb1bcc6c6 100644 --- a/plugins/modules/docker_container.py +++ b/plugins/modules/docker_container.py @@ -20,11 +20,11 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ rate: description: - "Device read limit in format C([])." - - "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 @@ rate: description: - "Device read limit in format C([])." - - "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 @@ 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 @@ 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 @@ - 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 @@ 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 @@ 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 @@ 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 @@ 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:) to reuse another container's IPC namespace or C(host) to use + - Can be one of V(container:) 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 @@ kernel_memory: description: - "Kernel memory limit in format C([]). 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 @@ 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 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 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([]), 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 @@ 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 @@ 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 @@ - 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 @@ - 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 @@ tmpfs_size: description: - "The size for the tmpfs mount in bytes in format []." - - "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 @@ required: true network_mode: description: - - Connect the container to a network. Choices are C(bridge), C(host), C(none), C(container:), C() 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:), C() 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ shm_size: description: - "Size of C(/dev/shm) in format C([]). 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 ''' diff --git a/plugins/modules/docker_container_copy_into.py b/plugins/modules/docker_container_copy_into.py index f140bfe6a..2af99152d 100644 --- a/plugins/modules/docker_container_copy_into.py +++ b/plugins/modules/docker_container_copy_into.py @@ -19,7 +19,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 ''' diff --git a/plugins/modules/docker_container_exec.py b/plugins/modules/docker_container_exec.py index 522a70a33..6a28cd3e3 100644 --- a/plugins/modules/docker_container_exec.py +++ b/plugins/modules/docker_container_exec.py @@ -42,21 +42,21 @@ 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 @@ 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 @@ 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 @@ 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. diff --git a/plugins/modules/docker_container_info.py b/plugins/modules/docker_container_info.py index bfc28156b..ff24b1bc0 100644 --- a/plugins/modules/docker_container_info.py +++ b/plugins/modules/docker_container_info.py @@ -66,7 +66,7 @@ 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: '{ diff --git a/plugins/modules/docker_host_info.py b/plugins/modules/docker_host_info.py index f08845faa..696cdfd0c 100644 --- a/plugins/modules/docker_host_info.py +++ b/plugins/modules/docker_host_info.py @@ -108,10 +108,10 @@ 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 @@ 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 @@ 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 ''' diff --git a/plugins/modules/docker_image.py b/plugins/modules/docker_image.py index 735de786a..02ae38383 100644 --- a/plugins/modules/docker_image.py +++ b/plugins/modules/docker_image.py @@ -38,12 +38,12 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 diff --git a/plugins/modules/docker_image_info.py b/plugins/modules/docker_image_info.py index e4f480b1c..2f441672f 100644 --- a/plugins/modules/docker_image_info.py +++ b/plugins/modules/docker_image_info.py @@ -19,8 +19,8 @@ - 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 @@ 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 diff --git a/plugins/modules/docker_login.py b/plugins/modules/docker_login.py index 360dd5785..69146a061 100644 --- a/plugins/modules/docker_login.py +++ b/plugins/modules/docker_login.py @@ -46,12 +46,12 @@ 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 @@ - 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 @@ RETURN = ''' login_results: description: Results from the login. - returned: when I(state=present) + returned: when O(state=present) type: dict sample: { "serveraddress": "localhost:5000", diff --git a/plugins/modules/docker_network.py b/plugins/modules/docker_network.py index db9323636..899f8f8b0 100644 --- a/plugins/modules/docker_network.py +++ b/plugins/modules/docker_network.py @@ -61,8 +61,8 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 diff --git a/plugins/modules/docker_network_info.py b/plugins/modules/docker_network_info.py index 9818baad5..c2c445bd1 100644 --- a/plugins/modules/docker_network_info.py +++ b/plugins/modules/docker_network_info.py @@ -66,7 +66,7 @@ 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: { diff --git a/plugins/modules/docker_node.py b/plugins/modules/docker_node.py index d097b07f7..bfa369e98 100644 --- a/plugins/modules/docker_node.py +++ b/plugins/modules/docker_node.py @@ -39,19 +39,19 @@ 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 @@ - 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: diff --git a/plugins/modules/docker_node_info.py b/plugins/modules/docker_node_info.py index d943db31b..c64de0f8d 100644 --- a/plugins/modules/docker_node_info.py +++ b/plugins/modules/docker_node_info.py @@ -33,14 +33,14 @@ - 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 @@ 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 diff --git a/plugins/modules/docker_plugin.py b/plugins/modules/docker_plugin.py index 9bb850665..141f2b3f2 100644 --- a/plugins/modules/docker_plugin.py +++ b/plugins/modules/docker_plugin.py @@ -38,10 +38,10 @@ 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 @@ actions: description: - List of actions performed during task execution. - returned: when I(state!=absent) + returned: when O(state) is not V(absent) type: list ''' diff --git a/plugins/modules/docker_prune.py b/plugins/modules/docker_prune.py index 1557f85a4..1dfbf290e 100644 --- a/plugins/modules/docker_prune.py +++ b/plugins/modules/docker_prune.py @@ -124,14 +124,14 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 ''' diff --git a/plugins/modules/docker_secret.py b/plugins/modules/docker_secret.py index 546756a49..cf4324541 100644 --- a/plugins/modules/docker_secret.py +++ b/plugins/modules/docker_secret.py @@ -18,7 +18,7 @@ - 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 @@ 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 @@ 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 @@ 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 @@ 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 diff --git a/plugins/modules/docker_stack.py b/plugins/modules/docker_stack.py index 98f4c3ad9..f019a6195 100644 --- a/plugins/modules/docker_stack.py +++ b/plugins/modules/docker_stack.py @@ -68,8 +68,8 @@ 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 @@ 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 diff --git a/plugins/modules/docker_swarm.py b/plugins/modules/docker_swarm.py index 69b88f583..e2138d60e 100644 --- a/plugins/modules/docker_swarm.py +++ b/plugins/modules/docker_swarm.py @@ -32,11 +32,11 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 diff --git a/plugins/modules/docker_swarm_info.py b/plugins/modules/docker_swarm_info.py index df1e5af95..6c6008dcf 100644 --- a/plugins/modules/docker_swarm_info.py +++ b/plugins/modules/docker_swarm_info.py @@ -77,10 +77,10 @@ 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 @@ 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_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 diff --git a/plugins/modules/docker_swarm_service.py b/plugins/modules/docker_swarm_service.py index 564234cb5..20a7a1310 100644 --- a/plugins/modules/docker_swarm_service.py +++ b/plugins/modules/docker_swarm_service.py @@ -64,7 +64,7 @@ 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 @@ 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 @@ - 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 @@ - 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,14 @@ - 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) etc. 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 +201,15 @@ 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 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 +249,7 @@ 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 +259,7 @@ 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 +278,7 @@ 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 +290,12 @@ 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 +309,14 @@ tmpfs_size: description: - "Size of the tmpfs mount in format C([]). 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 +327,8 @@ 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 +399,9 @@ 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 +411,15 @@ 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 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 +447,7 @@ 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 +459,7 @@ 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 +477,7 @@ 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 +494,7 @@ 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 +529,7 @@ 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 +542,12 @@ 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 +558,7 @@ 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 +584,14 @@ 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 +601,7 @@ 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 +619,7 @@ 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 +648,7 @@ - "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 +661,7 @@ - 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": [ diff --git a/plugins/modules/docker_swarm_service_info.py b/plugins/modules/docker_swarm_service_info.py index ebe8a8e10..0a9dd56c8 100644 --- a/plugins/modules/docker_swarm_service_info.py +++ b/plugins/modules/docker_swarm_service_info.py @@ -58,7 +58,7 @@ 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 ''' diff --git a/plugins/modules/docker_volume.py b/plugins/modules/docker_volume.py index 09b1d386b..9a2ba1ff2 100644 --- a/plugins/modules/docker_volume.py +++ b/plugins/modules/docker_volume.py @@ -38,7 +38,7 @@ 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 @@ 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 @@ 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: diff --git a/plugins/modules/docker_volume_info.py b/plugins/modules/docker_volume_info.py index 100010ba4..9345d2e6e 100644 --- a/plugins/modules/docker_volume_info.py +++ b/plugins/modules/docker_volume_info.py @@ -63,7 +63,7 @@ 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: '{ diff --git a/tests/sanity/extra/extra-docs.py b/tests/sanity/extra/extra-docs.py index c636beb08..251e6d70f 100755 --- a/tests/sanity/extra/extra-docs.py +++ b/tests/sanity/extra/extra-docs.py @@ -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, ) From 185d9222e3dc949cec57bfe61a4804f45ce5227f Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 11 Jun 2023 15:56:58 +0200 Subject: [PATCH 2/5] Linting. --- plugins/modules/docker_swarm_service.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/plugins/modules/docker_swarm_service.py b/plugins/modules/docker_swarm_service.py index 20a7a1310..7b5ef713c 100644 --- a/plugins/modules/docker_swarm_service.py +++ b/plugins/modules/docker_swarm_service.py @@ -143,8 +143,9 @@ - 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. - - "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) etc. The supported units are V(us), V(ms), V(s), V(m) and V(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: From 61ee1200095a4f781a5f8940c386b707b020118d Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 13 Jun 2023 22:53:44 +0200 Subject: [PATCH 3/5] Define docsite targets. --- docs/docsite/config.yml | 14 +++++++++++ docs/docsite/rst/scenario_guide.rst | 37 +++++++++++++++++------------ 2 files changed, 36 insertions(+), 15 deletions(-) create mode 100644 docs/docsite/config.yml diff --git a/docs/docsite/config.yml b/docs/docsite/config.yml new file mode 100644 index 000000000..6d22a53e2 --- /dev/null +++ b/docs/docsite/config.yml @@ -0,0 +1,14 @@ +--- +# 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_VERIFY diff --git a/docs/docsite/rst/scenario_guide.rst b/docs/docsite/rst/scenario_guide.rst index 310c9bb77..3fb928133 100644 --- a/docs/docsite/rst/scenario_guide.rst +++ b/docs/docsite/rst/scenario_guide.rst @@ -86,27 +86,34 @@ 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. - :envvar:`DOCKER_HOST` - The URL or Unix socket path used to connect to the Docker API. +.. envvar:: DOCKER_HOST - :envvar:`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. - :envvar:`DOCKER_TIMEOUT` - The maximum amount of time in seconds to wait on a response from the API. +.. envvar:: DOCKER_API_VERSION - :envvar:`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. - :envvar:`DOCKER_SSL_VERSION` - Provide a valid SSL version number. +.. envvar:: DOCKER_TIMEOUT - :envvar:`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. - :envvar:`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_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 From 792280a7040e9c6ebc897308715ba06a33de7006 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 13 Jun 2023 23:14:15 +0200 Subject: [PATCH 4/5] Forgot one env var. --- docs/docsite/config.yml | 1 + docs/docsite/rst/scenario_guide.rst | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/docs/docsite/config.yml b/docs/docsite/config.yml index 6d22a53e2..846b95f62 100644 --- a/docs/docsite/config.yml +++ b/docs/docsite/config.yml @@ -11,4 +11,5 @@ envvar_directives: - DOCKER_CERT_PATH - DOCKER_SSL_VERSION - DOCKER_TLS + - DOCKER_TLS_HOSTNAME - DOCKER_TLS_VERIFY diff --git a/docs/docsite/rst/scenario_guide.rst b/docs/docsite/rst/scenario_guide.rst index 3fb928133..3f371bc37 100644 --- a/docs/docsite/rst/scenario_guide.rst +++ b/docs/docsite/rst/scenario_guide.rst @@ -111,6 +111,10 @@ For plugins, they have to be set for the environment Ansible itself runs in. For 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. From 9b76a9e5c7d045e1e6e81458c85a7b16a519eb1e Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 20 Jun 2023 22:55:28 +0200 Subject: [PATCH 5/5] Add array stubs. --- plugins/modules/docker_network.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/docker_network.py b/plugins/modules/docker_network.py index 899f8f8b0..5670ceea0 100644 --- a/plugins/modules/docker_network.py +++ b/plugins/modules/docker_network.py @@ -98,7 +98,7 @@ 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 O(ipam_config.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: