Skip to content

quick-start-guide.md

Latest commit

 

History

History
233 lines (168 loc) · 5.59 KB

quick-start-guide.md

File metadata and controls

233 lines (168 loc) · 5.59 KB

Quick Start Guide

Before we begin be sure to download and install confd.

Select a backend

confd supports the following backends:

Backend Description Watch Support Documentation
env Environment variables No Details
file Local YAML/JSON files Yes Details
etcd etcd v3 key-value store Yes Details
consul HashiCorp Consul KV Yes Details
vault HashiCorp Vault secrets No Details
redis Redis key-value store Yes Details
zookeeper Apache ZooKeeper Yes Details
dynamodb AWS DynamoDB No Details
ssm AWS Systems Manager Parameter Store No Details
secretsmanager AWS Secrets Manager No Details
acm AWS Certificate Manager No Details
imds AWS EC2 Instance Metadata Service No Details

This quick start uses the env and file backends which require no external services. For production use cases, see the backend-specific documentation linked above.

Quick Start with Environment Variables

The env backend is the simplest way to get started.

1. Set environment variables

export MYAPP_DATABASE_URL=db.example.com
export MYAPP_DATABASE_USER=admin

2. Create the confdir

sudo mkdir -p /etc/confd/{conf.d,templates}

3. Create a template resource config

/etc/confd/conf.d/myconfig.toml:

[template]
src = "myconfig.conf.tmpl"
dest = "/tmp/myconfig.conf"
keys = [
  "/myapp/database",
]

4. Create the source template

/etc/confd/templates/myconfig.conf.tmpl:

[myconfig]
database_url = {{getv "/myapp/database/url"}}
database_user = {{getv "/myapp/database/user"}}

5. Run confd

confd env --onetime

Check the output:

cat /tmp/myconfig.conf

Quick Start with File Backend

The file backend reads configuration from local YAML or JSON files.

1. Create a YAML configuration file

myapp.yaml:

myapp:
  database:
    url: db.example.com
    user: admin

2. Create the confdir

sudo mkdir -p /etc/confd/{conf.d,templates}

3. Create a template resource config

/etc/confd/conf.d/myconfig.toml:

[template]
src = "myconfig.conf.tmpl"
dest = "/tmp/myconfig.conf"
keys = [
  "/myapp/database",
]

4. Create the source template

/etc/confd/templates/myconfig.conf.tmpl:

[myconfig]
database_url = {{getv "/myapp/database/url"}}
database_user = {{getv "/myapp/database/user"}}

5. Run confd

confd file --file myapp.yaml --onetime

Running Modes

confd supports two modes of operation:

One-time mode

Process templates once and exit:

confd env --onetime

Daemon mode with interval polling

Poll the backend at regular intervals:

confd env --interval 60

Watch mode (supported backends only)

Watch for changes in real-time (etcd, consul, redis, zookeeper, file):

confd file --file myapp.yaml --watch

Next Steps

  • Template Functions: See templates.md for available template functions
  • Configuration: See configuration-guide.md for all configuration options
  • Multi-Backend: See multi-backend.md for using multiple backends (e.g., Consul + Vault)
  • Backend Details: Click the backend links above for authentication, advanced options, and examples

Advanced Example

This example manages nginx config files using etcd or consul.

Add keys (etcd)

etcdctl put /myapp/subdomain myapp
etcdctl put /myapp/upstream/app1 "10.0.1.100:80"
etcdctl put /myapp/upstream/app2 "10.0.1.101:80"

Add keys (consul)

consul kv put myapp/subdomain myapp
consul kv put myapp/upstream/app1 "10.0.1.100:80"
consul kv put myapp/upstream/app2 "10.0.1.101:80"

Create template resource

/etc/confd/conf.d/myapp-nginx.toml:

[template]
prefix = "/myapp"
src = "nginx.tmpl"
dest = "/tmp/myapp.conf"
owner = "nginx"
mode = "0644"
keys = [
  "/subdomain",
  "/upstream",
]
check_cmd = "/usr/sbin/nginx -t -c {{.src}}"
reload_cmd = "/usr/sbin/service nginx reload"

Create the source template

/etc/confd/templates/nginx.tmpl:

upstream {{getv "/subdomain"}} {
{{range getvs "/upstream/*"}}
    server {{.}};
{{end}}
}

server {
    server_name  {{getv "/subdomain"}}.example.com;
    location / {
        proxy_pass        http://{{getv "/subdomain"}};
        proxy_redirect    off;
        proxy_set_header  Host             $host;
        proxy_set_header  X-Real-IP        $remote_addr;
        proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
   }
}

Run confd

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

# consul
confd consul --node 127.0.0.1:8500 --watch