ansible-collections/community.docker
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.docker.git synced 2026-07-30 12:15:45 +00:00
Code Packages Projects Releases Wiki Activity

Use semantic markup (#645)

Browse Source 
* Use semantic markup.

* Linting.

* Define docsite targets.

* Forgot one env var.

* Add array stubs.
This commit is contained in:
Felix Fontein
2023-06-22 07:01:31 +02:00
committed by GitHub
parent f94beeb027
commit 024bdec919
34 changed files with 571 additions and 547 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/modules/docker_container.py
+157 -155
View File
@@ -20,11 +20,11 @@ description:
notes:
- For most config changes, the container needs to be recreated. This means that the existing container has to be destroyed and
a new one created. This can cause unexpected data loss and downtime. You can use the I(comparisons) option to
a new one created. This can cause unexpected data loss and downtime. You can use the O(comparisons) option to
prevent this.
- If the module needs to recreate the container, it will only use the options provided to the module to create the
new container (except I(image)). Therefore, always specify B(all) options relevant to the container.
- When I(restart) is set to C(true), the module will only restart the container if no config changes are detected.
new container (except O(image)). Therefore, always specify B(all) options relevant to the container.
- When O(restart) is set to V(true), the module will only restart the container if no config changes are detected.
extends_documentation_fragment:
- community.docker.docker.api_documentation
@@ -43,7 +43,7 @@ options:
auto_remove:
description:
- Enable auto-removal of the container on daemon side when the container's process exits.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
blkio_weight:
description:
@@ -76,14 +76,14 @@ options:
version_added: 1.1.0
cleanup:
description:
- Use with I(detach=false) to remove the container after successful execution.
- Use with O(detach=false) to remove the container after successful execution.
type: bool
default: false
command:
description:
- Command to execute when the container starts. A command may be either a string or a list.
- Prior to version 2.4, strings were split on commas.
- See I(command_handling) for differences in how strings and lists are handled.
- See O(command_handling) for differences in how strings and lists are handled.
type: raw
comparisons:
description:
@@ -91,30 +91,30 @@ options:
module options to decide whether the container should be recreated / updated
or not.
- Only options which correspond to the state of a container as handled by the
Docker daemon can be specified, as well as I(networks).
- Must be a dictionary specifying for an option one of the keys C(strict), C(ignore)
and C(allow_more_present).
- If C(strict) is specified, values are tested for equality, and changes always
result in updating or restarting. If C(ignore) is specified, changes are ignored.
- C(allow_more_present) is allowed only for lists, sets and dicts. If it is
Docker daemon can be specified, as well as O(networks).
- Must be a dictionary specifying for an option one of the keys V(strict), V(ignore)
and V(allow_more_present).
- If V(strict) is specified, values are tested for equality, and changes always
result in updating or restarting. If V(ignore) is specified, changes are ignored.
- V(allow_more_present) is allowed only for lists, sets and dicts. If it is
specified for lists or sets, the container will only be updated or restarted if
the module option contains a value which is not present in the container's
options. If the option is specified for a dict, the container will only be updated
or restarted if the module option contains a key which is not present in the
container's option, or if the value of a key present differs.
- The wildcard option C(*) can be used to set one of the default values C(strict)
or C(ignore) to I(all) comparisons which are not explicitly set to other values.
- The wildcard option C(*) can be used to set one of the default values V(strict)
or V(ignore) to I(all) comparisons which are not explicitly set to other values.
- See the examples for details.
type: dict
container_default_behavior:
description:
- In older versions of this module, various module options used to have default values.
This caused problems with containers which use different values for these options.
- The default value is now C(no_defaults). To restore the old behavior, set it to
C(compatibility), which will ensure that the default values are used when the values
- The default value is now V(no_defaults). To restore the old behavior, set it to
V(compatibility), which will ensure that the default values are used when the values
are not explicitly specified by the user.
- This affects the I(auto_remove), I(detach), I(init), I(interactive), I(memory),
I(paused), I(privileged), I(read_only) and I(tty) options.
- This affects the O(auto_remove), O(detach), O(init), O(interactive), O(memory),
O(paused), O(privileged), O(read_only), and O(tty) options.
type: str
choices:
- compatibility
@@ -122,15 +122,15 @@ options:
default: no_defaults
command_handling:
description:
- The default behavior for I(command) (when provided as a list) and I(entrypoint) is to
- The default behavior for O(command) (when provided as a list) and O(entrypoint) is to
convert them to strings without considering shell quoting rules. (For comparing idempotency,
the resulting string is split considering shell quoting rules.)
- Also, setting I(command) to an empty list of string, and setting I(entrypoint) to an empty
- Also, setting O(command) to an empty list of string, and setting O(entrypoint) to an empty
list will be handled as if these options are not specified. This is different from idempotency
handling for other container-config related options.
- When this is set to C(compatibility), which was the default until community.docker 3.0.0, the
- When this is set to V(compatibility), which was the default until community.docker 3.0.0, the
current behavior will be kept.
- When this is set to C(correct), these options are kept as lists, and an empty value or empty
- When this is set to V(correct), these options are kept as lists, and an empty value or empty
list will be handled correctly for idempotency checks. This has been the default since
community.docker 3.0.0.
type: str
@@ -142,25 +142,25 @@ options:
cpu_period:
description:
- Limit CPU CFS (Completely Fair Scheduler) period.
- See I(cpus) for an easier to use alternative.
- See O(cpus) for an easier to use alternative.
type: int
cpu_quota:
description:
- Limit CPU CFS (Completely Fair Scheduler) quota.
- See I(cpus) for an easier to use alternative.
- See O(cpus) for an easier to use alternative.
type: int
cpus:
description:
- Specify how much of the available CPU resources a container can use.
- A value of C(1.5) means that at most one and a half CPU (core) will be used.
- A value of V(1.5) means that at most one and a half CPU (core) will be used.
type: float
cpuset_cpus:
description:
- CPUs in which to allow execution C(1,3) or C(1-3).
- CPUs in which to allow execution V(1,3) or V(1-3).
type: str
cpuset_mems:
description:
- Memory nodes (MEMs) in which to allow execution C(0-3) or C(0,1).
- Memory nodes (MEMs) in which to allow execution V(0-3) or V(0,1).
type: str
cpu_shares:
description:
@@ -170,19 +170,19 @@ 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 (C("")) to avoid the
- With Docker 20.10.2 or newer, this should be set to an empty string (V("")) to avoid the
port bindings without an explicit IP address to only bind to IPv4.
See U(https://github.com/ansible-collections/community.docker/issues/70) for details.
- By default, the module will try to auto-detect this value from the C(bridge) network's
C(com.docker.network.bridge.host_binding_ipv4) option. If it cannot auto-detect it, it
will fall back to C(0.0.0.0).
will fall back to V(0.0.0.0).
type: str
version_added: 1.2.0
detach:
description:
- Enable detached mode to leave the container running in background.
- If disabled, the task will reflect the status of the container run (failed if the command failed).
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(true).
- If O(container_default_behavior=compatibility), this option has a default of V(true).
type: bool
devices:
description:
@@ -204,8 +204,8 @@ options:
rate:
description:
- "Device read limit in format C(<number>[<unit>])."
- "Number is a positive integer. Unit can be one of C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- "Number is a positive integer. Unit can be one of V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- "Omitting the unit defaults to bytes."
type: str
required: true
@@ -223,8 +223,8 @@ options:
rate:
description:
- "Device read limit in format C(<number>[<unit>])."
- "Number is a positive integer. Unit can be one of C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- "Number is a positive integer. Unit can be one of V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- "Omitting the unit defaults to bytes."
type: str
required: true
@@ -281,7 +281,7 @@ options:
count:
description:
- Number or devices to request.
- Set to C(-1) to request all available devices.
- Set to V(-1) to request all available devices.
type: int
device_ids:
description:
@@ -319,19 +319,19 @@ 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 C("true")) in order to avoid data loss.
- Please note that if you are passing values in with Jinja2 templates, like C("{{ value }}"), you need to add C(| string) to prevent Ansible to
convert strings such as C("true") back to booleans. The correct way is to use C("{{ value | string }}").
- Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example V("true")) in order to avoid data loss.
- Please note that if you are passing values in with Jinja2 templates, like V("{{ value }}"), you need to add V(| string) to prevent Ansible to
convert strings such as V("true") back to booleans. The correct way is to use V("{{ value | string }}").
type: dict
env_file:
description:
- Path to a file, present on the target, containing environment variables I(FOO=BAR).
- If variable also present in I(env), then the I(env) value will override.
- Path to a file, present on the target, containing environment variables C(FOO=BAR).
- If variable also present in O(env), then the O(env) value will override.
type: path
entrypoint:
description:
- Command that overwrites the default C(ENTRYPOINT) of the image.
- See I(command_handling) for differences in how strings and lists are handled.
- See O(command_handling) for differences in how strings and lists are handled.
type: list
elements: str
etc_hosts:
@@ -367,34 +367,35 @@ options:
- Configure a check that is run to determine whether or not containers for this service are "healthy".
- "See the docs for the L(HEALTHCHECK Dockerfile instruction,https://docs.docker.com/engine/reference/builder/#healthcheck)
for details on how healthchecks work."
- "I(interval), I(timeout) and I(start_period) are specified as durations. They accept duration as a string in a format
that look like: C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)."
- "O(healthcheck.interval), O(healthcheck.timeout) and O(healthcheck.start_period) are specified as durations.
They accept duration as a string in a format that look like: V(5h34m56s), V(1m30s), and so on.
The supported units are V(us), V(ms), V(s), V(m) and V(h)."
type: dict
suboptions:
test:
description:
- Command to run to check health.
- Must be either a string or a list. If it is a list, the first item must be one of C(NONE), C(CMD) or C(CMD-SHELL).
- Must be either a string or a list. If it is a list, the first item must be one of V(NONE), V(CMD) or V(CMD-SHELL).
type: raw
interval:
description:
- Time between running the check.
- The default used by the Docker daemon is C(30s).
- The default used by the Docker daemon is V(30s).
type: str
timeout:
description:
- Maximum time to allow one check to run.
- The default used by the Docker daemon is C(30s).
- The default used by the Docker daemon is V(30s).
type: str
retries:
description:
- Consecutive number of failures needed to report unhealthy.
- The default used by the Docker daemon is C(3).
- The default used by the Docker daemon is V(3).
type: int
start_period:
description:
- Start period for the container to initialize before starting health-retries countdown.
- The default used by the Docker daemon is C(0s).
- The default used by the Docker daemon is V(0s).
type: str
hostname:
description:
@@ -402,30 +403,30 @@ options:
type: str
ignore_image:
description:
- When I(state) is C(present) or C(started), the module compares the configuration of an existing
- When O(state) is V(present) or V(started), the module compares the configuration of an existing
container to requested configuration. The evaluation includes the image version. If the image
version in the registry does not match the container, the container will be recreated. You can
stop this behavior by setting I(ignore_image) to C(true).
stop this behavior by setting O(ignore_image) to V(true).
- "B(Warning:) This option is ignored if C(image: ignore) or C(*: ignore) is specified in the
I(comparisons) option."
O(comparisons) option."
- "This option is deprecated since community.docker 3.2.0 and will be removed in community.docker 4.0.0.
Use C(image: ignore) in I(comparisons) instead of I(ignore_image=true)."
Use C(image: ignore) in O(comparisons) instead of O(ignore_image=true)."
type: bool
default: false
image:
description:
- Repository path and tag used to create the container. If an image is not found or pull is true, the image
will be pulled from the registry. If no tag is included, C(latest) will be used.
will be pulled from the registry. If no tag is included, V(latest) will be used.
- Can also be an image ID. If this is the case, the image is assumed to be available locally.
The I(pull) option is ignored for this case.
The O(pull) option is ignored for this case.
type: str
image_comparison:
description:
- Determines which image to use for idempotency checks that depend on image parameters.
- The default, C(desired-image), will use the image that is provided to the module via the I(image) parameter.
- C(current-image) will use the image that the container is currently using, if the container exists. It
- The default, V(desired-image), will use the image that is provided to the module via the O(image) parameter.
- V(current-image) will use the image that the container is currently using, if the container exists. It
falls back to the image that is provided in case the container does not yet exist.
- This affects the I(env), I(env_file), I(exposed_ports), I(labels), and I(volumes) options.
- This affects the O(env), O(env_file), O(exposed_ports), O(labels), and O(volumes) options.
type: str
choices:
- desired-image
@@ -435,13 +436,13 @@ options:
image_label_mismatch:
description:
- How to handle labels inherited from the image that are not set explicitly.
- When C(ignore), labels that are present in the image but not specified in I(labels) will be
ignored. This is useful to avoid having to specify the image labels in I(labels) while keeping
labels I(comparisons) C(strict).
- When C(fail), if there are labels present in the image which are not set from I(labels), the
- When V(ignore), labels that are present in the image but not specified in O(labels) will be
ignored. This is useful to avoid having to specify the image labels in O(labels) while keeping
labels O(comparisons) V(strict).
- When V(fail), if there are labels present in the image which are not set from O(labels), the
module will fail. This prevents introducing unexpected labels from the base image.
- "B(Warning:) This option is ignored unless C(labels: strict) or C(*: strict) is specified in
the I(comparisons) option."
the O(comparisons) option."
type: str
choices:
- 'ignore'
@@ -452,9 +453,9 @@ options:
description:
- Determines what the module does if the image matches, but the image name in the container's configuration
does not match the image name provided to the module.
- "This is ignored if C(image: ignore) is set in I(comparisons)."
- If set to C(recreate) the container will be recreated.
- If set to C(ignore) the container will not be recreated because of this. It might still get recreated for other reasons.
- "This is ignored if C(image: ignore) is set in O(comparisons)."
- If set to V(recreate) the container will be recreated.
- If set to V(ignore) the container will not be recreated because of this. It might still get recreated for other reasons.
This has been the default behavior of the module for a long time, but might not be what users expect.
type: str
choices:
@@ -465,17 +466,17 @@ options:
init:
description:
- Run an init inside the container that forwards signals and reaps processes.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
interactive:
description:
- Keep stdin open after a container is launched, even if not attached.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
ipc_mode:
description:
- Set the IPC mode for the container.
- Can be one of C(container:<name|id>) to reuse another container's IPC namespace or C(host) to use
- 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:
@@ -490,8 +491,8 @@ options:
kernel_memory:
description:
- "Kernel memory limit in format C(<number>[<unit>]). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte). Minimum is C(4M)."
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte). Minimum is V(4M)."
- Omitting the unit defaults to bytes.
type: str
labels:
@@ -506,42 +507,43 @@ options:
elements: str
log_driver:
description:
- Specify the logging driver. Docker uses C(json-file) by default.
- See L(here,https://docs.docker.com/config/containers/logging/configure/) for possible choices.
- Specify the logging driver. Docker uses V(json-file) by default.
- See L(the Docker logging configuration documentation,https://docs.docker.com/config/containers/logging/configure/)
for possible choices.
type: str
log_options:
description:
- Dictionary of options specific to the chosen I(log_driver).
- Dictionary of options specific to the chosen O(log_driver).
- See U(https://docs.docker.com/engine/admin/logging/overview/) for details.
- I(log_driver) needs to be specified for I(log_options) to take effect, even if using the default C(json-file) driver.
- O(log_driver) needs to be specified for O(log_options) to take effect, even if using the default V(json-file) driver.
type: dict
aliases:
- log_opt
mac_address:
description:
- Container MAC address (for example, C(92:d0:c6:0a:29:33)).
- Container MAC address (for example, V(92:d0:c6:0a:29:33)).
type: str
memory:
description:
- "Memory limit in format C(<number>[<unit>]). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- Omitting the unit defaults to bytes.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C("0").
- If O(container_default_behavior=compatibility), this option has a default of V("0").
type: str
memory_reservation:
description:
- "Memory soft limit in format C(<number>[<unit>]). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- Omitting the unit defaults to bytes.
type: str
memory_swap:
description:
- "Total memory limit (memory + swap) in format C(<number>[<unit>]), or
the special values C(unlimited) or C(-1) for unlimited swap usage.
Number is a positive integer. Unit can be C(B) (byte), C(K) (kibibyte, 1024B),
C(M) (mebibyte), C(G) (gibibyte), C(T) (tebibyte), or C(P) (pebibyte)."
the special values V(unlimited) or V(-1) for unlimited swap usage.
Number is a positive integer. Unit can be V(B) (byte), V(K) (kibibyte, 1024B),
V(M) (mebibyte), V(G) (gibibyte), V(T) (tebibyte), or V(P) (pebibyte)."
- Omitting the unit defaults to bytes.
type: str
memory_swappiness:
@@ -554,7 +556,7 @@ options:
type: list
elements: dict
description:
- Specification for mounts to be added to the container. More powerful alternative to I(volumes).
- Specification for mounts to be added to the container. More powerful alternative to O(volumes).
suboptions:
target:
description:
@@ -565,12 +567,12 @@ options:
description:
- Mount source.
- For example, this can be a volume name or a host path.
- If not supplied when I(type=volume) an anonymous volume will be created.
- If not supplied when O(mounts[].type=volume) an anonymous volume will be created.
type: str
type:
description:
- The mount type.
- Note that C(npipe) is only supported by Docker for Windows.
- Note that V(npipe) is only supported by Docker for Windows.
type: str
choices:
- bind
@@ -593,7 +595,7 @@ options:
- delegated
propagation:
description:
- Propagation mode. Only valid for the C(bind) type.
- Propagation mode. Only valid for the V(bind) type.
type: str
choices:
- private
@@ -604,16 +606,16 @@ options:
- rslave
no_copy:
description:
- False if the volume should be populated with the data from the target. Only valid for the C(volume) type.
- The default value is C(false).
- False if the volume should be populated with the data from the target. Only valid for the V(volume) type.
- The default value is V(false).
type: bool
labels:
description:
- User-defined name and labels for the volume. Only valid for the C(volume) type.
- User-defined name and labels for the volume. Only valid for the V(volume) type.
type: dict
volume_driver:
description:
- Specify the volume driver. Only valid for the C(volume) type.
- Specify the volume driver. Only valid for the V(volume) type.
- See L(here,https://docs.docker.com/storage/volumes/#use-a-volume-driver) for details.
type: str
volume_options:
@@ -624,8 +626,8 @@ options:
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 C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- "Number is a positive integer. Unit can be one of V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- "Omitting the unit defaults to bytes."
type: str
tmpfs_mode:
@@ -640,24 +642,24 @@ options:
required: true
network_mode:
description:
- Connect the container to a network. Choices are C(bridge), C(host), C(none), C(container:<name|id>), C(<network_name>) or C(default).
- "Since community.docker 2.0.0, if I(networks_cli_compatible) is C(true) and I(networks) contains at least one network,
the default value for I(network_mode) is the name of the first network in the I(networks) list. You can prevent this
by explicitly specifying a value for I(network_mode), like the default value C(default) which will be used by Docker if
I(network_mode) is not specified."
- Connect the container to a network. Choices are V(bridge), V(host), V(none), C(container:<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:
- Set the user namespace mode for the container. Currently, the only valid value are C(host) and the empty string.
- Set the user namespace mode for the container. Currently, the only valid value are V(host) and the empty string (V("")).
type: str
networks:
description:
- List of networks the container belongs to.
- For examples of the data structure and usage see EXAMPLES below.
- "To remove a container from one or more networks, use C(networks: strict) in the I(comparisons) option."
- "If I(networks_cli_compatible) is set to C(false), this will not remove the default network if I(networks) is specified.
This is different from the behavior of C(docker run ...). You need to explicitly use C(networks: strict) in I(comparisons)
to enforce the removal of the default network (and all other networks not explicitly mentioned in I(networks)) in that case."
- "To remove a container from one or more networks, use C(networks: strict) in the O(comparisons) option."
- "If O(networks_cli_compatible=false), this will not remove the default network if O(networks) is specified.
This is different from the behavior of C(docker run ...). You need to explicitly use C(networks: strict) in O(comparisons)
to enforce the removal of the default network (and all other networks not explicitly mentioned in O(networks)) in that case."
type: list
elements: dict
suboptions:
@@ -687,15 +689,15 @@ options:
elements: str
networks_cli_compatible:
description:
- "If I(networks_cli_compatible) is set to C(true) (default), this module will behave as
C(docker run --network) and will B(not) add the default network if I(networks) is
specified. If I(networks) is not specified, the default network will be attached."
- "When I(networks_cli_compatible) is set to C(false) and networks are provided to the module
via the I(networks) option, the module behaves differently than C(docker run --network):
- "If O(networks_cli_compatible=true) (default), this module will behave as
C(docker run --network) and will B(not) add the default network if O(networks) is
specified. If O(networks) is not specified, the default network will be attached."
- "When O(networks_cli_compatible=false) and networks are provided to the module
via the O(networks) option, the module behaves differently than C(docker run --network):
C(docker run --network other) will create a container with network C(other) attached,
but the default network not attached. This module with I(networks: {name: other}) will
but the default network not attached. This module with O(networks) set to C({name: other}) will
create a container with both C(default) and C(other) attached. If C(networks: strict)
or C(*: strict) is set in I(comparisons), the C(default) network will be removed afterwards."
or C(*: strict) is set in O(comparisons), the C(default) network will be removed afterwards."
type: bool
default: true
oom_killer:
@@ -710,13 +712,13 @@ options:
output_logs:
description:
- If set to true, output of the container command will be printed.
- Only effective when I(log_driver) is set to C(json-file), C(journald), or C(local).
- Only effective when O(log_driver) is set to V(json-file), V(journald), or V(local).
type: bool
default: false
paused:
description:
- Use with the started state to pause running processes inside the container.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
pid_mode:
description:
@@ -725,31 +727,31 @@ options:
pids_limit:
description:
- Set PIDs limit for the container. It accepts an integer value.
- Set C(-1) for unlimited PIDs.
- Set V(-1) for unlimited PIDs.
type: int
platform:
description:
- Platform for the container in the format C(os[/arch[/variant]]).
- "Please note that inspecting the container does not always return the exact platform string used to
create the container. This can cause idempotency to break for this module. Use the I(comparisons) option
create the container. This can cause idempotency to break for this module. Use the O(comparisons) option
with C(platform: ignore) to prevent accidental recreation of the container due to this."
type: str
version_added: 3.0.0
privileged:
description:
- Give extended privileges to the container.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
publish_all_ports:
description:
- Publish all ports to the host.
- Any specified port bindings from I(published_ports) will remain intact when C(true).
- Any specified port bindings from O(published_ports) will remain intact when V(true).
type: bool
version_added: 1.8.0
published_ports:
description:
- List of ports to publish from the container to the host.
- "Use docker CLI syntax: C(8000), C(9000:8000), or C(0.0.0.0:9000:8000), where 8000 is a
- "Use docker CLI syntax: V(8000), V(9000:8000), or V(0.0.0.0:9000:8000), where 8000 is a
container port, 9000 is a host port, and 0.0.0.0 is a host interface."
- Port ranges can be used for source and destination ports. If two ranges with
different lengths are specified, the shorter range will be used.
@@ -757,16 +759,16 @@ options:
to the first port of the destination range, but to a free port in that range. This is the
same behavior as for C(docker) command line utility.
- "Bind addresses must be either IPv4 or IPv6 addresses. Hostnames are B(not) allowed. This
is different from the C(docker) command line utility. Use the R(dig lookup,ansible_collections.community.general.dig_lookup)
is different from the C(docker) command line utility. Use the P(community.general.dig#lookup) lookup
to resolve hostnames."
- If I(networks) parameter is provided, will inspect each network to see if there exists
- If O(networks) parameter is provided, will inspect each network to see if there exists
a bridge network with optional parameter C(com.docker.network.bridge.host_binding_ipv4).
If such a network is found, then published ports where no host IP address is specified
will be bound to the host IP pointed to by C(com.docker.network.bridge.host_binding_ipv4).
Note that the first bridge network with a C(com.docker.network.bridge.host_binding_ipv4)
value encountered in the list of I(networks) is the one that will be used.
- The value C(all) was allowed in earlier versions of this module. Support for it was removed in
community.docker 3.0.0. Use the I(publish_all_ports) option instead.
value encountered in the list of O(networks) is the one that will be used.
- The value V(all) was allowed in earlier versions of this module. Support for it was removed in
community.docker 3.0.0. Use the O(publish_all_ports) option instead.
type: list
elements: str
aliases:
@@ -781,17 +783,17 @@ options:
default: false
purge_networks:
description:
- Remove the container from ALL networks not included in I(networks) parameter.
- Any default networks such as C(bridge), if not found in I(networks), will be removed as well.
- Remove the container from ALL networks not included in O(networks) parameter.
- Any default networks such as C(bridge), if not found in O(networks), will be removed as well.
- "This option is deprecated since community.docker 3.2.0 and will be removed in community.docker 4.0.0.
Use C(networks: strict) in I(comparisons) instead of I(purge_networks=true) and make sure that
I(networks) is specified. If you want to remove all networks, specify I(networks: [])."
Use C(networks: strict) in O(comparisons) instead of O(purge_networks=true) and make sure that
O(networks) is specified. If you want to remove all networks, specify O(networks) as C([])."
type: bool
default: false
read_only:
description:
- Mount the container's root file system as read-only.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
recreate:
description:
@@ -816,7 +818,7 @@ options:
restart_policy:
description:
- Container restart policy.
- Place quotes around C(no) option.
- Place quotes around V(no) option.
type: str
choices:
- 'no'
@@ -834,9 +836,9 @@ options:
shm_size:
description:
- "Size of C(/dev/shm) in format C(<number>[<unit>]). Number is positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte)."
- Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses C(64M).
Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte),
V(T) (tebibyte), or V(P) (pebibyte)."
- Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses V(64M).
type: str
security_opts:
description:
@@ -845,22 +847,22 @@ options:
elements: str
state:
description:
- 'C(absent) - A container matching the specified name will be stopped and removed. Use I(force_kill) to kill the container
rather than stopping it. Use I(keep_volumes) to retain anonymous volumes associated with the removed container.'
- 'C(present) - Asserts the existence of a container matching the name and any provided configuration parameters. If no
- 'V(absent) - A container matching the specified name will be stopped and removed. Use O(force_kill) to kill the container
rather than stopping it. Use O(keep_volumes) to retain anonymous volumes associated with the removed container.'
- 'V(present) - Asserts the existence of a container matching the name and any provided configuration parameters. If no
container matches the name, a container will be created. If a container matches the name but the provided configuration
does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and re-created
with the requested config.'
- 'C(started) - Asserts that the container is first C(present), and then if the container is not running moves it to a running
state. Use I(restart) to force a matching container to be stopped and restarted.'
- 'C(stopped) - Asserts that the container is first C(present), and then if the container is running moves it to a stopped
- 'V(started) - Asserts that the container is first V(present), and then if the container is not running moves it to a running
state. Use O(restart) to force a matching container to be stopped and restarted.'
- 'V(stopped) - Asserts that the container is first V(present), and then if the container is running moves it to a stopped
state.'
- "To control what will be taken into account when comparing configuration, see the I(comparisons) option. To avoid that the
image version will be taken into account, you can also use the C(image: ignore) in the I(comparisons) option."
- Use the I(recreate) option to always force re-creation of a matching container, even if it is running.
- If the container should be killed instead of stopped in case it needs to be stopped for recreation, or because I(state) is
C(stopped), please use the I(force_kill) option. Use I(keep_volumes) to retain anonymous volumes associated with a removed container.
- Use I(keep_volumes) to retain anonymous volumes associated with a removed container.
- "To control what will be taken into account when comparing configuration, see the O(comparisons) option. To avoid that the
image version will be taken into account, you can also use the V(image: ignore) in the O(comparisons) option."
- Use the O(recreate) option to always force re-creation of a matching container, even if it is running.
- If the container should be killed instead of stopped in case it needs to be stopped for recreation, or because O(state) is
V(stopped), please use the O(force_kill) option. Use O(keep_volumes) to retain anonymous volumes associated with a removed container.
- Use O(keep_volumes) to retain anonymous volumes associated with a removed container.
type: str
default: started
choices:
@@ -896,11 +898,11 @@ options:
tty:
description:
- Allocate a pseudo-TTY.
- If I(container_default_behavior) is set to C(compatibility), this option has a default of C(false).
- If O(container_default_behavior=compatibility), this option has a default of V(false).
type: bool
ulimits:
description:
- "List of ulimit options. A ulimit is specified as C(nofile:262144:262144)."
- "List of ulimit options. A ulimit is specified as V(nofile:262144:262144)."
type: list
elements: str
sysctls:
@@ -920,12 +922,12 @@ options:
description:
- List of volumes to mount within the container.
- "Use docker CLI-style syntax: C(/host:/container[:mode])"
- "Mount modes can be a comma-separated list of various modes such as C(ro), C(rw), C(consistent),
C(delegated), C(cached), C(rprivate), C(private), C(rshared), C(shared), C(rslave), C(slave), and
C(nocopy). Note that the docker daemon might not support all modes and combinations of such modes."
- SELinux hosts can additionally use C(z) or C(Z) to use a shared or private label for the volume.
- "Note that Ansible 2.7 and earlier only supported one mode, which had to be one of C(ro), C(rw),
C(z), and C(Z)."
- "Mount modes can be a comma-separated list of various modes such as V(ro), V(rw), V(consistent),
V(delegated), V(cached), V(rprivate), V(private), V(rshared), V(shared), V(rslave), V(slave), and
V(nocopy). Note that the docker daemon might not support all modes and combinations of such modes."
- SELinux hosts can additionally use V(z) or V(Z) to use a shared or private label for the volume.
- "Note that Ansible 2.7 and earlier only supported one mode, which had to be one of V(ro), V(rw),
V(z), and V(Z)."
type: list
elements: str
volume_driver:
@@ -1225,9 +1227,9 @@ RETURN = '''
container:
description:
- Facts representing the current state of the container. Matches the docker inspection output.
- Empty if I(state) is C(absent).
- If I(detach=false), will include C(Output) attribute containing any output from container run.
returned: success; or when I(state=started) and I(detach=false), and when waiting for the container result did not fail
- Empty if O(state=absent).
- If O(detach=false), will include C(Output) attribute containing any output from container run.
returned: success; or when O(state=started) and O(detach=false), and when waiting for the container result did not fail
type: dict
sample: '{
"AppArmorProfile": "",
@@ -1265,7 +1267,7 @@ 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 I(state=started) and I(detach=false), and when waiting for the container result did not fail
returned: when O(state=started) and O(detach=false), and when waiting for the container result did not fail
type: int
sample: 0
'''