Ansible Role: etcd

This role sets up etcd and etcdctl on your target machine. It supports all options for configuring etcd and aims to be very flexible.

Requirements

This role was developed and tested with the following Ansible versions:

Name	Version
ansible	>= 2.9.13
ansible-base	>= 2.10.1

Other versions may work, but have not been tested.

Installation

Run ansible-galaxy install igor_nikiforov.etcd to install the latest version of this role.

You can also install it using a requirements file like this: ansible-galaxy install -r requirements.yml:

# requirements.yml
---
roles:
  - name: igor_nikiforov.etcd
    version: v1.0.0

Platforms

Name	Version
Debian	buster, bullseye
Ubuntu	focal, jammy
CentOS	7.4+, stream8
RedHat	7.4+, 8

Other operating systems may work, but have not been tested. If they don’t work, please create a pull request (PR).

Variables

Name	Description	Default
etcd_version	The etcd version to install	3.4.13
etcd_user	etcd username	etcd
etcd_group	etcd user group	etcd
etcd_config	Key-value list of etcd configuration settings	{}
etcd_service_enabled	If the service should start at boot	True
etcd_service_state	etcd service state	started
etcdctl_output_format	Output format for etcdctl queries	table

Usage

This role supports all etcd configuration options that can be set with the etcd_config variable. You can see example YAML configurations in the etcd official repository and find available flags with descriptions in the etcd official documentation.

etcd can form a cluster using two methods:

1. Static.

   After running the playbook, you will need to manually add each member using the etcdctl member add command. You can do this manually or automate it using a separate Ansible task.

2. DNS discovery.

   For this method, you need to have SRV and A records ready in your local DNS zone. Please check the requirements for DNS records that should be created beforehand. If everything is set up correctly, add the following properties to etcd_config:

   etcd_config:
     discovery-srv: "company.local"
     discovery-srv-name: "dev" # optional
   

   After running the playbook, the etcd cluster will be created automatically. It's recommended to use this method in production.

Important:

• Change etcd_config.initial-cluster-state from new to existing in the playbook after the first run.
• Use serial: 1 in your playbook after building the cluster for safe updates in case the configuration changes. More info can be found here.

Examples

Static

# playbook.yml
---
- hosts: all
  become: True
  gather_facts: False

  pre_tasks:
    - wait_for_connection: {timeout: 300}
    - setup:

  tasks:
    - name: Install etcd
      import_role:
        name: etcd
      vars:
        etcd_version: "3.4.13"
        etcd_config:
          name: "{{ ansible_facts.hostname }}"
          data-dir: "/var/lib/etcd/data"
          wal-dir: "/var/lib/etcd/wal"
          initial-advertise-peer-urls: "https://{{ ansible_facts.fqdn }}:2380"
          initial-cluster-token: "token"
          initial-cluster-state: "new"
          advertise-client-urls: "https://{{ ansible_facts.fqdn }}:2379"
          listen-client-urls: "https://{{ ansible_default_ipv4.address }}:2379,https://127.0.0.1:2379"
          listen-peer-urls: "https://{{ ansible_default_ipv4.address }}:2380"
          client-transport-security:
            trusted-ca-file: "{{ etcd_conf_dir }}/certs/ca.crt"
            cert-file: "{{ etcd_conf_dir }}/certs/server.crt"
            key-file: "{{ etcd_conf_dir }}/certs/server.key"
          peer-transport-security:
            trusted-ca-file: "{{ etcd_conf_dir }}/certs/ca.crt"
            cert-file: "{{ etcd_conf_dir }}/certs/server.crt"
            key-file: "{{ etcd_conf_dir }}/certs/server.key"
          log-level: "debug"
          logger: "zap"

DNS discovery

# playbook.yml
---
- hosts: all
  become: True
  gather_facts: False

  pre_tasks:
    - wait_for_connection: {timeout: 300}
    - setup:

  tasks:
    - name: Install etcd
      import_role:
        name: etcd
      vars:
        etcd_version: "3.4.13"
        etcd_config:
          name: "{{ ansible_facts.hostname }}"
          data-dir: "/var/lib/etcd/data"
          wal-dir: "/var/lib/etcd/wal"
          discovery-srv: "company.local"
          initial-advertise-peer-urls: "https://{{ ansible_facts.fqdn }}:2380"
          initial-cluster-token: "token"
          initial-cluster-state: "new"
          advertise-client-urls: "https://{{ ansible_facts.fqdn }}:2379"
          listen-client-urls: "https://{{ ansible_default_ipv4.address }}:2379,https://127.0.0.1:2379"
          listen-peer-urls: "https://{{ ansible_default_ipv4.address }}:2380"
          client-transport-security:
            trusted-ca-file: "{{ etcd_conf_dir }}/certs/ca.crt"
            cert-file: "{{ etcd_conf_dir }}/certs/server.crt"
            key-file: "{{ etcd_conf_dir }}/certs/server.key"
          peer-transport-security:
            trusted-ca-file: "{{ etcd_conf_dir }}/certs/ca.crt"
            cert-file: "{{ etcd_conf_dir }}/certs/server.crt"
            key-file: "{{ etcd_conf_dir }}/certs/server.key"
          log-level: "debug"
          logger: "zap"

License

MIT

Author Information

Igor Nikiforov