Try SpotterAnsible dynamic inventory plugin for Docker containers
| "added in version" 1.1.0 of community.docker"
Authors: Felix Fontein (@felixfontein)
Install with ansible-galaxy collection install community.docker:==3.5.0
collections:
- name: community.docker
version: 3.5.0Reads inventories from the Docker API.
Uses a YAML configuration file that ends with C(docker.[yml|yaml]).
tls:
default: false
description:
- Secure the connection to the API by using TLS without verifying the authenticity
of the Docker host server. Note that if O(validate_certs) is set to V(true) as well,
it will take precedence.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS)
will be used instead. If the environment variable is not set, the default value
will be used.
type: bool
debug:
default: false
description:
- Debug mode
type: bool
groups:
default: {}
description: Add hosts to group based on Jinja2 conditionals.
type: dict
plugin:
choices:
- community.docker.docker_containers
description:
- The name of this plugin, it should always be set to V(community.docker.docker_containers)
for this plugin to recognize it as it's own.
required: true
type: str
strict:
default: false
description:
- If V(yes) make invalid entries a fatal error, otherwise skip and continue.
- Since it is possible to use facts in the expressions they might not always be available
and we ignore those errors by default.
type: bool
ca_cert:
aliases:
- tls_ca_cert
- cacert_path
description:
- Use a CA certificate when performing server verification by providing the path to
a CA certificate file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
is set, the file C(ca.pem) from the directory specified in the environment variable
E(DOCKER_CERT_PATH) will be used.
type: path
compose:
default: {}
description: Create vars from jinja2 expressions.
type: dict
timeout:
default: 60
description:
- The maximum amount of time in seconds to wait on a response from the API.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT)
will be used instead. If the environment variable is not set, the default value
will be used.
type: int
client_key:
aliases:
- tls_client_key
- key_path
description:
- Path to the client's TLS key file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
is set, the file C(key.pem) from the directory specified in the environment variable
E(DOCKER_CERT_PATH) will be used.
type: path
default_ip:
default: 127.0.0.1
description:
- The IP address to assign to ansible_host when the container's SSH port is mapped
to interface '0.0.0.0'.
- Only used if O(connection_type) is V(ssh).
type: str
api_version:
aliases:
- docker_api_version
default: auto
description:
- The version of the Docker API running on the Docker Host.
- Defaults to the latest version of the API supported by this collection and the docker
daemon.
- If the value is not specified in the task, the value of environment variable E(DOCKER_API_VERSION)
will be used instead. If the environment variable is not set, the default value
will be used.
type: str
client_cert:
aliases:
- tls_client_cert
- cert_path
description:
- Path to the client's TLS certificate file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
is set, the file C(cert.pem) from the directory specified in the environment variable
E(DOCKER_CERT_PATH) will be used.
type: path
docker_host:
aliases:
- docker_url
default: unix://var/run/docker.sock
description:
- The URL or Unix socket path used to connect to the Docker API. To connect to a remote
host, provide the TCP connection string. For example, V(tcp://192.0.2.23:2376).
If TLS is used to encrypt the connection, the module will automatically replace
C(tcp) in the connection URL with C(https).
- If the value is not specified in the task, the value of environment variable E(DOCKER_HOST)
will be used instead. If the environment variable is not set, the default value
will be used.
type: str
ssl_version:
description:
- Provide a valid SSL version number. Default value determined by L(SSL Python module,
https://docs.python.org/3/library/ssl.html).
- If the value is not specified in the task, the value of environment variable E(DOCKER_SSL_VERSION)
will be used instead.
type: str
keyed_groups:
default: []
description: Add hosts to group based on the values of a variable.
elements: dict
suboptions:
default_value:
description:
- The default value when the host variable's value is an empty string.
- This option is mutually exclusive with O(keyed_groups[].trailing_separator).
type: str
version_added: '2.12'
version_added_collection: ansible.builtin
key:
description:
- The key from input dictionary used to generate groups
type: str
parent_group:
description: parent group for keyed group
type: str
prefix:
default: ''
description: A keyed group name will start with this prefix
type: str
separator:
default: _
description: separator used to build the keyed group name
type: str
trailing_separator:
default: true
description:
- Set this option to V(False) to omit the O(keyed_groups[].separator) after the
host variable when the value is an empty string.
- This option is mutually exclusive with O(keyed_groups[].default_value).
type: bool
version_added: '2.12'
version_added_collection: ansible.builtin
type: list
tls_hostname:
description:
- When verifying the authenticity of the Docker Host server, provide the expected
name of the server.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME)
will be used instead. If the environment variable is not set, the default value
will be used.
- Note that this option had a default value V(localhost) in older versions. It was
removed in community.docker 3.0.0.
type: str
use_extra_vars:
default: false
description: Merge extra vars into the available variables for composition (highest
precedence).
env:
- name: ANSIBLE_INVENTORY_USE_EXTRA_VARS
ini:
- key: use_extra_vars
section: inventory_plugins
type: bool
version_added: '2.11'
version_added_collection: ansible.builtin
use_ssh_client:
default: false
description:
- For SSH transports, use the C(ssh) CLI tool instead of paramiko.
type: bool
version_added: 1.5.0
version_added_collection: community.docker
validate_certs:
aliases:
- tls_verify
default: false
description:
- Secure the connection to the API by using TLS and verifying the authenticity of
the Docker host server.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_VERIFY)
will be used instead. If the environment variable is not set, the default value
will be used.
type: bool
verbose_output:
default: false
description:
- Toggle to (not) include all available inspection metadata.
- Note that all top-level keys will be transformed to the format C(docker_xxx). For
example, C(HostConfig) is converted to C(docker_hostconfig).
- If this is V(false), these values can only be used during O(compose), O(groups),
and O(keyed_groups).
- The C(docker) inventory script always added these variables, so for compatibility
set this to V(true).
type: bool
connection_type:
choices:
- ssh
- docker-cli
- docker-api
default: docker-api
description:
- Which connection type to use the containers.
- One way to connect to containers is to use SSH (V(ssh)). For this, the options O(default_ip)
and O(private_ssh_port) are used. This requires that a SSH daemon is running inside
the containers.
- Alternatively, V(docker-cli) selects the P(community.docker.docker#connection) connection
plugin, and V(docker-api) (default) selects the P(community.docker.docker_api#connection)
connection plugin.
- When V(docker-api) is used, all Docker daemon configuration values are passed from
the inventory plugin to the connection plugin. This can be controlled with O(configure_docker_daemon).
- Note that the P(community.docker.docker_api#connection) does B(not work with TCP
TLS sockets)! See U(https://github.com/ansible-collections/community.docker/issues/605)
for more information.
type: str
private_ssh_port:
default: 22
description:
- The port containers use for SSH.
- Only used if O(connection_type) is V(ssh).
type: int
add_legacy_groups:
default: false
description:
- 'Add the same groups as the C(docker) inventory script does. These are the following:'
- 'C(<container id>): contains the container of this ID.'
- 'C(<container name>): contains the container that has this name.'
- 'C(<container short id>): contains the containers that have this short ID (first
13 letters of ID).'
- 'C(image_<image name>): contains the containers that have the image C(<image name>).'
- 'C(stack_<stack name>): contains the containers that belong to the stack C(<stack
name>).'
- 'C(service_<service name>): contains the containers that belong to the service C(<service
name>)'
- 'C(<docker_host>): contains the containers which belong to the Docker daemon O(docker_host).
Useful if you run this plugin against multiple Docker daemons.'
- 'C(running): contains all containers that are running.'
- 'C(stopped): contains all containers that are not running.'
- If this is not set to V(true), you should use keyed groups to add the containers
to groups. See the examples for how to do that.
type: bool
leading_separator:
default: true
description:
- Use in conjunction with keyed_groups.
- By default, a keyed group that does not have a prefix or a separator provided will
have a name that starts with an underscore.
- This is because the default prefix is "" and the default separator is "_".
- Set this option to False to omit the leading underscore (or other separator) if
no prefix is given.
- If the group name is derived from a mapping the separator is still used to concatenate
the items.
- To not use a separator in the group name at all, set the separator for the keyed
group to an empty string instead.
type: boolean
version_added: '2.11'
version_added_collection: ansible.builtin
configure_docker_daemon:
default: true
description:
- Whether to pass all Docker daemon configuration from the inventory plugin to the
connection plugin.
- Only used when O(connection_type=docker-api).
type: bool
version_added: 1.8.0
version_added_collection: community.docker