consul

Consul Backend

The Consul backend enables confd to retrieve configuration data from HashiCorp Consul's key-value store.

Configuration

Basic Connection

Connect to Consul without authentication:

confd consul --node 127.0.0.1:8500 --onetime

Authentication

HTTP Basic Auth

confd consul --node 127.0.0.1:8500 \
  --basic-auth --username admin --password secret --onetime

ACL Token

Set the CONSUL_HTTP_TOKEN environment variable:

export CONSUL_HTTP_TOKEN=your-acl-token
confd consul --node 127.0.0.1:8500 --onetime

TLS Client Certificates

confd consul --node 127.0.0.1:8501 \
  --scheme https \
  --client-cert /path/to/client.crt \
  --client-key /path/to/client.key \
  --client-ca-keys /path/to/ca.crt --onetime

Options

Environment Variables

Consul's standard environment variables are also supported:

Basic Example

Add keys to Consul:

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

Or using the HTTP API:

curl -X PUT -d 'db.example.com' http://localhost:8500/v1/kv/myapp/database/url
curl -X PUT -d 'admin' http://localhost:8500/v1/kv/myapp/database/user
curl -X PUT -d 'secret123' http://localhost:8500/v1/kv/myapp/database/password

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 consul --node 127.0.0.1:8500 --onetime

Advanced Example

Using ACL Tokens

Create a policy for confd:

# confd-policy.hcl
key_prefix "myapp/" {
  policy = "read"
}

# Create the policy
consul acl policy create -name confd -rules @confd-policy.hcl

# Create a token
consul acl token create -policy-name confd -description "confd token"

Use the token:

export CONSUL_HTTP_TOKEN=<token-secret-id>
confd consul --node 127.0.0.1:8500 --watch

TLS Configuration

confd consul --node consul.example.com:8501 \
  --scheme https \
  --client-ca-keys /etc/consul.d/ca.pem \
  --client-cert /etc/consul.d/client.pem \
  --client-key /etc/consul.d/client-key.pem \
  --watch

Kubernetes with Consul Connect

apiVersion: v1
kind: Pod
metadata:
  name: myapp
  annotations:
    consul.hashicorp.com/connect-inject: "true"
spec:
  containers:
  - name: myapp
    env:
    - name: CONSUL_HTTP_TOKEN
      valueFrom:
        secretKeyRef:
          name: consul-token
          key: token
    command:
    - confd
    - consul
    - --node=127.0.0.1:8500
    - --watch

Watch Mode Support

Watch mode is supported for the Consul backend. confd uses Consul's blocking queries for efficient change detection.

confd consul --node 127.0.0.1:8500 --watch

Consul blocking queries long-poll the server, returning immediately when data changes. This provides near-real-time updates without constant polling.

Per-Resource Backend Configuration

Instead of using the global backend, individual template resources can specify their own Consul 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 = "consul"
nodes = ["consul.example.com:8500"]
scheme = "https"
basic_auth = true
username = "admin"
password = "secret"

Available backend options:

• backend - Must be "consul"
• nodes - Array of Consul agent addresses
• scheme - "http" or "https"
• basic_auth - Enable HTTP 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

Connection Notes

• Only the first --node is used; Consul client does not support multiple nodes
• Use a local Consul agent or load balancer for high availability
• Consul's default HTTP timeout applies to blocking queries