Skip to Content

Service Discovery

Consul integration for service registration, health checks, and DNS.

Overview

Consul provides:

  • Service Registry - 42+ services registered
  • Health Checks - TCP/HTTP health monitoring
  • DNS Interface - Service discovery via DNS
  • KV Store - Configuration management
  • UI Dashboard - Visual service monitoring

Ports

PortPurpose
8500HTTP API / UI
8600DNS
8301Serf LAN
8302Serf WAN
8300RPC

Service Registration

Manual Registration

curl -X PUT http://localhost:8500/v1/agent/service/register \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "auth_service",
    "ID": "auth_service-1",
    "Port": 8201,
    "Tags": ["api", "v1", "http"],
    "Check": {
      "HTTP": "http://localhost:8201/health",
      "Interval": "10s",
      "Timeout": "5s"
    }
  }'

Python Registration

from isa_common import ConsulClient
 
consul = ConsulClient(host="localhost", port=8500)
 
# Register service
await consul.register_service(
    name="auth_service",
    port=8201,
    tags=["api", "v1"],
    health_check={
        "http": "http://localhost:8201/health",
        "interval": "10s"
    }
)
 
# Deregister on shutdown
await consul.deregister_service("auth_service-1")

Health Checks

Check Types

TypeDescription
HTTPGET request, 2xx = healthy
TCPConnection test
gRPCgRPC health protocol
ScriptCustom script execution
TTLHeartbeat-based

HTTP Check

{
  "Check": {
    "HTTP": "http://localhost:8201/health",
    "Interval": "10s",
    "Timeout": "5s",
    "DeregisterCriticalServiceAfter": "30m"
  }
}

gRPC Check

{
  "Check": {
    "GRPC": "localhost:50061",
    "GRPCUseTLS": false,
    "Interval": "10s"
  }
}

Service Discovery

HTTP API

# List all services
curl http://localhost:8500/v1/catalog/services
 
# Get service instances
curl http://localhost:8500/v1/catalog/service/auth_service
 
# Get healthy instances only
curl http://localhost:8500/v1/health/service/auth_service?passing=true

DNS

# Resolve service
dig @localhost -p 8600 auth_service.service.consul
 
# SRV record (includes port)
dig @localhost -p 8600 auth_service.service.consul SRV

Python Client

from isa_common import ConsulClient
 
consul = ConsulClient(host="localhost", port=8500)
 
# Discover service
services = await consul.get_service("auth_service")
for svc in services:
    print(f"{svc.address}:{svc.port}")
 
# Get healthy instances
healthy = await consul.get_healthy_service("auth_service")

Registered Services

Infrastructure Services (9)

ServicePortType
postgres-grpc50061gRPC
redis-grpc50055gRPC
neo4j-grpc50063gRPC
nats-grpc50056gRPC
mqtt-grpc50053gRPC
minio-grpc50051gRPC
qdrant-grpc50062gRPC
duckdb-grpc50052gRPC
loki-grpc50054gRPC

Business Services (33)

From isA_user and other repositories, dynamically registered.

KV Store

Store Configuration

# Set value
curl -X PUT http://localhost:8500/v1/kv/config/database/host \
  -d "localhost"
 
# Get value
curl http://localhost:8500/v1/kv/config/database/host?raw

Python KV Access

# Store config
await consul.kv_put("config/database/host", "localhost")
 
# Get config
host = await consul.kv_get("config/database/host")
 
# Watch for changes
async for value in consul.kv_watch("config/database"):
    print(f"Config changed: {value}")

Health Status

StatusDescription
passingAll checks pass
warningSome warnings
criticalService unhealthy

Check Service Health

curl http://localhost:8500/v1/health/service/auth_service | jq '.[].Checks'

Consul UI

Access at http://localhost:8500:

  • Services - View all registered services
  • Nodes - Cluster node status
  • Key/Value - Configuration browser
  • Intentions - Service mesh policies

Troubleshooting

Service Not Registered

# Check agent services
curl http://localhost:8500/v1/agent/services
 
# Check agent health
curl http://localhost:8500/v1/agent/self

Health Check Failing

# View check details
curl http://localhost:8500/v1/health/checks/auth_service
 
# Test health endpoint directly
curl http://localhost:8201/health

Next Steps

Home