consul-template: Render Config From Consul and Vault
consul-template renders a Go template using live data from Consul KV and Vault, either once or continuously as values change.
consul-template pulls config and secrets at deploy time instead of baking them in. In CI you typically run it once to produce a rendered file, not as a daemon.
What it does
consul-template evaluates a template with functions like key, service, and secret that read from Consul and Vault. -template maps a source template to a destination file (with an optional command). -once renders a single time and exits, which is the CI mode; without it, it watches and re-renders.
Common usage
# render once and exit (CI mode)
consul-template -once \
-template "app.tmpl:app.conf"
# render, then run a command after
consul-template -once \
-template "app.tmpl:app.conf:systemctl reload app"
# validate config without rendering
consul-template -dry -once -template "app.tmpl:app.conf"Options
| Flag | What it does |
|---|---|
| -template "src:dst[:cmd]" | Template source, destination, and optional post-render command |
| -once | Render one time and exit (do not watch) |
| -dry | Render to stdout without writing files |
| -consul-addr <addr> | Consul HTTP address |
| -vault-addr <addr> | Vault address for the secret function |
| -config <file> | HCL config file instead of flags |
In CI
Use -once so the process exits instead of daemonizing and hanging the job. Keep the rendered secret file out of artifacts and logs: write to a tmpfs path and delete it after use, since secret pulled from Vault lands in plaintext in the destination file. Pin the consul-template version for stable template function behavior.
Common errors in CI
"failed to execute template" or "template: :N:M: executing ... map has no entry for key" means a Consul key or Vault path the template references does not exist. "Error: connection refused" or "dial tcp ...: connect: connection refused" means -consul-addr/-vault-addr is wrong or the agent is down. "Error making API request ... permission denied" is a Vault token lacking a policy for that path.