HA ETCD Cluster Setup

7 min readSep 28, 2026

ETCD Cluster Installation and Configuration Guide

1. Overview

This document describes the installation, configuration, and validation of a three-node ETCD cluster with TLS encryption and certificate-based authentication.

1.1 Cluster Architecture

Node | IP Address | ETCD Name

Node 1 | 10.45.45.11 | ubuntu1

Node 2 | 10.45.45.12 | ubuntu2

Node 3 | 10.45.45.13 | ubuntu3

1.2 Ports

Port | Purpose

2379 | Client communication

2380 | Peer-to-peer communication

1.3 Prerequisites

Three Linux servers with network connectivity.
SSH access between the servers.
Root or sudo privileges.
Required ports 2379 and 2380 allowed between the nodes.
A working DNS or IP-based network configuration.

2. Install CFSSL

CFSSL is used to generate the Certificate Authority (CA) and TLS certificates required for secure ETCD communication.

2.1 Download CFSSL Binaries

wget https://pkg.cfssl.org/R1.2/cfssl_linux-amd64
wget https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64

2.2 Add Execution Permissions

chmod +x cfssl*

2.3 Move Binaries to `/usr/local/bin`

sudo mv cfssl_linux-amd64 /usr/local/bin/cfssl
sudo mv cfssljson_linux-amd64 /usr/local/bin/cfssljson

2.4 Verify CFSSL Installation

cfssl version
cfssljson -version

3. Install ETCD

3.1 Create the ETCD Directory

mkdir -p /root/etcd
cd /root/etcd

3.2 Download the ETCD Release

wget https://github.com/etcd-io/etcd/releases/download/v3.6.14/etcd-v3.6.14-linux-amd64.tar.gz

3.3 Extract the ETCD Archive

tar -xvf etcd-v3.6.14-linux-amd64.tar.gz

3.4 Add Execution Permissions

chmod +x etcd-v3.6.14-linux-amd64/etcd*

3.5 Move ETCD Binaries

mv etcd-v3.6.14-linux-amd64/etcd* /usr/local/bin/

3.6 Verify ETCD Installation

etcd -version

4. Create ETCD Directories

Create the required directories for certificates, data storage, and TLS configuration.

mkdir -p /root/etcd-cert
mkdir -p /app/data/etcd
mkdir -p /etc/etcd/ssl

Change to the certificate directory:

cd /root/etcd-cert

5. Generate TLS Certificates

TLS certificates are used to secure client-to-server and peer-to-peer communication between ETCD nodes.

5.1 Create the CA Configuration File

Create the file:

vi ca-config.json

Add the following configuration:

{
  "signing": {
    "default": {
      "expiry": "8760h"
    },
    "profiles": {
      "server": {
        "expiry": "43800h",
        "usages": [
          "signing",
          "key encipherment",
          "server auth",
          "client auth"
        ]
      },
      "client": {
        "expiry": "43800h",
        "usages": [
          "signing",
          "key encipherment",
          "client auth"
        ]
      },
      "peer": {
        "expiry": "43800h",
        "usages": [
          "signing",
          "key encipherment",
          "server auth",
          "client auth"
        ]
      }
    }
  }
}

Set file permissions:

chmod 600 ca-config.json

5.2 Create the CA Certificate Signing Request

Create the file:

vi ca-csr.json

Add the following configuration:

{
  "CN": "etcd",
  "key": {
    "algo": "rsa",
    "size": 2048
  },
  "names": [
    {
      "C": "IN",
      "ST": "Maharashtra",
      "L": "Mumbai",
      "O": "etcd",
      "OU": "etcd-server"
    }
  ]
}

Set file permissions:.

chmod 600 ca-csr.json

5.3 Create the ETCD Certificate Signing Request

Create the file:

vi etcd-csr.json

Add the following configuration:

{
  "CN": "etcd",
  "key": {
    "algo": "ecdsa",
    "size": 256
  },
  "names": [
    {
      "C": "IN",
      "ST": "Maharashtra",
      "L": "Mumbai",
      "O": "etcd",
      "OU": "etcd-server"
    }
  ]
}

Set file permissions:

chmod 600 etcd-csr.json

5.4 Generate the CA Certificate

Run the following command to generate the CA certificate and private key:

cfssl gencert -initca ca-csr.json | cfssljson -bare ca

This generates:

ca.pem: CA certificate
ca-key.pem: CA private key
ca.csr: Certificate signing request

5.5 Generate the ETCD Certificate

Run the following command to generate the ETCD certificate:

Get Opsboxstudio’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Commands:

cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -hostname=10.45.45.11,10.45.45.12,10.45.45.13,127.0.0.1,kubernetes.default -profile=server etcd-csr.json | cfssljson -bare etcd

This generates:

etcd.pem: ETCD certificate
etcd-key.pem: ETCD private key
etcd.csr: Certificate signing request

Note: The generated certificate must include the IP addresses and DNS names used by ETCD clients. The above certificate is a server-profile certificate and does not create separate server.pem and peer.pem files.

6. Copy Certificates to the ETCD SSL Directory

6.1 Copy Certificates on the First Node

sudo cp /root/etcd-cert/etcd.pem /etc/etcd/ssl/
sudo cp /root/etcd-cert/etcd-key.pem /etc/etcd/ssl/
sudo cp /root/etcd-cert/ca.pem /etc/etcd/ssl/

Press enter or click to view image in full size

6.2 Copy Certificates to the Other Nodes

Ensure SSH connectivity between all three servers.

Run the following commands from Node 1:

scp -rp /etc/etcd/ssl/* 10.45.45.12:/etc/etcd/ssl/
scp -rp /etc/etcd/ssl/* 10.45.45.13:/etc/etcd/ssl/

Security note: Protect the CA private key (ca-key.pem) and ETCD private keys. Avoid distributing the CA private key to every node.

7. Configure the ETCD Systemd Service

Create a systemd service file on each node.

vi /etc/systemd/system/etcd.service

7.1 Node 1 Configuration

[Unit]
Description=etcd - distributed reliable key-value store
Documentation=https://etcd.io/docs/
Wants=network-online.target
After=network-online.target

[Service]
Type=notify
User=etcd
Group=etcd
WorkingDirectory=/app/data/etcdExecStart=/usr/local/bin/etcd \
  --name=ubuntu1 \
  --data-dir=/app/data/etcd \
  --listen-client-urls=https://10.45.45.11:2379,https://127.0.0.1:2379 \
  --advertise-client-urls=https://10.45.45.11:2379 \
  --listen-peer-urls=https://10.45.45.11:2380 \
  --initial-advertise-peer-urls=https://10.45.45.11:2380 \
  --initial-cluster=ubuntu1=https://10.45.45.11:2380,ubuntu2=https://10.45.45.12:2380,ubuntu3=https://10.45.45.13:2380 \
  --initial-cluster-state=new \
  --initial-cluster-token=etcd-cluster-01 \
  --client-cert-auth=true \
  --trusted-ca-file=/etc/etcd/ssl/ca.pem \
  --cert-file=/etc/etcd/ssl/server.pem \
  --key-file=/etc/etcd/ssl/server-key.pem \
  --peer-client-cert-auth=true \
  --peer-trusted-ca-file=/etc/etcd/ssl/ca.pem \
  --peer-cert-file=/etc/etcd/ssl/peer.pem \
  --peer-key-file=/etc/etcd/ssl/peer-key.pemRestart=on-failure
RestartSec=5
LimitNOFILE=65536[Install]
WantedBy=multi-user.target

7.2 Node 2 Configuration

vi /etc/systemd/system/etcd.service

[Unit]
Description=etcd - distributed reliable key-value store
Documentation=https://etcd.io/docs/
Wants=network-online.target
After=network-online.target

[Service]
Type=notify
User=etcd
Group=etcd
WorkingDirectory=/app/data/etcdExecStart=/usr/local/bin/etcd \
  --name=ubuntu2 \
  --data-dir=/app/data/etcd \
  --listen-client-urls=https://10.45.45.12:2379,https://127.0.0.1:2379 \
  --advertise-client-urls=https://10.45.45.12:2379 \
  --listen-peer-urls=https://10.45.45.12:2380 \
  --initial-advertise-peer-urls=https://10.45.45.12:2380 \
  --initial-cluster=ubuntu1=https://10.45.45.11:2380,ubuntu2=https://10.45.45.12:2380,ubuntu3=https://10.45.45.13:2380 \
  --initial-cluster-state=new \
  --initial-cluster-token=etcd-cluster-01 \
  --client-cert-auth=true \
  --trusted-ca-file=/etc/etcd/ssl/ca.pem \
  --cert-file=/etc/etcd/ssl/server.pem \
  --key-file=/etc/etcd/ssl/server-key.pem \
  --peer-client-cert-auth=true \
  --peer-trusted-ca-file=/etc/etcd/ssl/ca.pem \
  --peer-cert-file=/etc/etcd/ssl/peer.pem \
  --peer-key-file=/etc/etcd/ssl/peer-key.pemRestart=on-failure
RestartSec=5
LimitNOFILE=65536[Install]
WantedBy=multi-user.target

7.3 Node 3 Configuration

vi /etc/systemd/system/etcd.service

[Unit]
Description=etcd - distributed reliable key-value store
Documentation=https://etcd.io/docs/
Wants=network-online.target
After=network-online.target

[Service]
Type=notify
User=etcd
Group=etcd
WorkingDirectory=/app/data/etcdExecStart=/usr/local/bin/etcd \
  --name=ubuntu3 \
  --data-dir=/app/data/etcd \
  --listen-client-urls=https://10.45.45.13:2379,https://127.0.0.1:2379 \
  --advertise-client-urls=https://10.45.45.13:2379 \
  --listen-peer-urls=https://10.45.45.13:2380 \
  --initial-advertise-peer-urls=https://10.45.45.13:2380 \
  --initial-cluster=ubuntu1=https://10.45.45.11:2380,ubuntu2=https://10.45.45.12:2380,ubuntu3=https://10.45.45.13:2380 \
  --initial-cluster-state=new \
  --initial-cluster-token=etcd-cluster-01 \
  --client-cert-auth=true \
  --trusted-ca-file=/etc/etcd/ssl/ca.pem \
  --cert-file=/etc/etcd/ssl/server.pem \
  --key-file=/etc/etcd/ssl/server-key.pem \
  --peer-client-cert-auth=true \
  --peer-trusted-ca-file=/etc/etcd/ssl/ca.pem \
  --peer-cert-file=/etc/etcd/ssl/peer.pem \
  --peer-key-file=/etc/etcd/ssl/peer-key.pemRestart=on-failure
RestartSec=5
LimitNOFILE=65536[Install]
WantedBy=multi-user.target

8. Configure ETCD Service Permissions

Set the appropriate permissions for the service file:

chmod 755 /etc/systemd/system/etcd.service

Press enter or click to view image in full size

Reload systemd and enable ETCD to start automatically at boot:

systemctl daemon-reload
systemctl enable etcd

Press enter or click to view image in full size

9. Start and Verify the ETCD Service

9.1 Start ETCD

Run on all three nodes:

systemctl start etcd

9.2 Check ETCD Service Status

systemctl status etcd

9.3 Check ETCD Logs

journalctl -u etcd -f

10. Verify ETCD Cluster Health

Run the following command to check the health of all cluster endpoints:

etcdctl   --endpoints=https://10.45.45.11:2379   --cacert=/etc/etcd/ssl/ca.pem   --cert=/etc/etcd/ssl/etcd.pem   --key=/etc/etcd/ssl/etcd-key.pem   endpoint health --cluster -w table

11. Configure ETCDCTL Connection Options

Set the environment variables on an ETCD node:

export ETCDCTL_API=3

export ETCDCTL_ENDPOINTS="https://127.0.0.1:2379"
export ETCDCTL_CACERT="/etc/etcd/ssl/ca.pem"
export ETCDCTL_CERT="/etc/etcd/ssl/etcd.pem"
export ETCDCTL_KEY="/etc/etcd/ssl/etcd-key.pem"

These variables allow etcdctl to connect to the local ETCD endpoint using TLS certificates.

12. Perform ETCD Key-Value Operations

12.1 Create a Key-Value Pair

etcdctl put test/key "Hello etcd"

12.2 Read a Key-Value Pair

etcdctl get test/key

12.3 Update a Key-Value Pair

etcdctl put test/key "Updated value"

Verify the updated value:

12.4 Create Multiple Key-Value Entries

etcdctl put test/name "etcd-cluster"
etcdctl put test/environment "production"
etcdctl put test/status "active"

12.5 List All Keys Under the `test/` Prefix

etcdctl get test/ --prefix

12.6 Delete a Specific Key

etcdctl del test/key

12.7 Verify Key Deletion

If the key has been deleted, the command returns no key-value pair.

13. Troubleshooting

13.1 Check ETCD Service Logs

journalctl -u etcd -n 100 --no-pager

13.2 Check Listening Ports

ss -lntp | grep -E '2379|2380'

13.3 Check Cluster Member Status

etcdctl endpoint status --cluster -w table

13.4 Check Cluster Health

etcdctl endpoint health --cluster

13.5 Verify Certificate Details

openssl x509 -in /etc/etcd/ssl/etcd.pem -text -noout

Opsboxstudio

HA ETCD Cluster Setup

ETCD Cluster Installation and Configuration Guide

1. Overview

1.1 Cluster Architecture

1.2 Ports

1.3 Prerequisites

2. Install CFSSL

2.1 Download CFSSL Binaries

2.2 Add Execution Permissions

2.3 Move Binaries to /usr/local/bin

2.4 Verify CFSSL Installation

3. Install ETCD

3.1 Create the ETCD Directory

3.2 Download the ETCD Release

3.3 Extract the ETCD Archive

3.4 Add Execution Permissions

3.5 Move ETCD Binaries

3.6 Verify ETCD Installation

4. Create ETCD Directories

5. Generate TLS Certificates

5.1 Create the CA Configuration File

5.2 Create the CA Certificate Signing Request

5.3 Create the ETCD Certificate Signing Request

5.4 Generate the CA Certificate

5.5 Generate the ETCD Certificate

Get Opsboxstudio’s stories in your inbox

6. Copy Certificates to the ETCD SSL Directory

6.1 Copy Certificates on the First Node

6.2 Copy Certificates to the Other Nodes

7. Configure the ETCD Systemd Service

7.1 Node 1 Configuration

7.2 Node 2 Configuration

7.3 Node 3 Configuration

8. Configure ETCD Service Permissions

9. Start and Verify the ETCD Service

9.1 Start ETCD

9.2 Check ETCD Service Status

9.3 Check ETCD Logs

10. Verify ETCD Cluster Health

11. Configure ETCDCTL Connection Options

12. Perform ETCD Key-Value Operations

12.1 Create a Key-Value Pair

12.2 Read a Key-Value Pair

12.3 Update a Key-Value Pair

12.4 Create Multiple Key-Value Entries

12.5 List All Keys Under the test/ Prefix

12.6 Delete a Specific Key

12.7 Verify Key Deletion

13. Troubleshooting

13.1 Check ETCD Service Logs

13.2 Check Listening Ports

13.3 Check Cluster Member Status

13.4 Check Cluster Health

13.5 Verify Certificate Details

Written by Opsboxstudio

No responses yet

More from Opsboxstudio

Jenkins Standalone Setup

Installation of Java

Jenkins Standalone Setup

Installation of Java

Recommended from Medium

Kubernetes Cost Optimization: 15 Proven Ways to Reduce Cloud Costs

Kubernetes makes it possible to run highly scalable applications across cloud infrastructure, but that flexibility can come with a…

How to Scale PostgreSQL Reads and Writes: From Query Optimization to Sharding

Your application generates 3,000 database reads and 200 writes per second. Requests are getting slower during busy periods, and the spare…

Howto Install a Single-Node Microceph Cluster

OK, I’m really having problems when I try to run my Openshift cluster and Microceph cluster at the same Vmware Workstation lab environment…

Integrating Trend Micro Vision One Logs with Wazuh: Syslog, CEF Decoders, and Rules

This walkthrough documents a syslog-to-Wazuh workflow using CEF messages whose headers identify Trend Micro Deep Security Agent and Deep…

Helm in Kubernetes: A Beginner-Friendly Guide to Managing Applications

A practical beginner-friendly guide to Kubernetes package management, Helm charts, templates, releases, upgrades, and rollbacks.

We Added OpenTelemetry Zero-Code Instrumentation Without Replacing Prometheus

We had 214 Prometheus alert rules.

No responses yet

More from Opsboxstudio

Jenkins Standalone Setup

Installation of Java

Jenkins Standalone Setup

2.3 Move Binaries to `/usr/local/bin`

12.5 List All Keys Under the `test/` Prefix