Consul Cheat Sheet
Reference for HashiCorp Consul service discovery, health checks, the KV store, and CLI commands for cluster and agent operations.
2 PagesAdvancedFeb 2, 2026
Agent & Cluster Commands
Running and inspecting a Consul agent.
bash
consul agent -dev # Start a dev-mode agent (single node)consul members # List cluster membersconsul info # Agent runtime infoconsul catalog services # List registered servicesconsul catalog nodes # List cluster nodesconsul monitor # Stream agent logsconsul leave # Gracefully leave the cluster
Service Definition
Registering a service with a health check via config file.
json
{ "service": { "name": "web", "tags": ["v1"], "port": 8080, "check": { "http": "http://localhost:8080/health", "interval": "10s", "timeout": "1s" } }}
KV Store CLI
Reading, writing, and deleting keys in Consul's key/value store.
bash
consul kv put config/app/db_host "db.internal" # Write a keyconsul kv get config/app/db_host # Read a keyconsul kv get -recurse config/app/ # List a prefixconsul kv delete config/app/db_host # Delete a keyconsul kv export config/ > backup.json # Export a treeconsul kv import @backup.json # Import a tree
Core Concepts
Key building blocks of a Consul deployment.
- Service Discovery- Agents register services; clients query DNS (service.consul) or HTTP API to find healthy instances
- Health Checks- HTTP, TCP, script, or TTL checks that mark service instances healthy/critical
- KV Store- Hierarchical key/value store used for dynamic configuration and coordination
- Consul Connect- Service mesh providing mTLS and traffic authorization between services via sidecar proxies
- Server vs Client agents- Servers maintain the Raft-replicated state; clients forward RPCs and run local checks
- ACL system- Token-based access control for gating API, KV, and service operations
DNS & HTTP Interfaces
Common ways applications interact with Consul at runtime.
- web.service.consul- DNS name resolving to healthy instances of the 'web' service
- GET /v1/catalog/service/web- HTTP API to list all instances of a service
- GET /v1/health/service/web?passing- HTTP API filtered to only passing health checks
- GET /v1/kv/config/app/db_host- HTTP API to fetch a KV entry (base64-encoded value)
Service Mesh Intentions
Defining and managing Consul Connect authorization between services.
bash
# Allow 'web' to talk to 'api' over the service meshconsul intention create web api# Deny by default, then allow specific pairs (zero-trust posture)consul intention create -deny "*" "*"consul intention create -allow web apiconsul intention create -allow api db# Check whether a connection would be allowedconsul intention check web api# List all intentionsconsul intention list# Sidecar proxy registration (paired with the 'web' service)consul services register - <<EOF{ "service": { "name": "web-sidecar-proxy", "kind": "connect-proxy", "port": 21000, "proxy": { "destination_service_name": "web", "local_service_port": 8080 } }}EOF
Prepared Queries & Failover
Server-side query templates that add automatic nearest/failover routing to service lookups.
json
{ "Name": "web-nearest", "Service": { "Service": "web", "OnlyPassing": true, "Near": "_agent", "Failover": { "NearestN": 3, "Datacenters": ["dc2", "dc3"] } }}# Register with: consul query create [email protected]# Resolve via DNS: dig @127.0.0.1 -p 8600 web-nearest.query.consul# Resolve via HTTP: curl localhost:8500/v1/query/<query-id>/execute
ACL Bootstrap & Token Policies
Enabling the ACL system and scoping tokens to least-privilege policies.
bash
# One-time bootstrap (prints the initial management token)consul acl bootstrap# Define a service-scoped policycat > web-policy.hcl <<EOFservice "web" { policy = "write" }service "api" { policy = "read" }node_prefix "" { policy = "read" }EOFconsul acl policy create -name web-policy -rules @web-policy.hcl# Mint a token bound to that policy, with a TTLconsul acl token create -description "web service token" \ -policy-name=web-policy -expires-ttl=24h
Cluster & Mesh Internals
How Consul maintains consistency and connects datacenters under the hood.
- Raft consensus- Server agents replicate the catalog/KV state via Raft; writes require a quorum (3 or 5 servers is typical)
- Serf gossip- LAN/WAN gossip pools detect agent failure and disseminate membership changes without a central coordinator
- WAN federation- Multiple datacenters join a WAN gossip pool so `consul catalog services -datacenter=dc2` can query remote DCs
- Anti-entropy- Client agents continuously sync locally known service/check state back to the servers' catalog
- Snapshot agent- `consul snapshot save backup.snap` captures a point-in-time Raft snapshot for disaster recovery
- Envoy xDS- Consul Connect configures sidecar Envoy proxies dynamically over xDS instead of static config
- Mesh gateways- Route mTLS mesh traffic between federated datacenters without exposing every service publicly
Watches & consul-template
Reacting to catalog/KV changes and rendering config files automatically.
bash
# Watch for changes to a service's health and run a handler scriptconsul watch -type=service -service=web ./reload-lb.sh# Watch a KV prefix for config changesconsul watch -type=keyprefix -prefix=config/app/ ./notify.sh# consul-template: render an nginx upstream block from live catalog data# nginx.ctmpl:# upstream web {# {{ range service "web" }} server {{ .Address }}:{{ .Port }};# {{ end }}}consul-template -template="nginx.ctmpl:/etc/nginx/conf.d/upstream.conf:nginx -s reload"
Pro Tip
Prefer the `?passing` query filter (or DNS's automatic health filtering) when discovering services — Consul's catalog includes unhealthy instances by default, so naive catalog queries can route traffic to failing nodes.
Was this cheat sheet helpful?
Explore Topics
#Consul#ConsulCheatSheet#DevOps#Advanced#AgentClusterCommands#ServiceDefinition#KVStoreCLI#CoreConcepts#CommandLine#CheatSheet#SkillVeris
