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)

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?

Packer Cheat Sheet

Vault (Secrets Management) Cheat Sheet