Managing Consul Connect

Consul Connect Service Mesh Skill

Manage Consul Connect service mesh, intentions, gateways, proxies, and service discovery.

Core Helper Functions

#!/bin/bash

CONSUL_HTTP_ADDR="${CONSUL_HTTP_ADDR:-http://localhost:8500}"

consul_api() {
    local endpoint="$1"
    shift
    curl -s -H "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
         "$CONSUL_HTTP_ADDR/v1/$endpoint" "$@"
}

MANDATORY: Discovery-First Pattern

Phase 1: Discovery

#!/bin/bash

echo "=== Consul Members ==="
consul members 2>/dev/null | head -15 || consul_api "agent/members" | jq -r '
    .[] | "\(.Name)\t\(.Addr)\t\(.Status)\t\(.Tags.role)\t\(.Tags.dc)"
' | column -t | head -15

echo ""
echo "=== Services ==="
consul_api "catalog/services" | jq -r 'to_entries[] | "\(.key)\tTags: \(.value | join(", "))"' | head -20

echo ""
echo "=== Connect Intentions ==="
consul_api "connect/intentions" | jq -r '
    .[] | "\(.SourceName)\t->\t\(.DestinationName)\t\(.Action)\t\(.Precedence)"
' | column -t | head -15

echo ""
echo "=== Mesh Gateways ==="
consul_api "catalog/service/mesh-gateway" | jq -r '
    .[]? | "\(.Node)\t\(.Address):\(.ServicePort)\t\(.Datacenter)\t\(.ServiceMeta.wan_address // "n/a")"
' | column -t | head -10

echo ""
echo "=== Ingress Gateways ==="
consul_api "catalog/service/ingress-gateway" | jq -r '
    .[]? | "\(.Node)\t\(.Address):\(.ServicePort)\t\(.Datacenter)"
' | column -t | head -10

echo ""
echo "=== Connect CA Info ==="
consul_api "connect/ca/roots" | jq '{
    ActiveRootID: .ActiveRootID[:12],
    TrustDomain: .TrustDomain,
    Roots: [.Roots[] | {ID: .ID[:12], Active: .Active, NotAfter: .NotAfter[:10]}]
}'

Phase 2: Analysis

#!/bin/bash
SERVICE="${1:?Service name required}"

echo "=== Service Health ==="
consul_api "health/service/$SERVICE" | jq -r '
    .[] | "\(.Node.Node)\t\(.Service.Address):\(.Service.Port)\tStatus: \(.Checks | map(.Status) | join(","))"
' | column -t | head -15

echo ""
echo "=== Service Proxy Config ==="
consul_api "catalog/service/$SERVICE-sidecar-proxy" | jq '
    .[0]? | {
        Service: .ServiceName, Port: .ServicePort,
        Proxy: .ServiceProxy | {
            DestinationServiceName, LocalServicePort,
            Upstreams: [.Upstreams[]? | {DestinationName, LocalBindPort}]
        }
    }'

echo ""
echo "=== Intentions for Service ==="
consul_api "connect/intentions?filter=DestinationName==\"$SERVICE\"" | jq -r '
    .[] | "\(.SourceName)\t->\t\(.DestinationName)\t\(.Action)\tCreated: \(.CreatedAt[:10])"
' | column -t | head -10

echo ""
echo "=== Service Resolver ==="
consul_api "config/service-resolver/$SERVICE" | jq '{
    Name: .Name, DefaultSubset: .DefaultSubset,
    Subsets: .Subsets, Redirect: .Redirect, Failover: .Failover
}' 2>/dev/null

echo ""
echo "=== Service Splitter ==="
consul_api "config/service-splitter/$SERVICE" | jq '{
    Name: .Name, Splits: [.Splits[]? | {Weight, Service, ServiceSubset}]
}' 2>/dev/null

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Use jq to parse Consul HTTP API responses
• Show intention relationships clearly (source -> destination)

Safety Rules

• Read-only by default: Use catalog, health, and config GET endpoints
• Intention changes affect service-to-service authorization immediately
• Never delete mesh gateways without confirming cross-DC traffic impact
• CA rotation must follow Consul's built-in rotation procedure

Output Format

Present results as a structured report:

Managing Consul Connect Report
══════════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• Default deny vs allow: Intention default can be set to deny all -- check acl.default_policy
• Sidecar naming: Sidecar proxy service is service-name-sidecar-proxy
• Datacenter isolation: Services in different DCs need mesh gateways for Connect traffic
• L4 vs L7 intentions: L7 intentions require service protocol to be set to HTTP
• ACL tokens: Connect operations require specific ACL policies for service identity