globalartltd/etcd

By globalartltd

•Updated 12 months ago

Image

147

Overview Tags

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:

Variable	Default	Description
`ETCD_NAME`	`etcd-node`	Node name
`ETCD_DATA_DIR`	`/var/lib/etcd`	Data directory path
`ETCD_LISTEN_CLIENT_URLS`	`http://0.0.0.0:2379`	Client URLs to listen on
`ETCD_ADVERTISE_CLIENT_URLS`	`http://0.0.0.0:2379`	Client URLs to advertise
`ETCD_LISTEN_PEER_URLS`	`http://0.0.0.0:2380`	Peer URLs to listen on
`ETCD_INITIAL_ADVERTISE_PEER_URLS`	`http://0.0.0.0:2380`	Peer URLs to advertise
`ETCD_INITIAL_CLUSTER`	`${ETCD_NAME}=${ETCD_INITIAL_ADVERTISE_PEER_URLS}`	Initial cluster configuration
`ETCD_INITIAL_CLUSTER_STATE`	`new`	Initial cluster state (`new` or `existing`)
`ETCD_INITIAL_CLUSTER_TOKEN`	`etcd-cluster`	Cluster 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 Version	Required Go Version	Dockerfile Support
v3.5.x	Go 1.19+	✅
v3.6.x	Go 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

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

⁠Additional Resources

⁠License

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

Tag summary

Recent tags

Content type

Image

Digest

sha256:efdad2830…

Size

58.7 MB

Last updated

12 months ago

docker pull globalartltd/etcd:3.6.5