Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Getting Started

Configuring a Consul Agent

Write production-style Consul agent configuration in HCL: server and client files, retry_join, bootstrap_expect, bind addresses, merging rules and validation.

The dev agent needs no configuration, but real clusters do. A Consul agent reads settings from command-line flags and from configuration files in HCL or JSON. Files are the right choice for anything you keep: they can be reviewed, version-controlled and deployed by tools like Terraform or configuration management.

This lesson shows a server file and a client file, explains the options you must understand, and covers how multiple files merge. The Consul commands are read-only; the stand-ins model merging and validation.

A server configuration

Save this as /etc/consul.d/consul.hcl on each of three server machines (the node name differs per machine):

HCL
datacenter = "dc1"
node_name  = "server-1"
data_dir   = "/opt/consul"

server           = true
bootstrap_expect = 3

bind_addr   = "10.0.0.11"
client_addr = "127.0.0.1"

retry_join = ["10.0.0.11", "10.0.0.12", "10.0.0.13"]

encrypt   = "BASE64-GOSSIP-KEY-HERE"
log_level = "INFO"

ui_config {
  enabled = true
}

What each line does:

Option Meaning
datacenter Name of this cluster; all agents in it must agree
node_name Unique node name (defaults to the hostname)
data_dir Where Raft logs and snapshots live; must persist on servers
server Run in server mode
bootstrap_expect Wait until this many servers are present, then bootstrap Raft
bind_addr The address used for cluster traffic (gossip and RPC)
client_addr Where the HTTP, DNS and gRPC interfaces listen
retry_join Addresses to keep trying until the agent joins; accepts cloud auto-join strings
encrypt Gossip encryption key (generate with consul keygen)
ui_config.enabled Serve the web UI

Generate the gossip key once and give the same value to every agent:

Terminal
$ consul keygen

A client configuration

A client is the same minus server mode:

HCL
datacenter = "dc1"
node_name  = "web-1"
data_dir   = "/opt/consul"

bind_addr   = "10.0.1.21"
client_addr = "127.0.0.1"

retry_join = ["10.0.0.11", "10.0.0.12", "10.0.0.13"]
encrypt    = "BASE64-GOSSIP-KEY-HERE"

Clients need a data_dir too (for local state such as registered checks), but it need not be durable.

Keep client_addr at 127.0.0.1 unless you really must expose the API. Binding the HTTP API to a public address without ACLs and TLS lets anyone on the network read and change your cluster. If you must listen more widely, enable ACLs, TLS and a firewall first.

Starting and validating

Terminal
$ consul validate /etc/consul.d/            # check files before using them
$ consul agent -config-dir=/etc/consul.d/   # run in the foreground
$ consul reload                             # re-read most settings without a restart
$ systemctl enable --now consul             # packages install a systemd unit

consul validate catches typos and bad values without starting anything. Run it in your deploy pipeline.

How files merge

You may pass -config-dir with many files. Consul reads files ending in .hcl or .json in lexical order and merges them: later files override scalar values; maps merge; lists such as retry_join and the services definitions are appended. Command-line flags win over files. A good layout:

TEXT
/etc/consul.d/
  00-base.hcl        # datacenter, data_dir, bind
  10-gossip.hcl      # encrypt key (restricted permissions)
  20-acl.hcl         # acl block
  web-service.hcl    # a service definition

Splitting by concern lets you restrict who can read the key file, and lets a package or tool drop in just a service file.

Stand-in 1: merge configuration files

This program applies the lexical-order rule to Python dictionaries. It is a model of the behavior (scalars override, dictionaries merge, lists append), not Consul's parser.

Python Stand-in: merge config files

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: a configuration checker

Real consul validate is far more thorough. This model checks four rules that cause real outages: an even number of expected servers, a missing data_dir, binding the API on all interfaces, and a server without retry_join.

Python Stand-in: lint an agent config

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.

Other settings you will meet

  • ports { http = 8500 dns = 8600 } changes listening ports; ports { https = 8501 } enables the TLS API.
  • addresses binds individual interfaces separately from client_addr.
  • advertise_addr is the address told to other agents (use it behind NAT).
  • node_meta attaches key-value metadata to the node.
  • services and checks blocks register services from the config file (next chapter).
  • acl { ... } and tls { ... } blocks harden the agent; both are covered in the security chapter of this course.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does bootstrap_expect = 3 tell a server?

    Servers hold off electing a leader until the expected number have joined, so the cluster starts safely.
  2. 2. Two files 00-base.hcl and 10-extra.hcl both set log_level. Which value is used?

    Files merge in lexical order and later scalar values override earlier ones.
  3. 3. Why validate configuration before deploying?

    consul validate is a safe, offline syntax and value check ideal for pipelines.
  4. 4. Which setting is risky when set to 0.0.0.0 without ACLs and TLS?

    client_addr controls where the HTTP, DNS and gRPC interfaces listen; exposing them publicly invites abuse.

Summary

  • Agent settings live in HCL or JSON files loaded with -config-dir; flags override files.
  • Servers need server = true, bootstrap_expect, data_dir, bind_addr and retry_join.
  • Share one gossip encrypt key (from consul keygen) across the datacenter.
  • Files merge in lexical order; lists append, maps merge, scalars override.
  • Run consul validate in your pipeline and keep client_addr on localhost unless secured.

Next: Registering Services