Note: This is a divergent fork of kelseyhightower/confd. Backward compatibility is not guaranteed. YMMV

confd

confd is a lightweight configuration management tool focused on:

• keeping local configuration files up-to-date using data stored in etcd, consul, dynamodb, redis, vault, zookeeper, aws ssm parameter store, aws secrets manager, aws acm, aws ec2 imds, or env vars and processing template resources.
• reloading applications to pick up new config file changes

Features

• Multiple Backends: etcd, Consul, Vault, DynamoDB, Redis, Zookeeper, AWS SSM/Secrets Manager/ACM/IMDS, environment variables, and files
• Template Processing: Go text/template with custom functions for configuration generation
• Watch Mode: Real-time config updates for supported backends (Consul, etcd, Redis, Zookeeper, file)
• Polling Mode: Configurable interval-based polling for all backends
• Validation: Pre-flight checks, template validation, and configuration validation
• Metrics: Prometheus metrics for observability (backend operations, template processing, commands)
• Health Checks: HTTP endpoints for health and readiness checks
• Structured Logging: JSON and text formats with timing metrics
• Resilience: Configurable timeouts, retries, and failure modes (best-effort/fail-fast)
• Performance: Template caching and backend client pooling

Installation

Docker

# Pull from Docker Hub
docker pull abtreece/confd:latest

# Or from GitHub Container Registry
docker pull ghcr.io/abtreece/confd:latest

# Run with env backend
docker run --rm \
  -e DATABASE_HOST=db.example.com \
  -v $(pwd)/conf.d:/etc/confd/conf.d:ro \
  -v $(pwd)/templates:/etc/confd/templates:ro \
  -v $(pwd)/output:/output \
  abtreece/confd:latest env --onetime

See Docker documentation for complete usage including Docker Compose and Kubernetes.

Building from Source

Go 1.26.2 is required to build confd. The module uses go 1.26 for language compatibility and toolchain go1.26.2 to pin the expected patch-level toolchain.

git clone https://github.com/abtreece/confd.git
cd confd
make build

You should now have confd in your bin/ directory:

ls bin/
confd

See Installation for more options including binary downloads.

Quick Start

One-time run with etcd

# Start with etcd backend
confd etcd --node http://127.0.0.1:2379 --onetime

# With environment variables
confd env --onetime

# With file backend
confd file --file /path/to/config.yaml --onetime

Watch mode for real-time updates

# Watch etcd for changes
confd etcd --node http://127.0.0.1:2379 --watch

# Watch with debouncing (wait 2s after changes settle)
confd etcd --watch --debounce 2s

# Batch processing (collect changes every 5s)
confd etcd --watch --batch-interval 5s

Interval polling

# Poll Vault every 60 seconds
confd vault --node http://127.0.0.1:8200 --interval 60 \
  --auth-type token --auth-token s.XXX

# Poll EC2 IMDS for instance metadata (on EC2 instances)
confd imds --interval 300

Metrics and Observability

Enable Prometheus metrics and health checks:

confd etcd --metrics-addr :9100

Endpoints:

• http://localhost:9100/metrics - Prometheus metrics
• http://localhost:9100/health - Health check
• http://localhost:9100/ready - Readiness check
• http://localhost:9100/ready/detailed - Detailed readiness

Metrics include:

• Backend request durations and error rates
• Template processing performance
• Command execution times
• Cache hit/miss rates
• File sync operations

Configuration

confd can be configured via:

1. Configuration file (/etc/confd/confd.toml)
2. Environment variables (prefix: CONFD_)
3. Command-line flags

Example confd.toml:

backend = "etcd"
log-level = "info"
log-format = "json"
interval = 600
nodes = ["http://127.0.0.1:2379"]
prefix = "/production"

# Timeouts
backend-timeout = "30s"
check-cmd-timeout = "30s"
reload-cmd-timeout = "60s"

# Retries
retry-max-attempts = 3
retry-base-delay = "100ms"
retry-max-delay = "5s"

# Metrics
metrics_addr = ":9100"

Service Deployment

confd is production-ready with support for systemd, Docker, and Kubernetes deployments.

Systemd Integration

Run confd as a systemd service with Type=notify support:

# Install service
sudo cp examples/systemd/confd.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable confd
sudo systemctl start confd

# Reload configuration without restarting
sudo systemctl reload confd

# Check status
sudo systemctl status confd

Key features:

• Graceful shutdown - Wait for in-flight operations before exit
• SIGHUP reload - Reload templates and configuration without downtime
• Watchdog support - Automatic restart if service becomes unresponsive
• Clean exits - Proper backend connection cleanup

See Service Deployment Guide for complete documentation including:

• systemd service configuration
• Docker deployment with signal forwarding
• Kubernetes manifests with health probes
• Monitoring and troubleshooting

Command-Line Flags

# Graceful shutdown timeout (default: 30s)
confd --shutdown-timeout=30s etcd --watch

# Systemd integration (Linux only)
confd --systemd-notify --watchdog-interval=30s etcd --watch

# Reload configuration
kill -HUP $(pidof confd)

Validation and Testing

Validate configuration

# Check template resource files
confd --check-config etcd

# Validate specific resource
confd --check-config --resource nginx.toml etcd

Preflight checks

# Test backend connectivity and authentication
confd --preflight etcd --node http://127.0.0.1:2379

Template validation

# Syntax check
confd --validate etcd

# With mock data
confd --validate --mock-data test-data.json etcd

Dry run with diff

# Show pending changes without applying
confd --noop --diff --color etcd

Documentation

See the full documentation index for all guides, organized by topic:

• Getting Started — Quick Start, Installation, Docker
• Configuration — Config Guide, CLI Flags, Template Resources, Template Functions
• Backends — per-backend READMs, Multi-Backend Architectures, DNS SRV Discovery
• Operating — Service Deployment, Logging, Noop Mode
• Development — Dev Guide, Architecture, Contributing

Supported Backends

Backend	Watch Mode	Polling	Authentication
etcd	✅	✅	Basic, TLS, Token
Consul	✅	✅	Basic, TLS, Token
Redis	✅	✅	Password
Zookeeper	✅	✅	None
Env	❌	✅	None
File	✅	✅	None
Vault	❌	✅	Token, AppRole, App-ID, Kubernetes
DynamoDB	❌	✅	AWS SDK
SSM	❌	✅	AWS SDK
Secrets Manager	❌	✅	AWS SDK
ACM	❌	✅	AWS SDK
IMDS	❌	✅	AWS SDK (IMDSv2)

Development

See the Development Guide for detailed instructions on setting up your environment, running tests, and adding new features.

Quick Start

# Build
make build

# Run tests
make test

# Run linter
make lint

# Integration tests (requires backend services)
make integration

Building Releases

# Snapshot build
make snapshot

# Release build
make release

See Release Checklist for the full release process.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Code style and commit conventions
• Pull request process
• Adding new backends or template functions

License

See LICENSE file.