Skip to content

README.md

Latest commit

 

History

History
206 lines (161 loc) · 4.79 KB

README.md

File metadata and controls

206 lines (161 loc) · 4.79 KB

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

Flag Description Default
-n, --node etcd node address (can be specified multiple times) -
--basic-auth Enable basic authentication false
--username Username for basic auth -
--password Password for basic auth -
--client-cert Path to client certificate -
--client-key Path to client private key -
--client-ca-keys Path to CA certificate -
--scheme URI scheme (http or https) http
--client-insecure Skip TLS certificate verification false

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