etcd (Optional)

etcd is a distributed, key-value store designed for storing and managing configuration data with high availability and strong consistency guarantees in distributed systems. As of FlagFlow 1.5.0, etcd is optional - you can use filesystem storage instead for simpler deployments.

When to Use etcd vs Filesystem Storage

Choose etcd for:

✅ Production environments requiring high availability
✅ Multiple FlagFlow instances with real-time synchronization
✅ Distributed deployments across multiple servers/clusters
✅ Enterprise environments with complex infrastructure
✅ High-frequency flag changes requiring instant propagation

Choose Filesystem Storage for:

✅ Small companies without heavy infrastructure needs
✅ Development and testing environments
✅ Single-instance deployments (no replicas needed)
✅ Simple setups avoiding etcd complexity
✅ Cost-conscious deployments minimizing resource usage

💡 Recommendation: Start with filesystem storage for initial deployments and migrate to etcd when you need distributed features or real-time synchronization across multiple instances.

Why Choose etcd?

The etcd is a high-performance and reliable distributed key-value store that serves as the backbone for many cloud-native applications. It's most famously known as the configuration store for Kubernetes, where it's often referred to as the "heart" of Kubernetes because it stores all cluster state data. etcd's architecture ensures fast and reliable access to configuration data while providing real-time monitoring of cluster state changes through its sophisticated watch mechanism.

FlagFlow leverages etcd as its primary configuration data store because of its exceptional performance characteristics and efficient change notification system. Unlike traditional polling-based approaches, etcd's watch API not only notifies clients of changes but also delivers the updated data payload in a single operation, providing immediate access to the latest configuration state. This real-time synchronization capability is crucial for distributed FlagFlow deployments, where multiple application instances must stay synchronized with feature flag changes without the overhead of periodic polling or manual data refresh operations.

The watch mechanism operates through HTTP/2 streaming, ensuring low-latency updates across all connected FlagFlow instances. This architecture enables instant feature flag propagation, making it ideal for high-frequency flag toggles and real-time A/B testing scenarios where immediate consistency across all application nodes is essential.

Why not XY?

You might wonder why FlagFlow doesn't use alternative solutions like Redis, MongoDB, or PostgreSQL. While these are excellent technologies in their respective domains, etcd offers distinct advantages specifically designed for configuration management use cases. etcd was purpose-built for storing and managing small-scale, configuration-oriented data with exceptional speed, reliability, and horizontal scalability characteristics that align perfectly with FlagFlow's requirements.

Beyond performance considerations, etcd's native watch functionality provides a critical architectural advantage for feature flag management. This capability enables real-time configuration updates and immediate change notifications, ensuring that FlagFlow applications always operate with the most current flag states. This becomes particularly valuable in multi-instance deployments where consistent flag behavior across all application nodes is essential for maintaining user experience integrity and preventing feature flag inconsistencies.

Traditional database management systems, while powerful, introduce unnecessary complexity and overhead for FlagFlow's specific use case. We don't require relational data modeling, complex indexing strategies, heavyweight transaction processing, or advanced query optimization features that these systems provide. Additionally, managed database services typically employ usage-based pricing models that can become cost-prohibitive for high-frequency configuration access patterns common in feature flag systems.

etcd's lightweight footprint, combined with its RAFT consensus algorithm for distributed consistency, provides the optimal balance of simplicity, performance, and reliability needed for enterprise-grade feature flag management without the operational overhead and licensing costs associated with traditional database solutions.

etcd Client Library

FlagFlow uses the etcd3 library maintained by Microsoft for etcd connectivity. This high-performance Node.js client provides robust support for all etcd v3 API features including transactions, leases, and streaming watch operations that are essential for FlagFlow's real-time configuration updates.

The etcd3 library is actively maintained by Microsoft and offers excellent TypeScript support, making it the ideal choice for FlagFlow's architecture.

Installation

There are several approaches to deploy etcd for FlagFlow, depending on your infrastructure requirements and operational preferences. Choose the method that best aligns with your deployment strategy and maintenance capabilities.

Docker Compose Deployment Recommended for simple setups

For development environments and simple deployments, Docker Compose provides the fastest setup path. Later you can extend it with FlagFlow services in a single file. For complete FlagFlow Docker setup instructions, see Docker Installation Guide.

docker-compose.yml

version: '3.8'
services:
  etcd:
    image: bitnami/etcd:3.6.4-debian-12-r2
    container_name: flagflow-etcd
    environment:
      - ETCD_ROOT_PASSWORD=pw_flagflow
	# Not needed, because network allows communication between containers
    ports:
      - "2379:2379"
    volumes:
      - etcd-data:/bitnami/etcd
    networks:
      - flagflow-network
	# Health check is not mandatory, but recommended in production
	healthcheck:
		test: ["CMD", "etcdctl", "--user=root:pw_flagflow", "endpoint", "health"]
		interval: 15s
		timeout: 10s
		retries: 2
	restart: on-failure

volumes:
  etcd-data:

networks:
  flagflow-network:
    driver: bridge

Kubernetes Deployment Recommended for production setups

For production Kubernetes environments, deploy etcd as a StatefulSet with persistent storage. For complete FlagFlow Kubernetes setup instructions, see Kubernetes Installation Guide.

etcd-statefulset.yaml

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: etcd
  namespace: flagflow
spec:
  serviceName: etcd
  replicas: 3
  selector:
    matchLabels:
      app: etcd
  template:
    metadata:
      labels:
        app: etcd
    spec:
      containers:
      - name: etcd
        image: bitnami/etcd:3.6.4-debian-12-r2
        ports:
        - containerPort: 2379
          name: client
        env:
        - name: ETCD_ROOT_PASSWORD
		  value: pw_flagflow
        volumeMounts:
        - name: etcd-data
          mountPath: /var/lib/etcd
        # Kubernetes healthchecks for production reliability
        livenessProbe:
          exec:
            command:
            - etcdctl
            - --user=root:pw_flagflow
            - endpoint
            - health
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3
        readinessProbe:
          exec:
            command:
            - etcdctl
            - --user=root:pw_flagflow
            - endpoint
            - health
          initialDelaySeconds: 15
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 2
  volumeClaimTemplates:
  - metadata:
      name: etcd-data
    spec:
      accessModes: [ "ReadWriteOnce" ]
      resources:
        requests:
          storage: 1Gi

Binary Installation If you have a bare-metal or VM setup

For direct server installations, download and install etcd binaries and set up as a systemd service:

etcd-binary-install.sh

wget https://github.com/etcd-io/etcd/releases/download/v3.6.4-debian-12-r2/etcd-v3.6.4-debian-12-r2-linux-amd64.tar.gz
tar -xzf etcd-v3.6.4-debian-12-r2-linux-amd64.tar.gz
sudo mv etcd-v3.6.4-debian-12-r2-linux-amd64/etcd* /usr/local/bin/

/etc/systemd/system/etcd.service

[Unit]
Description=etcd key-value store
Documentation=https://github.com/etcd-io/etcd
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/etcd \
  --name etcd-server \
  --data-dir=/var/lib/etcd \
  --listen-client-urls=http://0.0.0.0:2379 \
  --advertise-client-urls=http://localhost:2379 \
  --listen-peer-urls=http://0.0.0.0:2380 \
  --initial-advertise-peer-urls=http://localhost:2380 \
  --initial-cluster=etcd-server=http://localhost:2380
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target

Enable and start etcd

sudo systemctl enable etcd
sudo systemctl start etcd

Check etcd connection

After configuration, verify the connection using etcd client tools:

Connection Verification

# Test basic connectivity
etcdctl --endpoints=http://etcd-server:2379 endpoint health

# Check FlagFlow data structure
etcdctl --endpoints=http://etcd-server:2379 get --prefix /flagflow/

# Monitor real-time changes (useful for debugging)
etcdctl --endpoints=http://etcd-server:2379 watch --prefix /flagflow/

FlagFlow Configuration

Once etcd is deployed, configure FlagFlow to connect to your etcd instance. The configuration approach varies depending on your FlagFlow deployment method.

Configuration with ENVs

ETCD_SERVER=etcd-server:2379
ETCD_USERNAME=flagflow
ETCD_PASSWORD=**********
ETCD_NAMESPACE=default

On this page