Service mesh (Connect)

Connect is Consul's mesh: service-to-service mTLS, identity-based authorization (intentions), and L7 traffic management — all served by Envoy proxies that learn their config from a Consul agent (or directly from the dataplane).

Pieces

Piece	Where
Identity (SPIFFE)	agent/connect/uri.go, agent/structs/identity.go
Connect CA (roots, leafs, providers)	Connect CA, agent/connect/ca/, agent/leafcert/
Sidecar service registration	agent/sidecar_service.go
Discovery chain	agent/structs/config_entry_discoverychain.go, agent/consul/discoverychain/
Intentions (auth)	Intentions, agent/consul/intention_endpoint.go
Mesh config	agent/structs/config_entry_mesh.go
Proxy config (proxycfg)	Proxy config, agent/proxycfg/
xDS server	xDS server, agent/xds/
Envoy extensions	envoyextensions/ (Go module)
Mesh gateways	agent/proxycfg/mesh_gateway.go, agent/structs/config_entry_gateways.go
Ingress gateways	agent/proxycfg/ingress_gateway.go
Terminating gateways	agent/proxycfg/terminating_gateway.go
API gateway	API gateway, agent/consul/gateways/
Public gRPC	proto-public/pbconnectca/

End-to-end flow

graph TB
    subgraph Service["Service \"web\""]
        App[App container/process]
        Sidecar[Envoy sidecar]
        App -->|localhost| Sidecar
    end
    subgraph Cluster["Consul cluster"]
        Agent[Local agent<br/>proxycfg + xDS]
        Server[Server cluster]
    end

    Sidecar <-->|delta xDS over gRPC| Agent
    Agent <-->|streaming subscribe<br/>+ blocking RPC| Server

    Sidecar -->|mTLS| Sidecar2[Envoy sidecar of \"db\"]
    Sidecar2 --> App2[\"db\" app]

    Server -.signs leaf.- Agent
    Agent -.fetches leaf.- Sidecar

Identity and trust

Each mesh service has a SPIFFE URI:

spiffe://<trust-domain>.consul/ns/<ns>/dc/<dc>/svc/<service>

The trust domain is derived from the Consul cluster's CA. Both sides of an mTLS handshake validate the URI against the configured intentions and the issuer chain. Identity helpers live in agent/connect/uri.go (parsing) and agent/structs/identity.go (auth context).

Sidecar registration

Most mesh services are registered with an inline sidecar_service block:

service {
  name = "web"
  port = 8080
  connect { sidecar_service { proxy { upstreams = [...] } } }
}

agent/sidecar_service.go translates this into two registrations: the application service and a connect-proxy service whose Proxy.DestinationServiceName points back. The connect-proxy registration triggers proxycfg.Manager to start a watcher and the xDS server to wait for an Envoy connection.

Discovery chain

service-resolver, service-router, and service-splitter config entries compose into a per-service discovery chain: a DAG that says "to reach service X, evaluate these L7 routes, split by weight, then resolve to these targets, with this failover policy." The compiler in agent/consul/discoverychain/ produces a CompiledDiscoveryChain that the proxy config manager hands to xDS.

Mesh gateways

A mesh gateway is a special proxy that routes mTLS traffic across DCs/peerings:

• Inbound connections arrive on a single gateway port, identified by SNI.
• The SNI encodes the destination service + namespace + partition + peer.
• The gateway forwards to the local upstream Envoy.

Mesh gateways are critical for cluster peering and for WAN federation that runs over mesh gateways instead of direct WAN. See agent/proxycfg/mesh_gateway.go and agent/xds/listeners.go::buildMeshGatewayListener.

Ingress and terminating gateways

Gateway	Direction	Purpose
Ingress gateway	External → mesh	Lets non-mesh clients reach mesh services. HTTP/TCP listeners with route configs
Terminating gateway	Mesh → external	Lets mesh services connect to non-mesh destinations (e.g., legacy DBs) with TLS origination
Mesh gateway	Mesh ↔ Mesh (cross-DC/peer)	See above
API gateway	External → mesh (HTTP/L7)	Like ingress but with rich routing, JWT, and TLS material from config entries

Each kind has a builder in agent/proxycfg/<kind>_gateway.go and a config entry in agent/structs/config_entry_gateways.go.

Envoy extensions

envoyextensions/extensions/ provides built-in extensions that mutate xDS resources at build time:

• aws-lambda — surface AWS Lambda as a mesh service.
• awsauth — sign upstream calls with AWS SigV4.
• lua — apply Lua filters to listeners.
• otelaccesslogging — OTEL access log emitter.
• propertyoverride — patch arbitrary fields on resources.
• extauthz — external authorization filter.

Extensions are composed in agent/xds/extensionruntime/. Operators reference them via service-defaults.envoy_extensions.

Performance and operations

• xDS capacity: agent/consul/xdscapacity/ rebalances proxy attachments across servers as the count grows.
• Leaf cache: agent/leafcert/ keeps short-lived leaf certs in memory and pre-emptively rotates.
• Streaming: catalog and config-entry events are pushed via streaming subscribe so a hundred sidecars on one host don't poll separately.
• Proxy debugging: consul troubleshoot proxy|upstreams|ports (see troubleshoot/) introspects a sidecar's view.

Integration points

• Consul Dataplane — runs the same proxy config + xDS logic outside the agent for sidecar-less Kubernetes deployments. See proto-public/pbdataplane/ and the public services under agent/grpc-external/.
• Vault and AWS PCA — pluggable CA providers.
• Consul ESM and external dashboards consume metrics and event streams.

Entry points for modification

• Add a new mesh kind / extension: see envoyextensions/extensions/ examples.
• Add a new gateway kind: see how api-gateway was bolted on (agent/consul/gateways/, agent/proxycfg/api_gateway.go, agent/xds/listeners_apigateway.go).
• Tune intention RBAC compilation: agent/xds/rbac.go.
• Adjust leaf cert TTLs and renewal: agent/leafcert/leafcert.go.