HashiCorp Consul — Service Discovery & Service Mesh

What Consul Does

• Service Discovery: Register services and discover them via DNS or HTTP API
• Health Checking: Continuously monitor service health and remove unhealthy instances
• KV Store: Distributed key-value storage for dynamic configuration
• Service Mesh: Full mTLS service mesh with Envoy sidecar proxies
• Intentions: Declarative access control between services
• Multi-Datacenter: Federate Consul clusters across regions and clouds
• Network Segmentation: Isolate services via Consul Namespaces and Admin Partitions
• ACL: Fine-grained access control with tokens and policies
• Event System: Trigger events across clusters for coordinated actions

Architecture

┌─────────────────────────────────────────────┐
│  Datacenter 1                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ Consul   │──│ Consul   │──│ Consul   │  │
│  │ Server 1 │  │ Server 2 │  │ Server 3 │  │
│  └──────────┘  └──────────┘  └──────────┘  │
│       ▲             ▲             ▲         │
│       │  Raft Consensus         │         │
│  ┌────┴──────────────┴──────────┴────┐    │
│  │                                    │    │
│  │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐  │    │
│  │  │Agent│ │Agent│ │Agent│ │Agent│  │    │
│  │  │ Web │ │ API │ │ DB  │ │Cache│  │    │
│  │  └─────┘ └─────┘ └─────┘ └─────┘  │    │
│  │          Client Agents             │    │
│  └────────────────────────────────────┘    │
└─────────────────────────────────────────────┘
            │ WAN Federation
            ▼
┌─────────────────────────────────────────────┐
│  Datacenter 2 (Another region/cloud)       │
└─────────────────────────────────────────────┘

Self-Hosting

Docker Compose (Dev)

services:
  consul:
    image: hashicorp/consul:latest
    ports:
      - "8500:8500"        # HTTP API / UI
      - "8600:8600/udp"    # DNS
      - "8600:8600/tcp"
    command: agent -server -ui -bootstrap-expect=1 -client=0.0.0.0
    volumes:
      - consul-data:/consul/data

volumes:
  consul-data:

Production Cluster (3 Servers)

services:
  consul-server-1:
    image: hashicorp/consul:latest
    command: agent -server -ui -bootstrap-expect=3 -retry-join=consul-server-2 -retry-join=consul-server-3 -client=0.0.0.0
    volumes:
      - consul-1:/consul/data

  consul-server-2:
    image: hashicorp/consul:latest
    command: agent -server -bootstrap-expect=3 -retry-join=consul-server-1 -retry-join=consul-server-3 -client=0.0.0.0
    volumes:
      - consul-2:/consul/data

  consul-server-3:
    image: hashicorp/consul:latest
    command: agent -server -bootstrap-expect=3 -retry-join=consul-server-1 -retry-join=consul-server-2 -client=0.0.0.0
    volumes:
      - consul-3:/consul/data

volumes:
  consul-1:
  consul-2:
  consul-3:

Service Discovery

Register a Service

{
  "service": {
    "name": "web",
    "id": "web-1",
    "address": "10.0.1.5",
    "port": 8080,
    "tags": ["primary", "v2"],
    "checks": [
      {
        "http": "http://10.0.1.5:8080/health",
        "interval": "10s",
        "timeout": "5s"
      }
    ]
  }
}

curl -X PUT -d @service.json http://localhost:8500/v1/agent/service/register

Discover Services

# HTTP API
curl http://localhost:8500/v1/catalog/service/web

# DNS query (SRV record)
dig @localhost -p 8600 web.service.consul SRV

# Only healthy instances
curl http://localhost:8500/v1/health/service/web?passing=true

Integration in Code

// Go example
import "github.com/hashicorp/consul/api"

config := api.DefaultConfig()
client, _ := api.NewClient(config)

// Find web service
services, _, _ := client.Health().Service("web", "", true, nil)
for _, entry := range services {
    fmt.Printf("%s:%d
", entry.Service.Address, entry.Service.Port)
}

KV Store

# Write
curl -X PUT -d 'production' http://localhost:8500/v1/kv/config/app/environment
curl -X PUT -d '5432' http://localhost:8500/v1/kv/config/db/port

# Read
curl http://localhost:8500/v1/kv/config/app/environment?raw

# List keys
curl http://localhost:8500/v1/kv/config/?keys

# Watch for changes (long polling)
curl "http://localhost:8500/v1/kv/config/app/environment?index=123&wait=5m"

Service Mesh (Connect)

Enable Connect

{
  "service": {
    "name": "web",
    "port": 8080,
    "connect": {
      "sidecar_service": {
        "proxy": {
          "upstreams": [
            {
              "destination_name": "database",
              "local_bind_port": 9191
            }
          ]
        }
      }
    }
  }
}

Intentions (Access Control)

# Allow web service to access database
consul intention create web database

# Deny all except explicitly allowed
consul intention create -deny "*" "*"
consul intention create web database

Consul vs Alternatives

FAQ

Q: Consul or etcd — which should I pick? A: etcd is primarily a distributed KV store (K8s uses it for cluster state). Consul is a full service-networking platform that includes KV + service discovery + health checks + service mesh. If you just need a KV store, etcd is lighter. For service discovery and health checks, pick Consul.

Q: Consul or Istio — which should I pick? A: Istio is a Kubernetes-native service mesh (K8s only). Consul works on K8s, VMs, and hybrid environments. If your services run across both K8s and traditional VMs, pick Consul. In a pure K8s environment, Istio has richer features.

Q: Does the BSL license affect usage? A: The Business Source License (BSL) permits free use and modification, only restricting you from offering it as a competing commercial product to Consul. For the vast majority of users (self-hosted or internal use), the BSL is effectively equivalent to an open-source license.

Sources & Credits

• GitHub: hashicorp/consul — 29.8K+ ⭐ | BSL
• Website: consul.io