ansible-collections/community.docker
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.docker.git synced 2026-07-29 11:55:04 +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/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,