istio/istio

Traffic management

Active contributors: howardjohn, hzxuzhonghu, ramaraochavali, stevenctl

What users do

Traffic management is Istio's flagship feature set: HTTP/gRPC routing, weighted splits, retries, timeouts, fault injection, mirroring, locality-aware load balancing, circuit breaking, outlier detection, and TLS origination. All of it is configured through three CRDs: VirtualService, DestinationRule, and Gateway (for ingress).

The user-facing docs are at https://istio.io/latest/docs/concepts/traffic-management/. This page is the implementation map.

CRDs and where they're defined

The schemas live in istio/api:

CRD	Purpose	Schema
`VirtualService`	HTTP / TCP / TLS route rules per host	`networking/v1/virtual_service.proto`
`DestinationRule`	Per-cluster traffic policy: LB, conn pool, outlier, mTLS	`networking/v1/destination_rule.proto`
`Gateway`	Ingress/egress gateway config	`networking/v1/gateway.proto`
`ServiceEntry`	Add an external host to the mesh	`networking/v1/service_entry.proto`
`Sidecar`	Restrict per-namespace visibility	`networking/v1/sidecar.proto`
`WorkloadEntry`, `WorkloadGroup`	VM workloads	`networking/v1/workload_entry.proto`

The Istio repo consumes these via go.mod (istio.io/api).

Translation pipeline

graph LR
    user[User CRDs] --> store[ConfigStore<br/>pilot/pkg/config/kube/crdclient]
    store --> push[PushContext build]
    reg[Service Registry] --> push
    mc[MeshConfig] --> push
    push --> sidescope[SidecarScope per proxy]
    sidescope --> route[Route compile<br/>networking/core/route]
    sidescope --> cluster[Cluster compile<br/>networking/core/cluster*]
    sidescope --> listener[Listener compile<br/>networking/core/listener*]
    route --> rds[RDS]
    cluster --> cds[CDS]
    listener --> lds[LDS]
    rds --> envoy[Envoy proxies]
    cds --> envoy
    lds --> envoy

VirtualService → routes

A VirtualService is a host-keyed routing table. The compiler in pilot/pkg/networking/core/route/route.go (and helpers in the same directory) turns each HTTPRoute into an Envoy Route:

match clauses → Envoy URL path / header / method matchers.
redirect / rewrite → Envoy redirect actions.
route.weight → Envoy weighted clusters.
retries, timeout, fault, mirror, corsPolicy → per-route filter config.

The output is per-virtual-host, packed into a single RouteConfiguration per outbound port (pilot/pkg/networking/core/httproute.go).

DestinationRule → cluster traffic policy

A DestinationRule is a hostname-keyed bag of cluster overrides. The compiler in pilot/pkg/networking/core/cluster_traffic_policy.go and cluster_tls.go applies:

Connection pool sizes (connectionPool.tcp.maxConnections, etc.).
LB policy (round-robin, random, ringHash, leastRequest, locality-weighted).
Outlier detection thresholds.
Subsets — one Envoy cluster per labeled variant of the service.
TLS settings — origination, SNI, caCertificates, mode (SIMPLE, ISTIO_MUTUAL, MUTUAL).

The relationship between VirtualService route weights and DestinationRule subsets is the canonical canary pattern — see examples/bookinfo/.

Gateway → ingress listeners

Gateway is bound to a workload via selector (Istio API) or via the Kubernetes Gateway API (preferred). For the Istio API path, pilot/pkg/networking/core/gateway.go builds:

A listener per gateway port + TLS settings combo.
A virtual host per host in any matching VirtualService with gateways: [<this>].

For the Kubernetes Gateway API path, pilot/pkg/config/kube/gateway/ translates Gateway + HTTPRoute + TCPRoute etc. into the same internal types. See features/gateway-api.

Sidecar → scope

A Sidecar resource (CRD; not the istio-proxy container) restricts which services and configs a proxy in a namespace sees. This shrinks the proxy's config and is the recommended way to isolate large meshes. The compiler is in pilot/pkg/model/sidecar.go.

A common deployment pattern: install a single Sidecar per namespace with egress.hosts: ["./*"] to limit outbound visibility to the local namespace, then add explicit allowlists for services in other namespaces.

EnvoyFilter — escape hatch

When the stable APIs don't cover a need, EnvoyFilter patches the rendered Envoy config. Patches run after Istio has built the standard config. See systems/networking-core for the patch model.

Locality and failover

Locality-weighted load balancing uses Kubernetes node labels (topology.kubernetes.io/region etc.) plus DestinationRule.trafficPolicy.loadBalancer.localityLbSetting. Endpoints are tagged with locality at registry build time (pilot/pkg/serviceregistry/kube/controller/); the priority ranking of localities is computed per-proxy at push time.

Failover overrides (e.g. "if us-west is unhealthy, send to us-east") are configured via localityLbSetting.failover.

Outlier detection / circuit breaking

Outlier detection is per-cluster (in cluster_traffic_policy.go). Defaults are conservative; aggressive ejection requires user opt-in. Combined with connectionPool limits, this is Istio's circuit-breaker story.

ServiceEntry

A ServiceEntry adds an external host (e.g. api.example.com) to the mesh. The translation:

The ServiceEntry controller (pilot/pkg/serviceregistry/serviceentry/) creates model.Service and model.WorkloadInstance entries for the external host.
From there, the same routing pipeline applies: VirtualService and DestinationRule work as if it were a regular service.

For TLS origination (encrypt traffic to an external HTTPS endpoint), the DestinationRule.tls block on a SE is the standard pattern.

Caching

Most traffic-management changes trigger a full PushContext rebuild. The xDS cache mitigates this — see systems/networking-core. The Sidecar scope cache is the second-largest lever (pilot/pkg/model/sidecar.go).

Trade-offs

Sidecar scoping vs convenience — narrowing scope shrinks config but breaks "just create a service and it works" demos. The default scope is "everything, everywhere", which doesn't scale. Production users should add Sidecar resources for any cluster larger than ~100 services.
EnvoyFilter vs stable APIs — EnvoyFilter is powerful but tightly coupled to Envoy versions. Upgrades can break it silently. Use only when no stable API does the job.
Outlier detection aggressiveness — false positives eject healthy endpoints. The defaults err on the side of "do nothing"; users have to tune up.

Key source files

File	Purpose
`pilot/pkg/networking/core/route/route.go`	`VirtualService` → Envoy routes
`pilot/pkg/networking/core/httproute.go`	RDS RouteConfiguration
`pilot/pkg/networking/core/cluster.go`	Cluster top
`pilot/pkg/networking/core/cluster_traffic_policy.go`	DR traffic policy
`pilot/pkg/networking/core/cluster_tls.go`	DR TLS settings
`pilot/pkg/networking/core/listener.go`	LDS top
`pilot/pkg/networking/core/gateway.go`	Istio Gateway listeners
`pilot/pkg/serviceregistry/serviceentry/controller.go`	ServiceEntry registry
`pilot/pkg/model/sidecar.go`	Sidecar scope
`pilot/pkg/model/virtualservice.go`	VirtualService model