ansible-collections/community.docker
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.docker.git synced 2025-12-15 19:42:06 +00:00
Code Packages Projects Releases Wiki Activity

Improve documentation (#278)

Browse Source 
* Improve documentation.

* More fixes.
This commit is contained in:
Felix Fontein 2022-01-09 14:52:44 +01:00 committed by GitHub
parent 9ca2c61848
commit 3d20ba1bc2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 40 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
plugins/inventory/docker_machine.py
View File

@ -42,11 +42,14 @@ DOCUMENTATION = '''
- skip
default: require
running_required:
description: when true, hosts which Docker Machine indicates are in a state other than C(running) will be skipped.
description:
- When C(true), hosts which Docker Machine indicates are in a state other than C(running) will be skipped.
type: bool
default: yes
verbose_output:
description: when true, include all available nodes metadata (e.g. Image, Region, Size) as a JSON object named C(docker_machine_node_attributes).
description:
- When C(true), include all available nodes metadata (for exmaple C(Image), C(Region), C(Size)) as a JSON object
named C(docker_machine_node_attributes).
type: bool
default: yes
'''
@ -56,7 +59,7 @@ EXAMPLES = '''
plugin: community.docker.docker_machine
# Example using constructed features to create a group per Docker Machine driver
# (https://docs.docker.com/machine/drivers/), e.g.:
# (https://docs.docker.com/machine/drivers/), for example:
# $ docker-machine create --driver digitalocean ... mymachine
# $ ansible-inventory -i ./path/to/docker-machine.yml --host=mymachine
# {

8
plugins/inventory/docker_swarm.py
View File

@ -38,7 +38,7 @@ DOCUMENTATION = '''
required: true
aliases: [ docker_url ]
verbose_output:
description: Toggle to (not) include all available nodes metadata (e.g. C(Platform), C(Architecture), C(OS),
description: Toggle to (not) include all available nodes metadata (for example C(Platform), C(Architecture), C(OS),
C(EngineVersion))
type: bool
default: yes
@ -132,14 +132,14 @@ plugin: community.docker.docker_swarm
docker_host: tcp://my-docker-host:2375
strict: False
keyed_groups:
# add e.g. x86_64 hosts to an arch_x86_64 group
# add for example x86_64 hosts to an arch_x86_64 group
- prefix: arch
key: 'Description.Platform.Architecture'
# add e.g. linux hosts to an os_linux group
# add for example linux hosts to an os_linux group
- prefix: os
key: 'Description.Platform.OS'
# create a group per node label
# e.g. a node labeled w/ "production" ends up in group "label_production"
# for exomple a node labeled w/ "production" ends up in group "label_production"
# hint: labels containing special characters will be converted to safe names
- key: 'Spec.Labels'
prefix: label

21
plugins/modules/docker_container.py
View File

@ -19,11 +19,11 @@ description:
notes:
- For most config changes, the container needs to be recreated, i.e. the existing container has to be destroyed and
- 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
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 *all* options relevant to the container.
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.
options:
@ -81,7 +81,7 @@ options:
or restarted if the module option contains a key which isn't 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 *all* comparisons which are not explicitly set to other values.
or C(ignore) to I(all) comparisons which are not explicitly set to other values.
- See the examples for details.
type: dict
container_default_behavior:
@ -296,7 +296,7 @@ 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 (e.g. C("true")) in order to avoid data loss.
- 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 }}").
type: dict
@ -383,7 +383,7 @@ options:
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).
- "*Warning:* This option is ignored if C(image: ignore) or C(*: ignore) is specified in the
- "B(Warning:) This option is ignored if C(image: ignore) or C(*: ignore) is specified in the
I(comparisons) option."
type: bool
default: no
@ -451,7 +451,7 @@ options:
- log_opt
mac_address:
description:
- Container MAC address (e.g. 92:d0:c6:0a:29:33).
- Container MAC address (for example, C(92:d0:c6:0a:29:33)).
type: str
memory:
description:
@ -495,7 +495,8 @@ options:
required: true
source:
description:
- Mount source (e.g. a volume name or a host path).
- 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.
type: str
type:
@ -619,7 +620,7 @@ options:
networks_cli_compatible:
description:
- "If I(networks_cli_compatible) is set to C(yes) (default), this module will behave as
C(docker run --network) and will *not* add the default network if I(networks) is
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(no) and networks are provided to the module
via the I(networks) option, the module behaves differently than C(docker run --network):
@ -681,7 +682,7 @@ options:
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 *not* allowed. This
- "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)
to resolve hostnames."
- A value of C(all) will publish all exposed container ports to random host ports, ignoring
@ -701,7 +702,7 @@ options:
description:
- If true, always pull the latest version of an image. Otherwise, will only pull an image
when missing.
- "*Note:* images are only pulled when specified by name. If the image is specified
- "B(Note:) images are only pulled when specified by name. If the image is specified
as a image ID (hash), it cannot be pulled."
type: bool
default: no

8
plugins/modules/docker_image.py
View File

@ -28,7 +28,7 @@ options:
be specified when this value is used."
- "Use C(pull) to pull the image from a registry."
- "Use C(local) to make sure that the image is already available on the local
docker daemon, i.e. do not try to build, pull or load the image."
docker daemon. This means that the module does not try to build, pull or load the image."
type: str
choices:
- build
@ -101,7 +101,8 @@ options:
type: int
memswap:
description:
- Total memory (memory + swap), -1 to disable swap.
- Total memory (memory + swap).
- Use C(-1) to disable swap.
type: int
cpushares:
description:
@ -109,7 +110,8 @@ options:
type: int
cpusetcpus:
description:
- CPUs in which to allow execution, e.g., "0-3", "0,1".
- CPUs in which to allow execution.
- For example, C(0-3) or C(0,1).
type: str
use_config_proxy:
description:

2
plugins/modules/docker_login.py
View File

@ -15,7 +15,7 @@ DOCUMENTATION = '''
module: docker_login
short_description: Log into a Docker registry.
description:
- Provides functionality similar to the "docker login" command.
- 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

4
plugins/modules/docker_network.py
View File

@ -12,7 +12,7 @@ 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 "docker network" CLI subcommand.
- Performs largely the same function as the C(docker network) CLI subcommand.
options:
name:
description:
@ -155,7 +155,7 @@ notes:
It does not try to reconnect containers, except the ones listed in (I(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, i.e. it will not try to disconnect or reconnect services. If services are connected to the
- 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.

2
plugins/modules/docker_node_info.py
View File

@ -31,7 +31,7 @@ options:
elements: str
self:
description:
- If C(true), queries the node (i.e. the docker daemon) the module communicates with.
- If C(true), queries the node (that is, the docker daemon) the module communicates with.
- If C(true) then I(name) is ignored.
- If C(false) then query depends on I(name) presence and value.
type: bool

4
plugins/modules/docker_secret.py
View File

@ -16,8 +16,8 @@ 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 'ansible_key', an encrypted hash representation of the data, which is then used
in future runs to test if a secret has changed. If 'ansible_key is not present, then a secret will not be updated
- Adds to the metadata of new secrets C(ansible_key), an encrypted hash representation of the data, which is then used
in future runs to test if a secret has changed. If C(ansible_key) is not present, then a secret will not be updated
unless the I(force) option is set.
- Updates to secrets are performed by removing the secret and creating it again.
options:

2
plugins/modules/docker_stack.py
View File

@ -14,7 +14,7 @@ module: docker_stack
author: "Dario Zanzico (@dariko)"
short_description: docker stack module
description:
- Manage docker stacks using the 'docker stack' command
- Manage docker stacks using the C(docker stack) command
on the target node (see examples).
options:
name:

4
plugins/modules/docker_swarm_service.py
View File

@ -103,7 +103,7 @@ options:
- 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 (e.g. C("true"))
booleans or other types by the YAML parser must be quoted (for example C("true"))
in order to avoid data loss.
- Corresponds to the C(--env) option of C(docker service create).
type: raw
@ -242,7 +242,7 @@ options:
suboptions:
source:
description:
- Mount source (e.g. a volume name or a host path).
- Mount source (for example a volume name or a host path).
- Must be specified if I(type) is not C(tmpfs).
type: str
target:

8
plugins/modules/docker_volume.py
View File

@ -13,7 +13,7 @@ module: docker_volume
short_description: Manage Docker volumes
description:
- Create/remove Docker volumes.
- Performs largely the same function as the "docker volume" CLI subcommand.
- Performs largely the same function as the C(docker volume) CLI subcommand.
options:
volume_name:
description:
@ -32,7 +32,7 @@ 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)"
U(https://docs.docker.com/engine/reference/commandline/volume_create/#driver-specific-options)."
type: dict
labels:
@ -43,8 +43,8 @@ options:
recreate:
description:
- Controls when a volume will be recreated when I(state) is C(present). Please
note that recreating an existing volume will cause **any data in the existing volume
to be lost!** The volume will be deleted and a new volume with the same name will be
note that recreating an existing volume will cause B(any data in the existing volume
to be lost!) The volume will be deleted and a new volume with the same name will be
created.
- The value C(always) forces the volume to be always recreated.
- The value C(never) makes sure the volume will not be recreated.

2
plugins/modules/docker_volume_info.py
View File

@ -12,7 +12,7 @@ DOCUMENTATION = '''
module: docker_volume_info
short_description: Retrieve facts about Docker volumes
description:
- Performs largely the same function as the "docker volume inspect" CLI subcommand.
- Performs largely the same function as the C(docker volume inspect) CLI subcommand.
options:
name:
description: