etcd Distributed Config with Python — Core Concepts

What etcd is

etcd is a distributed key-value store designed for configuration data, service discovery, and coordination. Developed by CoreOS (now part of Red Hat), it uses the Raft consensus algorithm to replicate data across a cluster of nodes, guaranteeing strong consistency.

The name comes from the Unix /etc directory (where configuration files live) plus “d” for distributed.

Why Python apps need distributed config

Single-server applications can read config from files or environment variables. But when your Python service runs as multiple instances — behind a load balancer, in Kubernetes, or across data centers — you need a shared config source that:

• Provides the same values to all instances simultaneously
• Notifies instances when values change (no polling delay)
• Survives server failures without losing data
• Supports atomic updates so partial changes never propagate

etcd delivers all four. This is why Kubernetes chose it as its backing store — every pod definition, service endpoint, and config map ultimately lives in etcd.

Core features

Key-value storage — etcd stores data as key-value pairs. Keys are organized hierarchically using paths like /config/myapp/database_url. Values are bytes (typically UTF-8 strings or JSON).

Strong consistency — every read returns the most recent write. There’s no “stale data” window. This is guaranteed by the Raft consensus protocol, which requires a majority of nodes to agree before a write is committed.

Watch mechanism — clients can subscribe to changes on a key or key prefix. When any write occurs, etcd pushes the change to all watchers immediately. This enables real-time configuration updates.

Leases and TTL — keys can be attached to leases with a time-to-live. When the lease expires, the key is deleted. This is used for service registration: a service registers itself with a lease and periodically renews it. If the service crashes, the lease expires and the registration disappears.

Transactions — etcd supports compare-and-swap operations: “if key X equals Y, then set it to Z.” This enables distributed locking and leader election without race conditions.

Using etcd from Python

The etcd3 library provides a Pythonic interface:

import etcd3

client = etcd3.client(host="etcd.internal", port=2379)

# Write a configuration value
client.put("/config/myapp/rate_limit", "200")

# Read it back
value, metadata = client.get("/config/myapp/rate_limit")
print(value.decode())  # "200"

# List all config keys for an app
for value, metadata in client.get_prefix("/config/myapp/"):
    print(f"{metadata.key.decode()} = {value.decode()}")

Watch for real-time updates

The watch feature is etcd’s most powerful capability for Python services:

def handle_config_change(event):
    key = event.key.decode()
    value = event.value.decode()
    print(f"Config changed: {key} = {value}")

# Watch all keys under /config/myapp/
watch_id = client.add_watch_prefix_callback(
    "/config/myapp/",
    handle_config_change,
)

This callback fires immediately when any key under the prefix changes — no polling interval, no delay. Your Python service can react to configuration changes in milliseconds.

Common misconception

Developers sometimes confuse etcd with Redis or general-purpose databases. etcd is not designed for high-throughput data storage. It’s optimized for small amounts of critical configuration data with strong consistency guarantees. A typical etcd cluster stores megabytes of config, not gigabytes of application data. Using etcd as a cache or data store will perform poorly and isn’t its intended use.

Use cases for Python applications

Feature flags — store flag values in etcd, watch for changes, and toggle features across all service instances without redeployment.

Database connection strings — update the database URL in etcd during a migration, and all services switch over simultaneously.

Service discovery — services register themselves in etcd with leases. Other services watch for registrations to discover available endpoints.

Leader election — when only one instance of a Python service should perform a task (like a scheduled job), etcd’s transactions enable safe leader election.

Rate limit coordination — share rate limit counters across service instances using etcd’s atomic operations.

etcd vs alternatives

etcd competes with Consul (HashiCorp) and ZooKeeper (Apache). Consul adds service mesh and health checking features. ZooKeeper is older and has a more complex API. etcd’s advantage is simplicity, a clean gRPC API, and being the Kubernetes standard. For Python teams already running Kubernetes, etcd is already there.

The one thing to remember: etcd gives Python services a reliable, consistent shared configuration store with real-time change notifications — making it the foundation for dynamic configuration in distributed systems.