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

Note

This lookup plugin is part of the community.general collection (version 4.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

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)

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.