From 479c4d17f1c63a7d9b4be99b2b524a7a72cc4b71 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 28 Dec 2024 15:06:07 +0100 Subject: [PATCH] Reformat documentation with 'andebox yaml-doc'. --- plugins/connection/docker.py | 201 +++--- plugins/connection/docker_api.py | 191 +++--- plugins/connection/nsenter.py | 51 +- plugins/doc_fragments/attributes.py | 56 +- plugins/doc_fragments/compose_v2.py | 119 ++-- plugins/doc_fragments/docker.py | 193 +++--- plugins/inventory/docker_containers.py | 178 +++-- plugins/inventory/docker_machine.py | 105 ++- plugins/inventory/docker_swarm.py | 198 +++--- plugins/modules/current_container_facts.py | 82 +-- plugins/modules/docker_compose_v2.py | 35 +- plugins/modules/docker_compose_v2_exec.py | 58 +- plugins/modules/docker_compose_v2_pull.py | 22 +- plugins/modules/docker_compose_v2_run.py | 64 +- plugins/modules/docker_config.py | 46 +- plugins/modules/docker_container.py | 610 ++++++++---------- plugins/modules/docker_container_copy_into.py | 55 +- plugins/modules/docker_container_exec.py | 72 +-- plugins/modules/docker_container_info.py | 75 +-- plugins/modules/docker_host_info.py | 149 ++--- plugins/modules/docker_image.py | 146 ++--- plugins/modules/docker_image_build.py | 106 ++- plugins/modules/docker_image_export.py | 28 +- plugins/modules/docker_image_info.py | 143 +--- plugins/modules/docker_image_load.py | 41 +- plugins/modules/docker_image_pull.py | 32 +- plugins/modules/docker_image_push.py | 26 +- plugins/modules/docker_image_remove.py | 55 +- plugins/modules/docker_image_tag.py | 46 +- plugins/modules/docker_login.py | 36 +- plugins/modules/docker_network.py | 72 +-- plugins/modules/docker_network_info.py | 66 +- plugins/modules/docker_node.py | 126 ++-- plugins/modules/docker_node_info.py | 31 +- plugins/modules/docker_plugin.py | 33 +- plugins/modules/docker_prune.py | 171 +++-- plugins/modules/docker_secret.py | 46 +- plugins/modules/docker_stack.py | 115 ++-- plugins/modules/docker_stack_info.py | 50 +- plugins/modules/docker_stack_task_info.py | 50 +- plugins/modules/docker_swarm.py | 126 ++-- plugins/modules/docker_swarm_info.py | 140 ++-- plugins/modules/docker_swarm_service.py | 233 ++----- plugins/modules/docker_swarm_service_info.py | 34 +- plugins/modules/docker_volume.py | 43 +- plugins/modules/docker_volume_info.py | 44 +- 46 files changed, 2072 insertions(+), 2527 deletions(-) diff --git a/plugins/connection/docker.py b/plugins/connection/docker.py index 252f64518..fa521fb7d 100644 --- a/plugins/connection/docker.py +++ b/plugins/connection/docker.py @@ -10,116 +10,107 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" author: - - Lorin Hochestein (!UNKNOWN) - - Leendert Brouwer (!UNKNOWN) + - Lorin Hochestein (!UNKNOWN) + - Leendert Brouwer (!UNKNOWN) name: docker short_description: Run tasks in docker containers description: - - Run commands or put/fetch files to an existing docker container. - - Uses the Docker CLI to execute commands in the container. If you prefer - to directly connect to the Docker daemon, use the - P(community.docker.docker_api#connection) connection plugin. + - 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 P(community.docker.docker_api#connection) connection plugin. options: - remote_addr: - description: - - The name of the container you want to access. - default: inventory_hostname - vars: - - name: inventory_hostname - - name: ansible_host - - name: ansible_docker_host - remote_user: - description: - - The user to execute as inside the container. - - If Docker is too old to allow this (< 1.7), the one set by Docker itself will be used. - vars: - - name: ansible_user - - name: ansible_docker_user - ini: - - section: defaults - key: remote_user - env: - - name: ANSIBLE_REMOTE_USER - cli: - - name: user - keyword: - - name: remote_user - docker_extra_args: - description: - - Extra arguments to pass to the docker command line. - default: '' - vars: - - name: ansible_docker_extra_args - ini: - - section: docker_connection - key: extra_cli_args - container_timeout: - default: 10 - description: - - Controls how long we can wait to access reading output from the container once execution started. - env: - - name: ANSIBLE_TIMEOUT - - name: ANSIBLE_DOCKER_TIMEOUT - version_added: 2.2.0 - ini: - - key: timeout - section: defaults - - key: timeout - section: docker_connection - version_added: 2.2.0 - vars: - - name: ansible_docker_timeout - version_added: 2.2.0 - cli: - - name: timeout - type: integer - extra_env: - description: - - Provide extra environment variables to set when running commands in the Docker container. - - This option can currently only be provided as Ansible variables due to limitations of - ansible-core's configuration manager. - # env: - # - name: ANSIBLE_DOCKER_EXTRA_ENV - # ini: - # - key: extra_env - # section: docker_connection - # ansible-core's config manager does NOT support converting JSON strings (or other things) to dictionaries, - # it only accepts actual dictionaries (which do not happen to come from env and ini vars). So there's no way - # to actually provide this parameter from env and ini sources... :-( - vars: - - name: ansible_docker_extra_env - type: dict - version_added: 3.12.0 - working_dir: - description: - - The directory inside the container to run commands in. - - Requires Docker CLI version 18.06 or later. - env: - - name: ANSIBLE_DOCKER_WORKING_DIR - ini: - - key: working_dir - section: docker_connection - vars: - - name: ansible_docker_working_dir - type: string - version_added: 3.12.0 - privileged: - description: - - Whether commands should be run with extended privileges. - - B(Note) that this allows command to potentially break out of the container. Use with care! - env: - - name: ANSIBLE_DOCKER_PRIVILEGED - ini: - - key: privileged - section: docker_connection - vars: - - name: ansible_docker_privileged - type: boolean - default: false - version_added: 3.12.0 -''' + remote_addr: + description: + - The name of the container you want to access. + default: inventory_hostname + vars: + - name: inventory_hostname + - name: ansible_host + - name: ansible_docker_host + remote_user: + description: + - The user to execute as inside the container. + - If Docker is too old to allow this (< 1.7), the one set by Docker itself will be used. + vars: + - name: ansible_user + - name: ansible_docker_user + ini: + - section: defaults + key: remote_user + env: + - name: ANSIBLE_REMOTE_USER + cli: + - name: user + keyword: + - name: remote_user + docker_extra_args: + description: + - Extra arguments to pass to the docker command line. + default: '' + vars: + - name: ansible_docker_extra_args + ini: + - section: docker_connection + key: extra_cli_args + container_timeout: + default: 10 + description: + - Controls how long we can wait to access reading output from the container once execution started. + env: + - name: ANSIBLE_TIMEOUT + - name: ANSIBLE_DOCKER_TIMEOUT + version_added: 2.2.0 + ini: + - key: timeout + section: defaults + - key: timeout + section: docker_connection + version_added: 2.2.0 + vars: + - name: ansible_docker_timeout + version_added: 2.2.0 + cli: + - name: timeout + type: integer + extra_env: + description: + - Provide extra environment variables to set when running commands in the Docker container. + - This option can currently only be provided as Ansible variables due to limitations of ansible-core's configuration + manager. + vars: + - name: ansible_docker_extra_env + type: dict + version_added: 3.12.0 + working_dir: + description: + - The directory inside the container to run commands in. + - Requires Docker CLI version 18.06 or later. + env: + - name: ANSIBLE_DOCKER_WORKING_DIR + ini: + - key: working_dir + section: docker_connection + vars: + - name: ansible_docker_working_dir + type: string + version_added: 3.12.0 + privileged: + description: + - Whether commands should be run with extended privileges. + - B(Note) that this allows command to potentially break out of the container. Use with care! + env: + - name: ANSIBLE_DOCKER_PRIVILEGED + ini: + - key: privileged + section: docker_connection + vars: + - name: ansible_docker_privileged + type: boolean + default: false + version_added: 3.12.0 +""" import fcntl import os diff --git a/plugins/connection/docker_api.py b/plugins/connection/docker_api.py index 50028664a..595f70179 100644 --- a/plugins/connection/docker_api.py +++ b/plugins/connection/docker_api.py @@ -5,114 +5,105 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" author: - - Felix Fontein (@felixfontein) + - Felix Fontein (@felixfontein) name: docker_api short_description: Run tasks in docker containers version_added: 1.1.0 description: - - Run commands or put/fetch files to an existing docker container. - - Uses the L(requests library,https://pypi.org/project/requests/) to interact - directly with the Docker daemon instead of using the Docker CLI. Use the - P(community.docker.docker#connection) connection plugin if you want to use the Docker CLI. + - 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 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. + - 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. extends_documentation_fragment: - - community.docker.docker.api_documentation - - community.docker.docker.var_names + - community.docker.docker.api_documentation + - community.docker.docker.var_names options: - remote_user: - type: str - description: - - The user to execute as inside the container. - vars: - - name: ansible_user - - name: ansible_docker_user - ini: - - section: defaults - key: remote_user - env: - - name: ANSIBLE_REMOTE_USER - cli: - - name: user - keyword: - - name: remote_user - remote_addr: - type: str - description: - - The name of the container you want to access. - default: inventory_hostname - vars: - - name: inventory_hostname - - name: ansible_host - - name: ansible_docker_host - container_timeout: - default: 10 - description: - - Controls how long we can wait to access reading output from the container once execution started. - env: - - name: ANSIBLE_TIMEOUT - - name: ANSIBLE_DOCKER_TIMEOUT - version_added: 2.2.0 - ini: - - key: timeout - section: defaults - - key: timeout - section: docker_connection - version_added: 2.2.0 - vars: - - name: ansible_docker_timeout - version_added: 2.2.0 - cli: - - name: timeout - type: integer - extra_env: - description: - - Provide extra environment variables to set when running commands in the Docker container. - - This option can currently only be provided as Ansible variables due to limitations of - ansible-core's configuration manager. - # env: - # - name: ANSIBLE_DOCKER_EXTRA_ENV - # ini: - # - key: extra_env - # section: docker_connection - # ansible-core's config manager does NOT support converting JSON strings (or other things) to dictionaries, - # it only accepts actual dictionaries (which do not happen to come from env and ini vars). So there's no way - # to actually provide this parameter from env and ini sources... :-( - vars: - - name: ansible_docker_extra_env - type: dict - version_added: 3.12.0 - working_dir: - description: - - The directory inside the container to run commands in. - - Requires Docker API version 1.35 or later. - env: - - name: ANSIBLE_DOCKER_WORKING_DIR - ini: - - key: working_dir - section: docker_connection - vars: - - name: ansible_docker_working_dir - type: string - version_added: 3.12.0 - privileged: - description: - - Whether commands should be run with extended privileges. - - B(Note) that this allows command to potentially break out of the container. Use with care! - env: - - name: ANSIBLE_DOCKER_PRIVILEGED - ini: - - key: privileged - section: docker_connection - vars: - - name: ansible_docker_privileged - type: boolean - default: false - version_added: 3.12.0 -''' + remote_user: + type: str + description: + - The user to execute as inside the container. + vars: + - name: ansible_user + - name: ansible_docker_user + ini: + - section: defaults + key: remote_user + env: + - name: ANSIBLE_REMOTE_USER + cli: + - name: user + keyword: + - name: remote_user + remote_addr: + type: str + description: + - The name of the container you want to access. + default: inventory_hostname + vars: + - name: inventory_hostname + - name: ansible_host + - name: ansible_docker_host + container_timeout: + default: 10 + description: + - Controls how long we can wait to access reading output from the container once execution started. + env: + - name: ANSIBLE_TIMEOUT + - name: ANSIBLE_DOCKER_TIMEOUT + version_added: 2.2.0 + ini: + - key: timeout + section: defaults + - key: timeout + section: docker_connection + version_added: 2.2.0 + vars: + - name: ansible_docker_timeout + version_added: 2.2.0 + cli: + - name: timeout + type: integer + extra_env: + description: + - Provide extra environment variables to set when running commands in the Docker container. + - This option can currently only be provided as Ansible variables due to limitations of ansible-core's configuration + manager. + vars: + - name: ansible_docker_extra_env + type: dict + version_added: 3.12.0 + working_dir: + description: + - The directory inside the container to run commands in. + - Requires Docker API version 1.35 or later. + env: + - name: ANSIBLE_DOCKER_WORKING_DIR + ini: + - key: working_dir + section: docker_connection + vars: + - name: ansible_docker_working_dir + type: string + version_added: 3.12.0 + privileged: + description: + - Whether commands should be run with extended privileges. + - B(Note) that this allows command to potentially break out of the container. Use with care! + env: + - name: ANSIBLE_DOCKER_PRIVILEGED + ini: + - key: privileged + section: docker_connection + vars: + - name: ansible_docker_privileged + type: boolean + default: false + version_added: 3.12.0 +""" import os import os.path diff --git a/plugins/connection/nsenter.py b/plugins/connection/nsenter.py index ccc660b99..79eff89d6 100644 --- a/plugins/connection/nsenter.py +++ b/plugins/connection/nsenter.py @@ -8,40 +8,37 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" name: nsenter short_description: execute on host running controller container version_added: 1.9.0 description: - - This connection plugin allows Ansible, running in a privileged container, to execute tasks on the container - host instead of in the container itself. - - This is useful for running Ansible in a pull model, while still keeping the Ansible control node - containerized. - - It relies on having privileged access to run C(nsenter) in the host's PID namespace, allowing it to enter the - namespaces of the provided PID (default PID 1, or init/systemd). + - This connection plugin allows Ansible, running in a privileged container, to execute tasks on the container host instead + of in the container itself. + - This is useful for running Ansible in a pull model, while still keeping the Ansible control node containerized. + - It relies on having privileged access to run C(nsenter) in the host's PID namespace, allowing it to enter the namespaces + of the provided PID (default PID 1, or init/systemd). author: Jeff Goldschrafe (@jgoldschrafe) options: - nsenter_pid: - description: - - PID to attach with using nsenter. - - The default should be fine unless you are attaching as a non-root user. - type: int - default: 1 - vars: - - name: ansible_nsenter_pid - env: - - name: ANSIBLE_NSENTER_PID - ini: - - section: nsenter_connection - key: nsenter_pid + nsenter_pid: + description: + - PID to attach with using nsenter. + - The default should be fine unless you are attaching as a non-root user. + type: int + default: 1 + vars: + - name: ansible_nsenter_pid + env: + - name: ANSIBLE_NSENTER_PID + ini: + - section: nsenter_connection + key: nsenter_pid notes: - - The remote user is ignored; this plugin always runs as root. - - >- - This plugin requires the Ansible controller container to be launched in the following way: - (1) The container image contains the C(nsenter) program; - (2) The container is launched in privileged mode; - (3) The container is launched in the host's PID namespace (C(--pid host)). -''' + - The remote user is ignored; this plugin always runs as root. + - "This plugin requires the Ansible controller container to be launched in the following way: (1) The container image contains + the C(nsenter) program; (2) The container is launched in privileged mode; (3) The container is launched in the host's + PID namespace (C(--pid host))." +""" import os import pty diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py index 00b3319fc..e9d68bf17 100644 --- a/plugins/doc_fragments/attributes.py +++ b/plugins/doc_fragments/attributes.py @@ -11,14 +11,14 @@ class ModuleDocFragment(object): # Standard documentation fragment - DOCUMENTATION = r''' + DOCUMENTATION = r""" options: {} attributes: - check_mode: - description: Can run in C(check_mode) and return changed status prediction without modifying target. - diff_mode: - description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode. -''' + check_mode: + description: Can run in C(check_mode) and return changed status prediction without modifying target. + diff_mode: + description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode. +""" # Should be used together with the standard fragment INFO_MODULE = r''' @@ -45,23 +45,23 @@ class ModuleDocFragment(object): - docker ''' - CONN = r''' + CONN = r""" options: {} attributes: - become: - description: Is usable alongside C(become) keywords. - connection: - description: Uses the target's configured connection information to execute code on it. - delegation: - description: Can be used in conjunction with C(delegate_to) and related keywords. -''' + become: + description: Is usable alongside C(become) keywords. + connection: + description: Uses the target's configured connection information to execute code on it. + delegation: + description: Can be used in conjunction with C(delegate_to) and related keywords. +""" - FACTS = r''' + FACTS = r""" options: {} attributes: - facts: - description: Action returns an C(ansible_facts) dictionary that will update existing host facts. -''' + facts: + description: Action returns an C(ansible_facts) dictionary that will update existing host facts. +""" # Should be used together with the standard fragment and the FACTS fragment FACTS_MODULE = r''' @@ -79,18 +79,18 @@ class ModuleDocFragment(object): support: full ''' - FILES = r''' + FILES = r""" options: {} attributes: - safe_file_operations: - description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption. -''' + safe_file_operations: + description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption. +""" - FLOW = r''' + FLOW = r""" options: {} attributes: - action: - description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller. - async: - description: Supports being used with the C(async) keyword. -''' + action: + description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller. + async: + description: Supports being used with the C(async) keyword. +""" diff --git a/plugins/doc_fragments/compose_v2.py b/plugins/doc_fragments/compose_v2.py index 58ea7dc28..4a6457b2a 100644 --- a/plugins/doc_fragments/compose_v2.py +++ b/plugins/doc_fragments/compose_v2.py @@ -11,72 +11,67 @@ class ModuleDocFragment(object): # Docker doc fragment - DOCUMENTATION = r''' + DOCUMENTATION = r""" options: - project_src: - description: - - Path to a directory containing a Compose file - (C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)). - - If O(files) is provided, will look for these files in this directory instead. - - Mutually exclusive with O(definition). One of O(project_src) and O(definition) must be provided. - type: path - project_name: - description: - - Provide a project name. If not provided, the project name is taken from the basename of O(project_src). - - Required when O(definition) is provided. - type: str - files: - description: - - List of Compose file names relative to O(project_src) to be used instead of the main Compose file - (C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)). - - Files are loaded and merged in the order given. - - Mutually exclusive with O(definition). - type: list - elements: path - version_added: 3.7.0 - definition: - description: - - Compose file describing one or more services, networks and volumes. - - Mutually exclusive with O(project_src) and O(files). One of O(project_src) and O(definition) must be provided. - - If provided, PyYAML must be available to this module, and O(project_name) must be specified. - - Note that a temporary directory will be created and deleted afterwards when using this option. - type: dict - version_added: 3.9.0 - env_files: - description: - - By default environment files are loaded from a C(.env) file located directly under the O(project_src) directory. - - O(env_files) can be used to specify the path of one or multiple custom environment files instead. - - The path is relative to the O(project_src) directory. - type: list - elements: path - profiles: - description: - - List of profiles to enable when starting services. - - Equivalent to C(docker compose --profile). - type: list - elements: str - check_files_existing: - description: - - If set to V(false), the module will not check whether one of the files - C(compose.yaml), C(compose.yml), C(docker-compose.yaml), or C(docker-compose.yml) - exists in O(project_src) if O(files) is not provided. - - This can be useful if environment files with C(COMPOSE_FILE) are used to configure a different - filename. The module currently does not check for C(COMPOSE_FILE) in environment files or the - current environment. - type: bool - default: true - version_added: 3.9.0 + project_src: + description: + - Path to a directory containing a Compose file (C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)). + - If O(files) is provided, will look for these files in this directory instead. + - Mutually exclusive with O(definition). One of O(project_src) and O(definition) must be provided. + type: path + project_name: + description: + - Provide a project name. If not provided, the project name is taken from the basename of O(project_src). + - Required when O(definition) is provided. + type: str + files: + description: + - List of Compose file names relative to O(project_src) to be used instead of the main Compose file (C(compose.yml), + C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)). + - Files are loaded and merged in the order given. + - Mutually exclusive with O(definition). + type: list + elements: path + version_added: 3.7.0 + definition: + description: + - Compose file describing one or more services, networks and volumes. + - Mutually exclusive with O(project_src) and O(files). One of O(project_src) and O(definition) must be provided. + - If provided, PyYAML must be available to this module, and O(project_name) must be specified. + - Note that a temporary directory will be created and deleted afterwards when using this option. + type: dict + version_added: 3.9.0 + env_files: + description: + - By default environment files are loaded from a C(.env) file located directly under the O(project_src) directory. + - O(env_files) can be used to specify the path of one or multiple custom environment files instead. + - The path is relative to the O(project_src) directory. + type: list + elements: path + profiles: + description: + - List of profiles to enable when starting services. + - Equivalent to C(docker compose --profile). + type: list + elements: str + check_files_existing: + description: + - If set to V(false), the module will not check whether one of the files C(compose.yaml), C(compose.yml), C(docker-compose.yaml), + or C(docker-compose.yml) exists in O(project_src) if O(files) is not provided. + - This can be useful if environment files with C(COMPOSE_FILE) are used to configure a different filename. The module + currently does not check for C(COMPOSE_FILE) in environment files or the current environment. + type: bool + default: true + version_added: 3.9.0 requirements: - "PyYAML if O(definition) is used" notes: - - |- - The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)), - and for the main operations also no machine friendly output format. The module tries to accomodate this with various - version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin. - - Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions - will change over time. New releases of the Docker compose CLI plugin can break this module at any time. -''' + - "The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)),\n + and for the main operations also no machine friendly output format. The module tries to accomodate this with various\n + version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin. Currently + the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions\nwill + change over time. New releases of the Docker compose CLI plugin can break this module at any time." +""" # The following needs to be kept in sync with the compose_v2 module utils MINIMUM_VERSION = r''' diff --git a/plugins/doc_fragments/docker.py b/plugins/doc_fragments/docker.py index b2e213937..a919b8eaa 100644 --- a/plugins/doc_fragments/docker.py +++ b/plugins/doc_fragments/docker.py @@ -11,107 +11,106 @@ class ModuleDocFragment(object): # Docker doc fragment - DOCUMENTATION = r''' + DOCUMENTATION = r""" options: - docker_host: - description: - - The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the - TCP connection string. For example, V(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection, - the module will automatically replace C(tcp) in the connection URL with C(https). - - If the value is not specified in the task, the value of environment variable E(DOCKER_HOST) will be used - instead. If the environment variable is not set, the default value will be used. - type: str - default: unix:///var/run/docker.sock - aliases: [ docker_url ] - tls_hostname: - description: - - When verifying the authenticity of the Docker Host server, provide the expected name of the server. - - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME) will - be used instead. If the environment variable is not set, the default value will be used. - - Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0. - - B(Note:) this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for - Python 7.0.0 or newer will lead to an error. - type: str - api_version: - description: - - The version of the Docker API running on the Docker Host. - - Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon. - - If the value is not specified in the task, the value of environment variable E(DOCKER_API_VERSION) will be - used instead. If the environment variable is not set, the default value will be used. - type: str - default: auto - aliases: [ docker_api_version ] - timeout: - description: - - The maximum amount of time in seconds to wait on a response from the API. - - If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT) will be used - instead. If the environment variable is not set, the default value will be used. - type: int - default: 60 - ca_path: - description: - - Use a CA certificate when performing server verification by providing the path to a CA certificate file. - - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, - the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. - - This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has - been added as an alias and can still be used. - type: path - aliases: [ ca_cert, tls_ca_cert, cacert_path ] - client_cert: - description: - - Path to the client's TLS certificate file. - - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, - the file C(cert.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. - type: path - aliases: [ tls_client_cert, cert_path ] - client_key: - description: - - Path to the client's TLS key file. - - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, - the file C(key.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. - type: path - aliases: [ tls_client_key, key_path ] - tls: - description: - - Secure the connection to the API by using TLS without verifying the authenticity of the Docker host - server. Note that if O(validate_certs) is set to V(true) as well, it will take precedence. - - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used - instead. If the environment variable is not set, the default value will be used. - type: bool - default: false - use_ssh_client: - description: - - For SSH transports, use the C(ssh) CLI tool instead of paramiko. - - Requires Docker SDK for Python 4.4.0 or newer. - type: bool - default: false - version_added: 1.5.0 - validate_certs: - description: - - Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. - - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_VERIFY) will be - used instead. If the environment variable is not set, the default value will be used. - type: bool - default: false - aliases: [ tls_verify ] - debug: - description: - - Debug mode - type: bool - default: false + docker_host: + description: + - The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection + string. For example, V(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection, the module will automatically + replace C(tcp) in the connection URL with C(https). + - If the value is not specified in the task, the value of environment variable E(DOCKER_HOST) will be used instead. + If the environment variable is not set, the default value will be used. + type: str + default: unix:///var/run/docker.sock + aliases: [docker_url] + tls_hostname: + description: + - When verifying the authenticity of the Docker Host server, provide the expected name of the server. + - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME) will be used instead. + If the environment variable is not set, the default value will be used. + - Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0. + - B(Note:) this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python + 7.0.0 or newer will lead to an error. + type: str + api_version: + description: + - The version of the Docker API running on the Docker Host. + - Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon. + - If the value is not specified in the task, the value of environment variable E(DOCKER_API_VERSION) will be used instead. + If the environment variable is not set, the default value will be used. + type: str + default: auto + aliases: [docker_api_version] + timeout: + description: + - The maximum amount of time in seconds to wait on a response from the API. + - If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT) will be used instead. + If the environment variable is not set, the default value will be used. + type: int + default: 60 + ca_path: + description: + - Use a CA certificate when performing server verification by providing the path to a CA certificate file. + - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, the file C(ca.pem) + from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. + - This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has been added + as an alias and can still be used. + type: path + aliases: [ca_cert, tls_ca_cert, cacert_path] + client_cert: + description: + - Path to the client's TLS certificate file. + - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, the file C(cert.pem) + from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. + type: path + aliases: [tls_client_cert, cert_path] + client_key: + description: + - Path to the client's TLS key file. + - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, the file C(key.pem) + from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. + type: path + aliases: [tls_client_key, key_path] + tls: + description: + - Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that + if O(validate_certs) is set to V(true) as well, it will take precedence. + - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used instead. If + the environment variable is not set, the default value will be used. + type: bool + default: false + use_ssh_client: + description: + - For SSH transports, use the C(ssh) CLI tool instead of paramiko. + - Requires Docker SDK for Python 4.4.0 or newer. + type: bool + default: false + version_added: 1.5.0 + validate_certs: + description: + - Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. + - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_VERIFY) will be used instead. + If the environment variable is not set, the default value will be used. + type: bool + default: false + aliases: [tls_verify] + debug: + description: + - Debug mode. + type: bool + default: false notes: - - Connect to the Docker daemon by providing parameters with each task or by defining environment variables. - You can define E(DOCKER_HOST), E(DOCKER_TLS_HOSTNAME), E(DOCKER_API_VERSION), E(DOCKER_CERT_PATH), - E(DOCKER_TLS), E(DOCKER_TLS_VERIFY) and E(DOCKER_TIMEOUT). If you are using docker machine, run the script shipped - with the product that sets up the environment. It will set these variables for you. See - U(https://docs.docker.com/machine/reference/env/) for more details. - - When connecting to Docker daemon with TLS, you might need to install additional Python packages. - For the Docker SDK for Python, version 2.4 or newer, this can be done by installing C(docker[tls]) with M(ansible.builtin.pip). + - Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define + E(DOCKER_HOST), E(DOCKER_TLS_HOSTNAME), E(DOCKER_API_VERSION), E(DOCKER_CERT_PATH), E(DOCKER_TLS), E(DOCKER_TLS_VERIFY) + and E(DOCKER_TIMEOUT). If you are using docker machine, run the script shipped with the product that sets up the environment. + It will set these variables for you. See U(https://docs.docker.com/machine/reference/env/) for more details. + - When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for + Python, version 2.4 or newer, this can be done by installing C(docker[tls]) with M(ansible.builtin.pip). - Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. - In general, it will use C($HOME/.docker/config.json) if the E(DOCKER_CONFIG) environment variable is not specified, - and use C($DOCKER_CONFIG/config.json) otherwise. -''' + In general, it will use C($HOME/.docker/config.json) if the E(DOCKER_CONFIG) environment variable is not specified, and + use C($DOCKER_CONFIG/config.json) otherwise. +""" # For plugins: allow to define common options with Ansible variables diff --git a/plugins/inventory/docker_containers.py b/plugins/inventory/docker_containers.py index a9b310f05..d8fd0df8a 100644 --- a/plugins/inventory/docker_containers.py +++ b/plugins/inventory/docker_containers.py @@ -12,104 +12,102 @@ __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" name: docker_containers short_description: Ansible dynamic inventory plugin for Docker containers version_added: 1.1.0 author: - - Felix Fontein (@felixfontein) + - Felix Fontein (@felixfontein) extends_documentation_fragment: - - ansible.builtin.constructed - - community.docker.docker.api_documentation - - community.library_inventory_filtering_v1.inventory_filter + - ansible.builtin.constructed + - community.docker.docker.api_documentation + - community.library_inventory_filtering_v1.inventory_filter description: - - Reads inventories from the Docker API. - - Uses a YAML configuration file that ends with V(docker.(yml|yaml\)). + - Reads inventories from the Docker API. + - Uses a YAML configuration file that ends with V(docker.(yml|yaml\)). notes: - - The configuration file must be a YAML file whose filename ends with V(docker.yml) or V(docker.yaml). - Other filenames will not be accepted. - + - The configuration file must be a YAML file whose filename ends with V(docker.yml) or V(docker.yaml). Other filenames will + not be accepted. options: - plugin: - description: - - The name of this plugin, it should always be set to V(community.docker.docker_containers) - for this plugin to recognize it as its own. - type: str - required: true - choices: [ community.docker.docker_containers ] - - connection_type: - description: - - Which connection type to use the containers. - - 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: - - ssh - - docker-cli - - docker-api - - configure_docker_daemon: - description: - - Whether to pass all Docker daemon configuration from the inventory plugin to the connection plugin. - - Only used when O(connection_type=docker-api). - type: bool - default: true - version_added: 1.8.0 - - verbose_output: - description: - - 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 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 - - default_ip: - 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 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 O(connection_type) is V(ssh). - type: int - default: 22 - - add_legacy_groups: - description: - - "Add the same groups as the C(docker) inventory script does. These are the following:" - - "C(): contains the container of this ID." - - "C(): contains the container that has this name." - - "C(): contains the containers that have this short ID (first 13 letters of ID)." - - "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 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 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 - - filters: - version_added: 3.5.0 -''' + plugin: + description: + - The name of this plugin, it should always be set to V(community.docker.docker_containers) for this plugin to recognize + it as its own. + type: str + required: true + choices: [community.docker.docker_containers] + + connection_type: + description: + - Which connection type to use the containers. + - 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: + - ssh + - docker-cli + - docker-api + + configure_docker_daemon: + description: + - Whether to pass all Docker daemon configuration from the inventory plugin to the connection plugin. + - Only used when O(connection_type=docker-api). + type: bool + default: true + version_added: 1.8.0 + + verbose_output: + description: + - 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 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 + + default_ip: + 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 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 O(connection_type) is V(ssh). + type: int + default: 22 + + add_legacy_groups: + description: + - 'Add the same groups as the C(docker) inventory script does. These are the following:' + - 'C(): contains the container of this ID.' + - 'C(): contains the container that has this name.' + - 'C(): contains the containers that have this short ID (first 13 letters of ID).' + - '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 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 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 + + filters: + version_added: 3.5.0 +""" EXAMPLES = ''' # Minimal example using local Docker daemon diff --git a/plugins/inventory/docker_machine.py b/plugins/inventory/docker_machine.py index 132390781..6c0a8429f 100644 --- a/plugins/inventory/docker_machine.py +++ b/plugins/inventory/docker_machine.py @@ -6,60 +6,59 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' - name: docker_machine - author: Ximon Eighteen (@ximon18) - short_description: Docker Machine inventory source - requirements: - - L(Docker Machine,https://docs.docker.com/machine/) - extends_documentation_fragment: - - ansible.builtin.constructed - - community.library_inventory_filtering_v1.inventory_filter +DOCUMENTATION = r""" +name: docker_machine +author: Ximon Eighteen (@ximon18) +short_description: Docker Machine inventory source +requirements: + - L(Docker Machine,https://docs.docker.com/machine/) +extends_documentation_fragment: + - ansible.builtin.constructed + - community.library_inventory_filtering_v1.inventory_filter +description: + - Get inventory hosts from Docker Machine. + - Uses a YAML configuration file that ends with V(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 C(dm_) prefixed host variables. +notes: + - The configuration file must be a YAML file whose filename ends with V(docker_machine.yml) or V(docker_machine.yaml). Other + filenames will not be accepted. +options: + plugin: + description: Token that ensures this is a source file for the C(docker_machine) plugin. + required: true + choices: ['docker_machine', 'community.docker.docker_machine'] + daemon_env: description: - - Get inventory hosts from Docker Machine. - - Uses a YAML configuration file that ends with V(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 C(dm_) prefixed host variables. - notes: - - The configuration file must be a YAML file whose filename ends with V(docker_machine.yml) or V(docker_machine.yaml). - Other filenames will not be accepted. - - options: - plugin: - description: token that ensures this is a source file for the C(docker_machine) plugin. - required: true - choices: ['docker_machine', 'community.docker.docker_machine'] - daemon_env: - description: - - Whether docker daemon connection environment variables should be fetched, and how to behave if they cannot be fetched. - - 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 - - require-silently - - optional - - optional-silently - - skip - default: require - running_required: - description: - - 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 V(true), include all available nodes metadata (for example C(Image), C(Region), C(Size)) as a JSON object - named C(docker_machine_node_attributes). - type: bool - default: true - filters: - version_added: 3.5.0 -''' + - Whether docker daemon connection environment variables should be fetched, and how to behave if they cannot be fetched. + - 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 + - require-silently + - optional + - optional-silently + - skip + default: require + running_required: + description: + - 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 V(true), include all available nodes metadata (for example C(Image), C(Region), C(Size)) as a JSON object named + C(docker_machine_node_attributes). + type: bool + default: true + filters: + version_added: 3.5.0 +""" EXAMPLES = ''' # Minimal example diff --git a/plugins/inventory/docker_swarm.py b/plugins/inventory/docker_swarm.py index 5fb864368..89ec1714d 100644 --- a/plugins/inventory/docker_swarm.py +++ b/plugins/inventory/docker_swarm.py @@ -8,109 +8,103 @@ __metaclass__ = type -DOCUMENTATION = r''' - name: docker_swarm - author: - - Stefan Heitmüller (@morph027) - short_description: Ansible dynamic inventory plugin for Docker swarm nodes. - requirements: - - python >= 2.7 - - L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0 - extends_documentation_fragment: - - ansible.builtin.constructed - - community.library_inventory_filtering_v1.inventory_filter +DOCUMENTATION = r""" +name: docker_swarm +author: + - Stefan Heitmüller (@morph027) +short_description: Ansible dynamic inventory plugin for Docker swarm nodes +requirements: + - python >= 2.7 + - L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0 +extends_documentation_fragment: + - ansible.builtin.constructed + - community.library_inventory_filtering_v1.inventory_filter +description: + - Reads inventories from the Docker swarm API. + - Uses a YAML configuration file that ends with V(docker_swarm.(yml|yaml\)). + - '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.' +notes: + - The configuration file must be a YAML file whose filename ends with V(docker_swarm.yml) or V(docker_swarm.yaml). Other + filenames will not be accepted. +options: + plugin: + description: The name of this plugin, it should always be set to V(community.docker.docker_swarm) for this plugin to recognize + it as its own. + type: str + required: true + choices: [docker_swarm, community.docker.docker_swarm] + docker_host: description: - - Reads inventories from the Docker swarm API. - - Uses a YAML configuration file that ends with V(docker_swarm.(yml|yaml\)). - - "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." - notes: - - The configuration file must be a YAML file whose filename ends with V(docker_swarm.yml) or V(docker_swarm.yaml). - Other filenames will not be accepted. - - options: - plugin: - description: The name of this plugin, it should always be set to V(community.docker.docker_swarm) - for this plugin to recognize it as its own. - type: str - required: true - choices: [ docker_swarm, community.docker.docker_swarm ] - docker_host: - description: - - Socket of a Docker swarm manager node (C(tcp), C(unix)). - - "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)). - type: bool - default: true - tls: - description: Connect using TLS without verifying the authenticity of the Docker host server. - type: bool - default: false - validate_certs: - description: Toggle if connecting using TLS with or without verifying the authenticity of the Docker - host server. - type: bool - default: false - aliases: [ tls_verify ] - client_key: - description: Path to the client's TLS key file. - type: path - aliases: [ tls_client_key, key_path ] - ca_path: - description: - - Use a CA certificate when performing server verification by providing the path to a CA certificate file. - - This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has - been added as an alias and can still be used. - type: path - aliases: [ ca_cert, tls_ca_cert, cacert_path ] - client_cert: - description: Path to the client's TLS certificate file. - type: path - aliases: [ tls_client_cert, cert_path ] - tls_hostname: - description: When verifying the authenticity of the Docker host server, provide the expected name of - the server. - 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. - type: str - aliases: [ docker_api_version ] - timeout: - description: - - The maximum amount of time in seconds to wait on a response from the API. - - If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT). - will be used instead. If the environment variable is not set, the default value will be used. - type: int - default: 60 - aliases: [ time_out ] - use_ssh_client: - description: - - For SSH transports, use the C(ssh) CLI tool instead of paramiko. - - Requires Docker SDK for Python 4.4.0 or newer. - type: bool - default: false - version_added: 1.5.0 - 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 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 C(ansible_host_uri). - type: int - filters: - version_added: 3.5.0 -''' + - Socket of a Docker swarm manager node (C(tcp), C(unix)). + - 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)). + type: bool + default: true + tls: + description: Connect using TLS without verifying the authenticity of the Docker host server. + type: bool + default: false + validate_certs: + description: Toggle if connecting using TLS with or without verifying the authenticity of the Docker host server. + type: bool + default: false + aliases: [tls_verify] + client_key: + description: Path to the client's TLS key file. + type: path + aliases: [tls_client_key, key_path] + ca_path: + description: + - Use a CA certificate when performing server verification by providing the path to a CA certificate file. + - This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has been added + as an alias and can still be used. + type: path + aliases: [ca_cert, tls_ca_cert, cacert_path] + client_cert: + description: Path to the client's TLS certificate file. + type: path + aliases: [tls_client_cert, cert_path] + tls_hostname: + description: When verifying the authenticity of the Docker host server, provide the expected name of the server. + 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. + type: str + aliases: [docker_api_version] + timeout: + description: + - The maximum amount of time in seconds to wait on a response from the API. + - If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT). will be used instead. + If the environment variable is not set, the default value will be used. + type: int + default: 60 + aliases: [time_out] + use_ssh_client: + description: + - For SSH transports, use the C(ssh) CLI tool instead of paramiko. + - Requires Docker SDK for Python 4.4.0 or newer. + type: bool + default: false + version_added: 1.5.0 + 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 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 C(ansible_host_uri). + type: int + filters: + version_added: 3.5.0 +""" EXAMPLES = ''' # Minimal example using local docker diff --git a/plugins/modules/current_container_facts.py b/plugins/modules/current_container_facts.py index 2daf60bb0..1b05ad0f5 100644 --- a/plugins/modules/current_container_facts.py +++ b/plugins/modules/current_container_facts.py @@ -9,25 +9,23 @@ __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: current_container_facts short_description: Return facts about whether the module runs in a container version_added: 1.1.0 description: - Return facts about whether the module runs in a Docker or podman container. - - This module attempts a best-effort detection. There might be special cases where - it does not work; if you encounter one, L(please file an issue, - https://github.com/ansible-collections/community.docker/issues/new?assignees=&labels=&template=bug_report.md). + - This module attempts a best-effort detection. There might be special cases where it does not work; if you encounter one, + L(please file an issue, https://github.com/ansible-collections/community.docker/issues/new?assignees=&labels=&template=bug_report.md). author: - Felix Fontein (@felixfontein) extends_documentation_fragment: - community.docker.attributes - community.docker.attributes.facts - community.docker.attributes.facts_module -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get facts on current container community.docker.current_container_facts: @@ -35,42 +33,44 @@ ansible.builtin.debug: msg: "Container ID is {{ ansible_module_container_id }}" when: ansible_module_running_in_container -''' +""" -RETURN = r''' +RETURN = r""" ansible_facts: - description: Ansible facts returned by the module - type: dict - returned: always - contains: - ansible_module_running_in_container: - description: - - Whether the module was able to detect that it runs in a container or not. - returned: always - type: bool - ansible_module_container_id: - description: - - The detected container ID. - - Contains an empty string if no container was detected. - returned: always - type: str - ansible_module_container_type: - description: - - The detected container environment. - - Contains an empty string if no container was detected, or a non-empty string identifying the container environment. - - 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: - - '' - - docker - - azure_pipelines - - github_actions - - podman -''' + description: Ansible facts returned by the module. + type: dict + returned: always + contains: + ansible_module_running_in_container: + description: + - Whether the module was able to detect that it runs in a container or not. + returned: always + type: bool + ansible_module_container_id: + description: + - The detected container ID. + - Contains an empty string if no container was detected. + returned: always + type: str + ansible_module_container_type: + description: + - The detected container environment. + - Contains an empty string if no container was detected, or a non-empty string identifying the container environment. + - 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: + - '' + - docker + - azure_pipelines + - github_actions + - podman +""" import os import re diff --git a/plugins/modules/docker_compose_v2.py b/plugins/modules/docker_compose_v2.py index 366f0bc2a..63f2b9746 100644 --- a/plugins/modules/docker_compose_v2.py +++ b/plugins/modules/docker_compose_v2.py @@ -10,8 +10,7 @@ __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: docker_compose_v2 short_description: Manage multi-container Docker applications with Docker Compose CLI plugin @@ -20,7 +19,6 @@ description: - Uses Docker Compose to start or shutdown services. - extends_documentation_fragment: - community.docker.compose_v2 - community.docker.compose_v2.minimum_version @@ -56,7 +54,8 @@ - Whether to pull images before running. This is used when C(docker compose up) is run. - V(always) ensures that the images are always pulled, even when already present on the Docker daemon. - V(missing) only pulls them when they are not present on the Docker daemon. - - V(never) never pulls images. If they are not present, the module will fail when trying to create the containers that need them. + - V(never) never pulls images. If they are not present, the module will fail when trying to create the containers that + need them. - V(policy) use the Compose file's C(pull_policy) defined for the service to figure out what to do. type: str choices: @@ -68,8 +67,10 @@ build: description: - Whether to build images before starting containers. This is used when C(docker compose up) is run. - - V(always) always builds before starting containers. This is equivalent to the C(--build) option of C(docker compose up). - - V(never) never builds before starting containers. This is equivalent to the C(--no-build) option of C(docker compose up). + - V(always) always builds before starting containers. This is equivalent to the C(--build) option of C(docker compose + up). + - V(never) never builds before starting containers. This is equivalent to the C(--no-build) option of C(docker compose + up). - V(policy) uses the policy as defined in the Compose file. type: str choices: @@ -85,10 +86,10 @@ ignore_build_events: description: - Ignores image building events for change detection. - - If O(state=present) and O(ignore_build_events=true) and O(build=always), a rebuild that does - not trigger a container restart no longer results in RV(ignore:changed=true). - - Note that Docker Compose 2.31.0 is the first Compose 2.x version to emit build events. - For older versions, the behavior is always as if O(ignore_build_events=true). + - If O(state=present) and O(ignore_build_events=true) and O(build=always), a rebuild that does not trigger a container + restart no longer results in RV(ignore:changed=true). + - Note that Docker Compose 2.31.0 is the first Compose 2.x version to emit build events. For older versions, the behavior + is always as if O(ignore_build_events=true). type: bool default: true version_added: 4.2.0 @@ -139,8 +140,8 @@ scale: description: - Define how to scale services when running C(docker compose up). - - 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. + - 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 version_added: 3.7.0 wait: @@ -161,9 +162,9 @@ seealso: - module: community.docker.docker_compose_v2_pull -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # Examples use the django example at https://docs.docker.com/compose/django. Follow it to create the # flask directory @@ -238,9 +239,9 @@ {{ output.containers | selectattr("Service", "equalto", "web") | first }} db_container: >- {{ output.containers | selectattr("Service", "equalto", "db") | first }} -''' +""" -RETURN = ''' +RETURN = r""" containers: description: - A list of containers associated to the service. @@ -420,7 +421,7 @@ - Recreating - Pulling - Building -''' +""" import traceback diff --git a/plugins/modules/docker_compose_v2_exec.py b/plugins/modules/docker_compose_v2_exec.py index bd3391d16..666fa5d06 100644 --- a/plugins/modules/docker_compose_v2_exec.py +++ b/plugins/modules/docker_compose_v2_exec.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: docker_compose_v2_exec short_description: Run command in a container of a Compose service @@ -18,9 +17,7 @@ description: - Uses Docker Compose to run a command in a service's container. - - This can be used to run one-off commands in an existing service's container, - and encapsulates C(docker compose exec). - + - This can be used to run one-off commands in an existing service's container, and encapsulates C(docker compose exec). extends_documentation_fragment: - community.docker.compose_v2 - community.docker.compose_v2.minimum_version @@ -63,8 +60,7 @@ detach: description: - 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. + - 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 user: @@ -99,9 +95,11 @@ 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 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 }}"). + - 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 author: @@ -111,11 +109,11 @@ - module: community.docker.docker_compose_v2 notes: - - If you need to evaluate environment variables of the container in O(command) or O(argv), you need to pass the command through a shell, - like O(command=/bin/sh -c "echo $ENV_VARIABLE"). -''' + - If you need to evaluate environment variables of the container in O(command) or O(argv), you need to pass the command + through a shell, like O(command=/bin/sh -c "echo $ENV_VARIABLE"). +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Run a simple command (command) community.docker.docker_compose_v2_exec: service: foo @@ -140,26 +138,26 @@ - name: Print stderr lines ansible.builtin.debug: var: result.stderr_lines -''' +""" -RETURN = ''' +RETURN = r""" stdout: - type: str - returned: success and O(detach=false) - description: - - The standard output of the container command. + type: str + returned: success and O(detach=false) + description: + - The standard output of the container command. stderr: - type: str - returned: success and O(detach=false) - description: - - The standard error output of the container command. + type: str + returned: success and O(detach=false) + description: + - The standard error output of the container command. rc: - type: int - returned: success and O(detach=false) - sample: 0 - description: - - The exit code of the command. -''' + type: int + returned: success and O(detach=false) + sample: 0 + description: + - The exit code of the command. +""" import shlex import traceback diff --git a/plugins/modules/docker_compose_v2_pull.py b/plugins/modules/docker_compose_v2_pull.py index ba054e504..11bed9cf8 100644 --- a/plugins/modules/docker_compose_v2_pull.py +++ b/plugins/modules/docker_compose_v2_pull.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: docker_compose_v2_pull short_description: Pull a Docker compose project @@ -18,7 +17,6 @@ description: - Uses Docker Compose to pull images for a project. - extends_documentation_fragment: - community.docker.compose_v2 - community.docker.compose_v2.minimum_version @@ -30,9 +28,8 @@ check_mode: support: full details: - - If O(policy=always), the module will always indicate a change. - Docker Compose does not give any information whether pulling would - update the image or not. + - If O(policy=always), the module will always indicate a change. Docker Compose does not give any information whether + pulling would update the image or not. diff_mode: support: none @@ -41,7 +38,8 @@ description: - Whether to pull images before running. This is used when C(docker compose up) is ran. - V(always) ensures that the images are always pulled, even when already present on the Docker daemon. - - V(missing) only pulls them when they are not present on the Docker daemon. This is only supported since Docker Compose 2.22.0. + - V(missing) only pulls them when they are not present on the Docker daemon. This is only supported since Docker Compose + 2.22.0. type: str choices: - always @@ -72,15 +70,15 @@ seealso: - module: community.docker.docker_compose_v2 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Pull images for flask project community.docker.docker_compose_v2_pull: project_src: /path/to/flask -''' +""" -RETURN = ''' +RETURN = r""" actions: description: - A list of actions that have been applied. @@ -108,7 +106,7 @@ sample: Pulling choices: - Pulling -''' +""" import traceback diff --git a/plugins/modules/docker_compose_v2_run.py b/plugins/modules/docker_compose_v2_run.py index 6c8df8ed3..6a0c5f9c4 100644 --- a/plugins/modules/docker_compose_v2_run.py +++ b/plugins/modules/docker_compose_v2_run.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: docker_compose_v2_run short_description: Run command in a new container of a Compose service @@ -19,7 +18,6 @@ description: - Uses Docker Compose to run a command in a new container for a service. - This encapsulates C(docker compose run). - extends_documentation_fragment: - community.docker.compose_v2 - community.docker.compose_v2.minimum_version @@ -134,8 +132,8 @@ detach: description: - 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. Instead, the return value RV(container_id) is provided. + - If set to V(true), O(stdin) cannot be provided, and the return values RV(stdout), RV(stderr), and RV(rc) are not returned. + Instead, the return value RV(container_id) is provided. type: bool default: false user: @@ -165,9 +163,11 @@ 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 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 }}"). + - 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 author: @@ -177,11 +177,11 @@ - module: community.docker.docker_compose_v2 notes: - - If you need to evaluate environment variables of the container in O(command) or O(argv), you need to pass the command through a shell, - like O(command=/bin/sh -c "echo $ENV_VARIABLE"). -''' + - If you need to evaluate environment variables of the container in O(command) or O(argv), you need to pass the command + through a shell, like O(command=/bin/sh -c "echo $ENV_VARIABLE"). +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Run a simple command (command) community.docker.docker_compose_v2_run: service: foo @@ -206,31 +206,31 @@ - name: Print stderr lines ansible.builtin.debug: var: result.stderr_lines -''' +""" -RETURN = ''' +RETURN = r""" container_id: - type: str - returned: success and O(detach=true) - description: - - The ID of the created container. + type: str + returned: success and O(detach=true) + description: + - The ID of the created container. stdout: - type: str - returned: success and O(detach=false) - description: - - The standard output of the container command. + type: str + returned: success and O(detach=false) + description: + - The standard output of the container command. stderr: - type: str - returned: success and O(detach=false) - description: - - The standard error output of the container command. + type: str + returned: success and O(detach=false) + description: + - The standard error output of the container command. rc: - type: int - returned: success and O(detach=false) - sample: 0 - description: - - The exit code of the command. -''' + type: int + returned: success and O(detach=false) + sample: 0 + description: + - The exit code of the command. +""" import shlex import traceback diff --git a/plugins/modules/docker_config.py b/plugins/modules/docker_config.py index 88a92f2e5..fdceb5aff 100644 --- a/plugins/modules/docker_config.py +++ b/plugins/modules/docker_config.py @@ -8,19 +8,17 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_config -short_description: Manage docker configs. +short_description: Manage docker configs description: - Create and remove Docker configs in a Swarm environment. Similar to C(docker config create) and C(docker config rm). - - Adds to the metadata of new configs 'ansible_key', an encrypted hash representation of the data, which is then used - in future runs to test if a config has changed. If 'ansible_key' is not present, then a config will not be updated - unless the O(force) option is set. + - Adds to the metadata of new configs 'ansible_key', an encrypted hash representation of the data, which is then used in + future runs to test if a config has changed. If 'ansible_key' is not present, then a config will not be updated unless + the O(force) option is set. - Updates to configs are performed by removing the config and creating it again. - extends_documentation_fragment: - community.docker.docker - community.docker.docker.docker_py_2_documentation @@ -41,10 +39,8 @@ type: str data_is_b64: description: - - If set to V(true), the data is assumed to be Base64 encoded and will be - decoded before being used. - - To use binary O(data), it is better to keep it Base64 encoded and let it - be decoded by this option. + - If set to V(true), the data is assumed to be Base64 encoded and will be decoded before being used. + - 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: @@ -55,8 +51,9 @@ version_added: 1.10.0 labels: description: - - "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. + - 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: @@ -107,16 +104,15 @@ author: - Chris Houseknecht (@chouseknecht) - John Hu (@ushuz) -''' - -EXAMPLES = ''' +""" +EXAMPLES = r""" - name: Create config foo (from a file on the control machine) community.docker.docker_config: name: foo - # If the file is JSON or binary, Ansible might modify it (because - # it is first decoded and later re-encoded). Base64-encoding the - # file directly after reading it prevents this to happen. + # If the file is JSON or binary, Ansible might modify it (because + # it is first decoded and later re-encoded). Base64-encoding the + # file directly after reading it prevents this to happen. data: "{{ lookup('file', '/path/to/config/file') | b64encode }}" data_is_b64: true state: present @@ -143,7 +139,7 @@ labels: bar: baz one: '1' - # Adding a new label will cause a remove/create of the config + # Adding a new label will cause a remove/create of the config two: '2' state: present @@ -154,7 +150,7 @@ labels: bar: baz one: '1' - # Even though 'two' is missing, there is no change to the existing config + # Even though 'two' is missing, there is no change to the existing config state: present - name: Update an existing label @@ -162,7 +158,7 @@ name: foo data: Goodnight everyone! labels: - bar: monkey # Changing a label will cause a remove/create of the config + bar: monkey # Changing a label will cause a remove/create of the config one: '1' state: present @@ -177,9 +173,9 @@ community.docker.docker_config: name: foo state: absent -''' +""" -RETURN = ''' +RETURN = r""" config_id: description: - The ID assigned by Docker to the config object. @@ -193,7 +189,7 @@ type: str sample: 'awesome_config' version_added: 2.2.0 -''' +""" import base64 import hashlib diff --git a/plugins/modules/docker_container.py b/plugins/modules/docker_container.py index 4760bfde9..f8af631a3 100644 --- a/plugins/modules/docker_container.py +++ b/plugins/modules/docker_container.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_container short_description: manage Docker containers @@ -17,15 +16,13 @@ description: - Manage the life cycle of Docker containers. - Supports check mode. Run with C(--check) and C(--diff) to view config difference and list of actions to be taken. - 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 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 O(image)). Therefore, always specify B(all) options relevant to the container. + - 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 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 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 - community.docker.attributes @@ -35,7 +32,8 @@ check_mode: support: partial details: - - When trying to pull an image, the module assumes this is never changed in check mode except when the image is not present on the Docker daemon. + - When trying to pull an image, the module assumes this is never changed in check mode except when the image is not + present on the Docker daemon. - This behavior can be configured with O(pull_check_mode_behavior). diff_mode: support: full @@ -88,34 +86,29 @@ type: raw comparisons: description: - - Allows to specify how properties of existing containers are compared with - module options to decide whether the container should be recreated / updated - or not. - - Only options which correspond to the state of a container as handled by the - Docker daemon can be specified, as well as 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 V(strict) - or V(ignore) to I(all) comparisons which are not explicitly set to other values. + - Allows to specify how properties of existing containers are compared with module options to decide whether the container + should be recreated / updated or not. + - Only options which correspond to the state of a container as handled by the Docker daemon can be specified, as well + as 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 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 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 O(auto_remove), O(detach), O(init), O(interactive), O(memory), - O(paused), O(privileged), O(read_only), and O(tty) options. + - 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 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 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 @@ -123,17 +116,16 @@ default: no_defaults command_handling: description: - - 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 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 V(compatibility), which was the default until community.docker 3.0.0, the - current behavior will be kept. - - 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. + - 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 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 V(compatibility), which was the default until community.docker 3.0.0, the current behavior will + be kept. + - 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 choices: - compatibility @@ -172,12 +164,11 @@ 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 (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 V(0.0.0.0). + - 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 V(0.0.0.0). type: str version_added: 1.2.0 detach: @@ -189,79 +180,79 @@ devices: description: - List of host device bindings to add to the container. - - "Each binding is a mapping expressed in the format C(::)." + - Each binding is a mapping expressed in the format C(::). type: list elements: str device_read_bps: description: - - "List of device path and read rate (bytes per second) from device." + - List of device path and read rate (bytes per second) from device. type: list elements: dict suboptions: path: description: - - Device path in the container. + - Device path in the container. type: str required: true rate: description: - - "Device read limit in format C([])." - - "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." + - Device read limit in format C([]). + - 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 device_write_bps: description: - - "List of device and write rate (bytes per second) to device." + - List of device and write rate (bytes per second) to device. type: list elements: dict suboptions: path: description: - - Device path in the container. + - Device path in the container. type: str required: true rate: description: - - "Device read limit in format C([])." - - "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." + - Device read limit in format C([]). + - 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 device_read_iops: description: - - "List of device and read rate (IO per second) from device." + - List of device and read rate (IO per second) from device. type: list elements: dict suboptions: path: description: - - Device path in the container. + - Device path in the container. type: str required: true rate: description: - - "Device read limit." - - "Must be a positive integer." + - Device read limit. + - Must be a positive integer. type: int required: true device_write_iops: description: - - "List of device and write rate (IO per second) to device." + - List of device and write rate (IO per second) to device. type: list elements: dict suboptions: path: description: - - Device path in the container. + - Device path in the container. type: str required: true rate: description: - - "Device read limit." - - "Must be a positive integer." + - Device read limit. + - Must be a positive integer. type: int required: true device_requests: @@ -273,11 +264,10 @@ capabilities: description: - List of lists of strings to request capabilities. - - The top-level list entries are combined by OR, and for every list entry, - the entries in the list it contains are combined by AND. + - The top-level list entries are combined by OR, and for every list entry, the entries in the list it contains are + combined by AND. - The driver tries to satisfy one of the sub-lists. - - Available capabilities for the C(nvidia) driver can be found at - U(https://github.com/NVIDIA/nvidia-container-runtime). + - Available capabilities for the C(nvidia) driver can be found at U(https://github.com/NVIDIA/nvidia-container-runtime). type: list elements: list count: @@ -327,9 +317,11 @@ 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 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 }}"). + - 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: @@ -344,18 +336,16 @@ elements: str etc_hosts: description: - - Dict of host-to-IP mappings, where each host name is a key in the dictionary. - Each host name will be added to the container's C(/etc/hosts) file. - - Instead of an IP address, the special value V(host-gateway) can also be used, which - resolves to the host's gateway IP and allows containers to connect to services running - on the host. + - Dict of host-to-IP mappings, where each host name is a key in the dictionary. Each host name will be added to the + container's C(/etc/hosts) file. + - Instead of an IP address, the special value V(host-gateway) can also be used, which resolves to the host's gateway + IP and allows containers to connect to services running on the host. type: dict exposed_ports: description: - - List of additional container ports which informs Docker that the container - listens on the specified network ports at runtime. - - If the port is already exposed using C(EXPOSE) in a Dockerfile, it does not - need to be exposed again. + - List of additional container ports which informs Docker that the container listens on the specified network ports + at runtime. + - If the port is already exposed using C(EXPOSE) in a Dockerfile, it does not need to be exposed again. type: list elements: str aliases: @@ -376,11 +366,11 @@ healthcheck: description: - 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), O(healthcheck.start_period), and O(healthcheck.start_interval) 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)." + - 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), O(healthcheck.start_period), and O(healthcheck.start_interval) 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).' - See also O(state=healthy). type: dict suboptions: @@ -392,10 +382,10 @@ test_cli_compatible: description: - If set to V(true), omitting O(healthcheck.test) while providing O(healthcheck) does not disable healthchecks, - but simply overwrites the image's values by the ones specified in O(healthcheck). This is - the behavior used by the Docker CLI. - - If set to V(false), omitting O(healthcheck.test) will disable the container's health check. - This is the classical behavior of the module and currently the default behavior. + but simply overwrites the image's values by the ones specified in O(healthcheck). This is the behavior used by + the Docker CLI. + - If set to V(false), omitting O(healthcheck.test) will disable the container's health check. This is the classical + behavior of the module and currently the default behavior. default: false type: bool version_added: 3.10.0 @@ -431,17 +421,17 @@ type: str 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, 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 O(pull) option is ignored for this case. + - Repository path and tag used to create the container. If an image is not found or pull is true, the image will be + pulled from the registry. If no tag is included, 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 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, 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. + - 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 O(env), O(env_file), O(exposed_ports), O(labels), and O(volumes) options. type: str choices: @@ -452,13 +442,11 @@ image_label_mismatch: description: - How to handle labels inherited from the image that are not set explicitly. - - 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 O(comparisons) option." + - 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 O(comparisons) option.' type: str choices: - 'ignore' @@ -467,9 +455,9 @@ version_added: 2.6.0 image_name_mismatch: 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 O(comparisons)." + - 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 O(comparisons).' - If set to V(recreate) (default) 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. @@ -493,8 +481,8 @@ ipc_mode: description: - Set the IPC mode for the container. - - 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. + - 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: description: @@ -507,9 +495,8 @@ type: str kernel_memory: description: - - "Kernel memory limit in format C([]). 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). Minimum is V(4M)." + - Kernel memory limit in format C([]). 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). Minimum is V(4M). - Omitting the unit defaults to bytes. type: str labels: @@ -544,32 +531,29 @@ type: str memory: description: - - "Memory limit in format C([]). 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)." + - Memory limit in format C([]). 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. - 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 V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte), - V(T) (tebibyte), or V(P) (pebibyte)." + - Memory soft limit in format C([]). 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_swap: description: - - "Total memory limit (memory + swap) in format C([]), or - 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)." + - Total memory limit (memory + swap) in format C([]), or 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: description: - - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. - - If not set, the value will be remain the same if container exists and will be inherited - from the host machine if it is (re-)created. + - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. + - If not set, the value will be remain the same if container exists and will be inherited from the host machine if it + is (re-)created. type: int mounts: type: list @@ -639,15 +623,15 @@ type: str volume_options: description: - - Dictionary of options specific to the chosen volume_driver. See - L(here,https://docs.docker.com/storage/volumes/#use-a-volume-driver) for details. + - Dictionary of options specific to the chosen volume_driver. See L(here,https://docs.docker.com/storage/volumes/#use-a-volume-driver) + for details. type: dict tmpfs_size: description: - - "The size for the tmpfs mount in bytes in format []." - - "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." + - The size for the tmpfs mount in bytes in format []. + - 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: description: @@ -661,11 +645,12 @@ required: true network_mode: description: - - 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." + - 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: @@ -675,10 +660,11 @@ 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 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." + - '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: @@ -702,30 +688,26 @@ elements: str aliases: description: - - List of aliases for this container in this network. These names - can be used in the network to reach this container. + - List of aliases for this container in this network. These names can be used in the network to reach this container. type: list elements: str mac_address: description: - Endpoint MAC address (for example, V(92:d0:c6:0a:29:33)). - This is only available for Docker API version 1.44 and later. - - Please note that when a container is attached to a network after creation, - this is currently ignored by the Docker Daemon at least in some cases. - When passed on creation, this seems to work better. + - Please note that when a container is attached to a network after creation, this is currently ignored by the Docker + Daemon at least in some cases. When passed on creation, this seems to work better. type: str version_added: 3.6.0 networks_cli_compatible: description: - - "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 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 O(comparisons), the C(default) network will be removed afterwards." + - 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 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 O(comparisons), + the C(default) network will be removed afterwards.' type: bool default: true oom_killer: @@ -734,8 +716,7 @@ type: bool oom_score_adj: description: - - An integer value containing the score given to the container in order to tune - OOM killer preferences. + - An integer value containing the score given to the container in order to tune OOM killer preferences. type: int output_logs: description: @@ -760,12 +741,11 @@ platform: description: - Platform for the container in the format C(os[/arch[/variant]]). - - "Note that since community.docker 3.5.0, the module uses both the image's metadata and the Docker - daemon's information to normalize platform strings similarly to how Docker itself is doing this. - If you notice idempotency problems, L(please create an issue in the community.docker GitHub repository, - https://github.com/ansible-collections/community.docker/issues/new?assignees=&labels=&projects=&template=bug_report.md). - For older community.docker versions, you can use the O(comparisons) option with C(platform: ignore) - to prevent accidental recreation of the container due to this." + - "Note that since community.docker 3.5.0, the module uses both the image's metadata and the Docker daemon's information + to normalize platform strings similarly to how Docker itself is doing this. If you notice idempotency problems, L(please + create an issue in the community.docker GitHub repository, https://github.com/ansible-collections/community.docker/issues/new?assignees=&labels=&projects=&template=bug_report.md). + For older community.docker versions, you can 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: @@ -782,39 +762,35 @@ published_ports: description: - List of ports to publish from the container to the host. - - "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. - Since community.general 0.2.0, if the source port range has length 1, the port will not be assigned - to the first port of the destination range, but to a free port in that range. This is the - same behavior as for 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 P(community.general.dig#lookup) lookup - to resolve hostnames." - - 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 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. + - '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. Since community.general 0.2.0, if the source port range has length 1, the port will not + be assigned to the first port of the destination range, but to a free port in that range. This is the same behavior + as for 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 P(community.general.dig#lookup) lookup to resolve hostnames. + - 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 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: - ports pull: description: - - If set to V(never), will never try to pull an image. Will fail if the image is not available - on the Docker daemon. - - If set to V(missing) or V(false), only pull the image if it is not available on the Docker - daemon. This is the default behavior. + - If set to V(never), will never try to pull an image. Will fail if the image is not available on the Docker daemon. + - If set to V(missing) or V(false), only pull the image if it is not available on the Docker daemon. This is the default + behavior. - If set to V(always) or V(true), always try to pull the latest version of the image. - - "B(Note:) images are only pulled when specified by name. If the image is specified - as a image ID (hash), it cannot be pulled, and this option is ignored." - - "B(Note:) the values V(never), V(missing), and V(always) are only available since - community.docker 3.8.0. Earlier versions only support V(true) and V(false)." + - B(Note:) images are only pulled when specified by name. If the image is specified as a image ID (hash), it cannot + be pulled, and this option is ignored. + - B(Note:) the values V(never), V(missing), and V(always) are only available since community.docker 3.8.0. Earlier versions + only support V(true) and V(false). type: raw choices: - never @@ -826,9 +802,8 @@ pull_check_mode_behavior: description: - Allows to adjust the behavior when O(pull=always) or O(pull=true) in check mode. - - Since the Docker daemon does not expose any functionality to test whether a pull will result - in a changed image, the module by default acts like O(pull=always) only results in a change when - the image is not present. + - Since the Docker daemon does not expose any functionality to test whether a pull will result in a changed image, the + module by default acts like O(pull=always) only results in a change when the image is not present. - If set to V(image_not_present) (default), only report changes in check mode when the image is not present. - If set to V(always), always report changes in check mode. type: str @@ -849,13 +824,11 @@ default: false removal_wait_timeout: description: - - When removing an existing container, the docker daemon API call exists after the container - is scheduled for removal. Removal usually is very fast, but it can happen that during high I/O - load, removal can take longer. By default, the module will wait until the container has been - removed before trying to (re-)create it, however long this takes. - - By setting this option, the module will wait at most this many seconds for the container to be - removed. If the container is still in the removal phase after this many seconds, the module will - fail. + - When removing an existing container, the docker daemon API call exists after the container is scheduled for removal. + Removal usually is very fast, but it can happen that during high I/O load, removal can take longer. By default, the + module will wait until the container has been removed before trying to (re-)create it, however long this takes. + - By setting this option, the module will wait at most this many seconds for the container to be removed. If the container + is still in the removal phase after this many seconds, the module will fail. type: float restart: description: @@ -882,9 +855,8 @@ type: str shm_size: description: - - "Size of C(/dev/shm) in format C([]). Number is 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)." + - Size of C(/dev/shm) in format C([]). Number is 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. If you omit the size entirely, Docker daemon uses V(64M). type: str security_opts: @@ -894,26 +866,26 @@ elements: str state: description: - - '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 + - 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.' - - '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(healthy) - Asserts that the container is V(present) and V(started), and is actually healthy as well. - This means that the conditions defined in O(healthcheck) respectively in the image's C(HEALTHCHECK) - (L(Docker reference for HEALTHCHECK, https://docs.docker.com/reference/dockerfile/#healthcheck)) - are satisfied. - The time waited can be controlled with O(healthy_wait_timeout). This state has been added in community.docker 3.11.0. - - '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 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." + with the requested config. + - 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(healthy) - Asserts that the container is V(present) and V(started), and is actually healthy as well. This means + that the conditions defined in O(healthcheck) respectively in the image's C(HEALTHCHECK) (L(Docker reference for HEALTHCHECK, + https://docs.docker.com/reference/dockerfile/#healthcheck)) are satisfied. The time waited can be controlled with + O(healthy_wait_timeout). This state has been added in community.docker 3.11.0. + - 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 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. + - 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 @@ -929,24 +901,21 @@ type: str healthy_wait_timeout: description: - - When waiting for the container to become healthy if O(state=healthy), this option controls how long - the module waits until the container state becomes healthy. + - When waiting for the container to become healthy if O(state=healthy), this option controls how long the module waits + until the container state becomes healthy. - The timeout is specified in seconds. The default, V(300), is 5 minutes. - - Set this to 0 or a negative value to wait indefinitely. - Note that depending on the container this can result in the module not terminating. + - Set this to 0 or a negative value to wait indefinitely. Note that depending on the container this can result in the + module not terminating. default: 300 type: float version_added: 3.11.0 stop_timeout: description: - - Number of seconds to wait for the container to stop before sending C(SIGKILL). - When the container is created by this module, its C(StopTimeout) configuration - will be set to this value. - - When the container is stopped, will be used as a timeout for stopping the - container. In case the container has a custom C(StopTimeout) configuration, - the behavior depends on the version of the docker daemon. New versions of - the docker daemon will always use the container's configured C(StopTimeout) - value if it has been configured. + - Number of seconds to wait for the container to stop before sending C(SIGKILL). When the container is created by this + module, its C(StopTimeout) configuration will be set to this value. + - When the container is stopped, will be used as a timeout for stopping the container. In case the container has a custom + C(StopTimeout) configuration, the behavior depends on the version of the docker daemon. New versions of the docker + daemon will always use the container's configured C(StopTimeout) value if it has been configured. type: int storage_opts: description: @@ -965,7 +934,7 @@ type: bool ulimits: description: - - "List of ulimit options. A ulimit is specified as V(nofile:262144:262144)." + - List of ulimit options. A ulimit is specified as V(nofile:262144:262144). type: list elements: str sysctls: @@ -975,7 +944,7 @@ user: description: - Sets the username or UID used and optionally the groupname or GID for the specified command. - - "Can be of the forms C(user), C(user:group), C(uid), C(uid:gid), C(user:gid) or C(uid:group)." + - Can be of the forms C(user), C(user:group), C(uid), C(uid:gid), C(user:gid) or C(uid:group). type: str uts: description: @@ -984,13 +953,12 @@ volumes: 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 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." + - 'Use docker CLI-style syntax: C(/host:/container[:mode]).' + - 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)." + - 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: @@ -1020,9 +988,9 @@ requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a data container community.docker.docker_container: name: mydata @@ -1049,25 +1017,25 @@ state: started restart: true links: - - "myredis:aliasedredis" + - "myredis:aliasedredis" devices: - - "/dev/sda:/dev/xvda:rwm" + - "/dev/sda:/dev/xvda:rwm" ports: - # Publish container port 9000 as host port 8080 - - "8080:9000" - # Publish container UDP port 9001 as host port 8081 on interface 127.0.0.1 - - "127.0.0.1:8081:9001/udp" - # Publish container port 9002 as a random host port - - "9002" - # Publish container port 9003 as a free host port in range 8000-8100 - # (the host port will be selected by the Docker daemon) - - "8000-8100:9003" - # Publish container ports 9010-9020 to host ports 7000-7010 - - "7000-7010:9010-9020" + # Publish container port 9000 as host port 8080 + - "8080:9000" + # Publish container UDP port 9001 as host port 8081 on interface 127.0.0.1 + - "127.0.0.1:8081:9001/udp" + # Publish container port 9002 as a random host port + - "9002" + # Publish container port 9003 as a free host port in range 8000-8100 + # (the host port will be selected by the Docker daemon) + - "8000-8100:9003" + # Publish container ports 9010-9020 to host ports 7000-7010 + - "7000-7010:9010-9020" env: - SECRET_KEY: "ssssh" - # Values which might be parsed as numbers, booleans or other types by the YAML parser need to be quoted - BOOLEAN_KEY: "yes" + SECRET_KEY: "ssssh" + # Values which might be parsed as numbers, booleans or other types by the YAML parser need to be quoted + BOOLEAN_KEY: "yes" - name: Container present community.docker.docker_container: @@ -1102,8 +1070,8 @@ log_options: syslog-address: tcp://my-syslog-server:514 syslog-facility: daemon - # NOTE: in Docker 1.13+ the "syslog-tag" option was renamed to "tag" for - # older docker installs, use "syslog-tag" instead + # NOTE: in Docker 1.13+ the "syslog-tag" option was renamed to "tag" for + # older docker installs, use "syslog-tag" instead tag: myservice - name: Create db container and connect to network @@ -1192,9 +1160,9 @@ volumes: - /tmp:/tmp comparisons: - image: ignore # do not restart containers with older versions of the image - env: strict # we want precisely this environment - volumes: allow_more_present # if there are more volumes, that's ok, as long as `/tmp:/tmp` is there + image: ignore # do not restart containers with older versions of the image + env: strict # we want precisely this environment + volumes: allow_more_present # if there are more volumes, that's ok, as long as `/tmp:/tmp` is there - name: Finer container restart/update control II community.docker.docker_container: @@ -1204,8 +1172,8 @@ arg1: "true" arg2: "whatever" comparisons: - '*': ignore # by default, ignore *all* options (including image) - env: strict # except for environment variables; there, we want to be strict + '*': ignore # by default, ignore *all* options (including image) + env: strict # except for environment variables; there, we want to be strict - name: Start container with healthstatus community.docker.docker_container: @@ -1213,8 +1181,8 @@ image: nginx:1.13 state: started healthcheck: - # Check if nginx server is healthy by curl'ing the server. - # If this fails or timeouts, the healthcheck fails. + # Check if nginx server is healthy by curl'ing the server. + # If this fails or timeouts, the healthcheck fails. test: ["CMD", "curl", "--fail", "http://nginx.host.com"] interval: 1m30s timeout: 10s @@ -1228,7 +1196,7 @@ image: nginx:1.13 state: started healthcheck: - # The "NONE" check needs to be specified + # The "NONE" check needs to be specified test: ["NONE"] - name: Create a tmpfs with a size and mode @@ -1248,11 +1216,11 @@ image: ubuntu:18.04 state: started device_read_bps: - # Limit read rate for /dev/sda to 20 mebibytes per second + # Limit read rate for /dev/sda to 20 mebibytes per second - path: /dev/sda rate: 20M device_read_iops: - # Limit read rate for /dev/sdb to 300 IO per second + # Limit read rate for /dev/sdb to 300 IO per second - path: /dev/sdb rate: 300 @@ -1262,19 +1230,20 @@ image: ubuntu:18.04 state: started device_requests: - - # Add some specific devices to this container - device_ids: + # Add some specific devices to this container + - device_ids: - '0' - 'GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a' - - # Add nVidia GPUs to this container - driver: nvidia - count: -1 # this means we want all + # Add nVidia GPUs to this container + - driver: nvidia + count: -1 # this means we want all capabilities: - # We have one OR condition: 'gpu' AND 'utility' - - - gpu - - utility - # See https://github.com/NVIDIA/nvidia-container-runtime#supported-driver-capabilities - # for a list of capabilities supported by the nvidia driver + # We have one OR condition: 'gpu' AND 'utility' + - + - gpu + - utility + # See https://github.com/NVIDIA/nvidia-container-runtime#supported-driver-capabilities + # for a list of capabilities supported by the nvidia driver - name: Start container with storage options community.docker.docker_container: @@ -1282,59 +1251,32 @@ image: ubuntu:18.04 state: started storage_opts: - # Limit root filesystem to 12 MB - note that this requires special storage backends - # (https://fabianlee.org/2020/01/15/docker-use-overlay2-with-an-xfs-backing-filesystem-to-limit-rootfs-size/) + # Limit root filesystem to 12 MB - note that this requires special storage backends + # (https://fabianlee.org/2020/01/15/docker-use-overlay2-with-an-xfs-backing-filesystem-to-limit-rootfs-size/) size: 12m -''' +""" -RETURN = ''' +RETURN = r""" container: - description: - - Facts representing the current state of the container. Matches the docker inspection output. - - 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": "", - "Args": [], - "Config": { - "AttachStderr": false, - "AttachStdin": false, - "AttachStdout": false, - "Cmd": [ - "/usr/bin/supervisord" - ], - "Domainname": "", - "Entrypoint": null, - "Env": [ - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" - ], - "ExposedPorts": { - "443/tcp": {}, - "80/tcp": {} - }, - "Hostname": "8e47bf643eb9", - "Image": "lnmp_nginx:v1", - "Labels": {}, - "OnBuild": null, - "OpenStdin": false, - "StdinOnce": false, - "Tty": false, - "User": "", - "Volumes": { - "/tmp/lnmp/nginx-sites/logs/": {} - }, - ... - }' + description: + - Facts representing the current state of the container. Matches the docker inspection output. + - 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": "", "Args": [], "Config": { "AttachStderr": false, "AttachStdin": false, "AttachStdout": false, + "Cmd": [ "/usr/bin/supervisord" ], "Domainname": "", "Entrypoint": null, "Env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + ], "ExposedPorts": { "443/tcp": {}, "80/tcp": {} }, "Hostname": "8e47bf643eb9", "Image": "lnmp_nginx:v1", "Labels": {}, + "OnBuild": null, "OpenStdin": false, "StdinOnce": false, "Tty": false, "User": "", "Volumes": { "/tmp/lnmp/nginx-sites/logs/": + {} }, ... }' status: - description: - - In case a container is started without detaching, this contains the exit code of the process in the container. - - Before community.docker 1.1.0, this was only returned when non-zero. - returned: when O(state=started) and O(detach=false), and when waiting for the container result did not fail - type: int - sample: 0 -''' + 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 O(state=started) and O(detach=false), and when waiting for the container result did not fail + type: int + sample: 0 +""" from ansible_collections.community.docker.plugins.module_utils.module_container.docker_api import ( DockerAPIEngineDriver, diff --git a/plugins/modules/docker_container_copy_into.py b/plugins/modules/docker_container_copy_into.py index 509067594..09c5e283e 100644 --- a/plugins/modules/docker_container_copy_into.py +++ b/plugins/modules/docker_container_copy_into.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_container_copy_into short_description: Copy a file into a Docker container @@ -19,9 +18,8 @@ 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 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. - + - 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: check_mode: support: full @@ -29,8 +27,8 @@ support: full details: - Additional data will need to be transferred to compute diffs. - - The module uses R(the MAX_FILE_SIZE_FOR_DIFF ansible-core configuration,MAX_FILE_SIZE_FOR_DIFF) - to determine for how large files diffs should be computed. + - The module uses R(the MAX_FILE_SIZE_FOR_DIFF ansible-core configuration,MAX_FILE_SIZE_FOR_DIFF) to determine for how + large files diffs should be computed. options: container: @@ -51,11 +49,9 @@ type: str content_is_b64: description: - - 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 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. + - 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 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 default: false container_path: @@ -71,24 +67,25 @@ default: false local_follow: description: - - This flag indicates that filesystem links in the source tree (where the module is executed), if they exist, should be followed. + - This flag indicates that filesystem links in the source tree (where the module is executed), if they exist, should + be followed. type: bool default: true owner_id: description: - The owner ID to use when writing the file to disk. - 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. + - 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. type: int group_id: description: - The group ID to use when writing the file to disk. - 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. + - 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. type: int mode: description: @@ -98,8 +95,8 @@ force: description: - 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 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 to compare it to the file to upload. @@ -115,9 +112,9 @@ requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Copy a file into the container community.docker.docker_container_copy_into: container: mydata @@ -129,19 +126,19 @@ container: mydata path: /home/user/bin/runme.o container_path: /bin/runme - owner_id: 0 # root - group_id: 0 # root - mode: 0755 # readable and executable by all users, writable by root -''' + owner_id: 0 # root + group_id: 0 # root + mode: 0755 # readable and executable by all users, writable by root +""" -RETURN = ''' +RETURN = r""" container_path: description: - The actual path in the container. - Can only be different from O(container_path) when O(follow=true). type: str returned: success -''' +""" import base64 import io diff --git a/plugins/modules/docker_container_exec.py b/plugins/modules/docker_container_exec.py index 251af5bcd..aab338562 100644 --- a/plugins/modules/docker_container_exec.py +++ b/plugins/modules/docker_container_exec.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_container_exec short_description: Execute command in a docker container @@ -18,7 +17,6 @@ description: - Executes a command in a Docker container. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -55,8 +53,7 @@ detach: description: - 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. + - 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 @@ -87,25 +84,28 @@ 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 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 }}"). + - 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 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. - - If you need to evaluate environment variables of the container in O(command) or O(argv), you need to pass the command through a shell, - like O(command=/bin/sh -c "echo $ENV_VARIABLE"). + - 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. + - If you need to evaluate environment variables of the container in O(command) or O(argv), you need to pass the command + through a shell, like O(command=/bin/sh -c "echo $ENV_VARIABLE"). author: - "Felix Fontein (@felixfontein)" requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Run a simple command (command) community.docker.docker_container_exec: container: foo @@ -130,33 +130,33 @@ - name: Print stderr lines ansible.builtin.debug: var: result.stderr_lines -''' +""" -RETURN = ''' +RETURN = r""" stdout: - type: str - returned: success and O(detach=false) - description: - - The standard output of the container command. + type: str + returned: success and O(detach=false) + description: + - The standard output of the container command. stderr: - type: str - returned: success and O(detach=false) - description: - - The standard error output of the container command. + type: str + returned: success and O(detach=false) + description: + - The standard error output of the container command. rc: - type: int - returned: success and O(detach=false) - sample: 0 - description: - - The exit code of the command. + type: int + returned: success and O(detach=false) + sample: 0 + description: + - The exit code of the command. exec_id: - type: str - returned: success and O(detach=true) - sample: 249d9e3075655baf705ed8f40488c5e9434049cf3431976f1bfdb73741c574c5 - description: - - The execution ID of the command. - version_added: 2.1.0 -''' + type: str + returned: success and O(detach=true) + sample: 249d9e3075655baf705ed8f40488c5e9434049cf3431976f1bfdb73741c574c5 + description: + - The execution ID of the command. + version_added: 2.1.0 +""" import shlex import traceback diff --git a/plugins/modules/docker_container_info.py b/plugins/modules/docker_container_info.py index ff24b1bc0..ffb4b9e32 100644 --- a/plugins/modules/docker_container_info.py +++ b/plugins/modules/docker_container_info.py @@ -8,17 +8,15 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_container_info short_description: Retrieves facts about docker container description: - Retrieves facts about a docker container. - - Essentially returns the output of C(docker inspect ), similar to what M(community.docker.docker_container) - returns for a non-absent container. - + - Essentially returns the output of C(docker inspect ), similar to what M(community.docker.docker_container) returns + for a non-absent container. extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -38,9 +36,9 @@ requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get infos on container community.docker.docker_container_info: name: mydata @@ -54,54 +52,27 @@ ansible.builtin.debug: var: result.container when: result.exists -''' +""" -RETURN = ''' +RETURN = r""" exists: - description: - - Returns whether the container exists. - type: bool - returned: always - sample: true + description: + - Returns whether the container exists. + type: bool + returned: always + sample: true container: - description: - - Facts representing the current state of the container. Matches the docker inspection output. - - Will be V(none) if container does not exist. - returned: always - type: dict - sample: '{ - "AppArmorProfile": "", - "Args": [], - "Config": { - "AttachStderr": false, - "AttachStdin": false, - "AttachStdout": false, - "Cmd": [ - "/usr/bin/supervisord" - ], - "Domainname": "", - "Entrypoint": null, - "Env": [ - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" - ], - "ExposedPorts": { - "443/tcp": {}, - "80/tcp": {} - }, - "Hostname": "8e47bf643eb9", - "Image": "lnmp_nginx:v1", - "Labels": {}, - "OnBuild": null, - "OpenStdin": false, - "StdinOnce": false, - "Tty": false, - "User": "", - "Volumes": { - "/tmp/lnmp/nginx-sites/logs/": {} - }, - ... - }' -''' + description: + - Facts representing the current state of the container. Matches the docker inspection output. + - Will be V(none) if container does not exist. + returned: always + type: dict + sample: '{ "AppArmorProfile": "", "Args": [], "Config": { "AttachStderr": false, "AttachStdin": false, "AttachStdout": false, + "Cmd": [ "/usr/bin/supervisord" ], "Domainname": "", "Entrypoint": null, "Env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + ], "ExposedPorts": { "443/tcp": {}, "80/tcp": {} }, "Hostname": "8e47bf643eb9", "Image": "lnmp_nginx:v1", "Labels": {}, + "OnBuild": null, "OpenStdin": false, "StdinOnce": false, "Tty": false, "User": "", "Volumes": { "/tmp/lnmp/nginx-sites/logs/": + {} }, ... }' +""" import traceback diff --git a/plugins/modules/docker_host_info.py b/plugins/modules/docker_host_info.py index 37e73e317..9d5ede58c 100644 --- a/plugins/modules/docker_host_info.py +++ b/plugins/modules/docker_host_info.py @@ -8,21 +8,18 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_host_info -short_description: Retrieves facts about docker host and lists of objects of the services. +short_description: Retrieves facts about docker host and lists of objects of the services description: - Retrieves facts about a docker host. - Essentially returns the output of C(docker system info). - - The module also allows to list object names for containers, images, networks and volumes. - It also allows to query information on disk usage. + - The module also allows to list object names for containers, images, networks and volumes. It also allows to query information + on disk usage. - The output differs depending on API version of the docker daemon. - - If the docker daemon cannot be contacted or does not meet the API version requirements, - the module will fail. - + - If the docker daemon cannot be contacted or does not meet the API version requirements, the module will fail. extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -54,11 +51,11 @@ containers_filters: description: - A dictionary of filter values used for selecting containers to list. - - "For example, C(until: 24h)." - - C(label) is a special case of filter which can be a string C() matching when a label is present, a string - C(=) matching when a label has a particular value, or a list of strings C()/C(=) matching when a label is present, a string C(=) + matching when a label has a particular value, or a list of strings C()/C(=) matching when a label is present, a string - C(=) matching when a label has a particular value, or a list of strings C()/C(=) matching when a label is present, a string C(=) + matching when a label has a particular value, or a list of strings C()/C(=) matching when a label is present, a string - C(=) matching when a label has a particular value, or a list of strings C()/C(=) matching when a label is present, a string C(=) + matching when a label has a particular value, or a list of strings C()/C(=) matching when a label is present, a string - C(=) matching when a label has a particular value, or a list of strings C()/C(=) matching when a label is present, a string C(=) + matching when a label has a particular value, or a list of strings C()/C(== 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get info on docker host community.docker.docker_host_info: register: result @@ -163,61 +160,55 @@ - name: Show host information ansible.builtin.debug: var: result.host_info +""" -''' - -RETURN = ''' +RETURN = r""" can_talk_to_docker: - description: - - Will be V(true) if the module can talk to the docker daemon. - returned: both on success and on error - type: bool + description: + - Will be V(true) if the module can talk to the docker daemon. + returned: both on success and on error + type: bool host_info: - description: - - Facts representing the basic state of the docker host. Matches the C(docker system info) output. - returned: always - type: dict + description: + - Facts representing the basic state of the docker host. Matches the C(docker system info) output. + returned: always + type: dict volumes: - description: - - List of dict objects containing the basic information about each volume. - 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 + description: + - List of dict objects containing the basic information about each volume. 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 O(verbose_output=true). - See description for O(verbose_output). - returned: When O(networks=true) - type: list - elements: dict + description: + - List of dict objects containing the basic information about each network. 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 O(verbose_output=true). - See description for O(verbose_output). - returned: When O(containers=true) - type: list - elements: dict + description: + - List of dict objects containing the basic information about each container. 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 O(verbose_output=true). - See description for O(verbose_output). - returned: When O(images=true) - type: list - elements: dict + description: + - List of dict objects containing the basic information about each image. 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 O(verbose_output=true). See description for O(verbose_output). - returned: When O(disk_usage=true) - type: dict - -''' + description: + - Information on summary disk usage by images, containers and volumes on docker host unless O(verbose_output=true). See + description for O(verbose_output). + returned: When O(disk_usage=true) + type: dict +""" import traceback diff --git a/plugins/modules/docker_image.py b/plugins/modules/docker_image.py index 6927d301a..287f2be48 100644 --- a/plugins/modules/docker_image.py +++ b/plugins/modules/docker_image.py @@ -8,20 +8,17 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_image short_description: Manage docker images description: - - Build, load or pull an image, making the image available for creating containers. Also supports tagging - an image, pushing an image, and archiving an image to a C(.tar) file. - + - Build, load or pull an image, making the image available for creating containers. Also supports tagging an image, pushing + an image, and archiving an image to a C(.tar) file. notes: - - Building images is done using Docker daemon's API. It is not possible to use BuildKit / buildx this way. - Use M(community.docker.docker_image_build) to build images with BuildKit. - + - Building images is done using Docker daemon's API. It is not possible to use BuildKit / buildx this way. Use M(community.docker.docker_image_build) + to build images with BuildKit. extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -38,23 +35,21 @@ options: source: description: - - "Determines where the module will try to retrieve the image from." - - "Use V(build) to build the image from a C(Dockerfile). O(build.path) must - be specified when this value is used." - - "Use V(load) to load the image from a C(.tar) file. O(load_path) must - be specified when this value is used." - - "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." + - Determines where the module will try to retrieve the image from. + - Use V(build) to build the image from a C(Dockerfile). O(build.path) must be specified when this value is used. + - Use V(load) to load the image from a C(.tar) file. O(load_path) must be specified when this value is used. + - 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: - - build - - load - - pull - - local + - build + - load + - pull + - local build: description: - - "Specifies options used for building images." + - Specifies options used for building images. type: dict suboptions: cache_from: @@ -64,7 +59,8 @@ elements: str dockerfile: description: - - Use with O(state=present) and O(source=build) to provide an alternate name for the Dockerfile to use when building an image. + - 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: @@ -74,8 +70,8 @@ type: int path: description: - - Use with state 'present' to build an image. Will be the path to a directory containing the context and - Dockerfile for building an image. + - Use with state 'present' to build an image. Will be the path to a directory containing the context and Dockerfile + for building an image. type: path required: true pull: @@ -100,9 +96,8 @@ etc_hosts: description: - Extra hosts to add to C(/etc/hosts) in building containers, as a mapping of hostname to IP address. - - Instead of an IP address, the special value V(host-gateway) can also be used, which - resolves to the host's gateway IP and allows building containers to connect to services running - on the host. + - Instead of an IP address, the special value V(host-gateway) can also be used, which resolves to the host's gateway + IP and allows building containers to connect to services running on the host. type: dict args: description: @@ -116,18 +111,16 @@ suboptions: memory: description: - - "Memory limit for build in format C([]). 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)." + - Memory limit for build in format C([]). 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. - Before community.docker 3.6.0, no units were allowed. type: str memswap: description: - - "Total memory limit (memory + swap) for build in format C([]), or - 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)." + - Total memory limit (memory + swap) for build in format C([]), or 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. - Before community.docker 3.6.0, no units were allowed, and neither was the special value V(unlimited). type: str @@ -142,14 +135,12 @@ type: str use_config_proxy: description: - - 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. + - 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 target: description: - - When building an image specifies an intermediate build stage by - name as a final stage for the resulting image. + - When building an image specifies an intermediate build stage by name as a final stage for the resulting image. type: str platform: description: @@ -158,9 +149,8 @@ version_added: 1.1.0 shm_size: description: - - "Size of C(/dev/shm) in format C([]). Number is 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)." + - Size of C(/dev/shm) in format C([]). Number is 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. If you omit the size entirely, Docker daemon uses V(64M). type: str version_added: 3.6.0 @@ -180,8 +170,8 @@ type: path force_source: description: - - 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. + - 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: @@ -196,23 +186,23 @@ 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 O(state=absent), for O(state=present) with O(source=load), - and for O(state=present) with O(source=local). + - '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 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: description: - - "Specifies options used for pulling images." + - Specifies options used for pulling images. type: dict version_added: 1.3.0 suboptions: platform: description: - When pulling an image, ask for this specific platform. - - Note that this value is not used to determine whether the image needs to be pulled. This might change - in the future in a minor release, though. + - Note that this value is not used to determine whether the image needs to be pulled. This might change in the future + in a minor release, though. type: str push: description: @@ -223,16 +213,16 @@ description: - 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). + - 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 V(absent) an image will be removed. Use the force option to un-tag and remove all images - matching the provided name. - - 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. + - When V(absent) an image will be removed. Use the force option to un-tag and remove all images matching the provided + name. + - 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: @@ -240,8 +230,7 @@ - present tag: description: - - Used to select an image when pulling. Will be added to the image when pushing, tagging or building. Defaults to - V(latest). + - Used to select an image when pulling. Will be added to the image when pushing, tagging or building. Defaults to V(latest). - If O(name) parameter format is C(name:tag), then tag value from O(name) will take precedence. type: str default: latest @@ -263,15 +252,14 @@ - module: community.docker.docker_image_push - module: community.docker.docker_image_remove - module: community.docker.docker_image_tag -''' - -EXAMPLES = ''' +""" +EXAMPLES = r""" - name: Pull an image community.docker.docker_image: name: pacur/centos-7 source: pull - # Select platform for pulling. If not specified, will pull whatever docker prefers. + # Select platform for pulling. If not specified, will pull whatever docker prefers. pull: platform: amd64 @@ -284,9 +272,9 @@ - name: Tag and push to local registry community.docker.docker_image: - # Image will be centos:7 + # Image will be centos:7 name: centos - # Will be pushed to localhost:5000/centos:7 + # Will be pushed to localhost:5000/centos:7 repository: localhost:5000/centos tag: 7 push: true @@ -296,7 +284,7 @@ community.docker.docker_image: name: myimage:7.1.2 repository: myimage:latest - # As 'latest' usually already is present, we need to enable overwriting of existing tags: + # As 'latest' usually already is present, we need to enable overwriting of existing tags: force_tag: true source: local @@ -345,26 +333,26 @@ name: myimage:latest build: path: /path/to/build/dir - # Use as cache source for building myimage + # Use as cache source for building myimage cache_from: - nginx:latest - alpine:3.8 source: build -''' +""" -RETURN = ''' +RETURN = r""" image: - description: Image inspection results for the affected image. - returned: success - type: dict - sample: {} + description: Image inspection results for the affected image. + returned: success + type: dict + sample: {} stdout: - description: Docker build output when building an image. - returned: success - type: str - sample: "" - version_added: 1.0.0 -''' + description: Docker build output when building an image. + returned: success + type: str + sample: "" + version_added: 1.0.0 +""" import errno import json diff --git a/plugins/modules/docker_image_build.py b/plugins/modules/docker_image_build.py index 1ebb2036c..f38e480cf 100644 --- a/plugins/modules/docker_image_build.py +++ b/plugins/modules/docker_image_build.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_image_build short_description: Build Docker images using Docker buildx @@ -18,10 +17,8 @@ description: - This module allows you to build Docker images using Docker's buildx plugin (BuildKit). - - Note that the module is B(not idempotent) in the sense of classical Ansible modules. - The only idempotence check is whether the built image already exists. This check can - be disabled with the O(rebuild) option. - + - Note that the module is B(not idempotent) in the sense of classical Ansible modules. The only idempotence check is whether + the built image already exists. This check can be disabled with the O(rebuild) option. extends_documentation_fragment: - community.docker.docker.cli_documentation - community.docker.attributes @@ -36,8 +33,8 @@ options: 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)." + - '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) and names with digest cannot be used. type: str required: true @@ -79,9 +76,8 @@ etc_hosts: description: - Extra hosts to add to C(/etc/hosts) in building containers, as a mapping of hostname to IP address. - - Instead of an IP address, the special value V(host-gateway) can also be used, which - resolves to the host's gateway IP and allows building containers to connect to services running - on the host. + - Instead of an IP address, the special value V(host-gateway) can also be used, which resolves to the host's gateway + IP and allows building containers to connect to services running on the host. type: dict args: description: @@ -90,8 +86,7 @@ type: dict target: description: - - When building an image specifies an intermediate build stage by - name as a final stage for the resulting image. + - When building an image specifies an intermediate build stage by name as a final stage for the resulting image. type: str platform: description: @@ -101,9 +96,8 @@ elements: str shm_size: description: - - "Size of C(/dev/shm) in format C([]). Number is 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)." + - Size of C(/dev/shm) in format C([]). Number is 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. If you omit the size entirely, Docker daemon uses V(64M). type: str labels: @@ -145,8 +139,8 @@ - Note that this requires the Buildkit plugin to have version 0.6.0 or newer. value: - Provides the secret from a given value O(secrets[].value). - - B(Note) that the secret will be passed as an environment variable to C(docker compose). - Use another mean of transport if you consider this not safe enough. + - B(Note) that the secret will be passed as an environment variable to C(docker compose). Use another mean of + transport if you consider this not safe enough. - Note that this requires the Buildkit plugin to have version 0.6.0 or newer. required: true src: @@ -162,24 +156,23 @@ value: description: - Value of the secret. - - B(Note) that the secret will be passed as an environment variable to C(docker compose). - Use another mean of transport if you consider this not safe enough. + - B(Note) that the secret will be passed as an environment variable to C(docker compose). Use another mean of transport + if you consider this not safe enough. - Only supported and required for O(secrets[].type=value). type: str outputs: description: - Output destinations. - - You can provide a list of exporters to export the built image in various places. - Note that not all exporters might be supported by the build driver used. - - Note that depending on how this option is used, no image with name O(name) and tag O(tag) might - be created, which can cause the basic idempotency this module offers to not work. - - Providing an empty list to this option is equivalent to not specifying it at all. - The default behavior is a single entry with O(outputs[].type=image). - - B(Note) that since community.docker 4.2.0, an entry for O(name)/O(tag) is added if O(outputs) - has at least one entry and no entry has type O(outputs[].type=image) and includes O(name)/O(tag) - in O(outputs[].name). This is because the module would otherwise pass C(--tag name:image) to - the buildx plugin, which for some reason overwrites all images in O(outputs) by the C(name:image) - provided in O(name)/O(tag). + - You can provide a list of exporters to export the built image in various places. Note that not all exporters might + be supported by the build driver used. + - Note that depending on how this option is used, no image with name O(name) and tag O(tag) might be created, which + can cause the basic idempotency this module offers to not work. + - Providing an empty list to this option is equivalent to not specifying it at all. The default behavior is a single + entry with O(outputs[].type=image). + - B(Note) that since community.docker 4.2.0, an entry for O(name)/O(tag) is added if O(outputs) has at least one entry + and no entry has type O(outputs[].type=image) and includes O(name)/O(tag) in O(outputs[].name). This is because the + module would otherwise pass C(--tag name:image) to the buildx plugin, which for some reason overwrites all images + in O(outputs) by the C(name:image) provided in O(name)/O(tag). type: list elements: dict version_added: 3.10.0 @@ -190,30 +183,27 @@ type: str choices: local: - - This export type writes all result files to a directory on the client. - The new files will be owned by the current user. - On multi-platform builds, all results will be put in subdirectories by their platform. + - This export type writes all result files to a directory on the client. The new files will be owned by the current + user. On multi-platform builds, all results will be put in subdirectories by their platform. - The destination has to be provided in O(outputs[].dest). tar: - - This export type export type writes all result files as a single tarball on the client. - On multi-platform builds, all results will be put in subdirectories by their platform. + - This export type export type writes all result files as a single tarball on the client. On multi-platform builds, + all results will be put in subdirectories by their platform. - The destination has to be provided in O(outputs[].dest). oci: - - This export type writes the result image or manifest list as an - L(OCI image layout, https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md) + - This export type writes the result image or manifest list as an L(OCI image layout, https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md) tarball on the client. - The destination has to be provided in O(outputs[].dest). docker: - This export type writes the single-platform result image as a Docker image specification tarball on the client. Tarballs created by this exporter are also OCI compatible. - - The destination can be provided in O(outputs[].dest). - If not specified, the tar will be loaded automatically to the local image store. + - The destination can be provided in O(outputs[].dest). If not specified, the tar will be loaded automatically + to the local image store. - The Docker context where to import the result can be provided in O(outputs[].context). image: - - This exporter writes the build result as an image or a manifest list. - When using this driver, the image will appear in C(docker images). - - The image name can be provided in O(outputs[].name). If it is not provided, - O(name) and O(tag) will be used. + - This exporter writes the build result as an image or a manifest list. When using this driver, the image will + appear in C(docker images). + - The image name can be provided in O(outputs[].name). If it is not provided, O(name) and O(tag) will be used. - Optionally, image can be automatically pushed to a registry by setting O(outputs[].push=true). required: true dest: @@ -250,9 +240,9 @@ seealso: - module: community.docker.docker_image_push - module: community.docker.docker_image_tag -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Build Python 3.12 image community.docker.docker_image_build: name: localhost/python/3.12:latest @@ -267,22 +257,22 @@ platform: - linux/amd64 - linux/arm64/v8 -''' +""" -RETURN = ''' +RETURN = r""" image: - description: Image inspection results for the affected image. - returned: success - type: dict - sample: {} + description: Image inspection results for the affected image. + returned: success + type: dict + sample: {} command: - description: The command executed. - returned: success and for some failures - type: list - elements: str - version_added: 4.2.0 -''' + description: The command executed. + returned: success and for some failures + type: list + elements: str + version_added: 4.2.0 +""" import base64 import os diff --git a/plugins/modules/docker_image_export.py b/plugins/modules/docker_image_export.py index 9e03875a2..e66ca7e48 100644 --- a/plugins/modules/docker_image_export.py +++ b/plugins/modules/docker_image_export.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_image_export short_description: Export (archive) Docker images @@ -19,7 +18,6 @@ description: - Creates an archive (tarball) from one or more Docker images. - This can be copied to another machine and loaded with M(community.docker.docker_image_load). - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -34,8 +32,8 @@ options: names: description: - - "One or more image names. 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)." + - 'One or more image names. 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) can also be used. type: list elements: str @@ -68,9 +66,9 @@ - module: community.docker.docker_image - module: community.docker.docker_image_info - module: community.docker.docker_image_load -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Export an image community.docker.docker_image_export: name: pacur/centos-7 @@ -82,16 +80,16 @@ - hello-world:latest - pacur/centos-7:latest path: /tmp/various.tar -''' +""" -RETURN = ''' +RETURN = r""" images: - description: Image inspection results for the affected images. - returned: success - type: list - elements: dict - sample: [] -''' + description: Image inspection results for the affected images. + returned: success + type: list + elements: dict + sample: [] +""" import traceback diff --git a/plugins/modules/docker_image_info.py b/plugins/modules/docker_image_info.py index 2f441672f..3bac5d7a0 100644 --- a/plugins/modules/docker_image_info.py +++ b/plugins/modules/docker_image_info.py @@ -8,23 +8,20 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_image_info short_description: Inspect docker images description: - Provide one or more image names, and the module will inspect each, returning an array of inspection results. - - If an image does not exist locally, it will not appear in the results. If you want to check whether an image exists - locally, you can call the module with the image name, then check whether the result list is empty (image does not - exist) or has one element (the image exists locally). - - The module will not attempt to pull images from registries. Use M(community.docker.docker_image) with - O(community.docker.docker_image#module:source=pull) to ensure an image is pulled. - + - 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 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. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -34,9 +31,8 @@ options: name: description: - - An image name or a list of image names. Name format will be C(name[:tag]) or C(repository/name[:tag]), - where C(tag) is optional. If a tag is not provided, V(latest) will be used. Instead of image names, also - image IDs can be used. + - An image name or a list of image names. Name format will be C(name[:tag]) or C(repository/name[:tag]), 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 elements: str @@ -46,10 +42,9 @@ author: - Chris Houseknecht (@chouseknecht) +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" - name: Inspect a single image community.docker.docker_image_info: name: pacur/centos-7 @@ -65,103 +60,31 @@ ansible.builtin.assert: that: - result.images | length == 2 -''' +""" -RETURN = ''' +RETURN = r""" images: - description: - - Inspection results for the selected images. - - The list only contains inspection results of images existing locally. - returned: always - type: list - elements: dict - sample: [ - { - "Architecture": "amd64", - "Author": "", - "Comment": "", - "Config": { - "AttachStderr": false, - "AttachStdin": false, - "AttachStdout": false, - "Cmd": [ - "/etc/docker/registry/config.yml" - ], - "Domainname": "", - "Entrypoint": [ - "/bin/registry" - ], - "Env": [ - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" - ], - "ExposedPorts": { - "5000/tcp": {} - }, - "Hostname": "e5c68db50333", - "Image": "c72dce2618dc8f7b794d2b2c2b1e64e0205ead5befc294f8111da23bd6a2c799", - "Labels": {}, - "OnBuild": [], - "OpenStdin": false, - "StdinOnce": false, - "Tty": false, - "User": "", - "Volumes": { - "/var/lib/registry": {} - }, - "WorkingDir": "" - }, - "Container": "e83a452b8fb89d78a25a6739457050131ca5c863629a47639530d9ad2008d610", - "ContainerConfig": { - "AttachStderr": false, - "AttachStdin": false, - "AttachStdout": false, - "Cmd": [ - "/bin/sh", - "-c", - '#(nop) CMD ["/etc/docker/registry/config.yml"]' - ], - "Domainname": "", - "Entrypoint": [ - "/bin/registry" - ], - "Env": [ - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" - ], - "ExposedPorts": { - "5000/tcp": {} - }, - "Hostname": "e5c68db50333", - "Image": "c72dce2618dc8f7b794d2b2c2b1e64e0205ead5befc294f8111da23bd6a2c799", - "Labels": {}, - "OnBuild": [], - "OpenStdin": false, - "StdinOnce": false, - "Tty": false, - "User": "", - "Volumes": { - "/var/lib/registry": {} - }, - "WorkingDir": "" - }, - "Created": "2016-03-08T21:08:15.399680378Z", - "DockerVersion": "1.9.1", - "GraphDriver": { - "Data": null, - "Name": "aufs" - }, - "Id": "53773d8552f07b730f3e19979e32499519807d67b344141d965463a950a66e08", - "Name": "registry:2", - "Os": "linux", - "Parent": "f0b1f729f784b755e7bf9c8c2e65d8a0a35a533769c2588f02895f6781ac0805", - "RepoDigests": [], - "RepoTags": [ - "registry:2" - ], - "Size": 0, - "VirtualSize": 165808884 - } - ] -''' + description: + - Inspection results for the selected images. + - The list only contains inspection results of images existing locally. + returned: always + type: list + elements: dict + sample: [{"Architecture": "amd64", "Author": "", "Comment": "", "Config": {"AttachStderr": false, "AttachStdin": false, + "AttachStdout": false, "Cmd": ["/etc/docker/registry/config.yml"], "Domainname": "", "Entrypoint": ["/bin/registry"], + "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"], "ExposedPorts": {"5000/tcp": {}}, + "Hostname": "e5c68db50333", "Image": "c72dce2618dc8f7b794d2b2c2b1e64e0205ead5befc294f8111da23bd6a2c799", "Labels": {}, + "OnBuild": [], "OpenStdin": false, "StdinOnce": false, "Tty": false, "User": "", "Volumes": {"/var/lib/registry": {}}, + "WorkingDir": ""}, "Container": "e83a452b8fb89d78a25a6739457050131ca5c863629a47639530d9ad2008d610", "ContainerConfig": { + "AttachStderr": false, "AttachStdin": false, "AttachStdout": false, "Cmd": ["/bin/sh", "-c", '#(nop) CMD ["/etc/docker/registry/config.yml"]'], + "Domainname": "", "Entrypoint": ["/bin/registry"], "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"], + "ExposedPorts": {"5000/tcp": {}}, "Hostname": "e5c68db50333", "Image": "c72dce2618dc8f7b794d2b2c2b1e64e0205ead5befc294f8111da23bd6a2c799", + "Labels": {}, "OnBuild": [], "OpenStdin": false, "StdinOnce": false, "Tty": false, "User": "", "Volumes": {"/var/lib/registry": {}}, + "WorkingDir": ""}, "Created": "2016-03-08T21:08:15.399680378Z", "DockerVersion": "1.9.1", "GraphDriver": {"Data": null, + "Name": "aufs"}, "Id": "53773d8552f07b730f3e19979e32499519807d67b344141d965463a950a66e08", "Name": "registry:2", + "Os": "linux", "Parent": "f0b1f729f784b755e7bf9c8c2e65d8a0a35a533769c2588f02895f6781ac0805", "RepoDigests": [], "RepoTags": [ + "registry:2"], "Size": 0, "VirtualSize": 165808884}] +""" import traceback diff --git a/plugins/modules/docker_image_load.py b/plugins/modules/docker_image_load.py index ec628d1ba..492fc14f2 100644 --- a/plugins/modules/docker_image_load.py +++ b/plugins/modules/docker_image_load.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_image_load short_description: Load docker image(s) from archives @@ -18,9 +17,7 @@ version_added: 1.3.0 description: - - Load one or multiple Docker images from a C(.tar) archive, and return information on - the loaded image(s). - + - Load one or multiple Docker images from a C(.tar) archive, and return information on the loaded image(s). extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -50,9 +47,9 @@ - module: community.docker.docker_image_push - module: community.docker.docker_image_remove - module: community.docker.docker_image_tag -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Load all image(s) from the given tar file community.docker.docker_image_load: path: /path/to/images.tar @@ -61,24 +58,24 @@ - name: Print the loaded image names ansible.builtin.debug: msg: "Loaded the following images: {{ result.image_names | join(', ') }}" -''' +""" -RETURN = ''' +RETURN = r""" image_names: - description: List of image names and IDs loaded from the archive. - returned: success - type: list - elements: str - sample: - - 'hello-world:latest' - - 'sha256:e004c2cc521c95383aebb1fb5893719aa7a8eae2e7a71f316a4410784edb00a9' + description: List of image names and IDs loaded from the archive. + returned: success + type: list + elements: str + sample: + - 'hello-world:latest' + - 'sha256:e004c2cc521c95383aebb1fb5893719aa7a8eae2e7a71f316a4410784edb00a9' images: - description: Image inspection results for the loaded images. - returned: success - type: list - elements: dict - sample: [] -''' + description: Image inspection results for the loaded images. + returned: success + type: list + elements: dict + sample: [] +""" import errno import traceback diff --git a/plugins/modules/docker_image_pull.py b/plugins/modules/docker_image_pull.py index a70942b3f..ce9c47be9 100644 --- a/plugins/modules/docker_image_pull.py +++ b/plugins/modules/docker_image_pull.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_image_pull short_description: Pull Docker images from registries @@ -18,7 +17,6 @@ description: - Pulls a Docker image from a registry. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -36,8 +34,8 @@ options: name: description: - - "Image name. Name format must be one of V(name), V(repository/name), or V(registry_server:port/name). - - The name can optionally include the tag by appending V(:tag_name), or it can contain a digest by appending V(@hash:digest)." + - Image name. Name format must be one of V(name), V(repository/name), or V(registry_server:port/name). - The name can + optionally include the tag by appending V(:tag_name), or it can contain a digest by appending V(@hash:digest). type: str required: true tag: @@ -54,8 +52,8 @@ description: - Determines when to pull an image. - If V(always), will always pull the image. - - If V(not_present), will only pull the image if no image of the name exists on the current Docker daemon, - or if O(platform) does not match. + - If V(not_present), will only pull the image if no image of the name exists on the current Docker daemon, or if O(platform) + does not match. type: str choices: - always @@ -72,23 +70,23 @@ - module: community.docker.docker_image_pull - module: community.docker.docker_image_remove - module: community.docker.docker_image_tag -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Pull an image community.docker.docker_image_pull: name: pacur/centos-7 - # Select platform for pulling. If not specified, will pull whatever docker prefers. + # Select platform for pulling. If not specified, will pull whatever docker prefers. platform: amd64 -''' +""" -RETURN = ''' +RETURN = r""" image: - description: Image inspection results for the affected image. - returned: success - type: dict - sample: {} -''' + description: Image inspection results for the affected image. + returned: success + type: dict + sample: {} +""" import traceback diff --git a/plugins/modules/docker_image_push.py b/plugins/modules/docker_image_push.py index f1474d838..e576eb8ef 100644 --- a/plugins/modules/docker_image_push.py +++ b/plugins/modules/docker_image_push.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_image_push short_description: Push Docker images to registries @@ -18,7 +17,6 @@ description: - Pushes a Docker image to a registry. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -33,8 +31,8 @@ options: name: description: - - "Image name. Name format must be one of V(name), V(repository/name), or V(registry_server:port/name). - - The name can optionally include the tag by appending V(:tag_name), or it can contain a digest by appending V(@hash:digest)." + - Image name. Name format must be one of V(name), V(repository/name), or V(registry_server:port/name). - The name can + optionally include the tag by appending V(:tag_name), or it can contain a digest by appending V(@hash:digest). type: str required: true tag: @@ -54,22 +52,22 @@ - module: community.docker.docker_image_pull - module: community.docker.docker_image_remove - module: community.docker.docker_image_tag -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Push an image community.docker.docker_image_push: name: registry.example.com:5000/repo/image tag: latest -''' +""" -RETURN = ''' +RETURN = r""" image: - description: Image inspection results for the affected image. - returned: success - type: dict - sample: {} -''' + description: Image inspection results for the affected image. + returned: success + type: dict + sample: {} +""" import traceback diff --git a/plugins/modules/docker_image_remove.py b/plugins/modules/docker_image_remove.py index da4ac2693..70efd4f4e 100644 --- a/plugins/modules/docker_image_remove.py +++ b/plugins/modules/docker_image_remove.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_image_remove short_description: Remove Docker images @@ -18,7 +17,6 @@ description: - Remove Docker images from the Docker daemon. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -33,8 +31,8 @@ options: 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)." + - '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) can also be used. type: str required: true @@ -65,38 +63,37 @@ - module: community.docker.docker_image_load - module: community.docker.docker_image_pull - module: community.docker.docker_image_tag -''' - -EXAMPLES = ''' +""" +EXAMPLES = r""" - name: Remove an image community.docker.docker_image_remove: name: pacur/centos-7 -''' +""" -RETURN = ''' +RETURN = r""" image: - description: - - Image inspection results for the affected image before removal. - - Empty if the image was not found. - returned: success - type: dict - sample: {} + description: + - Image inspection results for the affected image before removal. + - Empty if the image was not found. + returned: success + type: dict + sample: {} deleted: - description: - - The digests of the images that were deleted. - returned: success - type: list - elements: str - sample: [] + description: + - The digests of the images that were deleted. + returned: success + type: list + elements: str + sample: [] untagged: - description: - - The digests of the images that were untagged. - returned: success - type: list - elements: str - sample: [] -''' + description: + - The digests of the images that were untagged. + returned: success + type: list + elements: str + sample: [] +""" import traceback diff --git a/plugins/modules/docker_image_tag.py b/plugins/modules/docker_image_tag.py index c395a7fca..c918e3fbe 100644 --- a/plugins/modules/docker_image_tag.py +++ b/plugins/modules/docker_image_tag.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_image_tag short_description: Tag Docker images with new names and/or tags @@ -18,7 +17,6 @@ description: - This module allows to tag Docker images with new names and/or tags. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -33,8 +31,8 @@ options: 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)." + - '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) can also be used. type: str required: true @@ -47,13 +45,15 @@ repository: description: - List of new image names to tag the image as. - - Expects format C(repository:tag). If no tag is provided, will use the value of the O(tag) parameter if present, or V(latest). + - Expects format C(repository:tag). If no tag is provided, will use the value of the O(tag) parameter if present, or + V(latest). type: list elements: str required: true existing_images: description: - - Defines the behavior if the image to be tagged already exists and is another image than the one identified by O(name) and O(tag). + - Defines the behavior if the image to be tagged already exists and is another image than the one identified by O(name) + and O(tag). - If set to V(keep), the tagged image is kept. - If set to V(overwrite), the tagged image is overwritten by the specified one. type: str @@ -71,32 +71,32 @@ seealso: - module: community.docker.docker_image_push - module: community.docker.docker_image_remove -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Tag Python 3.12 image with two new names community.docker.docker_image_tag: name: python:3.12 repository: - python-3:3.12 - local-registry:5000/python-3/3.12:latest -''' +""" -RETURN = ''' +RETURN = r""" image: - description: Image inspection results for the affected image. - returned: success - type: dict - sample: {} + description: Image inspection results for the affected image. + returned: success + type: dict + sample: {} tagged_images: - description: - - A list of images that got tagged. - returned: success - type: list - elements: str - sample: - - python-3:3.12 -''' + description: + - A list of images that got tagged. + returned: success + type: list + elements: str + sample: + - python-3:3.12 +""" import traceback diff --git a/plugins/modules/docker_login.py b/plugins/modules/docker_login.py index f5398a2bd..90b814cbd 100644 --- a/plugins/modules/docker_login.py +++ b/plugins/modules/docker_login.py @@ -11,18 +11,16 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_login -short_description: Log into a Docker registry. +short_description: Log into a Docker registry description: - Provides functionality similar to the C(docker login) command. - - Authenticate with a docker registry and add the credentials to your local Docker config file respectively the - credentials store associated to the registry. Adding the credentials to the config files resp. the credential - store allows future connections to the registry using tools such as Ansible's Docker modules, the Docker CLI - and Docker SDK for Python without needing to provide credentials. + - Authenticate with a docker registry and add the credentials to your local Docker config file respectively the credentials + store associated to the registry. Adding the credentials to the config files resp. the credential store allows future + connections to the registry using tools such as Ansible's Docker modules, the Docker CLI and Docker SDK for Python without + needing to provide credentials. - Running in check mode will perform the authentication without updating the config file. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -82,10 +80,9 @@ author: - Olaf Kilian (@olsaki) - Chris Houseknecht (@chouseknecht) -''' - -EXAMPLES = ''' +""" +EXAMPLES = r""" - name: Log into DockerHub community.docker.docker_login: username: docker @@ -107,18 +104,15 @@ - name: Log out of DockerHub community.docker.docker_login: state: absent -''' +""" -RETURN = ''' +RETURN = r""" login_results: - description: Results from the login. - returned: when O(state=present) - type: dict - sample: { - "serveraddress": "localhost:5000", - "username": "testuser" - } -''' + description: Results from the login. + returned: when O(state=present) + type: dict + sample: {"serveraddress": "localhost:5000", "username": "testuser"} +""" import base64 import json diff --git a/plugins/modules/docker_network.py b/plugins/modules/docker_network.py index 9c3c777b3..48ccfdc22 100644 --- a/plugins/modules/docker_network.py +++ b/plugins/modules/docker_network.py @@ -8,13 +8,12 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: docker_network short_description: Manage Docker networks description: - Create/remove Docker networks and connect containers to them. - Performs largely the same function as the C(docker network) CLI subcommand. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -50,9 +49,9 @@ connected: description: - List of container names or container IDs to connect to a network. - - Please note that the module only makes sure that these containers are connected to the network, - but does not care about connection options. If you rely on specific IP addresses etc., use the - M(community.docker.docker_container) module to ensure your containers are correctly connected to this network. + - Please note that the module only makes sure that these containers are connected to the network, but does not care + about connection options. If you rely on specific IP addresses etc., use the M(community.docker.docker_container) + module to ensure your containers are correctly connected to this network. type: list elements: str default: [] @@ -73,10 +72,9 @@ force: description: - - With state V(present) will disconnect all containers for existing networks, delete the network and re-create the - network. - - This option is required if you have changed the IPAM or driver options - and want an existing network to be updated to use the new options. + - With state V(present) will disconnect all containers for existing networks, delete the network and re-create the network. + - This option is required if you have changed the IPAM or driver options and want an existing network to be updated + to use the new options. type: bool default: false @@ -112,9 +110,9 @@ ipam_config: 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). + - 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). type: list elements: dict suboptions: @@ -137,14 +135,11 @@ state: description: - - V(absent) deletes the network. If a network has connected containers, these will be - detached from the network. - - 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 - O(appends) option to leave existing containers connected. Use the O(force) - options to force re-creation of the network. + - V(absent) deletes the network. If a network has connected containers, these will be detached from the network. + - 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 O(appends) option to leave existing containers connected. + Use the O(force) options to force re-creation of the network. type: str default: present choices: @@ -173,18 +168,19 @@ attachable: description: - - If enabled, and the network is in the global scope, non-service containers on worker nodes will be able to connect to the network. + - If enabled, and the network is in the global scope, non-service containers on worker nodes will be able to connect + to the network. type: bool 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 (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 - network, deleting the network will fail. When network options are changed, the network has to be deleted and recreated, so this will - fail as well. - + - 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 (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 network, deleting the network will fail. When network options are changed, the network has to be + deleted and recreated, so this will fail as well. author: - "Ben Keith (@keitwb)" - "Chris Houseknecht (@chouseknecht)" @@ -192,9 +188,9 @@ requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a network community.docker.docker_network: name: network_one @@ -262,16 +258,16 @@ community.docker.docker_network: name: network_one state: absent -''' +""" -RETURN = ''' +RETURN = r""" network: - description: + description: - Network inspection results for the affected network. - returned: success - type: dict - sample: {} -''' + returned: success + type: dict + sample: {} +""" import re import traceback diff --git a/plugins/modules/docker_network_info.py b/plugins/modules/docker_network_info.py index c2c445bd1..79ca89d73 100644 --- a/plugins/modules/docker_network_info.py +++ b/plugins/modules/docker_network_info.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_network_info short_description: Retrieves facts about docker network @@ -18,7 +17,6 @@ - Retrieves facts about a docker network. - Essentially returns the output of C(docker network inspect ), similar to what M(community.docker.docker_network) returns for a non-absent network. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -38,9 +36,9 @@ requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get infos on network community.docker.docker_network_info: name: mydata @@ -54,50 +52,26 @@ ansible.builtin.debug: var: result.network when: result.exists -''' +""" -RETURN = ''' +RETURN = r""" exists: - description: - - Returns whether the network exists. - type: bool - returned: always - sample: true + description: + - Returns whether the network exists. + type: bool + returned: always + sample: true network: - description: - - Facts representing the current state of the network. Matches the docker inspection output. - - Will be V(none) if network does not exist. - returned: always - type: dict - sample: { - "Attachable": false, - "ConfigFrom": { - "Network": "" - }, - "ConfigOnly": false, - "Containers": {}, - "Created": "2018-12-07T01:47:51.250835114-06:00", - "Driver": "bridge", - "EnableIPv6": false, - "IPAM": { - "Config": [ - { - "Gateway": "192.168.96.1", - "Subnet": "192.168.96.0/20" - } - ], - "Driver": "default", - "Options": null - }, - "Id": "0856968545f22026c41c2c7c3d448319d3b4a6a03a40b148b3ac4031696d1c0a", - "Ingress": false, - "Internal": false, - "Labels": {}, - "Name": "ansible-test-f2700bba", - "Options": {}, - "Scope": "local" - } -''' + description: + - Facts representing the current state of the network. Matches the docker inspection output. + - Will be V(none) if network does not exist. + returned: always + type: dict + sample: {"Attachable": false, "ConfigFrom": {"Network": ""}, "ConfigOnly": false, "Containers": {}, "Created": "2018-12-07T01:47:51.250835114-06:00", + "Driver": "bridge", "EnableIPv6": false, "IPAM": {"Config": [{"Gateway": "192.168.96.1", "Subnet": "192.168.96.0/20"}], + "Driver": "default", "Options": null}, "Id": "0856968545f22026c41c2c7c3d448319d3b4a6a03a40b148b3ac4031696d1c0a", "Ingress": false, + "Internal": false, "Labels": {}, "Name": "ansible-test-f2700bba", "Options": {}, "Scope": "local"} +""" import traceback diff --git a/plugins/modules/docker_node.py b/plugins/modules/docker_node.py index 6ba08ed62..33dbe83b7 100644 --- a/plugins/modules/docker_node.py +++ b/plugins/modules/docker_node.py @@ -8,14 +8,12 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_node short_description: Manage Docker Swarm node description: - - Manages the Docker nodes via Swarm Manager. - - This module allows to change the node's role, its availability, and to modify, add or remove node labels. - + - Manages the Docker nodes via Swarm Manager. + - This module allows to change the node's role, its availability, and to modify, add or remove node labels. extends_documentation_fragment: - community.docker.docker - community.docker.docker.docker_py_1_documentation @@ -29,59 +27,57 @@ support: none options: - hostname: - description: - - The hostname or ID of node as registered in Swarm. - - If more than one node is registered using the same hostname the ID must be used, - otherwise module will fail. - type: str - required: true - 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 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 - 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 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 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' - choices: - - merge - - replace - labels_to_remove: - description: - - 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 O(labels_to_remove) and O(labels), then value provided in O(labels) remains - assigned to the node. - - 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: - description: Node availability to assign. If not provided then node availability remains unchanged. - choices: - - active - - pause - - drain - type: str - role: - description: Node role to assign. If not provided then node role remains unchanged. - choices: - - manager - - worker - type: str + hostname: + description: + - The hostname or ID of node as registered in Swarm. + - If more than one node is registered using the same hostname the ID must be used, otherwise module will fail. + type: str + required: true + 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 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 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 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 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' + choices: + - merge + - replace + labels_to_remove: + description: + - 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 O(labels_to_remove) and O(labels), then value provided in O(labels) remains assigned to + the node. + - 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: + description: Node availability to assign. If not provided then node availability remains unchanged. + choices: + - active + - pause + - drain + type: str + role: + description: Node role to assign. If not provided then node role remains unchanged. + choices: + - manager + - worker + type: str requirements: - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.4.0" @@ -89,10 +85,9 @@ author: - Piotr Wojciechowski (@WojciechowskiPiotr) - Thierry Bouvet (@tbouvet) +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" - name: Set node role community.docker.docker_node: hostname: mynode @@ -127,15 +122,14 @@ labels_to_remove: - key1 - key2 -''' +""" -RETURN = ''' +RETURN = r""" node: - description: Information about node after 'update' operation + description: Information about node after 'update' operation. returned: success type: dict - -''' +""" import traceback diff --git a/plugins/modules/docker_node_info.py b/plugins/modules/docker_node_info.py index c64de0f8d..f664f9be7 100644 --- a/plugins/modules/docker_node_info.py +++ b/plugins/modules/docker_node_info.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_node_info short_description: Retrieves facts about docker swarm node from Swarm Manager @@ -18,7 +17,6 @@ - Retrieves facts about a docker node. - Essentially returns the output of C(docker node inspect ). - Must be executed on a host running as Swarm Manager, otherwise the module will fail. - extends_documentation_fragment: - community.docker.docker - community.docker.docker.docker_py_1_documentation @@ -50,9 +48,9 @@ requirements: - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.4.0" - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get info on all nodes community.docker.docker_node_info: register: result @@ -73,20 +71,19 @@ community.docker.docker_node_info: self: true register: result -''' +""" -RETURN = ''' +RETURN = r""" 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 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 - type: list - elements: dict -''' + 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 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 + type: list + elements: dict +""" import traceback diff --git a/plugins/modules/docker_plugin.py b/plugins/modules/docker_plugin.py index e7242e8eb..718848f16 100644 --- a/plugins/modules/docker_plugin.py +++ b/plugins/modules/docker_plugin.py @@ -10,7 +10,7 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: docker_plugin short_description: Manage Docker plugins version_added: 1.3.0 @@ -19,7 +19,6 @@ - Performs largely the same function as the C(docker plugin) CLI subcommand. notes: - The C(--grant-all-permissions) CLI flag is true by default in this module. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -54,7 +53,7 @@ alias: description: - - Local name for plugin. + - Local name for plugin. type: str version_added: 1.8.0 @@ -82,9 +81,9 @@ requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install a plugin community.docker.docker_plugin: plugin_name: plugin_one @@ -111,21 +110,21 @@ plugin_options: IPALLOC_RANGE: "10.32.0.0/12" WEAVE_PASSWORD: "PASSWORD" -''' +""" -RETURN = ''' +RETURN = r""" plugin: - description: - - Plugin inspection results for the affected plugin. - returned: success - type: dict - sample: {} + description: + - Plugin inspection results for the affected plugin. + returned: success + type: dict + sample: {} actions: - description: - - List of actions performed during task execution. - returned: when O(state) is not V(absent) - type: list -''' + description: + - List of actions performed during task execution. + returned: when O(state) is not V(absent) + type: list +""" import traceback diff --git a/plugins/modules/docker_prune.py b/plugins/modules/docker_prune.py index d2b1e1934..7ba5c5f13 100644 --- a/plugins/modules/docker_prune.py +++ b/plugins/modules/docker_prune.py @@ -8,16 +8,14 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_prune short_description: Allows to prune various docker objects description: - - Allows to run C(docker container prune), C(docker image prune), C(docker network prune) - and C(docker volume prune) via the Docker API. - + - Allows to run C(docker container prune), C(docker image prune), C(docker network prune) and C(docker volume prune) via + the Docker API. extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -38,9 +36,9 @@ containers_filters: description: - A dictionary of filter values used for selecting containers to delete. - - "For example, C(until: 24h)." - - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/container_prune/#filtering) - for more information on possible filters. + - 'For example, C(until: 24h).' + - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/container_prune/#filtering) for + more information on possible filters. type: dict images: description: @@ -50,9 +48,9 @@ images_filters: description: - A dictionary of filter values used for selecting images to delete. - - "For example, C(dangling: true)." - - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/image_prune/#filtering) - for more information on possible filters. + - 'For example, C(dangling: true).' + - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/image_prune/#filtering) for more + information on possible filters. type: dict networks: description: @@ -62,8 +60,8 @@ networks_filters: description: - A dictionary of filter values used for selecting networks to delete. - - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/network_prune/#filtering) - for more information on possible filters. + - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/network_prune/#filtering) for + more information on possible filters. type: dict volumes: description: @@ -73,8 +71,8 @@ volumes_filters: description: - A dictionary of filter values used for selecting volumes to delete. - - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/volume_prune/#filtering) - for more information on possible filters. + - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/volume_prune/#filtering) for more + information on possible filters. type: dict builder_cache: description: @@ -90,17 +88,17 @@ builder_cache_filters: description: - A dictionary of filter values used for selecting images to delete. - - "For example, C(until: 10m)." - - See L(the API documentation,https://docs.docker.com/engine/api/v1.44/#tag/Image/operation/BuildPrune) - for more information on possible filters. + - 'For example, C(until: 10m).' + - See L(the API documentation,https://docs.docker.com/engine/api/v1.44/#tag/Image/operation/BuildPrune) for more information + on possible filters. type: dict version_added: 3.10.0 builder_cache_keep_storage: description: - - Amount of disk space to keep for cache in format C([])." - - "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." + - Amount of disk space to keep for cache in format C([]).". + - 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 version_added: 3.10.0 @@ -109,33 +107,32 @@ notes: - The module always returned C(changed=false) before community.docker 3.5.1. - requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Prune containers older than 24h community.docker.docker_prune: containers: true containers_filters: - # only consider containers created more than 24 hours ago + # only consider containers created more than 24 hours ago until: 24h - name: Prune containers with labels community.docker.docker_prune: containers: true containers_filters: - # Prune containers whose "foo" label has value "bar", and - # whose "bam" label has value "baz". If you only want to - # compare one label, you can provide it as a string instead - # of a list with one element. + # Prune containers whose "foo" label has value "bar", and + # whose "bam" label has value "baz". If you only want to + # compare one label, you can provide it as a string instead + # of a list with one element. label: - foo=bar - bam=baz - # Prune containers whose label "bar" does *not* have value - # "baz". If you want to avoid more than one label, you can - # provide a list of multiple label-value pairs. + # Prune containers whose label "bar" does *not* have value + # "baz". If you want to avoid more than one label, you can + # provide a list of multiple label-value pairs. "label!": bar=baz - name: Prune everything @@ -155,79 +152,79 @@ networks: true volumes: true builder_cache: true -''' +""" -RETURN = ''' +RETURN = r""" # containers containers: - description: - - List of IDs of deleted containers. - returned: O(containers=true) - type: list - elements: str - sample: [] + description: + - List of IDs of deleted containers. + returned: O(containers=true) + type: list + elements: str + sample: [] containers_space_reclaimed: - description: - - Amount of reclaimed disk space from container pruning in bytes. - returned: O(containers=true) - type: int - sample: 0 + description: + - Amount of reclaimed disk space from container pruning in bytes. + returned: O(containers=true) + type: int + sample: 0 # images images: - description: - - List of IDs of deleted images. - returned: O(images=true) - type: list - elements: str - sample: [] + description: + - List of IDs of deleted images. + returned: O(images=true) + type: list + elements: str + sample: [] images_space_reclaimed: - description: - - Amount of reclaimed disk space from image pruning in bytes. - returned: O(images=true) - type: int - sample: 0 + description: + - Amount of reclaimed disk space from image pruning in bytes. + returned: O(images=true) + type: int + sample: 0 # networks networks: - description: - - List of IDs of deleted networks. - returned: O(networks=true) - type: list - elements: str - sample: [] + description: + - List of IDs of deleted networks. + returned: O(networks=true) + type: list + elements: str + sample: [] # volumes volumes: - description: - - List of IDs of deleted volumes. - returned: O(volumes=true) - type: list - elements: str - sample: [] + description: + - List of IDs of deleted volumes. + returned: O(volumes=true) + type: list + elements: str + sample: [] volumes_space_reclaimed: - description: - - Amount of reclaimed disk space from volumes pruning in bytes. - returned: O(volumes=true) - type: int - sample: 0 + description: + - Amount of reclaimed disk space from volumes pruning in bytes. + returned: O(volumes=true) + type: int + sample: 0 # builder_cache builder_cache_space_reclaimed: - description: - - Amount of reclaimed disk space from builder cache pruning in bytes. - returned: O(builder_cache=true) - type: int - sample: 0 + description: + - Amount of reclaimed disk space from builder cache pruning in bytes. + returned: O(builder_cache=true) + type: int + sample: 0 builder_cache_caches_deleted: - description: - - The build caches that were deleted. - returned: O(builder_cache=true) and API version is 1.39 or later - type: list - elements: str - sample: [] - version_added: 3.10.0 -''' + description: + - The build caches that were deleted. + returned: O(builder_cache=true) and API version is 1.39 or later + type: list + elements: str + sample: [] + version_added: 3.10.0 +""" import traceback diff --git a/plugins/modules/docker_secret.py b/plugins/modules/docker_secret.py index 160d957a4..36994179b 100644 --- a/plugins/modules/docker_secret.py +++ b/plugins/modules/docker_secret.py @@ -8,19 +8,17 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_secret -short_description: Manage docker secrets. +short_description: Manage docker secrets description: - Create and remove Docker secrets in a Swarm environment. Similar to C(docker secret create) and C(docker secret rm). - - Adds to the metadata of new secrets C(ansible_key), an encrypted hash representation of the data, which is then used - in future runs to test if a secret has changed. If C(ansible_key) is not present, then a secret will not be updated - unless the O(force) option is set. + - 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 O(force) option is set. - Updates to secrets are performed by removing the secret and creating it again. - extends_documentation_fragment: - community.docker.docker - community.docker.docker.docker_py_2_documentation @@ -41,10 +39,8 @@ type: str data_is_b64: description: - - If set to V(true), the data is assumed to be Base64 encoded and will be - decoded before being used. - - To use binary O(data), it is better to keep it Base64 encoded and let it - be decoded by this option. + - If set to V(true), the data is assumed to be Base64 encoded and will be decoded before being used. + - 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: @@ -55,8 +51,9 @@ version_added: 1.10.0 labels: description: - - "A map of key:value meta data, where both key and value are expected to be strings." - - If new meta data is provided, or existing meta data is modified, the secret will be updated by removing it and creating it again. + - A map of key:value meta data, where both key and value are expected to be strings. + - If new meta data is provided, or existing meta data is modified, the secret will be updated by removing it and creating + it again. type: dict force: description: @@ -99,16 +96,15 @@ author: - Chris Houseknecht (@chouseknecht) -''' - -EXAMPLES = ''' +""" +EXAMPLES = r""" - name: Create secret foo (from a file on the control machine) community.docker.docker_secret: name: foo - # If the file is JSON or binary, Ansible might modify it (because - # it is first decoded and later re-encoded). Base64-encoding the - # file directly after reading it prevents this to happen. + # If the file is JSON or binary, Ansible might modify it (because + # it is first decoded and later re-encoded). Base64-encoding the + # file directly after reading it prevents this to happen. data: "{{ lookup('file', '/path/to/secret/file') | b64encode }}" data_is_b64: true state: present @@ -135,7 +131,7 @@ labels: bar: baz one: '1' - # Adding a new label will cause a remove/create of the secret + # Adding a new label will cause a remove/create of the secret two: '2' state: present @@ -146,7 +142,7 @@ labels: bar: baz one: '1' - # Even though 'two' is missing, there is no change to the existing secret + # Even though 'two' is missing, there is no change to the existing secret state: present - name: Update an existing label @@ -154,7 +150,7 @@ name: foo data: Goodnight everyone! labels: - bar: monkey # Changing a label will cause a remove/create of the secret + bar: monkey # Changing a label will cause a remove/create of the secret one: '1' state: present @@ -169,9 +165,9 @@ community.docker.docker_secret: name: foo state: absent -''' +""" -RETURN = ''' +RETURN = r""" secret_id: description: - The ID assigned by Docker to the secret object. @@ -185,7 +181,7 @@ type: str sample: 'awesome_secret' version_added: 2.2.0 -''' +""" import base64 import hashlib diff --git a/plugins/modules/docker_stack.py b/plugins/modules/docker_stack.py index 9848edd81..ff5f6c937 100644 --- a/plugins/modules/docker_stack.py +++ b/plugins/modules/docker_stack.py @@ -9,14 +9,12 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_stack author: "Dario Zanzico (@dariko)" short_description: docker stack module description: - - Manage docker stacks using the C(docker stack) command - on the target node (see examples). + - Manage docker stacks using the C(docker stack) command on the target node (see examples). extends_documentation_fragment: - community.docker.docker.cli_documentation - community.docker.attributes @@ -31,7 +29,7 @@ options: name: description: - - Stack name + - Stack name. type: str required: true state: @@ -44,47 +42,42 @@ - absent compose: description: - - List of compose definitions. Any element may be a string - referring to the path of the compose file on the target host + - List of compose definitions. Any element may be a string referring to the path of the compose file on the target host or the YAML contents of a compose file nested as dictionary. type: list elements: raw default: [] prune: description: - - If true will add the C(--prune) option to the C(docker stack deploy) command. - This will have docker remove the services not present in the - current stack definition. + - If true will add the C(--prune) option to the C(docker stack deploy) command. This will have docker remove the services + not present in the current stack definition. type: bool default: false detach: description: - - If V(false), the C(--detach=false) option is added to the C(docker stack deploy) command, - allowing Docker to wait for tasks to converge before exiting. + - If V(false), the C(--detach=false) option is added to the C(docker stack deploy) command, allowing Docker to wait + for tasks to converge before exiting. - If V(true) (default), Docker exits immediately instead of waiting for tasks to converge. type: bool default: true version_added: 4.1.0 with_registry_auth: description: - - If true will add the C(--with-registry-auth) option to the C(docker stack deploy) command. - This will have docker send registry authentication details to Swarm agents. + - If true will add the C(--with-registry-auth) option to the C(docker stack deploy) command. This will have docker send + registry authentication details to Swarm agents. type: bool default: false resolve_image: description: - - If set will add the C(--resolve-image) option to the C(docker stack deploy) command. - This will have docker query the registry to resolve image digest and - supported platforms. If not set, docker use "always" by default. + - If set will add the C(--resolve-image) option to the C(docker stack deploy) command. This will have docker query the + registry to resolve image digest and supported platforms. If not set, docker use "always" by default. type: str choices: ["always", "changed", "never"] absent_retries: description: - - 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. + - 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. type: int default: 0 absent_retries_interval: @@ -117,47 +110,47 @@ - Docker CLI tool C(docker) - jsondiff - pyyaml -''' +""" -RETURN = ''' +RETURN = r""" stack_spec_diff: - description: | - dictionary containing the differences between the 'Spec' field - of the stack services before and after applying the new stack - definition. - sample: > - "stack_spec_diff": - {'test_stack_test_service': {u'TaskTemplate': {u'ContainerSpec': {delete: [u'Env']}}}} - returned: on change - type: dict -''' - -EXAMPLES = ''' - - name: Deploy stack from a compose file - community.docker.docker_stack: - state: present - name: mystack - compose: - - /opt/docker-compose.yml - - - name: Deploy stack from base compose file and override the web service - community.docker.docker_stack: - state: present - name: mystack - compose: - - /opt/docker-compose.yml - - version: '3' - services: - web: - image: nginx:latest - environment: - ENVVAR: envvar - - - name: Remove stack - community.docker.docker_stack: - name: mystack - state: absent -''' + description: |- + Dictionary containing the differences between the 'Spec' field + of the stack services before and after applying the new stack + definition. + sample: > + "stack_spec_diff": + {'test_stack_test_service': {u'TaskTemplate': {u'ContainerSpec': {delete: [u'Env']}}}} + returned: on change + type: dict +""" + +EXAMPLES = r""" +- name: Deploy stack from a compose file + community.docker.docker_stack: + state: present + name: mystack + compose: + - /opt/docker-compose.yml + +- name: Deploy stack from base compose file and override the web service + community.docker.docker_stack: + state: present + name: mystack + compose: + - /opt/docker-compose.yml + - version: '3' + services: + web: + image: nginx:latest + environment: + ENVVAR: envvar + +- name: Remove stack + community.docker.docker_stack: + name: mystack + state: absent +""" import json diff --git a/plugins/modules/docker_stack_info.py b/plugins/modules/docker_stack_info.py index 21ce20dd6..1e97d0b2b 100644 --- a/plugins/modules/docker_stack_info.py +++ b/plugins/modules/docker_stack_info.py @@ -9,14 +9,12 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_stack_info author: "Jose Angel Munoz (@imjoseangel)" short_description: Return information on all docker stacks description: - - Retrieve information on docker stacks using the C(docker stack) command - on the target node (see examples). + - Retrieve information on docker stacks using the C(docker stack) command on the target node (see examples). requirements: - Docker CLI tool C(docker) extends_documentation_fragment: @@ -51,30 +49,30 @@ seealso: - module: community.docker.docker_stack_task_info description: >- - To retrieve detailed information about the services under a specific - stack use the M(community.docker.docker_stack_task_info) module. -''' + To retrieve detailed information about the services under a specific stack use the M(community.docker.docker_stack_task_info) + module. +""" -RETURN = ''' +RETURN = r""" results: - description: - - List of dictionaries containing the list of stacks on the target node - sample: - - {"name":"grafana","namespace":"default","orchestrator":"Kubernetes","services":"2"} - returned: always - type: list - elements: dict -''' - -EXAMPLES = ''' - - name: Shows stack info - community.docker.docker_stack_info: - register: result - - - name: Show results - ansible.builtin.debug: - var: result.results -''' + description: + - List of dictionaries containing the list of stacks on the target node. + sample: + - {"name": "grafana", "namespace": "default", "orchestrator": "Kubernetes", "services": "2"} + returned: always + type: list + elements: dict +""" + +EXAMPLES = r""" +- name: Shows stack info + community.docker.docker_stack_info: + register: result + +- name: Show results + ansible.builtin.debug: + var: result.results +""" import json import traceback diff --git a/plugins/modules/docker_stack_task_info.py b/plugins/modules/docker_stack_task_info.py index 72076310a..c7dc9242a 100644 --- a/plugins/modules/docker_stack_task_info.py +++ b/plugins/modules/docker_stack_task_info.py @@ -9,14 +9,12 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_stack_task_info author: "Jose Angel Munoz (@imjoseangel)" short_description: Return information of the tasks on a docker stack description: - - Retrieve information on docker stacks tasks using the C(docker stack) command - on the target node (see examples). + - Retrieve information on docker stacks tasks using the C(docker stack) command on the target node (see examples). extends_documentation_fragment: - community.docker.docker.cli_documentation - community.docker.attributes @@ -53,30 +51,30 @@ version_added: 3.6.0 requirements: - Docker CLI tool C(docker) -''' +""" -RETURN = ''' +RETURN = r""" results: - description: - - List of dictionaries containing the list of tasks associated - to a stack name. - sample: - - {"CurrentState":"Running","DesiredState":"Running","Error":"","ID":"7wqv6m02ugkw","Image":"busybox","Name":"test_stack.1","Node":"swarm","Ports":""} - returned: always - type: list - elements: dict -''' - -EXAMPLES = ''' - - name: Shows stack info - community.docker.docker_stack_task_info: - name: test_stack - register: result - - - name: Show results - ansible.builtin.debug: - var: result.results -''' + description: + - List of dictionaries containing the list of tasks associated to a stack name. + sample: + - {"CurrentState": "Running", "DesiredState": "Running", "Error": "", "ID": "7wqv6m02ugkw", "Image": "busybox", "Name": "test_stack.1", + "Node": "swarm", "Ports": ""} + returned: always + type: list + elements: dict +""" + +EXAMPLES = r""" +- name: Shows stack info + community.docker.docker_stack_task_info: + name: test_stack + register: result + +- name: Show results + ansible.builtin.debug: + var: result.results +""" import json import traceback diff --git a/plugins/modules/docker_swarm.py b/plugins/modules/docker_swarm.py index 87c8f02cb..9967c8b40 100644 --- a/plugins/modules/docker_swarm.py +++ b/plugins/modules/docker_swarm.py @@ -7,14 +7,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_swarm short_description: Manage Swarm cluster description: - Create a new Swarm cluster. - Add/Remove nodes or managers to an existing cluster. - extends_documentation_fragment: - community.docker.docker - community.docker.docker.docker_py_1_documentation @@ -31,41 +29,32 @@ advertise_addr: description: - Externally reachable address advertised to other nodes. - - This can either be an address/port combination - 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 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 is not - considered for idempotency checking. + - This can either be an address/port combination 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 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 is not considered for idempotency checking. type: str default_addr_pool: description: - Default address pool in CIDR format. - - Only used when swarm is initialised. Because of this it is not considered - for idempotency checking. + - Only used when swarm is initialised. Because of this it is not considered for idempotency checking. - Requires API version >= 1.39. type: list elements: str subnet_size: description: - Default address pool subnet mask length. - - Only used when swarm is initialised. Because of this it is not considered - for idempotency checking. + - Only used when swarm is initialised. Because of this it is not considered for idempotency checking. - Requires API version >= 1.39. type: int listen_addr: description: - Listen address used for inter-manager communication. - - This can either be an address/port combination 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 default swarm listening port - is used. - - Only used when swarm is initialised or joined. Because of this it is not - considered for idempotency checking. + - This can either be an address/port combination 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 default swarm listening port is used. + - Only used when swarm is initialised or joined. Because of this it is not considered for idempotency checking. type: str default: 0.0.0.0:2377 force: @@ -79,8 +68,8 @@ - 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. + - 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 default: present @@ -98,8 +87,8 @@ description: - Swarm token used to join a swarm cluster. - 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. + - 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: @@ -140,13 +129,11 @@ 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 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 V(7776000000000000). - # DefaultNodeCertExpiration in https://github.com/moby/moby/blob/master/vendor/github.com/moby/swarmkit/v2/ca/certificates.go#L56 type: int name: description: @@ -155,8 +142,8 @@ labels: description: - User-defined key/value metadata. - - Label operations in this module apply to the docker swarm cluster. - Use M(community.docker.docker_node) module to add/modify/remove swarm node labels. + - Label operations in this module apply to the docker swarm cluster. Use M(community.docker.docker_node) module to add/modify/remove + swarm node labels. - Requires API version >= 1.32. type: dict signing_ca_cert: @@ -173,8 +160,7 @@ type: str ca_force_rotate: description: - - An integer whose purpose is to force swarm to generate a new signing CA certificate and key, - if none have been specified. + - 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 V(0). - Requires API version >= 1.30. type: int @@ -195,10 +181,8 @@ data_path_addr: description: - Address or interface to use for data path traffic. - - 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. + - 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. - Requires API version >= 1.30. type: str version_added: 2.5.0 @@ -206,8 +190,7 @@ description: - Port to use for data path traffic. - 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. + - Only used when swarm is initialised. Because of this it is not considered for idempotency checking. - Requires API version >= 1.40. type: int version_added: 3.1.0 @@ -218,10 +201,9 @@ author: - Thierry Bouvet (@tbouvet) - Piotr Wojciechowski (@WojciechowskiPiotr) -''' - -EXAMPLES = ''' +""" +EXAMPLES = r""" - name: Init a new swarm with default parameters community.docker.docker_swarm: state: present @@ -236,7 +218,7 @@ state: join advertise_addr: 192.168.1.2 join_token: SWMTKN-1--xxxxx - remote_addrs: [ '192.168.1.1:2377' ] + remote_addrs: ['192.168.1.1:2377'] - name: Leave swarm for a node community.docker.docker_swarm: @@ -262,43 +244,40 @@ community.docker.docker_swarm: state: present data_path_port: 9789 -''' +""" -RETURN = ''' +RETURN = r""" swarm_facts: description: Information about swarm. returned: success type: dict contains: - JoinTokens: - description: Tokens to connect to the Swarm. + JoinTokens: + description: Tokens to connect to the Swarm. + returned: success + type: dict + contains: + Worker: + description: + - Token to join the cluster as a new *worker* node. + - 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: dict - contains: - Worker: - description: - - Token to join the cluster as a new *worker* node. - - "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 - Manager: - description: - - Token to join the cluster as a new *manager* node. - - "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 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 + example: SWMTKN-1--xxxxx + Manager: + description: + - Token to join the cluster as a new *manager* node. + - 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 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 actions: description: Provides the actions done on the swarm. @@ -306,8 +285,7 @@ type: list elements: str example: ['This cluster is already a swarm cluster'] - -''' +""" import json import traceback diff --git a/plugins/modules/docker_swarm_info.py b/plugins/modules/docker_swarm_info.py index 641a5f019..0f4278c25 100644 --- a/plugins/modules/docker_swarm_info.py +++ b/plugins/modules/docker_swarm_info.py @@ -8,21 +8,18 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_swarm_info -short_description: Retrieves facts about Docker Swarm cluster. +short_description: Retrieves facts about Docker Swarm cluster description: - Retrieves facts about a Docker Swarm. - Returns lists of swarm objects names for the services - nodes, services, tasks. - The output differs depending on API version available on docker host. - - Must be run on Swarm Manager node; otherwise module fails with error message. - It does return boolean flags in on both error and success which indicate whether - the docker daemon can be communicated with, whether it is in Swarm mode, and + - Must be run on Swarm Manager node; otherwise module fails with error message. It does return boolean flags in on both + error and success which indicate whether the docker daemon can be communicated with, whether it is in Swarm mode, and whether it is a Swarm Manager node. - author: - Piotr Wojciechowski (@WojciechowskiPiotr) @@ -42,9 +39,9 @@ nodes_filters: description: - A dictionary of filter values used for selecting nodes to list. - - "For example, C(name: mynode)." - - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/node_ls/#filtering) - for more information on possible filters. + - 'For example, C(name: mynode).' + - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/node_ls/#filtering) for more information + on possible filters. type: dict services: description: @@ -54,9 +51,9 @@ services_filters: description: - A dictionary of filter values used for selecting services to list. - - "For example, C(name: myservice)." - - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/service_ls/#filtering) - for more information on possible filters. + - 'For example, C(name: myservice).' + - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/service_ls/#filtering) for more + information on possible filters. type: dict tasks: description: @@ -66,9 +63,9 @@ tasks_filters: description: - A dictionary of filter values used for selecting tasks to list. - - "For example, C(node: mynode-1)." - - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/service_ps/#filtering) - for more information on possible filters. + - 'For example, C(node: mynode-1).' + - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/service_ps/#filtering) for more + information on possible filters. type: dict unlock_key: description: @@ -77,20 +74,20 @@ default: false verbose_output: description: - - 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. + - 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 this info module - for each type of the objects. + - The verbose output in this module contains only subset of information returned by this info module for each type of + the objects. type: bool default: false requirements: - - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0" - - "Docker API >= 1.25" -''' + - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0" + - "Docker API >= 1.25" +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get info on Docker Swarm community.docker.docker_swarm_info: ignore_errors: true @@ -133,66 +130,59 @@ - name: Print swarm unlock key ansible.builtin.debug: var: result.swarm_unlock_key +""" -''' - -RETURN = ''' +RETURN = r""" can_talk_to_docker: - description: - - Will be V(true) if the module can talk to the docker daemon. - returned: both on success and on error - type: bool + description: + - 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 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 + description: + - 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 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 V(true), the module will not fail. - returned: both on success and on error - type: bool + description: + - 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 V(true), the module will not fail. + returned: both on success and on error + type: bool swarm_facts: - description: - - Facts representing the basic state of the docker Swarm cluster. - - Contains tokens to connect to the Swarm - returned: always - type: dict + description: + - Facts representing the basic state of the docker Swarm cluster. + - Contains tokens to connect to the Swarm. + returned: always + type: dict swarm_unlock_key: - description: - - Contains the key needed to unlock the swarm. - returned: When O(unlock_key=true). - type: str + description: + - Contains the key needed to unlock the swarm. + 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 O(verbose_output=true). - See description for O(verbose_output). - returned: When O(nodes=true) - type: list - elements: dict + description: + - List of dict objects containing the basic information about each volume. 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 O(verbose_output=true). - See description for O(verbose_output). - returned: When O(services=true) - type: list - elements: dict + description: + - List of dict objects containing the basic information about each volume. 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 O(verbose_output=true). - See description for O(verbose_output). - returned: When O(tasks=true) - type: list - elements: dict - -''' + description: + - List of dict objects containing the basic information about each volume. 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 +""" import traceback diff --git a/plugins/modules/docker_swarm_service.py b/plugins/modules/docker_swarm_service.py index 368f5f621..b0e254f89 100644 --- a/plugins/modules/docker_swarm_service.py +++ b/plugins/modules/docker_swarm_service.py @@ -7,8 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_swarm_service author: - "Dario Zanzico (@dariko)" @@ -19,7 +18,6 @@ description: - Manages docker services via a swarm manager node. - This modules does not support updating services in a stack. - extends_documentation_fragment: - community.docker.docker - community.docker.docker.docker_py_2_documentation @@ -118,16 +116,14 @@ description: - 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 V("true")) - in order to avoid data loss. + - If passed a dictionary values which might be parsed as numbers, booleans or other types by the YAML parser must be + quoted (for example V("true")) in order to avoid data loss. - Corresponds to the C(--env) option of C(docker service create). type: raw env_files: description: - 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. + - 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 O(env), then O(env) value will override. type: list elements: path @@ -145,12 +141,12 @@ elements: str healthcheck: description: - - 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), and so on. - The supported units are V(us), V(ms), V(s), V(m) and V(h)." + - 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), and so on. The supported units are + V(us), V(ms), V(s), V(m) and V(h).' type: dict suboptions: test: @@ -181,8 +177,8 @@ type: str hosts: description: - - Dict of host-to-IP mappings, where each host name is a key in the dictionary. - Each host name will be added to the container's /etc/hosts file. + - Dict of host-to-IP mappings, where each host name is a key in the dictionary. Each host name will be added to the + container's /etc/hosts file. - Corresponds to the C(--host) option of C(docker service create). type: dict image: @@ -212,9 +208,8 @@ type: float memory: description: - - "Service memory limit in format C([]). 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)." + - Service memory limit in format C([]). 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). - V(0) equals no limit. - Omitting the unit defaults to bytes. - Corresponds to the C(--limit-memory) option of C(docker service create). @@ -222,7 +217,7 @@ type: dict logging: description: - - "Logging configuration for the service." + - Logging configuration for the service. suboptions: driver: description: @@ -314,9 +309,8 @@ type: dict tmpfs_size: description: - - "Size of the tmpfs mount in format C([]). 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)." + - Size of the tmpfs mount in format C([]). 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). - Can only be used when O(mounts[].type=tmpfs). type: str tmpfs_mode: @@ -333,10 +327,9 @@ networks: description: - List of the service networks names or dictionaries. - - 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. + - 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). type: list elements: raw @@ -361,7 +354,7 @@ description: - Maximum number of tasks per node. - Corresponds to the C(--replicas_max_per_node) option of C(docker service create). - - Requires API version >= 1.40 + - Requires API version >= 1.40. type: int version_added: 1.3.0 type: dict @@ -422,9 +415,8 @@ type: float memory: description: - - "Service memory reservation in format C([]). 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)." + - Service memory reservation in format C([]). 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). - V(0) equals no reservation. - Omitting the unit defaults to bytes. - Corresponds to the C(--reserve-memory) option of C(docker service create). @@ -452,8 +444,8 @@ delay: description: - Delay between restarts. - - "Accepts a 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)." + - 'Accepts a 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).' - Corresponds to the C(--restart-delay) option of C(docker service create). type: str max_attempts: @@ -464,8 +456,8 @@ window: description: - Restart policy evaluation window. - - "Accepts 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)." + - 'Accepts 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).' - Corresponds to the C(--restart-window) option of C(docker service create). type: str type: dict @@ -482,8 +474,8 @@ delay: description: - Delay between task rollbacks. - - "Accepts 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)." + - 'Accepts 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).' - Corresponds to the C(--rollback-delay) option of C(docker service create). - Requires API version >= 1.28. type: str @@ -499,8 +491,8 @@ monitor: description: - Duration after each task rollback to monitor for failure. - - "Accepts 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)." + - 'Accepts 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).' - Corresponds to the C(--rollback-monitor) option of C(docker service create). - Requires API version >= 1.28. type: str @@ -553,8 +545,8 @@ state: description: - 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. + - 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 choices: @@ -563,8 +555,8 @@ stop_grace_period: description: - Time to wait before force killing a container. - - "Accepts a 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)." + - 'Accepts a 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).' - Corresponds to the C(--stop-grace-period) option of C(docker service create). type: str stop_signal: @@ -589,8 +581,8 @@ delay: description: - Rolling update delay. - - "Accepts 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)." + - 'Accepts 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).' - Corresponds to the C(--update-delay) option of C(docker service create). type: str failure_action: @@ -606,8 +598,8 @@ monitor: description: - Time to monitor updated tasks for failures. - - "Accepts 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)." + - 'Accepts 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).' - Corresponds to the C(--update-monitor) option of C(docker service create). type: str max_failure_ratio: @@ -653,122 +645,37 @@ - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.0.2" - "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 O(force_update=true) to trigger the swarm to resolve a new image." -''' + - 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 O(force_update=true) to trigger the swarm to resolve a new image. +""" -RETURN = ''' +RETURN = r""" swarm_service: returned: always type: dict description: - - Dictionary of variables representing the current state of the service. - Matches the module parameters format. + - Dictionary of variables representing the current state of the service. Matches the module parameters format. - Note that facts are not part of registered vars but accessible directly. - - Note that before Ansible 2.7.9, the return variable was documented as C(ansible_swarm_service), - while the module actually returned a variable called C(ansible_docker_service). The variable - 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": [ - "3600" - ], - "cap_add": null, - "cap_drop": [ - "ALL" - ], - "command": [ - "sleep" - ], - "configs": null, - "constraints": [ - "node.role == manager", - "engine.labels.operatingsystem == ubuntu 14.04" - ], - "container_labels": null, - "sysctls": null, - "dns": null, - "dns_options": null, - "dns_search": null, - "endpoint_mode": null, - "env": [ - "ENVVAR1=envvar1", - "ENVVAR2=envvar2" - ], - "force_update": null, - "groups": null, - "healthcheck": { - "interval": 90000000000, - "retries": 3, - "start_period": 30000000000, - "test": [ - "CMD", - "curl", - "--fail", - "http://nginx.host.com" - ], - "timeout": 10000000000 - }, - "healthcheck_disabled": false, - "hostname": null, - "hosts": null, - "image": "alpine:latest@sha256:b3dbf31b77fd99d9c08f780ce6f5282aba076d70a513a8be859d8d3a4d0c92b8", - "labels": { - "com.example.department": "Finance", - "com.example.description": "Accounting webapp" - }, - "limit_cpu": 0.5, - "limit_memory": 52428800, - "log_driver": "fluentd", - "log_driver_options": { - "fluentd-address": "127.0.0.1:24224", - "fluentd-async-connect": "true", - "tag": "myservice" - }, - "mode": "replicated", - "mounts": [ - { - "readonly": false, - "source": "/tmp/", - "target": "/remote_tmp/", - "type": "bind", - "labels": null, - "propagation": null, - "no_copy": null, - "driver_config": null, - "tmpfs_size": null, - "tmpfs_mode": null - } - ], - "networks": null, - "placement_preferences": [ - { - "spread": "node.labels.mylabel" - } - ], - "publish": null, - "read_only": null, - "replicas": 1, - "replicas_max_per_node": 1, - "reserve_cpu": 0.25, - "reserve_memory": 20971520, - "restart_policy": "on-failure", - "restart_policy_attempts": 3, - "restart_policy_delay": 5000000000, - "restart_policy_window": 120000000000, - "secrets": null, - "stop_grace_period": null, - "stop_signal": null, - "tty": null, - "update_delay": 10000000000, - "update_failure_action": null, - "update_max_failure_ratio": null, - "update_monitor": null, - "update_order": "stop-first", - "update_parallelism": 2, - "user": null, - "working_dir": null - }' + - 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 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": [ "3600" ], "cap_add": null, "cap_drop": [ "ALL" ], "command": [ "sleep" ], "configs": null, "constraints": + [ "node.role == manager", "engine.labels.operatingsystem == ubuntu 14.04" ], "container_labels": null, "sysctls": null, + "dns": null, "dns_options": null, "dns_search": null, "endpoint_mode": null, "env": [ "ENVVAR1=envvar1", "ENVVAR2=envvar2" + ], "force_update": null, "groups": null, "healthcheck": { "interval": 90000000000, "retries": 3, "start_period": 30000000000, + "test": [ "CMD", "curl", "--fail", "http://nginx.host.com" ], "timeout": 10000000000 }, "healthcheck_disabled": false, + "hostname": null, "hosts": null, "image": "alpine:latest@sha256:b3dbf31b77fd99d9c08f780ce6f5282aba076d70a513a8be859d8d3a4d0c92b8", + "labels": { "com.example.department": "Finance", "com.example.description": "Accounting webapp" }, "limit_cpu": 0.5, "limit_memory": + 52428800, "log_driver": "fluentd", "log_driver_options": { "fluentd-address": "127.0.0.1:24224", "fluentd-async-connect": + "true", "tag": "myservice" }, "mode": "replicated", "mounts": [ { "readonly": false, "source": "/tmp/", "target": "/remote_tmp/", + "type": "bind", "labels": null, "propagation": null, "no_copy": null, "driver_config": null, "tmpfs_size": null, "tmpfs_mode": + null } ], "networks": null, "placement_preferences": [ { "spread": "node.labels.mylabel" } ], "publish": null, "read_only": + null, "replicas": 1, "replicas_max_per_node": 1, "reserve_cpu": 0.25, "reserve_memory": 20971520, "restart_policy": "on-failure", + "restart_policy_attempts": 3, "restart_policy_delay": 5000000000, "restart_policy_window": 120000000000, "secrets": null, + "stop_grace_period": null, "stop_signal": null, "tty": null, "update_delay": 10000000000, "update_failure_action": null, + "update_max_failure_ratio": null, "update_monitor": null, "update_order": "stop-first", "update_parallelism": 2, "user": + null, "working_dir": null }' changes: returned: always description: @@ -779,12 +686,12 @@ rebuilt: returned: always description: - - True if the service has been recreated (removed and created) + - True if the service has been recreated (removed and created). type: bool sample: true -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Set command and arguments community.docker.docker_swarm_service: name: myservice @@ -913,8 +820,8 @@ name: myservice image: nginx:1.13 healthcheck: - # Check if nginx server is healthy by curl'ing the server. - # If this fails or timeouts, the healthcheck fails. + # Check if nginx server is healthy by curl'ing the server. + # If this fails or timeouts, the healthcheck fails. test: ["CMD", "curl", "--fail", "http://nginx.host.com"] interval: 1m30s timeout: 10s @@ -936,7 +843,7 @@ community.docker.docker_swarm_service: name: myservice state: absent -''' +""" import shlex import time diff --git a/plugins/modules/docker_swarm_service_info.py b/plugins/modules/docker_swarm_service_info.py index 0a9dd56c8..3c8c95216 100644 --- a/plugins/modules/docker_swarm_service_info.py +++ b/plugins/modules/docker_swarm_service_info.py @@ -8,8 +8,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: docker_swarm_service_info short_description: Retrieves information about docker services from a Swarm Manager @@ -18,7 +17,6 @@ - Retrieves information about a docker service. - Essentially returns the output of C(docker service inspect ). - Must be executed on a host running as Swarm Manager, otherwise the module will fail. - extends_documentation_fragment: - community.docker.docker - community.docker.docker.docker_py_1_documentation @@ -39,29 +37,29 @@ requirements: - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.0.0" - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get info from a service community.docker.docker_swarm_service_info: name: myservice register: result -''' +""" -RETURN = ''' +RETURN = r""" exists: - description: - - Returns whether the service exists. - type: bool - returned: always - sample: true + description: + - Returns whether the service exists. + type: bool + returned: always + sample: true service: - description: - - A dictionary representing the current state of the service. Matches the C(docker service inspect) output. - - Will be V(none) if service does not exist. - returned: always - type: dict -''' + description: + - A dictionary representing the current state of the service. Matches the C(docker service inspect) output. + - Will be V(none) if service does not exist. + returned: always + type: dict +""" import traceback diff --git a/plugins/modules/docker_volume.py b/plugins/modules/docker_volume.py index e0d6962e7..b43919e45 100644 --- a/plugins/modules/docker_volume.py +++ b/plugins/modules/docker_volume.py @@ -9,13 +9,12 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: docker_volume short_description: Manage Docker volumes description: - Create/remove Docker volumes. - Performs largely the same function as the C(docker volume) CLI subcommand. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -44,32 +43,30 @@ driver_options: description: - - "Dictionary of volume settings. Consult docker docs for valid options and values: - U(https://docs.docker.com/engine/reference/commandline/volume_create/#driver-specific-options)." + - 'Dictionary of volume settings. Consult docker docs for valid options and values: U(https://docs.docker.com/engine/reference/commandline/volume_create/#driver-specific-options).' type: dict default: {} labels: description: - - Dictionary of label key/values to set for the volume + - Dictionary of label key/values to set for the volume. type: dict recreate: description: - - 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. + - 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 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. + - 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 choices: - - always - - never - - options-changed + - always + - never + - options-changed state: description: @@ -86,9 +83,9 @@ requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a volume community.docker.docker_volume: name: volume_one @@ -104,16 +101,16 @@ driver_options: type: btrfs device: /dev/sda2 -''' +""" -RETURN = ''' +RETURN = r""" volume: - description: + description: - Volume inspection results for the affected volume. - returned: success - type: dict - sample: {} -''' + returned: success + type: dict + sample: {} +""" import traceback diff --git a/plugins/modules/docker_volume_info.py b/plugins/modules/docker_volume_info.py index 9345d2e6e..18e7260e6 100644 --- a/plugins/modules/docker_volume_info.py +++ b/plugins/modules/docker_volume_info.py @@ -9,12 +9,11 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: docker_volume_info short_description: Retrieve facts about Docker volumes description: - Performs largely the same function as the C(docker volume inspect) CLI subcommand. - extends_documentation_fragment: - community.docker.docker.api_documentation - community.docker.attributes @@ -35,9 +34,9 @@ requirements: - "Docker API >= 1.25" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get infos on volume community.docker.docker_volume_info: name: mydata @@ -51,31 +50,24 @@ ansible.builtin.debug: var: result.volume when: result.exists -''' +""" -RETURN = ''' +RETURN = r""" exists: - description: - - Returns whether the volume exists. - type: bool - returned: always - sample: true + description: + - Returns whether the volume exists. + type: bool + returned: always + sample: true volume: - description: - - Volume inspection results for the affected volume. - - Will be V(none) if volume does not exist. - returned: success - type: dict - sample: '{ - "CreatedAt": "2018-12-09T17:43:44+01:00", - "Driver": "local", - "Labels": null, - "Mountpoint": "/var/lib/docker/volumes/ansible-test-bd3f6172/_data", - "Name": "ansible-test-bd3f6172", - "Options": {}, - "Scope": "local" - }' -''' + description: + - Volume inspection results for the affected volume. + - Will be V(none) if volume does not exist. + returned: success + type: dict + sample: '{ "CreatedAt": "2018-12-09T17:43:44+01:00", "Driver": "local", "Labels": null, "Mountpoint": "/var/lib/docker/volumes/ansible-test-bd3f6172/_data", + "Name": "ansible-test-bd3f6172", "Options": {}, "Scope": "local" }' +""" import traceback