Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Key-Value and Config

Configuration Patterns and Consul Template

Organize Consul KV for real applications: key layout, defaults, feature flags and gradual rollout, then render live config files with Consul Template and envconsul.

You know how to store a key and how to wait for a change. Real systems add the last mile: how do you lay out configuration so people can find it, how do you get it into programs that read plain files or environment variables, and how do you use it for feature flags without a deploy? This lesson covers the patterns and the two tools that bridge Consul to ordinary software: Consul Template and envconsul.

Consul and these tools do not run on this site, so their commands and templates are read-only. The stand-ins re-create the rendering and rollout logic in Python.

A layout that scales

A good key layout answers "who owns it" and "which environment" from the path alone:

TEXT
config/<app>/<env>/<setting>

config/web/prod/log_level          = info
config/web/prod/max_connections    = 200
config/web/staging/log_level       = debug
config/shared/prod/smtp_host       = smtp.example.internal
flags/new-checkout/prod            = {"enabled": true, "percent": 25}

Guidelines:

  • Put defaults in a shared path and let applications override per environment (read the specific key first, then the default).
  • Keep values simple scalars or small JSON documents. Use Flags or a naming convention to mark JSON values.
  • Never rely on key order; list by prefix and sort in your program.
  • Protect each prefix with an ACL: developers may read config/*/staging while only the release team writes config/*/prod.
  • Version big changes: write a new key (.../v2/...), switch a pointer key, and keep the old one for rollback.

Feature flags

A feature flag decides at runtime whether new behavior is on. With Consul KV the flag is a key that your application watches (see watches), so changing it needs no deploy:

Terminal
$ consul kv put flags/new-checkout/prod '{"enabled": true, "percent": 25}'

For a percentage rollout, bucket each user deterministically so the same user always gets the same answer: hash the flag name and user ID to a number from 0 to 99, and enable the feature when the number is below percent. Increase percent in steps while you watch error rates. Rolling back is one kv put.

Consul Template

Consul Template is a separate small program that watches Consul (KV, services, health, and also Vault secrets) and renders text templates to files, then runs a command such as a reload. It is the classic way to keep nginx.conf, HAProxy configs and application config files in sync with the cluster.

A template file upstreams.ctmpl:

TEXT
upstream web_backend {
{{ range service "web|passing" }}
  server {{ .Address }}:{{ .Port }};
{{ end }}
}

log_level {{ keyOrDefault "config/web/prod/log_level" "info" }};

Run it:

Terminal
$ consul-template \
    -template "upstreams.ctmpl:/etc/nginx/conf.d/upstreams.conf:nginx -s reload" \
    -consul-addr 127.0.0.1:8500

Useful template functions:

Function Result
key "path" A KV value (errors if missing)
keyOrDefault "path" "x" A KV value or a default
ls "prefix" Keys directly under a prefix (a list of pairs)
tree "prefix" All keys under a prefix, recursively
service "name|passing" Healthy instances (.Address, .Port, .Tags, .Node)
services Names of all services
nodes All nodes

Consul Template re-renders only when a dependency changes and writes the file atomically; it runs the reload command after the file changed. It can run as a daemon, or once (-once) in a deploy script. In a render step always validate before reloading, for example nginx -t && nginx -s reload, so a bad template cannot take the proxy down.

envconsul

envconsul does for environment variables what Consul Template does for files. It reads a KV prefix, starts your program with those keys as environment variables, and restarts it when they change:

Terminal
$ envconsul -prefix config/web/prod ./web-server

Keys such as config/web/prod/max_connections become max_connections in the program's environment. It suits twelve-factor apps that already read configuration from the environment.

Stand-in 1: a miniature template renderer

This renders the service loop and keyOrDefault from the template above, using in-memory data. It is a teaching model that handles only these two constructs.

Python Stand-in: render an upstream block

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: percentage rollout

Deterministic bucketing with a stable hash. Because the hash does not depend on the process, the same user always sees the same result, and raising the percentage only adds users, never removes them.

Python Stand-in: feature flag rollout

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The exact count at each percentage depends on the hash and the user IDs, so it lands near, not exactly on, the percentage. The key property is the last column: increasing the percentage never turns a feature off for someone who already had it.

Good practices

  • Treat Consul KV changes like code: review, log who changed what (ACL tokens and audit logs), and keep a way to roll back.
  • Give applications sane built-in defaults so they still start when Consul is unreachable, and cache the last good config.
  • Debounce reloads. Consul Template has wait settings so a burst of changes triggers one reload.
  • Keep flags short-lived. Remove a flag and its code once a rollout is finished.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Consul Template do?

    It renders templates from KV, services and more, and can reload the consuming program.
  2. 2. Why use deterministic hashing for a percentage rollout?

    A stable bucket per user avoids flip-flopping behavior between requests.
  3. 3. Which template function returns a KV value or a fallback?

    keyOrDefault "path" "fallback" avoids an error when the key is missing.
  4. 4. What should a render step do before reloading nginx?

    Validating before reload keeps a faulty template from taking the service down.

Summary

  • Lay keys out as config/<app>/<env>/<setting> with shared defaults and ACLs per prefix.
  • Feature flags in KV change behavior without deploys; roll out by deterministic percentage buckets.
  • Consul Template renders files from KV and service data and runs reload commands; envconsul injects KV as environment variables.
  • Validate before reloading and keep built-in defaults for when Consul is unreachable.
  • Review, audit and retire flags like any other code change.

Next: Health Check Types