HashiCorp Consul

Service networking for any runtime, any cloud. Consul provides service discovery, health checking, distributed key-value configuration, and a zero-trust service mesh with automatic mTLS across VMs, containers, and Kubernetes.

Docker Quickstart

# Start a Consul dev agent (in-memory, single node)
docker run -d \
  --name consul \
  -p 8500:8500 \
  -p 8600:8600/udp \
  hashicorp/consul:latest \
  consul agent -dev -client=0.0.0.0

# Access the web UI at http://localhost:8500

# Install the Consul CLI (macOS)
brew install consul

# Point CLI at local agent
export CONSUL_HTTP_ADDR=http://localhost:8500

# Check cluster members
consul members

# Verify health
consul operator autopilot get-config

Service Registration and Health Checks

# Register a service via config file (drop in /etc/consul.d/)
# /etc/consul.d/web.json
{
  "service": {
    "name": "web",
    "id": "web-1",
    "tags": ["production", "v2"],
    "address": "10.0.0.10",
    "port": 8080,
    "check": {
      "id": "web-health",
      "name": "HTTP health check",
      "http": "http://localhost:8080/health",
      "method": "GET",
      "interval": "10s",
      "timeout": "3s"
    }
  }
}

# Register via HTTP API
curl -X PUT http://localhost:8500/v1/agent/service/register \
  -H 'Content-Type: application/json' \
  -d '{
    "Name": "api",
    "Port": 3000,
    "Check": {
      "TCP": "localhost:3000",
      "Interval": "10s"
    }
  }'

# Query registered services
consul catalog services

# Check service health
consul health service web --passing

DNS Interface for Service Discovery

# Consul provides a DNS interface at port 8600
# Services are resolvable as: service-name.service.consul

# Resolve healthy instances of the 'web' service
dig @127.0.0.1 -p 8600 web.service.consul

# Resolve with specific tag (only production instances)
dig @127.0.0.1 -p 8600 production.web.service.consul

# Resolve SRV record (includes port information)
dig @127.0.0.1 -p 8600 web.service.consul SRV

# Configure system DNS to use Consul (Linux with systemd-resolved)
cat > /etc/systemd/resolved.conf.d/consul.conf <<EOF
[Resolve]
DNS=127.0.0.1:8600
Domains=~consul
EOF
systemctl restart systemd-resolved

# Now applications can just use: http://web.service.consul:8080

Key-Value Store for Configuration

# Write configuration values
consul kv put config/my-app/db_host "postgres.service.consul"
consul kv put config/my-app/max_connections "50"
consul kv put config/my-app/feature_flags '{"dark_mode": true, "beta": false}'

# Read a value
consul kv get config/my-app/db_host

# List all keys under a prefix
consul kv get --recurse config/my-app/

# Watch for changes (blocks until key changes, then prints new value)
consul watch -type=key -key=config/my-app/db_host cat

# Delete a key
consul kv delete config/my-app/old_setting

# Application integration (Go example):
# client, _ := api.NewClient(api.DefaultConfig())
# kv := client.KV()
# pair, _, _ := kv.Get("config/my-app/db_host", nil)
# fmt.Println(string(pair.Value))

Consul Connect: mTLS Service Mesh

# Enable Connect in Consul config
{
  "connect": {
    "enabled": true
  }
}

# Register a service with Connect sidecar proxy
{
  "service": {
    "name": "api",
    "port": 8080,
    "connect": {
      "sidecar_service": {
        "proxy": {
          "upstreams": [
            {
              "destination_name": "database",
              "local_bind_port": 5432
            }
          ]
        }
      }
    }
  }
}

# Create an Intention: allow api → database
consul intention create api database

# Block all traffic except explicitly allowed pairs
consul intention create -deny "*" "*"
consul intention create api database    # allow
consul intention create frontend api    # allow

# Traffic flow with Connect:
# frontend:app → frontend:sidecar(mTLS) → api:sidecar(mTLS) → api:app
# All traffic encrypted, all connections authorized by intentions

Consul vs Kubernetes DNS vs Istio