Parameters

The ETCD module has 13 parameters, divided into two sections:

• ETCD: 10 parameters for etcd cluster deployment and configuration
• ETCD_REMOVE: 3 parameters for controlling etcd cluster removal

Parameter Overview

Use the ETCD parameter group to deploy and configure etcd clusters. It controls instance identification, cluster name, data directory, ports, and authentication password.

The ETCD_REMOVE parameter group controls etcd cluster removal behavior, including safeguard protection, data cleanup, and package uninstallation.

ETCD

This section contains parameters for the etcd role, which are used by the etcd.yml playbook.

Parameters are defined in roles/etcd/defaults/main.yml

#etcd_seq: 1                      # etcd instance identifier, explicitly required
etcd_cluster: etcd                # etcd cluster & group name, etcd by default
etcd_learner: false               # run etcd instance as learner? default is false
etcd_data: /data/etcd             # etcd data directory, /data/etcd by default
etcd_port: 2379                   # etcd client port, 2379 by default
etcd_peer_port: 2380              # etcd peer port, 2380 by default
etcd_init: new                    # etcd initial cluster state, new or existing
etcd_election_timeout: 1000       # etcd election timeout, 1000ms by default
etcd_heartbeat_interval: 100      # etcd heartbeat interval, 100ms by default
etcd_root_password: Etcd.Root     # etcd root user password for RBAC authentication (please change!)

etcd_seq

Parameter: etcd_seq, Type: int, Level: I

etcd instance identifier. This parameter is required. You must assign a unique identifier to each etcd instance.

Here is an example of a 3-node etcd cluster with identifiers 1 through 3:

etcd: # dcs service for postgres/patroni ha consensus
  hosts:  # 1 node for testing, 3 or 5 for production
    10.10.10.10: { etcd_seq: 1 }  # etcd_seq required
    10.10.10.11: { etcd_seq: 2 }  # assign from 1 ~ n
    10.10.10.12: { etcd_seq: 3 }  # use odd numbers
  vars: # cluster level parameter override roles/etcd
    etcd_cluster: etcd  # mark etcd cluster name etcd
    etcd_safeguard: false # safeguard against purging

etcd_cluster

Parameter: etcd_cluster, Type: string, Level: C

etcd cluster & group name, default value is the hard-coded etcd.

You can modify this parameter when you want to deploy an additional etcd cluster for backup purposes.

etcd_learner

Parameter: etcd_learner, Type: bool, Level: I/A

Specifies whether to initialize the etcd instance as a learner. The default is false.

If this parameter is true, Pigsty initializes the instance as a learner. A learner cannot vote in etcd cluster elections.

Use Cases:

• Cluster Expansion: Add members as learners to preserve the current quorum requirements until data synchronization completes.
• Safe Migration: During a rolling upgrade or migration, add the member as a learner. Confirm data synchronization before you promote it.

Workflow:

1. Set etcd_learner: true to initialize the new member as a learner
2. Wait for data synchronization to complete (check with etcdctl endpoint status)
3. Use etcdctl member promote <member_id> to promote it to a full member

etcd_data

Parameter: etcd_data, Type: path, Level: C

etcd data directory, default is /data/etcd.

etcd_port

Parameter: etcd_port, Type: port, Level: C

etcd client port, default is 2379.

etcd_peer_port

Parameter: etcd_peer_port, Type: port, Level: C

etcd peer port, default is 2380.

etcd_init

Parameter: etcd_init, Type: enum, Level: C

Initial etcd cluster state. Set it to new or existing. The default is new.

Option Values:

Important Notes:

Usage Examples:

# Create new cluster (default behavior)
./etcd.yml

# Add new member to existing cluster
./etcd.yml -l <new_ip> -e etcd_init=existing

# Or use the convenience script (automatically sets etcd_init=existing)
bin/etcd-add <new_ip>

etcd_election_timeout

Parameter: etcd_election_timeout, Type: int, Level: C

etcd election timeout, default is 1000 (milliseconds), i.e., 1 second.

etcd_heartbeat_interval

Parameter: etcd_heartbeat_interval, Type: int, Level: C

etcd heartbeat interval, default is 100 (milliseconds).

etcd_root_password

Parameter: etcd_root_password, Type: password, Level: G

etcd root user password for RBAC authentication, default value is Etcd.Root.

Since v4.0, Pigsty has enabled etcd RBAC (Role-Based Access Control) authentication by default. During cluster initialization, the etcd_auth task automatically creates the root user and enables authentication.

Password Storage Location:

• Password is stored in /etc/etcd/etcd.pass file
• File permissions are 0640 (owned by root, readable by etcd group)
• The etcdctl environment script /etc/profile.d/etcdctl.sh automatically reads this file

Integration with Other Components:

• Patroni uses the pg_etcd_password parameter to configure the password for connecting to etcd
• If pg_etcd_password is empty, Patroni will use the cluster name as password (not recommended)
• VIP-Manager also requires the same authentication credentials to connect to etcd

Security Recommendations:

etcd_root_password: 'YourSecurePassword'

ETCD_REMOVE

This section contains parameters for the etcd_remove role, which are action flags used by the etcd-rm.yml playbook.

Parameters are defined in roles/etcd_remove/defaults/main.yml

etcd_safeguard: false             # unconditionally refuse removal when true
etcd_rm_data: true                # remove etcd data and config files during removal?
etcd_rm_pkg: false                # uninstall etcd packages during removal?

etcd_safeguard

Parameter: etcd_safeguard, Type: bool, Level: G/C/A

Removal safeguard. The default is false. If set to true, etcd-rm.yml aborts before deregistration, cluster departure, service shutdown, or data deletion. This static boolean switch does not check whether the instance is running. Override it explicitly with -e etcd_safeguard=false.

Recommended Settings:

In emergencies, you can override the configuration with command-line parameters:

./etcd-rm.yml -l etcd -e etcd_safeguard=false # Override the guard and remove the target Etcd cluster

etcd_rm_data

Parameter: etcd_rm_data, Type: bool, Level: G/C/A

Specifies whether to delete etcd data and configuration files during removal. The default is true.

If enabled, etcd-rm.yml deletes these files and directories when it removes a cluster or member:

• /etc/etcd/ - Configuration directory (including certificates and password files)
• /var/lib/etcd/ - Alternate data directory
• {{ etcd_data }} - Primary data directory (default /data/etcd)
• /etc/systemd/system/etcd.service - Systemd service unit file
• /etc/profile.d/etcdctl.sh - Client environment script
• /etc/vector/etcd.yaml - Vector log collection config

Use Cases:

# Stop service only, preserve data
./etcd-rm.yml -l etcd -e etcd_rm_data=false

etcd_rm_pkg

Parameter: etcd_rm_pkg, Type: bool, Level: G/C/A

Specifies whether to uninstall etcd packages during removal. The default is false.

If enabled, etcd-rm.yml uninstalls etcd packages when it removes a cluster or member.

Use Cases:

# Uninstall packages during removal
./etcd-rm.yml -l etcd -e etcd_rm_pkg=true