ansible-collections/community.docker
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.docker.git synced 2026-07-29 03:46:55 +00:00
Code Packages Projects Releases Wiki Activity

Reformat documentation with 'andebox yaml-doc' (#1020)

Browse Source 
* Reformat documentation with 'andebox yaml-doc'.

* Revert unwanted changes.

* Fix too long lines.

* Fix broken quotes.

* Forgot two line breaks.
This commit is contained in:
Felix Fontein
2024-12-28 16:40:50 +01:00
committed by GitHub
parent f69536ef3b
commit 769d15de63
46 changed files with 2017 additions and 2469 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/connection/docker.py
+96 -105
View File
@@ -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
plugins/connection/docker_api.py
+91 -100
View File
@@ -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
plugins/connection/nsenter.py
+24 -27
View File
@@ -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
plugins/doc_fragments/attributes.py
+28 -28
View File
@@ -11,14 +11,14 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard documentation fragment
DOCUMENTATION = r'''
DOCUMENTATION = r"""
options: {}
attributes:
check_mode:
description: Can run in C(check_mode) and return changed status prediction without modifying target.
diff_mode:
description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
'''
check_mode:
description: Can run in C(check_mode) and return changed status prediction without modifying target.
diff_mode:
description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
"""
# Should be used together with the standard fragment
INFO_MODULE = r'''
@@ -45,23 +45,23 @@ attributes:
- docker
'''
CONN = r'''
CONN = r"""
options: {}
attributes:
become:
description: Is usable alongside C(become) keywords.
connection:
description: Uses the target's configured connection information to execute code on it.
delegation:
description: Can be used in conjunction with C(delegate_to) and related keywords.
'''
become:
description: Is usable alongside C(become) keywords.
connection:
description: Uses the target's configured connection information to execute code on it.
delegation:
description: Can be used in conjunction with C(delegate_to) and related keywords.
"""
FACTS = r'''
FACTS = r"""
options: {}
attributes:
facts:
description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
'''
facts:
description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
"""
# Should be used together with the standard fragment and the FACTS fragment
FACTS_MODULE = r'''
@@ -79,18 +79,18 @@ attributes:
support: full
'''
FILES = r'''
FILES = r"""
options: {}
attributes:
safe_file_operations:
description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
'''
safe_file_operations:
description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
"""
FLOW = r'''
FLOW = r"""
options: {}
attributes:
action:
description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
async:
description: Supports being used with the C(async) keyword.
'''
action:
description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
async:
description: Supports being used with the C(async) keyword.
"""
plugins/doc_fragments/compose_v2.py
+52 -56
View File
@@ -11,61 +11,58 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Docker doc fragment
DOCUMENTATION = r'''
DOCUMENTATION = r"""
options:
project_src:
description:
- Path to a directory containing a Compose file
(C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)).
- If O(files) is provided, will look for these files in this directory instead.
- Mutually exclusive with O(definition). One of O(project_src) and O(definition) must be provided.
type: path
project_name:
description:
- Provide a project name. If not provided, the project name is taken from the basename of O(project_src).
- Required when O(definition) is provided.
type: str
files:
description:
- List of Compose file names relative to O(project_src) to be used instead of the main Compose file
(C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)).
- Files are loaded and merged in the order given.
- Mutually exclusive with O(definition).
type: list
elements: path
version_added: 3.7.0
definition:
description:
- Compose file describing one or more services, networks and volumes.
- Mutually exclusive with O(project_src) and O(files). One of O(project_src) and O(definition) must be provided.
- If provided, PyYAML must be available to this module, and O(project_name) must be specified.
- Note that a temporary directory will be created and deleted afterwards when using this option.
type: dict
version_added: 3.9.0
env_files:
description:
- By default environment files are loaded from a C(.env) file located directly under the O(project_src) directory.
- O(env_files) can be used to specify the path of one or multiple custom environment files instead.
- The path is relative to the O(project_src) directory.
type: list
elements: path
profiles:
description:
- List of profiles to enable when starting services.
- Equivalent to C(docker compose --profile).
type: list
elements: str
check_files_existing:
description:
- If set to V(false), the module will not check whether one of the files
C(compose.yaml), C(compose.yml), C(docker-compose.yaml), or C(docker-compose.yml)
exists in O(project_src) if O(files) is not provided.
- This can be useful if environment files with C(COMPOSE_FILE) are used to configure a different
filename. The module currently does not check for C(COMPOSE_FILE) in environment files or the
current environment.
type: bool
default: true
version_added: 3.9.0
project_src:
description:
- Path to a directory containing a Compose file (C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)).
- If O(files) is provided, will look for these files in this directory instead.
- Mutually exclusive with O(definition). One of O(project_src) and O(definition) must be provided.
type: path
project_name:
description:
- Provide a project name. If not provided, the project name is taken from the basename of O(project_src).
- Required when O(definition) is provided.
type: str
files:
description:
- List of Compose file names relative to O(project_src) to be used instead of the main Compose file (C(compose.yml),
C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)).
- Files are loaded and merged in the order given.
- Mutually exclusive with O(definition).
type: list
elements: path
version_added: 3.7.0
definition:
description:
- Compose file describing one or more services, networks and volumes.
- Mutually exclusive with O(project_src) and O(files). One of O(project_src) and O(definition) must be provided.
- If provided, PyYAML must be available to this module, and O(project_name) must be specified.
- Note that a temporary directory will be created and deleted afterwards when using this option.
type: dict
version_added: 3.9.0
env_files:
description:
- By default environment files are loaded from a C(.env) file located directly under the O(project_src) directory.
- O(env_files) can be used to specify the path of one or multiple custom environment files instead.
- The path is relative to the O(project_src) directory.
type: list
elements: path
profiles:
description:
- List of profiles to enable when starting services.
- Equivalent to C(docker compose --profile).
type: list
elements: str
check_files_existing:
description:
- If set to V(false), the module will not check whether one of the files C(compose.yaml), C(compose.yml), C(docker-compose.yaml),
or C(docker-compose.yml) exists in O(project_src) if O(files) is not provided.
- This can be useful if environment files with C(COMPOSE_FILE) are used to configure a different filename. The module
currently does not check for C(COMPOSE_FILE) in environment files or the current environment.
type: bool
default: true
version_added: 3.9.0
requirements:
- "PyYAML if O(definition) is used"
notes:
@@ -73,10 +70,9 @@ notes:
The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)),
and for the main operations also no machine friendly output format. The module tries to accomodate this with various
version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin.
Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions
will change over time. New releases of the Docker compose CLI plugin can break this module at any time.
'''
"""
# The following needs to be kept in sync with the compose_v2 module utils
MINIMUM_VERSION = r'''
plugins/doc_fragments/docker.py
+96 -97
View File
@@ -11,107 +11,106 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Docker doc fragment
DOCUMENTATION = r'''
DOCUMENTATION = r"""
options:
docker_host:
description:
- The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the
TCP connection string. For example, V(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection,
the module will automatically replace C(tcp) in the connection URL with C(https).
- If the value is not specified in the task, the value of environment variable E(DOCKER_HOST) will be used
instead. If the environment variable is not set, the default value will be used.
type: str
default: unix:///var/run/docker.sock
aliases: [ docker_url ]
tls_hostname:
description:
- When verifying the authenticity of the Docker Host server, provide the expected name of the server.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME) will
be used instead. If the environment variable is not set, the default value will be used.
- Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0.
- B(Note:) this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for
Python 7.0.0 or newer will lead to an error.
type: str
api_version:
description:
- The version of the Docker API running on the Docker Host.
- Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon.
- If the value is not specified in the task, the value of environment variable E(DOCKER_API_VERSION) will be
used instead. If the environment variable is not set, the default value will be used.
type: str
default: auto
aliases: [ docker_api_version ]
timeout:
description:
- The maximum amount of time in seconds to wait on a response from the API.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT) will be used
instead. If the environment variable is not set, the default value will be used.
type: int
default: 60
ca_path:
description:
- Use a CA certificate when performing server verification by providing the path to a CA certificate file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
- This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has
been added as an alias and can still be used.
type: path
aliases: [ ca_cert, tls_ca_cert, cacert_path ]
client_cert:
description:
- Path to the client's TLS certificate file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
the file C(cert.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [ tls_client_cert, cert_path ]
client_key:
description:
- Path to the client's TLS key file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
the file C(key.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [ tls_client_key, key_path ]
tls:
description:
- Secure the connection to the API by using TLS without verifying the authenticity of the Docker host
server. Note that if O(validate_certs) is set to V(true) as well, it will take precedence.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used
instead. If the environment variable is not set, the default value will be used.
type: bool
default: false
use_ssh_client:
description:
- For SSH transports, use the C(ssh) CLI tool instead of paramiko.
- Requires Docker SDK for Python 4.4.0 or newer.
type: bool
default: false
version_added: 1.5.0
validate_certs:
description:
- Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_VERIFY) will be
used instead. If the environment variable is not set, the default value will be used.
type: bool
default: false
aliases: [ tls_verify ]
debug:
description:
- Debug mode
type: bool
default: false
docker_host:
description:
- The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection
string. For example, V(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection, the module will automatically
replace C(tcp) in the connection URL with C(https).
- If the value is not specified in the task, the value of environment variable E(DOCKER_HOST) will be used instead.
If the environment variable is not set, the default value will be used.
type: str
default: unix:///var/run/docker.sock
aliases: [docker_url]
tls_hostname:
description:
- When verifying the authenticity of the Docker Host server, provide the expected name of the server.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME) will be used instead.
If the environment variable is not set, the default value will be used.
- Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0.
- B(Note:) this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python
7.0.0 or newer will lead to an error.
type: str
api_version:
description:
- The version of the Docker API running on the Docker Host.
- Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon.
- If the value is not specified in the task, the value of environment variable E(DOCKER_API_VERSION) will be used instead.
If the environment variable is not set, the default value will be used.
type: str
default: auto
aliases: [docker_api_version]
timeout:
description:
- The maximum amount of time in seconds to wait on a response from the API.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT) will be used instead.
If the environment variable is not set, the default value will be used.
type: int
default: 60
ca_path:
description:
- Use a CA certificate when performing server verification by providing the path to a CA certificate file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, the file C(ca.pem)
from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
- This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has been added
as an alias and can still be used.
type: path
aliases: [ca_cert, tls_ca_cert, cacert_path]
client_cert:
description:
- Path to the client's TLS certificate file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, the file C(cert.pem)
from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [tls_client_cert, cert_path]
client_key:
description:
- Path to the client's TLS key file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set, the file C(key.pem)
from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
type: path
aliases: [tls_client_key, key_path]
tls:
description:
- Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that
if O(validate_certs) is set to V(true) as well, it will take precedence.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used instead. If
the environment variable is not set, the default value will be used.
type: bool
default: false
use_ssh_client:
description:
- For SSH transports, use the C(ssh) CLI tool instead of paramiko.
- Requires Docker SDK for Python 4.4.0 or newer.
type: bool
default: false
version_added: 1.5.0
validate_certs:
description:
- Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_VERIFY) will be used instead.
If the environment variable is not set, the default value will be used.
type: bool
default: false
aliases: [tls_verify]
debug:
description:
- Debug mode.
type: bool
default: false
notes:
- Connect to the Docker daemon by providing parameters with each task or by defining environment variables.
You can define E(DOCKER_HOST), E(DOCKER_TLS_HOSTNAME), E(DOCKER_API_VERSION), E(DOCKER_CERT_PATH),
E(DOCKER_TLS), E(DOCKER_TLS_VERIFY) and E(DOCKER_TIMEOUT). If you are using docker machine, run the script shipped
with the product that sets up the environment. It will set these variables for you. See
U(https://docs.docker.com/machine/reference/env/) for more details.
- When connecting to Docker daemon with TLS, you might need to install additional Python packages.
For the Docker SDK for Python, version 2.4 or newer, this can be done by installing C(docker[tls]) with M(ansible.builtin.pip).
- Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define
E(DOCKER_HOST), E(DOCKER_TLS_HOSTNAME), E(DOCKER_API_VERSION), E(DOCKER_CERT_PATH), E(DOCKER_TLS), E(DOCKER_TLS_VERIFY)
and E(DOCKER_TIMEOUT). If you are using docker machine, run the script shipped with the product that sets up the environment.
It will set these variables for you. See U(https://docs.docker.com/machine/reference/env/) for more details.
- When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for
Python, version 2.4 or newer, this can be done by installing C(docker[tls]) with M(ansible.builtin.pip).
- Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions.
In general, it will use C($HOME/.docker/config.json) if the E(DOCKER_CONFIG) environment variable is not specified,
and use C($DOCKER_CONFIG/config.json) otherwise.
'''
In general, it will use C($HOME/.docker/config.json) if the E(DOCKER_CONFIG) environment variable is not specified, and
use C($DOCKER_CONFIG/config.json) otherwise.
"""
# For plugins: allow to define common options with Ansible variables
plugins/inventory/docker_containers.py
+81 -83
View File
@@ -12,104 +12,102 @@ from __future__ import (absolute_import, division, print_function)
__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 ]
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
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
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
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
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
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(<container id>): contains the container of this ID."
- "C(<container name>): contains the container that has this name."
- "C(<container short id>): contains the containers that have this short ID (first 13 letters of ID)."
- "C(image_<image name>): contains the containers that have the image C(<image name>)."
- "C(stack_<stack name>): contains the containers that belong to the stack C(<stack name>)."
- "C(service_<service name>): contains the containers that belong to the service C(<service name>)"
- "C(<docker_host>): contains the containers which belong to the Docker daemon 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
add_legacy_groups:
description:
- 'Add the same groups as the C(docker) inventory script does. These are the following:'
- 'C(<container id>): contains the container of this ID.'
- 'C(<container name>): contains the container that has this name.'
- 'C(<container short id>): contains the containers that have this short ID (first 13 letters of ID).'
- 'C(image_<image name>): contains the containers that have the image C(<image name>).'
- 'C(stack_<stack name>): contains the containers that belong to the stack C(<stack name>).'
- 'C(service_<service name>): contains the containers that belong to the service C(<service name>).'
- 'C(<docker_host>): contains the containers which belong to the Docker daemon 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
'''
filters:
version_added: 3.5.0
"""
EXAMPLES = '''
# Minimal example using local Docker daemon
plugins/inventory/docker_machine.py
+52 -53
View File
@@ -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
plugins/inventory/docker_swarm.py
+96 -102
View File
@@ -8,109 +8,103 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
name: docker_swarm
author:
- Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com>
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) <stefan.heitmueller@gmx.com>
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
plugins/modules/current_container_facts.py
+41 -41
View File
@@ -9,25 +9,23 @@ from __future__ import absolute_import, division, print_function
__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 @@ EXAMPLES = '''
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
plugins/modules/docker_compose_v2.py
+18 -17
View File
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__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 @@ version_added: 3.6.0
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 @@ options:
- 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 @@ options:
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 @@ options:
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 @@ options:
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 @@ author:
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 @@ EXAMPLES = '''
{{ 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 @@ actions:
- Recreating
- Pulling
- Building
'''
"""
import traceback
plugins/modules/docker_compose_v2_exec.py
+28 -30
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__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 @@ version_added: 3.13.0
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 @@ options:
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 @@ options:
env:
description:
- Dictionary of environment variables with their respective values to be passed to the command ran inside the container.
- Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example 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 @@ seealso:
- 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 @@ EXAMPLES = '''
- 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
plugins/modules/docker_compose_v2_pull.py
+10 -12
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: docker_compose_v2_pull
short_description: Pull a Docker compose project
@@ -18,7 +17,6 @@ version_added: 3.6.0
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 @@ attributes:
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 @@ options:
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 @@ author:
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 @@ actions:
sample: Pulling
choices:
- Pulling
'''
"""
import traceback
plugins/modules/docker_compose_v2_run.py
+32 -32
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__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 @@ version_added: 3.13.0
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 @@ options:
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 @@ options:
env:
description:
- Dictionary of environment variables with their respective values to be passed to the command ran inside the container.
- Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example 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 @@ seealso:
- 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 @@ EXAMPLES = '''
- 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
plugins/modules/docker_config.py
+16 -20
View File
@@ -8,19 +8,17 @@ from __future__ import absolute_import, division, print_function
__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 @@ options:
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 @@ options:
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,10 +104,9 @@ requirements:
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
@@ -162,7 +158,7 @@ EXAMPLES = '''
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 @@ EXAMPLES = '''
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 @@ config_name:
type: str
sample: 'awesome_config'
version_added: 2.2.0
'''
"""
import base64
import hashlib
plugins/modules/docker_container.py
+259 -317
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_container
short_description: manage Docker containers
@@ -17,15 +16,13 @@ short_description: manage Docker containers
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 @@ attributes:
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 @@ options:
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 @@ options:
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 @@ options:
description:
- Define the default host IP to use.
- Must be an empty string, an IPv4 address, or an IPv6 address.
- With Docker 20.10.2 or newer, this should be set to an empty string (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 @@ options:
devices:
description:
- List of host device bindings to add to the container.
- "Each binding is a mapping expressed in the format C(<path_on_host>:<path_in_container>:<cgroup_permissions>)."
- Each binding is a mapping expressed in the format C(<path_on_host>:<path_in_container>:<cgroup_permissions>).
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>[<unit>])."
- "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>[<unit>]).
- 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>[<unit>])."
- "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>[<unit>]).
- 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 @@ options:
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 @@ options:
env:
description:
- Dictionary of key,value pairs.
- Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example 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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
ipc_mode:
description:
- Set the IPC mode for the container.
- Can be one of V(container:<name|id>) to reuse another container's IPC namespace or V(host) to use
the host's IPC namespace within the container.
- Can be one of V(container:<name|id>) to reuse another container's IPC namespace or V(host) to use the host's IPC namespace
within the container.
type: str
keep_volumes:
description:
@@ -507,9 +495,8 @@ options:
type: str
kernel_memory:
description:
- "Kernel memory limit in format C(<number>[<unit>]). 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>[<unit>]). 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 @@ options:
type: str
memory:
description:
- "Memory limit in format C(<number>[<unit>]). 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>[<unit>]). 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>[<unit>]). 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>[<unit>]). 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(<number>[<unit>]), 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(<number>[<unit>]), 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 @@ options:
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>[<unit>]."
- "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>[<unit>].
- 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 @@ options:
required: true
network_mode:
description:
- Connect the container to a network. Choices are V(bridge), V(host), V(none), C(container:<name|id>), C(<network_name>) or V(default).
- "Since community.docker 2.0.0, if O(networks_cli_compatible=true) and O(networks) contains at least one network,
the default value for O(network_mode) is the name of the first network in the O(networks) list. You can prevent this
by explicitly specifying a value for O(network_mode), like the default value V(default) which will be used by Docker if
O(network_mode) is not specified."
- Connect the container to a network. Choices are V(bridge), V(host), V(none), C(container:<name|id>), C(<network_name>)
or V(default).
- Since community.docker 2.0.0, if O(networks_cli_compatible=true) and O(networks) contains at least one network, the
default value for O(network_mode) is the name of the first network in the O(networks) list. You can prevent this by
explicitly specifying a value for O(network_mode), like the default value V(default) which will be used by Docker
if O(network_mode) is not specified.
type: str
userns_mode:
description:
@@ -675,10 +660,11 @@ options:
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 @@ options:
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 @@ options:
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,12 @@ options:
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 +763,35 @@ options:
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 +803,8 @@ options:
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 +825,11 @@ options:
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 +856,8 @@ options:
type: str
shm_size:
description:
- "Size of C(/dev/shm) in format C(<number>[<unit>]). 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>[<unit>]). 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 +867,26 @@ options:
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 +902,21 @@ options:
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 +935,7 @@ options:
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 +945,7 @@ options:
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 +954,12 @@ options:
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 +989,9 @@ author:
requirements:
- "Docker API >= 1.25"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a data container
community.docker.docker_container:
name: mydata
@@ -1049,25 +1018,25 @@ EXAMPLES = '''
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"
- "8080:9000"
# Publish container UDP port 9001 as host port 8081 on interface 127.0.0.1
- "127.0.0.1:8081:9001/udp"
- "127.0.0.1:8081:9001/udp"
# Publish container port 9002 as a random host port
- "9002"
- "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"
- "8000-8100:9003"
# Publish container ports 9010-9020 to host ports 7000-7010
- "7000-7010:9010-9020"
- "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:
@@ -1192,9 +1161,9 @@ EXAMPLES = '''
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 +1173,8 @@ EXAMPLES = '''
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:
@@ -1262,19 +1231,19 @@ EXAMPLES = '''
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'
# 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
# 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:
@@ -1285,56 +1254,29 @@ EXAMPLES = '''
# 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,
plugins/modules/docker_container_copy_into.py
+26 -29
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_container_copy_into
short_description: Copy a file into a Docker container
@@ -19,9 +18,8 @@ version_added: 3.4.0
description:
- Copy a file into a Docker container.
- Similar to C(docker cp).
- To copy files in a non-running container, you must provide the 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 @@ attributes:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ author:
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 @@ EXAMPLES = '''
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
plugins/modules/docker_container_exec.py
+36 -36
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_container_exec
short_description: Execute command in a docker container
@@ -18,7 +17,6 @@ version_added: 1.5.0
description:
- Executes a command in a Docker container.
extends_documentation_fragment:
- community.docker.docker.api_documentation
- community.docker.attributes
@@ -55,8 +53,7 @@ options:
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 @@ options:
env:
description:
- Dictionary of environment variables with their respective values to be passed to the command ran inside the container.
- Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example 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 @@ EXAMPLES = '''
- 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
plugins/modules/docker_container_info.py
+23 -52
View File
@@ -8,17 +8,15 @@ from __future__ import absolute_import, division, print_function
__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 <name>), similar to what M(community.docker.docker_container)
returns for a non-absent container.
- Essentially returns the output of C(docker inspect <name>), 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 @@ author:
requirements:
- "Docker API >= 1.25"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Get infos on container
community.docker.docker_container_info:
name: mydata
@@ -54,54 +52,27 @@ EXAMPLES = '''
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
plugins/modules/docker_host_info.py
+70 -79
View File
@@ -8,21 +8,18 @@ from __future__ import absolute_import, division, print_function
__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 @@ options:
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(<key>) matching when a label is present, a string
C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
- 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).'
- C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string C(<key>=<value>)
matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
- 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:
@@ -68,11 +65,11 @@ options:
images_filters:
description:
- A dictionary of filter values used for selecting images to list.
- "For example, C(dangling: true)."
- C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
- 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).'
- C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string C(<key>=<value>)
matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
- 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:
@@ -82,10 +79,10 @@ options:
networks_filters:
description:
- A dictionary of filter values used for selecting networks to list.
- C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
- See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/network_prune/#filtering)
for more information on possible filters.
- C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string C(<key>=<value>)
matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
- 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:
@@ -95,10 +92,10 @@ options:
volumes_filters:
description:
- A dictionary of filter values used for selecting volumes to list.
- C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
- See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/volume_prune/#filtering)
for more information on possible filters.
- C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string C(<key>=<value>)
matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
- See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/volume_prune/#filtering) for more
information on possible filters.
type: dict
disk_usage:
description:
@@ -108,11 +105,11 @@ options:
default: false
verbose_output:
description:
- When set to V(true) and O(networks), O(volumes), O(images), O(containers), or O(disk_usage) is set to V(true)
then output will contain verbose information about objects matching the full output of API method.
For details see the documentation of your version of Docker API at U(https://docs.docker.com/engine/api/).
- The verbose output in this module contains only subset of information returned by this module
for each type of the objects.
- When set to V(true) and O(networks), O(volumes), O(images), O(containers), or O(disk_usage) is set to V(true) then
output will contain verbose information about objects matching the full output of API method. For details see the
documentation of your version of Docker API at U(https://docs.docker.com/engine/api/).
- The verbose output in this module contains only subset of information returned by this module for each type of the
objects.
type: bool
default: false
@@ -121,9 +118,9 @@ author:
requirements:
- "Docker API >= 1.25"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Get info on docker host
community.docker.docker_host_info:
register: result
@@ -163,61 +160,55 @@ EXAMPLES = '''
- 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
plugins/modules/docker_image.py
+67 -79
View File
@@ -8,20 +8,17 @@ from __future__ import absolute_import, division, print_function
__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 @@ attributes:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
suboptions:
memory:
description:
- "Memory limit for build in format C(<number>[<unit>]). 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>[<unit>]). 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(<number>[<unit>]), 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(<number>[<unit>]), 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 @@ options:
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 @@ options:
version_added: 1.1.0
shm_size:
description:
- "Size of C(/dev/shm) in format C(<number>[<unit>]). 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>[<unit>]). 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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
- 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 @@ seealso:
- 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 @@ EXAMPLES = '''
- 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 @@ EXAMPLES = '''
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 @@ EXAMPLES = '''
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
plugins/modules/docker_image_build.py
+49 -58
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_image_build
short_description: Build Docker images using Docker buildx
@@ -18,10 +17,8 @@ version_added: 3.6.0
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 @@ attributes:
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 @@ options:
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 @@ options:
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 @@ options:
elements: str
shm_size:
description:
- "Size of C(/dev/shm) in format C(<number>[<unit>]). 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>[<unit>]). 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 @@ options:
- 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 @@ options:
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,28 @@ options:
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 +241,9 @@ author:
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 +258,22 @@ EXAMPLES = '''
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
plugins/modules/docker_image_export.py
+13 -15
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_image_export
short_description: Export (archive) Docker images
@@ -19,7 +18,6 @@ version_added: 3.7.0
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 @@ attributes:
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 @@ seealso:
- 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 @@ EXAMPLES = '''
- 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
plugins/modules/docker_image_info.py
+33 -110
View File
@@ -8,23 +8,20 @@ from __future__ import absolute_import, division, print_function
__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 @@ extends_documentation_fragment:
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 @@ requirements:
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 @@ EXAMPLES = '''
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
plugins/modules/docker_image_load.py
+19 -22
View File
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_image_load
short_description: Load docker image(s) from archives
@@ -18,9 +17,7 @@ short_description: Load docker image(s) from archives
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 @@ seealso:
- 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 @@ EXAMPLES = '''
- 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
plugins/modules/docker_image_pull.py
+14 -16
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_image_pull
short_description: Pull Docker images from registries
@@ -18,7 +17,6 @@ version_added: 3.6.0
description:
- Pulls a Docker image from a registry.
extends_documentation_fragment:
- community.docker.docker.api_documentation
- community.docker.attributes
@@ -36,8 +34,8 @@ attributes:
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 @@ options:
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 @@ seealso:
- 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.
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
plugins/modules/docker_image_push.py
+12 -14
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_image_push
short_description: Push Docker images to registries
@@ -18,7 +17,6 @@ version_added: 3.6.0
description:
- Pushes a Docker image to a registry.
extends_documentation_fragment:
- community.docker.docker.api_documentation
- community.docker.attributes
@@ -33,8 +31,8 @@ attributes:
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 @@ seealso:
- 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
plugins/modules/docker_image_remove.py
+26 -29
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_image_remove
short_description: Remove Docker images
@@ -18,7 +17,6 @@ version_added: 3.6.0
description:
- Remove Docker images from the Docker daemon.
extends_documentation_fragment:
- community.docker.docker.api_documentation
- community.docker.attributes
@@ -33,8 +31,8 @@ attributes:
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 @@ seealso:
- 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
plugins/modules/docker_image_tag.py
+23 -23
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_image_tag
short_description: Tag Docker images with new names and/or tags
@@ -18,7 +17,6 @@ version_added: 3.6.0
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 @@ attributes:
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 @@ options:
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 @@ author:
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
plugins/modules/docker_login.py
+15 -21
View File
@@ -11,18 +11,16 @@ from __future__ import absolute_import, division, print_function
__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 @@ requirements:
author:
- Olaf Kilian (@olsaki) <olaf.kilian@symanex.com>
- Chris Houseknecht (@chouseknecht)
'''
EXAMPLES = '''
"""
EXAMPLES = r"""
- name: Log into DockerHub
community.docker.docker_login:
username: docker
@@ -107,18 +104,15 @@ EXAMPLES = '''
- 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
plugins/modules/docker_network.py
+34 -38
View File
@@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function
__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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ author:
requirements:
- "Docker API >= 1.25"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a network
community.docker.docker_network:
name: network_one
@@ -262,16 +258,16 @@ EXAMPLES = '''
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
plugins/modules/docker_network_info.py
+20 -46
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_network_info
short_description: Retrieves facts about docker network
@@ -18,7 +17,6 @@ description:
- Retrieves facts about a docker network.
- Essentially returns the output of C(docker network inspect <name>), 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 @@ author:
requirements:
- "Docker API >= 1.25"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Get infos on network
community.docker.docker_network_info:
name: mydata
@@ -54,50 +52,26 @@ EXAMPLES = '''
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
plugins/modules/docker_node.py
+60 -66
View File
@@ -8,14 +8,12 @@ from __future__ import absolute_import, division, print_function
__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 @@ attributes:
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 @@ requirements:
author:
- Piotr Wojciechowski (@WojciechowskiPiotr)
- Thierry Bouvet (@tbouvet)
"""
'''
EXAMPLES = '''
EXAMPLES = r"""
- name: Set node role
community.docker.docker_node:
hostname: mynode
@@ -127,15 +122,14 @@ EXAMPLES = '''
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
plugins/modules/docker_node_info.py
+14 -17
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: docker_node_info
short_description: Retrieves facts about docker swarm node from Swarm Manager
@@ -18,7 +17,6 @@ description:
- Retrieves facts about a docker node.
- Essentially returns the output of C(docker node inspect <name>).
- 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 @@ author:
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 @@ EXAMPLES = '''
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
plugins/modules/docker_plugin.py
+16 -17
View File
@@ -10,7 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: docker_plugin
short_description: Manage Docker plugins
version_added: 1.3.0
@@ -19,7 +19,6 @@ description:
- 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 @@ options:
alias:
description:
- Local name for plugin.
- Local name for plugin.
type: str
version_added: 1.8.0
@@ -82,9 +81,9 @@ author:
requirements:
- "Docker API >= 1.25"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Install a plugin
community.docker.docker_plugin:
plugin_name: plugin_one
@@ -111,21 +110,21 @@ EXAMPLES = '''
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
plugins/modules/docker_prune.py
+76 -79
View File
@@ -8,16 +8,14 @@ from __future__ import absolute_import, division, print_function
__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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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>[<unit>])."
- "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>[<unit>]).".
- 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,12 +107,11 @@ author:
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
@@ -155,79 +152,79 @@ EXAMPLES = '''
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
plugins/modules/docker_secret.py
+16 -20
View File
@@ -8,19 +8,17 @@ from __future__ import absolute_import, division, print_function
__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 @@ options:
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 @@ options:
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,10 +96,9 @@ requirements:
author:
- Chris Houseknecht (@chouseknecht)
'''
EXAMPLES = '''
"""
EXAMPLES = r"""
- name: Create secret foo (from a file on the control machine)
community.docker.docker_secret:
name: foo
@@ -154,7 +150,7 @@ EXAMPLES = '''
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 @@ EXAMPLES = '''
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 @@ secret_name:
type: str
sample: 'awesome_secret'
version_added: 2.2.0
'''
"""
import base64
import hashlib
plugins/modules/docker_stack.py
+51 -58
View File
@@ -9,14 +9,12 @@ from __future__ import (absolute_import, division, print_function)
__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 @@ attributes:
options:
name:
description:
- Stack name
- Stack name.
type: str
required: true
state:
@@ -44,47 +42,42 @@ options:
- 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 @@ requirements:
- 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
'''
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
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: 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
'''
- name: Remove stack
community.docker.docker_stack:
name: mystack
state: absent
"""
import json
plugins/modules/docker_stack_info.py
+22 -24
View File
@@ -9,14 +9,12 @@ from __future__ import (absolute_import, division, print_function)
__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 @@ options:
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
'''
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
EXAMPLES = r"""
- name: Shows stack info
community.docker.docker_stack_info:
register: result
- name: Show results
ansible.builtin.debug:
var: result.results
'''
- name: Show results
ansible.builtin.debug:
var: result.results
"""
import json
import traceback
plugins/modules/docker_stack_task_info.py
+22 -24
View File
@@ -9,14 +9,12 @@ from __future__ import (absolute_import, division, print_function)
__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 @@ options:
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
'''
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
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
'''
- name: Show results
ansible.builtin.debug:
var: result.results
"""
import json
import traceback
plugins/modules/docker_swarm.py
+52 -74
View File
@@ -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 @@ options:
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 @@ options:
- 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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ requirements:
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 @@ EXAMPLES = '''
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 @@ EXAMPLES = '''
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 @@ actions:
type: list
elements: str
example: ['This cluster is already a swarm cluster']
'''
"""
import json
import traceback
plugins/modules/docker_swarm_info.py
+65 -75
View File
@@ -8,21 +8,18 @@ from __future__ import absolute_import, division, print_function
__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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ EXAMPLES = '''
- 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
plugins/modules/docker_swarm_service.py
+68 -161
View File
@@ -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 @@ short_description: docker swarm service
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
type: float
memory:
description:
- "Service memory limit in format C(<number>[<unit>]). 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>[<unit>]). 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 @@ options:
type: dict
logging:
description:
- "Logging configuration for the service."
- Logging configuration for the service.
suboptions:
driver:
description:
@@ -314,9 +309,8 @@ options:
type: dict
tmpfs_size:
description:
- "Size of the tmpfs mount in format C(<number>[<unit>]). 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>[<unit>]). 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 @@ options:
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 @@ options:
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 @@ options:
type: float
memory:
description:
- "Service memory reservation in format C(<number>[<unit>]). 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>[<unit>]). 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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ options:
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 @@ requirements:
- "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 @@ changes:
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
@@ -936,7 +843,7 @@ EXAMPLES = '''
community.docker.docker_swarm_service:
name: myservice
state: absent
'''
"""
import shlex
import time
plugins/modules/docker_swarm_service_info.py
+16 -18
View File
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__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 @@ description:
- Retrieves information about a docker service.
- Essentially returns the output of C(docker service inspect <name>).
- 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 @@ author:
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
plugins/modules/docker_volume.py
+21 -23
View File
@@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__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,31 @@ options:
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 the Docker documentation 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 +84,9 @@ author:
requirements:
- "Docker API >= 1.25"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a volume
community.docker.docker_volume:
name: volume_one
@@ -104,16 +102,16 @@ EXAMPLES = '''
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
plugins/modules/docker_volume_info.py
+18 -26
View File
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__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 @@ author:
requirements:
- "Docker API >= 1.25"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Get infos on volume
community.docker.docker_volume_info:
name: mydata
@@ -51,31 +50,24 @@ EXAMPLES = '''
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