confd: Render Config From a Key-Value Backend
confd renders configuration files from a template using keys read from a backend such as etcd, Consul, Vault, or the environment.
confd predates most templaters and is still common in older infra. Each template has a TOML resource file describing its keys, source, destination, and an optional validation command.
What it does
confd reads template resource files (.toml) from a confdir, fetches the listed keys from the chosen backend, renders the associated .tmpl into the destination, and optionally runs a check_cmd before replacing and a reload_cmd after. -onetime renders once and exits.
Common usage
# render once from the environment backend
confd -onetime -backend env -confdir ./confd
# render once from etcd
confd -onetime -backend etcdv3 -node http://127.0.0.1:2379
# validate templates only, no watch loop
confd -onetime -log-level debug -backend envOptions
| Flag | What it does |
|---|---|
| -onetime | Render once and exit instead of polling |
| -backend <name> | Backend: env, etcdv3, consul, vault, redis, ... |
| -confdir <dir> | Directory with conf.d resources and templates |
| -node <url> | Backend node address (repeatable) |
| -prefix <path> | Key prefix to prepend to all lookups |
| -noop | Render but do not write the destination |
In CI
Use -onetime so confd does not enter its polling loop and stall the job. The env backend is ideal in CI because it needs no external service: keys map to uppercased, slash-to-underscore env vars. Give each resource a check_cmd so a bad render fails before the file is swapped in.
Common errors in CI
"ERROR template: ...:N:M: executing ... map has no entry for key" or "key does not exist" means a required key is absent in the backend. "ERROR config check failed: ... exit status 1" means the resource's check_cmd rejected the rendered file (confd keeps the old one). "ERROR 501: All the given peers are not reachable" points at an unreachable etcd/consul node.