Skip to main content
In this lesson, we’ll explore how to configure the Consul agent using either JSON or HCL (HashiCorp Configuration Language). Proper agent configuration determines whether Consul runs in server or client mode and controls critical network, security, and cluster membership settings.

​
Sample JSON Configuration

Below is a baseline JSON file for a Consul server in us-east-1. You can also write this in HCL; refer to the Consul Configuration Documentation for HCL examples. 
{
  "datacenter": "us-east-1",
  "client_addr": "0.0.0.0",
  "bind_addr": "10.11.11.11",
  "advertise_addr": "10.11.11.11",
  "bootstrap_expect": 5,
  "retry_join": [
    "provider=aws tag_key=Environment-Name tag_value=consul-cluster region=us-east-1"
  ],
  "enable_syslog": true,
  "acl": {
    "enabled": true,
    "default_policy": "deny"
  }
}
Additional examples and a hands-on practice lab follow this section.

​
Understanding Configuration Sources

You can provide configuration through:
  • JSON/HCL files
  • Command-line flags (e.g., -server, -bootstrap-expect)
  • Environment variables prefixed with CONSUL_
Environment variables are useful for overrides in containerized or CI/CD environments. For complex configurations, maintain a single JSON or HCL file.

​
Key Options in a Server Configuration File

Below is a summary of the most common server directives. Adjust these values to match your deployment topology and security requirements.
OptionTypeDescription
serverBooleantrue for server agents; false for clients.
datacenterStringLogical data center name (e.g., us-east-1).
nodeStringUnique agent identifier (often the host name). Must be unique in the cluster.
retry_joinArray of stringsList of peers or cloud auto-join parameters to contact when forming/joining the cluster.
client_addrIP or interfaceAddress for client‐facing RPC, HTTP, and DNS servers.
bind_addrIP or interfaceAddress for internal gossip and serf LAN communications.
advertise_addrIP or interfaceAddress broadcast to other agents for cluster membership.
bootstrap_expectIntegerNumber of servers to wait for before bootstrapping the Raft cluster (only in server mode).
encryptString (base64)32-byte key generated via consul keygen for gossip encryption. Must match across all agents.
data_dirString (path)Local filesystem path for storing agent state and metadata.
log_levelStringVerbosity level (trace, debug, info, warn, err).
Keep your gossip encryption key (encrypt) confidential. If exposed, rotate it immediately using consul keygen and reconfigure all agents.
The image is a guide on interpreting a Consul agent configuration, listing key options in a server configuration file, such as server, datacenter, node, and others. It emphasizes that environment variables cannot configure the Consul client.
Depending on your environment, you may also configure: ACLs (acl block), syslog integration (enable_syslog), or cloud-specific auto-join settings.

​
Key Options in a Service Configuration File

Service definitions register application endpoints with Consul for discovery and health checking. Below is an overview of essential fields:
OptionTypeDescription
nameStringLogical service name (e.g., webapp1, database562).
idStringUnique instance identifier (e.g., webserver01).
portIntegerLocal port where the service listens (e.g., 8080, 443).
checkObject or ArrayHealth check definitions (HTTP, TCP, script). Specify interval, timeout, and status TTL.
You can define multiple health checks per service. Use deregister_critical_service_after to automatically remove unhealthy instances.
The image is a guide on interpreting a Consul agent configuration, highlighting key options in a service configuration file such as name, id, port, and check. It also notes that environment variables cannot configure the Consul client.
Next, we’ll walkthrough a real-world example, explaining each setting in depth and demonstrating best practices for high-availability and secure cluster management.

Watch Video