Sign inSign up

globalartltd/etcd

By globalartltd

•Updated 12 months ago

Image
0

147

globalartltd/etcd repository overview

⁠etcd Docker Image

Dockerfile for building etcd distributed key-value store from source.

⁠Overview

This project builds etcd from source using a multi-stage Docker build:

  • Stage 1: Compiles etcd from GitHub sources using Go
  • Stage 2: Creates minimal Alpine-based runtime image

⁠Features

  • ✅ Configurable version (build-time argument)
  • ✅ Environment variable configuration (no hardcoded values)
  • ✅ Small image size (Alpine-based)
  • ✅ Persistent data support
  • ✅ Production-ready defaults

⁠Quick Start

⁠Build Image
./build.sh

Or build specific version:

./build.sh v3.5.15

Or using Docker directly:

docker build -t etcd:3.6.4 .
⁠Run Single Node
docker run -d \
  --name etcd \
  -p 2379:2379 \
  -p 2380:2380 \
  etcd:3.6.4
⁠Run with Persistent Data
docker run -d \
  --name etcd \
  -p 2379:2379 \
  -p 2380:2380 \
  -v etcd-data:/var/lib/etcd \
  etcd:3.6.4
⁠Test Connection
docker exec etcd etcdctl version
docker exec etcd etcdctl put mykey "Hello etcd"
docker exec etcd etcdctl get mykey

⁠Configuration

⁠Environment Variables

All configuration is done via environment variables with sensible defaults:

VariableDefaultDescription
ETCD_NAMEetcd-nodeNode name
ETCD_DATA_DIR/var/lib/etcdData directory path
ETCD_LISTEN_CLIENT_URLShttp://0.0.0.0:2379Client URLs to listen on
ETCD_ADVERTISE_CLIENT_URLShttp://0.0.0.0:2379Client URLs to advertise
ETCD_LISTEN_PEER_URLShttp://0.0.0.0:2380Peer URLs to listen on
ETCD_INITIAL_ADVERTISE_PEER_URLShttp://0.0.0.0:2380Peer URLs to advertise
ETCD_INITIAL_CLUSTER${ETCD_NAME}=${ETCD_INITIAL_ADVERTISE_PEER_URLS}Initial cluster configuration
ETCD_INITIAL_CLUSTER_STATEnewInitial cluster state (new or existing)
ETCD_INITIAL_CLUSTER_TOKENetcd-clusterCluster token for identification
⁠Custom Configuration
docker run -d \
  --name etcd \
  -p 2379:2379 \
  -p 2380:2380 \
  -e ETCD_NAME=my-node \
  -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://etcd.example.com:2379 \
  -e ETCD_INITIAL_CLUSTER_TOKEN=my-cluster \
  etcd:3.6.4
⁠Using Environment File

Create .env file:

ETCD_NAME=production-node-1
ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
ETCD_ADVERTISE_CLIENT_URLS=http://10.0.1.10:2379
ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
ETCD_INITIAL_ADVERTISE_PEER_URLS=http://10.0.1.10:2380
ETCD_INITIAL_CLUSTER_STATE=new
ETCD_INITIAL_CLUSTER_TOKEN=prod-cluster

Run with env file:

docker run -d --name etcd -p 2379:2379 -p 2380:2380 --env-file .env etcd:3.6.4

⁠Cluster Setup

⁠3-Node Cluster

Create network:

docker network create etcd-net

Node 1:

docker run -d \
  --name etcd1 \
  --network etcd-net \
  -p 2379:2379 \
  -p 2380:2380 \
  -e ETCD_NAME=etcd1 \
  -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://etcd1:2379 \
  -e ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380 \
  -e ETCD_INITIAL_ADVERTISE_PEER_URLS=http://etcd1:2380 \
  -e ETCD_INITIAL_CLUSTER="etcd1=http://etcd1:2380,etcd2=http://etcd2:2380,etcd3=http://etcd3:2380" \
  -e ETCD_INITIAL_CLUSTER_STATE=new \
  -e ETCD_INITIAL_CLUSTER_TOKEN=etcd-cluster-1 \
  etcd:3.6.4

Node 2:

docker run -d \
  --name etcd2 \
  --network etcd-net \
  -p 2479:2379 \
  -p 2480:2380 \
  -e ETCD_NAME=etcd2 \
  -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://etcd2:2379 \
  -e ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380 \
  -e ETCD_INITIAL_ADVERTISE_PEER_URLS=http://etcd2:2380 \
  -e ETCD_INITIAL_CLUSTER="etcd1=http://etcd1:2380,etcd2=http://etcd2:2380,etcd3=http://etcd3:2380" \
  -e ETCD_INITIAL_CLUSTER_STATE=new \
  -e ETCD_INITIAL_CLUSTER_TOKEN=etcd-cluster-1 \
  etcd:3.6.4

Node 3:

docker run -d \
  --name etcd3 \
  --network etcd-net \
  -p 2579:2379 \
  -p 2580:2380 \
  -e ETCD_NAME=etcd3 \
  -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://etcd3:2379 \
  -e ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380 \
  -e ETCD_INITIAL_ADVERTISE_PEER_URLS=http://etcd3:2380 \
  -e ETCD_INITIAL_CLUSTER="etcd1=http://etcd1:2380,etcd2=http://etcd2:2380,etcd3=http://etcd3:2380" \
  -e ETCD_INITIAL_CLUSTER_STATE=new \
  -e ETCD_INITIAL_CLUSTER_TOKEN=etcd-cluster-1 \
  etcd:3.6.4

Verify cluster:

docker exec etcd1 etcdctl --endpoints=http://etcd1:2379,http://etcd2:2379,http://etcd3:2379 endpoint health
docker exec etcd1 etcdctl member list

⁠Operations

⁠Check Version
docker exec etcd etcd --version
docker exec etcd etcdctl version
⁠View Logs
docker logs etcd
docker logs -f etcd
⁠Health Check
docker exec etcd etcdctl endpoint health
docker exec etcd etcdctl endpoint status --write-out=table
⁠Backup Data
docker exec etcd etcdctl snapshot save /tmp/snapshot.db
docker cp etcd:/tmp/snapshot.db ./backup-$(date +%Y%m%d-%H%M%S).db
⁠Restore from Backup
docker cp backup.db etcd:/tmp/backup.db
docker exec etcd etcdctl snapshot restore /tmp/backup.db \
  --data-dir=/var/lib/etcd-restore \
  --name=etcd-node \
  --initial-cluster=etcd-node=http://0.0.0.0:2380
⁠Access Shell
docker exec -it etcd /bin/sh

⁠Version Compatibility

etcd VersionRequired Go VersionDockerfile Support
v3.5.xGo 1.19+✅
v3.6.xGo 1.21+✅

The Dockerfile uses Go 1.23 which supports all recent etcd versions.

Available versions: https://github.com/etcd-io/etcd/tags⁠

⁠Build Arguments

Build with specific version:

docker build --build-arg ETCD_VERSION=v3.5.15 -t etcd:3.5.15 .

⁠Ports

  • 2379 - Client communication
  • 2380 - Peer communication

⁠Volumes

  • /var/lib/etcd - Data directory (recommended to mount for persistence)

⁠Troubleshooting

⁠Build fails with "invalid go version" error

Error:

invalid go version '1.23.0': must match format 1.23
unknown directive: toolchain

Solution: Update Go version in Dockerfile:

FROM golang:1.23-alpine AS builder
⁠Container exits immediately

Check logs:

docker logs etcd

Common causes:

  • Port already in use
  • Data directory permissions
  • Configuration errors
⁠Can't connect to etcd

Verify container is running:

docker ps | grep etcd

Check if port is exposed:

docker port etcd

Test connection:

docker exec etcd etcdctl endpoint health
⁠Data not persisting

Use volume:

docker run -d \
  --name etcd \
  -p 2379:2379 \
  -p 2380:2380 \
  -v etcd-data:/var/lib/etcd \
  etcd:3.6.4
⁠Cluster nodes can't communicate

Ensure same network:

docker network create etcd-net
docker run --network etcd-net ...

Check firewall rules:

docker exec etcd1 ping etcd2

⁠Performance Tuning

⁠Resource Limits
docker run -d \
  --name etcd \
  --cpus="2" \
  --memory="2g" \
  -p 2379:2379 \
  -p 2380:2380 \
  etcd:3.6.4
⁠Restart Policy
docker run -d \
  --name etcd \
  --restart unless-stopped \
  -p 2379:2379 \
  -p 2380:2380 \
  etcd:3.6.4

⁠Examples

⁠Development Setup
docker run -d \
  --name etcd-dev \
  -p 2379:2379 \
  -p 2380:2380 \
  etcd:3.6.4
⁠Production Setup
docker run -d \
  --name etcd-prod \
  --restart unless-stopped \
  --cpus="4" \
  --memory="4g" \
  -p 2379:2379 \
  -p 2380:2380 \
  -v etcd-prod-data:/var/lib/etcd \
  -e ETCD_NAME=prod-node-1 \
  -e ETCD_INITIAL_CLUSTER_TOKEN=prod-cluster \
  etcd:3.6.4

⁠Security Considerations

  1. Use volumes for data persistence
  2. Set resource limits to prevent resource exhaustion
  3. Use networks to isolate etcd communication
  4. Enable TLS for production (configure via environment variables)
  5. Regular backups of data directory

⁠Additional Resources

⁠License

This Dockerfile configuration follows the etcd project license. See etcd LICENSE⁠.

Tag summary

Content type

Image

Digest

sha256:efdad2830…

Size

58.7 MB

Last updated

12 months ago

docker pull globalartltd/etcd:3.6.5