Consul: Service Discovery, Health Checks & KV Store

Consul (HashiCorp) provides service discovery, health checking, a distributed KV store, and service mesh for distributed systems -- letting services find each other, detect unhealthy instances, and share configuration dynamically.

Agent Architecture: Server vs Client

• A small odd-numbered set of server agents (typically 3 or 5) hold authoritative cluster state via Raft consensus.

• Many client agents run alongside actual application instances -- registering services locally, forwarding queries to servers.

• Serf gossip protocol handles membership/failure detection among ALL agents -- lighter-weight than Raft, appropriate for the larger client population.

• WAN federation lets separate per-datacenter clusters (each with its own local Raft group) be connected for cross-datacenter discovery/mesh.

Registering a Service & Health Checks

// service.json -- loaded by the local Consul agent
{
  "service": {
    "name": "payments-service",
    "port": 8080,
    "tags": ["api", "v2"],
    "check": {
      "http": "http://localhost:8080/health",
      "interval": "10s",
      "timeout": "2s"
    }
  }
}

// An unhealthy instance (failing check) is automatically excluded
// from what service discovery returns -- traffic isn't routed to it.

# Or register via the agent's HTTP API directly
curl -X PUT -d @service.json http://localhost:8500/v1/agent/service/register

# Service discovery via DNS -- no Consul-specific client needed
dig payments-service.service.consul

# Or via the HTTP API for programmatic access
curl http://localhost:8500/v1/health/service/payments-service?passing

Key-Value Store

# Dynamic configuration -- read at runtime, updatable without redeploy
consul kv put config/payments/max_retries 3
consul kv get config/payments/max_retries

# Watch for changes -- push-like reactive pattern, no polling
consul watch -type=key -key=config/payments/max_retries my-handler-script.sh