community.docker.docker_containers inventory – Ansible dynamic inventory plugin for Docker containers
Note
This inventory plugin is part of the community.docker collection (version 3.13.1).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.docker.
You need further requirements to be able to use this inventory plugin,
see Requirements for details.
To use it in a playbook, specify: community.docker.docker_containers.
New in community.docker 1.1.0
Synopsis
Reads inventories from the Docker API.
Uses a YAML configuration file that ends with
docker.(yml|yaml).
Requirements
The below requirements are needed on the local controller node that executes this inventory.
requests
pywin32 (when using named pipes on Windows 32)
paramiko (when using SSH with
use_ssh_client=false)pyOpenSSL (when using TLS)
backports.ssl_match_hostname (when using TLS on Python 2)
Parameters
Parameter |
Comments |
|---|---|
Add the same groups as the
If this is not set to Choices:
|
|
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 Default: |
|
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 This option was called |
|
Path to the client’s TLS certificate file. If the value is not specified in the task and the environment variable |
|
Path to the client’s TLS key file. If the value is not specified in the task and the environment variable |
|
Create vars from jinja2 expressions. Default: |
|
Whether to pass all Docker daemon configuration from the inventory plugin to the connection plugin. Only used when Choices:
|
|
Which connection type to use the containers. One way to connect to containers is to use SSH ( Alternatively, When Note that the community.docker.docker_api does not work with TCP TLS sockets! See https://github.com/ansible-collections/community.docker/issues/605 for more information. Choices:
|
|
Debug mode Choices:
|
|
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 Default: |
|
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, If the value is not specified in the task, the value of environment variable Default: |
|
A list of include/exclude filters that allows to select/deselect hosts for this inventory. Filters are processed sequentially until the first filter where |
|
A Jinja2 condition. If it matches for a host, that host is excluded. Exactly one of |
|
A Jinja2 condition. If it matches for a host, that host is included. Exactly one of |
|
Add hosts to group based on Jinja2 conditionals. Default: |
|
Add hosts to group based on the values of a variable. Default: |
|
The default value when the host variable’s value is an empty string. This option is mutually exclusive with |
|
The key from input dictionary used to generate groups |
|
parent group for keyed group |
|
A keyed group name will start with this prefix Default: |
|
separator used to build the keyed group name Default: |
|
Set this option to This option is mutually exclusive with Choices:
|
|
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. Choices:
|
|
The name of this plugin, it should always be set to Choices:
|
|
Provide a valid SSL version number. Default value determined by SSL Python module. If the value is not specified in the task, the value of environment variable |
|
If Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default. Choices:
|
|
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 Default: |
|
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if If the value is not specified in the task, the value of environment variable Choices:
|
|
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 Note that this option had a default value |
|
Merge extra vars into the available variables for composition (highest precedence). Choices:
Configuration:
|
|
For SSH transports, use the Choices:
|
|
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 Choices:
|
|
Toggle to (not) include all available inspection metadata. Note that all top-level keys will be transformed to the format If this is The Choices:
|
Notes
Note
The configuration file must be a YAML file whose filename ends with
docker.ymlordocker.yaml. Other filenames will not be accepted.Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define
DOCKER_HOST,DOCKER_TLS_HOSTNAME,DOCKER_API_VERSION,DOCKER_CERT_PATH,DOCKER_SSL_VERSION,DOCKER_TLS,DOCKER_TLS_VERIFYandDOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.This module does not use the Docker SDK for Python to communicate with the Docker daemon. It uses code derived from the Docker SDK or Python that is included in this collection.
Examples
# Minimal example using local Docker daemon
plugin: community.docker.docker_containers
docker_host: unix:///var/run/docker.sock
# Minimal example using remote Docker daemon
plugin: community.docker.docker_containers
docker_host: tcp://my-docker-host:2375
# Example using remote Docker daemon with unverified TLS
plugin: community.docker.docker_containers
docker_host: tcp://my-docker-host:2376
tls: true
# Example using remote Docker daemon with verified TLS and client certificate verification
plugin: community.docker.docker_containers
docker_host: tcp://my-docker-host:2376
validate_certs: true
ca_path: /somewhere/ca.pem
client_key: /somewhere/key.pem
client_cert: /somewhere/cert.pem
# Example using constructed features to create groups
plugin: community.docker.docker_containers
docker_host: tcp://my-docker-host:2375
strict: false
keyed_groups:
# Add containers with primary network foo to a network_foo group
- prefix: network
key: 'docker_hostconfig.NetworkMode'
# Add Linux hosts to an os_linux group
- prefix: os
key: docker_platform
# Example using SSH connection with an explicit fallback for when port 22 has not been
# exported: use container name as ansible_ssh_host and 22 as ansible_ssh_port
plugin: community.docker.docker_containers
connection_type: ssh
compose:
ansible_ssh_host: ansible_ssh_host | default(docker_name[1:], true)
ansible_ssh_port: ansible_ssh_port | default(22, true)
# Only consider containers which have a label 'foo', or whose name starts with 'a'
plugin: community.docker.docker_containers
filters:
# Accept all containers which have a label called 'foo'
- include: >-
"foo" in docker_config.Labels
# Next accept all containers whose inventory_hostname starts with 'a'
- include: >-
inventory_hostname.startswith("a")
# Exclude all containers that didn't match any of the above filters
- exclude: true