Skip to content

igor-nikiforov/ansible-role-etcd

Repository files navigation

Ansible role: etcd

This role configures etcd and etcdctl on your target host. It supports all etcd configuration options and strives to be as flexible as possible.

Requirements

This role developed and tested with following Ansible versions:

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

Other Ansible versions was not tested but will probably work.

Installation

Use ansible-galaxy install igor_nikiforov.etcd to install the latest stable release of role.

You could also install it from requirements 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 OS distributions was not tested but will probably work. In case if not please raise a PR!

Variables

Name Description Default
etcd_version Version of etcd to be installed 3.4.13
etcd_user etcd user etcd
etcd_group etcd group etcd
etcd_config List of key-values etcd configuration parameters. {}
etcd_service_enabled Whether the service should start on boot. True
etcd_service_state Service state for etcd. started
etcdctl_output_format Output format to be used in etcdctl. table

Usage

Role supports all etcd configuration parameters which could be passed via etcd_config variable. You could find example of YAML config format in etcd official repository and all availible flags with discription in etcd official documentation.

etcd supports two main methods to build a cluster:

  1. Static.

    After playbook execution you should manually add each member from one of host using etcdctl member add command. It supposing that you will do this manually or automate in separate Ansible task.

  2. DNS discovery.

    Main prerequisite here is to have ready SRV and A records in your DNS local zone. Please carefully check requirements for DNS records which should be created in advance. If everything created properly following DNS discovery related properties needs to be added to etcd_config:

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

    After playbook execution etcd cluster will be automatically created. It is strongly recommended to use this method in production.

Important:

  • Don't forget to change etcd_config.initial-cluster-state from new to existing in playbook after first execution.
  • Use serial: 1 in your playbook after you build a cluster to safely update it in case of configuration change. More info 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