Consul Template — Dynamic Configuration Rendering from HashiCorp Consul

Introduction

Consul Template is a standalone daemon from HashiCorp that queries Consul, Vault, and Nomad for live data, renders Go templates into configuration files, and optionally executes a reload command. It bridges the gap between dynamic service discovery and static config files.

What Consul Template Does

• Watches Consul's service catalog and KV store for real-time changes
• Renders Go templates into config files for Nginx, HAProxy, and any other service
• Fetches secrets from HashiCorp Vault and injects them into rendered output
• Executes a configurable command after rendering (e.g., systemctl reload nginx)
• Supports multiple templates and destinations in a single daemon instance

Architecture Overview

Consul Template runs as a long-lived process that maintains blocking queries against the Consul HTTP API. When a watched value changes, it re-evaluates the associated Go template, writes the result to disk atomically, and fires the specified reload command. It uses a dependency graph to batch multiple near-simultaneous changes into a single render cycle, avoiding unnecessary restarts.

Self-Hosting & Configuration

• Download a static binary from HashiCorp releases or install via package managers
• Point -consul-addr at your Consul cluster and -vault-addr at Vault if using secrets
• Define templates with -template="source:dest:command" on the CLI or in an HCL config file
• Use -once for one-shot rendering in CI or -retry for persistent daemon mode
• Run as a systemd service for production deployments

Key Features

• Atomic file writes prevent services from reading partially rendered configs
• Quiescence timers batch rapid changes to avoid reload storms
• Native Vault integration for secret injection without custom scripts
• Template functions for service health filtering, KV lookups, and environment variables
• Supports Consul Connect service mesh metadata and intentions

Comparison with Similar Tools

• confd — similar template rendering tool; Consul Template has deeper Consul and Vault integration
• envsubst — simple environment variable substitution; Consul Template offers live watching and complex logic
• Ansible templates — rendered at deploy time; Consul Template updates continuously at runtime
• Consul Connect / Envoy — handles service mesh routing directly; Consul Template generates config files for legacy apps
• gomplate — standalone Go template CLI; Consul Template adds the watching and reload loop

FAQ

Q: Can I use Consul Template without HashiCorp Consul? A: Consul is the primary data source. For Vault-only use cases, you can point it solely at Vault, but most deployments pair it with Consul.

Q: How does it handle rapid changes without thrashing restarts? A: It uses quiescence timers (min/max wait) to batch multiple changes into a single render-and-reload cycle.

Q: Is it safe to inject secrets into config files? A: Consul Template writes files with configurable permissions. Combine with short-lived Vault leases and restricted file ACLs for a secure setup.

Q: Can it render multiple templates? A: Yes. Define multiple -template flags or template blocks in the HCL config file. Each template can have its own reload command.

Sources

• https://github.com/hashicorp/consul-template
• https://developer.hashicorp.com/consul/tutorials/developer-configuration/consul-template