Steampunk Ansible Documentation - community.general.docker_config (1.3.14) - module

Install collection

Install with ansible-galaxy collection install community.general:==1.3.14

Add to requirements.yml

  collections:
    - name: community.general
      version: 1.3.14

Description

Create and remove Docker configs in a Swarm environment. Similar to C(docker config create) and C(docker config rm).

Adds to the metadata of new configs 'ansible_key', an encrypted hash representation of the data, which is then used in future runs to test if a config has changed. If 'ansible_key' is not present, then a config will not be updated unless the I(force) option is set.

Updates to configs are performed by removing the config and creating it again.

Requirements

Docker API >= 1.30
Docker SDK for Python: Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python module has been superseded by L(docker,https://pypi.org/project/docker/) (see L(here,https://github.com/docker/docker-py/issues/1310) for details). This module does *not* work with docker-py.
L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.6.0
Python >= 2.7

Usage examples

Scanned by Steampunk Spotter


- name: Create config foo (from a file on the control machine)
  community.general.docker_config:
    name: foo
    # If the file is JSON or binary, Ansible might modify it (because
    # it is first decoded and later re-encoded). Base64-encoding the
    # file directly after reading it prevents this to happen.
    data: "{{ lookup('file', '/path/to/config/file') | b64encode }}"
    data_is_b64: true
    state: present

Scanned by Steampunk Spotter

- name: Change the config data
  community.general.docker_config:
    name: foo
    data: Goodnight everyone!
    labels:
      bar: baz
      one: '1'
    state: present

Scanned by Steampunk Spotter

- name: Add a new label
  community.general.docker_config:
    name: foo
    data: Goodnight everyone!
    labels:
      bar: baz
      one: '1'
      # Adding a new label will cause a remove/create of the config
      two: '2'
    state: present

Scanned by Steampunk Spotter

- name: No change
  community.general.docker_config:
    name: foo
    data: Goodnight everyone!
    labels:
      bar: baz
      one: '1'
      # Even though 'two' is missing, there is no change to the existing config
    state: present

Scanned by Steampunk Spotter

- name: Update an existing label
  community.general.docker_config:
    name: foo
    data: Goodnight everyone!
    labels:
      bar: monkey   # Changing a label will cause a remove/create of the config
      one: '1'
    state: present

Scanned by Steampunk Spotter

- name: Force the (re-)creation of the config
  community.general.docker_config:
    name: foo
    data: Goodnight everyone!
    force: yes
    state: present

Scanned by Steampunk Spotter

- name: Remove config foo
  community.general.docker_config:
    name: foo
    state: absent

Inputs

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 I(validate_certs) is set to C(yes) as well,
it will take precedence.
- If the value is not specified in the task, the value of environment variable C(DOCKER_TLS)
will be used instead. If the environment variable is not set, the default value
will be used.
type: bool

data:
description:
- The value of the config. Required when state is C(present).
type: str

name:
description:
- The name of the config.
required: true
type: str

debug:
default: false
description:
- Debug mode
type: bool

force:
default: false
description:
- Use with state C(present) to always remove and recreate an existing config.
- If C(true), an existing config will be replaced, even if it has not been changed.
type: bool

state:
choices:
- absent
- present
default: present
description:
- Set to C(present), if the config should exist, and C(absent), if it should not.
type: str

labels:
description:
- A map of key:value meta data, where both the I(key) and I(value) are expected to
be a string.
- If new meta data is provided, or existing meta data is modified, the config will
be updated by removing it and creating it again.
type: dict

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 C(DOCKER_CERT_PATH)
is set, the file C(ca.pem) from the directory specified in the environment variable
C(DOCKER_CERT_PATH) will be used.
type: path

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 C(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 C(DOCKER_CERT_PATH)
is set, the file C(key.pem) from the directory specified in the environment variable
C(DOCKER_CERT_PATH) will be used.
type: path

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 Docker SDK for Python and
the docker daemon.
- If the value is not specified in the task, the value of environment variable C(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 C(DOCKER_CERT_PATH)
is set, the file C(cert.pem) from the directory specified in the environment variable
C(DOCKER_CERT_PATH) will be used.
type: path

data_is_b64:
default: false
description:
- If set to C(true), the data is assumed to be Base64 encoded and will be decoded
before being used.
- To use binary I(data), it is better to keep it Base64 encoded and let it be decoded
by this option.
type: bool

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, C(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 C(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 ssl.py module.
- If the value is not specified in the task, the value of environment variable C(DOCKER_SSL_VERSION)
will be used instead.
type: str

tls_hostname:
default: localhost
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 C(DOCKER_TLS_HOSTNAME)
will be used instead. If the environment variable is not set, the default value
will be used.
type: str

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 C(DOCKER_TLS_VERIFY)
will be used instead. If the environment variable is not set, the default value
will be used.
type: bool

Outputs

config_id:
  description:
  - The ID assigned by Docker to the config object.
  returned: success and I(state) is C(present)
  sample: hzehrmyjigmcp2gb6nlhmjqcv
  type: str