# docker_swarm – Ansible dynamic inventory plugin for Docker swarm nodes

New in version 2.8.

- Synopsis
- Requirements
- Parameters
- Examples
- Status

## Synopsis

- Reads inventories from the Docker swarm API.
- Uses a YAML configuration file docker_swarm.[yml|yaml].
- The plugin returns following groups of swarm nodes: all - all hosts; workers - all worker nodes; managers - all manager nodes; leader - the swarm leader node; nonleaders - all nodes except the swarm leader.

## Requirements

The below requirements are needed on the local master node that executes this inventory.

- python >= 2.7
- Docker SDK for Python >= 1.10.0

## Parameters

Parameter | Choices/Defaults | Configuration | Comments
--- | --- | --- | ---
api_version string |  |  | The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by docker-py. aliases: docker_api_version
ca_cert path |  |  | Use a CA certificate when performing server verification by providing the path to a CA certificate file. aliases: tls_ca_cert, cacert_path
client_cert path |  |  | Path to the client's TLS certificate file. aliases: tls_client_cert, cert_path
client_key path |  |  | Path to the client's TLS key file. aliases: tls_client_key, key_path
compose dictionary | Default: {} |  | Create vars from jinja2 expressions.
docker_host string / required |  |  | Socket of a Docker swarm manager node (`tcp`, `unix`). Use `unix://var/run/docker.sock` to connect via local socket. aliases: docker_url
groups dictionary | Default: {} |  | Add hosts to group based on Jinja2 conditionals.

include_host_uri
boolean

Choices:
- no ←
- yes

Toggle to return the additional attribute `ansible_host_uri` which contains the URI of the swarm leader in format of `tcp://172.16.0.1:2376`. This value may be used without additional modification as value of option docker_host in Docker Swarm modules when connecting via API. The port always defaults to `2376`.

include_host_uri_port integer |  |  | Override the detected port number included in ansible_host_uri
keyed_groups list | Default: [] |  | Add hosts to group based on the values of a variable.

plugin
string / required

Choices:
- d
- o
- c
- k
- e
- r
- _
- s
- w
- a
- r
- m

The name of this plugin, it should always be set to `docker_swarm` for this plugin to recognize it as it's own.

ssl_version string |  |  | Provide a valid SSL version number. Default value determined by ssl.py module.

strict
boolean

Choices:
- no ←
- yes

If `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.

timeout integer | Default: 60 |  | 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 `DOCKER_TIMEOUT` will be used instead. If the environment variable is not set, the default value will be used. aliases: time_out

tls
boolean

Choices:
- no ←
- yes

Connect using TLS without verifying the authenticity of the Docker host server.

tls_hostname string |  |  | When verifying the authenticity of the Docker host server, provide the expected name of the server.

validate_certs
boolean

Choices:
- no ←
- yes

Toggle if connecting using TLS with or without verifying the authenticity of the Docker host server.
aliases: tls_verify

verbose_output
boolean

Choices:
- no
- yes ←

Toggle to (not) include all available nodes metadata (e.g. `Platform`, `Architecture`, `OS`, `EngineVersion`)

## Examples

    # Minimal example using local docker
    plugin: docker_swarm
    docker_host: unix://var/run/docker.sock

    # Minimal example using remote docker
    plugin: docker_swarm
    docker_host: tcp://my-docker-host:2375

    # Example using remote docker with unverified TLS
    plugin: docker_swarm
    docker_host: tcp://my-docker-host:2376
    tls: yes

    # Example using remote docker with verified TLS and client certificate verification
    plugin: docker_swarm
    docker_host: tcp://my-docker-host:2376
    validate_certs: yes
    ca_cert: /somewhere/ca.pem
    client_key: /somewhere/key.pem
    client_cert: /somewhere/cert.pem

    # Example using constructed features to create groups and set ansible_host
    plugin: 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
      - prefix: arch
        key: 'Description.Platform.Architecture'
      # add e.g. 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"
      # hint: labels containing special characters will be converted to safe names
      - key: 'Spec.Labels'
        prefix: label

## Status

- This inventory is not guaranteed to have a backwards compatible interface. [preview]
- This inventory is maintained by the Ansible Community. [community]

### Authors

- Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com>

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type 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.