community.docker.docker_containers inventory – Ansible dynamic inventory plugin for Docker containers
Note
This inventory plugin is part of the community.docker collection (version 4.8.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 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 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 Set this option to 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:
|
|
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:
|
Note
Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. The entry types are also ordered by precedence from low to high priority order. For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
Notes
Note
The configuration file must be a YAML file whose filename ends with
docker.ymlordocker.yaml. Other filenames will not be accepted.Inventories are not finalized at this stage, so the auto populated
allandungroupedgroups will only reflect what previous inventory sources explicitly added to them.Runtime ‘magic variables’ are not available during inventory construction. For example,
groupsandhostvarsdo not exist yet.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_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 did not match any of the above filters
- exclude: true