You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

community.general.etcd3 – Get key values from etcd3 server

Note

This plugin is part of the community.general collection (version 3.8.3).

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.general.

To use it in a playbook, specify: community.general.etcd3.

New in version 0.2.0: of community.general

Synopsis

• Retrieves key values and/or key prefixes from etcd3 server using its native gRPC API.

• Try to reuse community.general.etcd3 options for connection parameters, but add support for some ETCDCTL_* environment variables.

• See https://github.com/etcd-io/etcd/tree/master/Documentation/op-guide for etcd overview.

Requirements

The below requirements are needed on the local controller node that executes this lookup.

• etcd3 >= 0.10

Parameters

Parameter	Comments
_terms list / elements=string / required	The list of keys (or key prefixes) to look up on the etcd3 server.
ca_cert string	etcd3 CA authority. Configuration: Environment variable: ETCDCTL_CACERT
cert_cert string	etcd3 client certificate. Configuration: Environment variable: ETCDCTL_CERT
cert_key string	etcd3 client private key. Configuration: Environment variable: ETCDCTL_KEY
endpoints string	Counterpart of ETCDCTL_ENDPOINTS environment variable. Specify the etcd3 connection with and URL form eg. https://hostname:2379 or <host>:<port> form. The host part is overwritten by host option, if defined. The port part is overwritten by port option, if defined. Default: “127.0.0.1:2379” Configuration: Environment variable: ETCDCTL_ENDPOINTS
host string	etcd3 listening client host. Takes precedence over endpoints.
password string	Authenticated user password. Configuration: Environment variable: ETCDCTL_PASSWORD
port integer	etcd3 listening client port. Takes precedence over endpoints.
prefix boolean	Look for key or prefix key. Choices: no ← (default) yes
timeout integer	Client timeout. Default: 60 Configuration: Environment variable: ETCDCTL_DIAL_TIMEOUT
user string	Authenticated user name. Configuration: Environment variable: ETCDCTL_USER

Notes

Note

• host and port options take precedence over (endpoints) option.

• The recommended way to connect to etcd3 server is using ETCDCTL_ENDPOINT environment variable and keep endpoints, host, and port unused.

See Also

See also

community.general.etcd3

The official documentation on the community.general.etcd3 module.

ansible_collections.community.general.etcd_lookup

The etcd v2 lookup.

Examples

- name: "a value from a locally running etcd"
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.etcd3', 'foo/bar') }}"

- name: "values from multiple folders on a locally running etcd"
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.etcd3', 'foo', 'bar', 'baz') }}"

- name: "look for a key prefix"
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.etcd3', '/foo/bar', prefix=True) }}"

- name: "connect to etcd3 with a client certificate"
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.etcd3', 'foo/bar', cert_cert='/etc/ssl/etcd/client.pem', cert_key='/etc/ssl/etcd/client.key') }}"

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key	Description
_raw list / elements=dictionary	List of keys and associated values. Returned: success
key string	The element’s key. Returned: success
value string	The element’s value. Returned: success

Authors

• Eric Belhomme (@eric-belhomme) <ebelhomme@fr.scc.com>