etcd

etcd Backend

The etcd backend enables confd to retrieve configuration data from etcd, a distributed key-value store. This backend uses the etcd v3 API.

Configuration

Basic Connection

Connect to etcd without authentication:

confd etcd --node http://127.0.0.1:2379 --onetime

Multiple nodes for high availability:

confd etcd \
  --node http://etcd1.example.com:2379 \
  --node http://etcd2.example.com:2379 \
  --node http://etcd3.example.com:2379 --onetime

Authentication

Username/Password

confd etcd --node http://127.0.0.1:2379 \
  --basic-auth --username admin --password secret --onetime

TLS Client Certificates

confd etcd --node https://127.0.0.1:2379 \
  --client-cert /path/to/client.crt \
  --client-key /path/to/client.key \
  --client-ca-keys /path/to/ca.crt --onetime

TLS with Authentication

confd etcd --node https://127.0.0.1:2379 \
  --client-cert /path/to/client.crt \
  --client-key /path/to/client.key \
  --client-ca-keys /path/to/ca.crt \
  --basic-auth --username admin --password secret --onetime

Options

Basic Example

Add keys to etcd:

etcdctl put /myapp/database/url "db.example.com"
etcdctl put /myapp/database/user "admin"
etcdctl put /myapp/database/password "secret123"

Create template resource (/etc/confd/conf.d/myapp.toml):

[template]
src = "myapp.conf.tmpl"
dest = "/etc/myapp/config.conf"
keys = [
  "/myapp/database",
]

Create template (/etc/confd/templates/myapp.conf.tmpl):

[database]
url = {{getv "/myapp/database/url"}}
user = {{getv "/myapp/database/user"}}
password = {{getv "/myapp/database/password"}}

Run confd:

confd etcd --node http://127.0.0.1:2379 --onetime

Advanced Example

Using DNS SRV Records

Discover etcd nodes via DNS SRV records:

confd etcd \
  --srv-record _etcd-client._tcp.example.com \
  --scheme https --onetime

Watch Mode with TLS

confd etcd \
  --node https://etcd.example.com:2379 \
  --client-ca-keys /etc/ssl/certs/etcd-ca.crt \
  --watch

Kubernetes Deployment

apiVersion: v1
kind: Pod
metadata:
  name: myapp
spec:
  containers:
  - name: myapp
    env:
    - name: ETCD_USERNAME
      valueFrom:
        secretKeyRef:
          name: etcd-credentials
          key: username
    - name: ETCD_PASSWORD
      valueFrom:
        secretKeyRef:
          name: etcd-credentials
          key: password
    command:
    - confd
    - etcd
    - --node=http://etcd.default.svc:2379
    - --basic-auth
    - --username=$(ETCD_USERNAME)
    - --password=$(ETCD_PASSWORD)
    - --watch

Watch Mode Support

Watch mode is supported for the etcd backend. confd uses etcd's native watch API for efficient real-time updates.

confd etcd --node http://127.0.0.1:2379 --watch

When keys change in etcd, confd immediately detects the change and re-renders affected templates.

Per-Resource Backend Configuration

Instead of using the global backend, individual template resources can specify their own etcd backend configuration. This allows mixing backends within a single confd instance.

Add a [backend] section to your template resource file:

[template]
src = "myapp.conf.tmpl"
dest = "/etc/myapp/config.conf"
keys = [
  "/myapp/database",
]

[backend]
backend = "etcd"
nodes = ["https://etcd.example.com:2379"]
basic_auth = true
username = "admin"
password = "secret"
client_cert = "/path/to/client.crt"
client_key = "/path/to/client.key"
client_cakeys = "/path/to/ca.crt"

Available backend options:

• backend - Must be "etcd"
• nodes - Array of etcd node addresses
• scheme - "http" or "https"
• basic_auth - Enable basic authentication
• username - Username for basic auth
• password - Password for basic auth
• client_cert - Path to client certificate
• client_key - Path to client private key
• client_cakeys - Path to CA certificate
• client_insecure - Skip TLS certificate verification

Connection Behavior

• Dial timeout: 5 seconds
• Keep-alive: 10 seconds interval, 3 seconds timeout
• Transaction limit: 128 operations per transaction (etcd v3 default)
• Automatic reconnection: Watch connections automatically reconnect after disconnection