etcd Deployment and Usage Guide

Prerequisites

Go (version 1.19 or later) - etcd is written in Go
Operating System: Linux, macOS, or Windows
Memory: Minimum 2GB RAM recommended for production deployments
Storage: Sufficient disk space for write-ahead logs and snapshots
Network: TCP ports 2379 (client communication) and 2380 (server-to-server communication)

Installation

Using Pre-built Binaries

The easiest way to get etcd is to use pre-built release binaries:

# Download the latest release
wget https://github.com/etcd-io/etcd/releases/latest/download/etcd-$(uname -s)-$(uname -m).tar.gz

# Extract the archive
tar xzvf etcd-$(uname -s)-$(uname -m).tar.gz

# Move etcd to system path
sudo mv etcd-$(uname -s)-$(uname -m)/etcd* /usr/local/bin/

Building from Source

# Clone the repository
git clone https://github.com/etcd-io/etcd.git
cd etcd

# Build etcd
make

# Verify installation
./bin/etcd --version
./bin/etcdctl version

Using Docker

# Pull the latest etcd image
docker pull etcd

# Run etcd
docker run -d --name etcd -p 2379:2379 -p 2380:2380 etcd

Configuration

Environment Variables

ETCD_DATA_DIR: Path to the data directory (default: /tmp/etcd)
ETCD_LISTEN_CLIENT_URLS: URLs to listen on for client traffic (default: http://localhost:2379)
ETCD_ADVERTISE_CLIENT_URLS: Client URLs to advertise to the public (default: http://localhost:2379)

Configuration File

Create a configuration file (e.g., etcd.conf.yml):

name: 'etcd-cluster'
data-dir: '/var/lib/etcd'
listen-client-urls: 'http://localhost:2379'
advertise-client-urls: 'http://localhost:2379'
initial-cluster: 'etcd0=http://localhost:2380,etcd1=http://localhost:2381'
initial-cluster-token: 'etcd-cluster-token'
initial-cluster-state: 'new'

Authentication Configuration

# Enable authentication
etcdctl auth enable

# Add a new user
etcdctl user add root:rootpass

# Grant root role to user
etcdctl user grant-role root root

Build & Run

Local Development

# Start a single-member cluster
etcd

# Start with configuration file
etcd --config-file etcd.conf.yml

# Start a local cluster using goreman
goreman start

Production Deployment

# Start etcd with TLS enabled
etcd \
  --cert-file=/path/to/server.crt \
  --key-file=/path/to/server.key \
  --client-cert-auth \
  --trusted-ca-file=/path/to/ca.crt

# Start with specific data directory
etcd --data-dir /var/lib/etcd/data

Using etcdctl

# Put a key-value pair
etcdctl put mykey "this is awesome"

# Get a value
etcdctl get mykey

# List all keys
etcdctl get --prefix ""

# Watch for changes
etcdctl watch --prefix mykey

Deployment

Kubernetes Deployment

# etcd.yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: etcd
spec:
  serviceName: etcd
  replicas: 3
  selector:
    matchLabels:
      app: etcd
  template:
    metadata:
      labels:
        app: etcd
    spec:
      containers:
      - name: etcd
        image: etcd:latest
        ports:
        - containerPort: 2379
          name: client
        - containerPort: 2380
          name: server
        env:
        - name: ETCD_INITIAL_CLUSTER
          value: "etcd-0=http://etcd-0.etcd:2380,etcd-1=http://etcd-1.etcd:2380,etcd-2=http://etcd-2.etcd:2380"

Cloud Deployment

AWS: Deploy on EC2 instances with EBS storage for data persistence

Google Cloud: Use Compute Engine with persistent disks

Azure: Deploy on Virtual Machines with managed disks

Docker Compose

# docker-compose.yml
version: '3'
services:
  etcd:
    image: etcd:latest
    ports:
      - "2379:2379"
      - "2380:2380"
    volumes:
      - etcd-data:/etcd-data
volumes:
  etcd-data:

Troubleshooting

Common Issues

Issue: etcd fails to start with port already in use

# Check for running processes
lsof -i :2379

# Kill conflicting processes
kill -9 <PID>

Issue: Connection refused when using etcdctl

# Check if etcd is running
ps aux | grep etcd

# Verify client URLs
etcdctl --endpoints http://localhost:2379 endpoint health

Issue: Raft internal errors

# Check etcd logs
journalctl -u etcd

# Verify cluster configuration
etcdctl member list

Issue: Authentication errors

# Check authentication status
etcdctl auth status

# Verify user credentials
etcdctl user get root

Performance Issues

High memory usage:

Increase system memory
Adjust ETCD_HEARTBEAT_INTERVAL and ETCD_ELECTION_TIMEOUT
Monitor with etcdctl endpoint status

Slow writes:

Check disk I/O performance
Increase ETCD_SNAPSHOT_COUNT
Monitor with etcdctl alarm list

Recovery Procedures

Corrupted data directory:

# Backup data
cp -r /var/lib/etcd /tmp/etcd-backup

# Remove corrupted data
rm -rf /var/lib/etcd/member

# Restart etcd (it will rebuild the data directory)
systemctl restart etcd

Lost member recovery:

# Remove failed member
etcdctl member remove <member-id>

# Add new member
etcdctl member add <new-member-name> http://<new-member-ip>:2380

# Start new member with correct configuration
etcd --initial-cluster <updated-cluster-config>

Monitoring

# Check cluster health
etcdctl endpoint health

# Monitor metrics
etcdctl endpoint status

# Check version compatibility
etcdctl version

For more detailed documentation, visit etcd.io/docs.

How to Deploy & Use coreos/etcd