istio/istio

Networking core (config translation)

Active contributors: howardjohn, hzxuzhonghu, ramaraochavali, stevenctl, keithmattix

Purpose

pilot/pkg/networking/core/ is the translation pipeline. It turns a (Proxy, PushContext) pair into Envoy listeners, clusters, routes, and supporting resources. This is the largest single concentration of code in istiod (~50 source files, hundreds of thousands of test lines) and the place where Istio's user-facing networking APIs become Envoy config.

Directory layout

pilot/pkg/networking/core/
├── configgen.go                # ConfigGeneratorImpl, the top-level entry
├── cluster.go / cluster_builder.go / cluster_traffic_policy.go / cluster_tls.go / cluster_waypoint.go
│                              # CDS: building Envoy clusters
├── cluster_cache.go            # Encoded-Any cache for clusters
├── listener.go / listener_builder.go / listener_inbound.go / listener_address.go / listener_waypoint.go
│                              # LDS: building Envoy listeners
├── httproute.go                # RDS: HTTP route configurations
├── route/                      # Route conversion helpers (URL match, redirect, retry, fault, ...)
├── networkfilter.go / tls.go / accesslog.go / tracing.go / waypoint.go
│                              # Filters and per-listener concerns
├── extension/                  # ECDS extension/Wasm wiring
├── envoyfilter/                # EnvoyFilter patching
├── filterchain_options.go      # Filter chain matching
├── loadbalancer/               # LB policy translation
├── match/                      # Listener matchers (SNI, ALPN, ...)
├── tunnelingconfig/            # HBONE tunneling for ambient
├── listenertest/               # Test helpers
├── fake.go                     # Test fake-istiod fixture
└── fuzz_test.go                # Fuzz harness

The companion package pilot/pkg/networking/util/ holds shared helpers (proto conversion, port matching, address formatting). pilot/pkg/networking/serviceentry/ and pilot/pkg/networking/telemetry/ add domain-specific helpers.

Key abstractions

Symbol	File	Role
`ConfigGeneratorImpl`	`configgen.go`	Top-level translator
`ClusterBuilder`	`cluster_builder.go`	Per-proxy cluster builder, owns the cache
`ListenerBuilder`	`listener_builder.go`	Per-proxy listener builder
`RouteCacheEntry`	`httproute.go`	RDS cache key
`MutableObjects`	various	Pre-XDS-encode struct shape that filters can mutate
`xdsfilters.*`	`pilot/pkg/networking/util/` and `pkg/wellknown/`	Constants for known filter type URLs

How it works

graph TD
    pc[PushContext] --> cgi[ConfigGeneratorImpl]
    proxy[Proxy] --> cgi
    cgi --> cb[ClusterBuilder]
    cgi --> lb[ListenerBuilder]
    cgi --> rb[Route Building]
    cb --> cache1[Cluster cache]
    lb --> cache2[Listener cache]
    rb --> cache3[Route cache]
    cache1 --> cds[CDS resources]
    cache2 --> lds[LDS resources]
    cache3 --> rds[RDS resources]
    EnvFilter[EnvoyFilter patches] -.->|last|cb
    EnvFilter -.->|last|lb
    EnvFilter -.->|last|rb

Three flavors of proxy

The translator handles three roles for each proxy:

Sidecar (outbound) — listeners on 0.0.0.0:15001 capturing outbound traffic, virtual outbound listener with filter chains per service IP/port.
Sidecar (inbound) — listeners on 0.0.0.0:15006 for inbound, with filter chains per service port.
Gateway — Istio Gateway or Kubernetes Gateway API. Listeners on configured ports per gateway resource.
Waypoint — a sidecar-less L7 proxy in Ambient mode. Same translator but distinct files: listener_waypoint.go, cluster_waypoint.go, waypoint.go.

Each role has slightly different listener and cluster shapes, but they share the route, TLS, and filter-chain code.

Sidecar scopes

model.SidecarScope (in pilot/pkg/model/sidecar.go) precomputes which services/configs are visible to a given proxy after applying any Sidecar resources. This shrinks the work the translator has to do per proxy, but the trade-off is that SidecarScope itself must be computed for every change that could affect visibility.

Filter chains

Listeners have filter chains; matching is by SNI / ALPN / source address / port / SAN. The matchers are built in match/. Filter ordering is deterministic and documented in filterchain_options.go.

The set of filters applied is largely fixed:

For HTTP: HTTP connection manager → AuthN (JWT, mTLS) → AuthZ (RBAC) → Stats → Tracing → Wasm extensions → Router.
For TCP: TCP proxy → AuthZ → Stats.

EnvoyFilter patches are applied last, on a per-stage basis (pilot/pkg/networking/core/envoyfilter/).

Per-cluster TLS

Cluster TLS is the most-edited area. Files: cluster_tls.go, tls.go. The translation has to handle:

mTLS auto-negotiation with PERMISSIVE peers.
DestinationRule.tls overrides.
PeerAuthentication mode resolution (per-port).
SDS resource references for client + CA certs.

Caching

cluster_cache.go (and similar files for listeners and routes) keys encoded Any payloads by:

The cluster name and basic shape.
The proxy class (sidecar vs gateway, IP mode).
Every input that influenced the result (DestinationRule, PeerAuthentication, mesh mtls mode, ClusterLocal flag, …).

Hits skip the proto encoding entirely. As of writing, hit ratios on busy istiods are typically 95%+.

A subtle property: cache reads and writes are protected by sync.Map-style operations so the cache is shared across pushes safely. The strict-mode assertion (-tags=assert) panics if the same key is written with two different values, which is the canonical "cache key bug" signature.

EnvoyFilter

EnvoyFilter is the user-facing escape hatch. It allows arbitrary patches against:

Listeners (filter chain, network filter, HTTP filter)
Clusters
Routes (route configuration, route)
Cluster manager
Bootstrap

Patches run after Istio has built the standard config. The patcher is in pilot/pkg/networking/core/envoyfilter/. EnvoyFilter is powerful enough to break things; the recommendation is to use it only when the stable APIs are insufficient.

Integration points

Inputs: model.PushContext (built by service discovery + config store), model.Proxy (per-stream).
Outputs: *discovery.Resource slices consumed by pilot/pkg/xds/.
Caches: per-type encoded-Any caches; the global xDS cache; Sidecar scope cache.
Calls into: pilot/pkg/security/authn/, pilot/pkg/security/authz/builder/ for security filter compilation; pkg/config/host/ for host matching; pkg/config/protocol/ for protocol detection.

Entry points for modification

New traffic-policy field → likely affects cluster_traffic_policy.go and possibly cluster_tls.go. Add to the cache key.
New filter → register a constant in pkg/wellknown/, add the build logic in the appropriate listener / network-filter file. Decide if EnvoyFilter users should be able to insert before/after.
New listener type → for sidecar/gateway listener changes, listener.go and listener_inbound.go are the entries. For waypoint listeners, the _waypoint.go files.
New gateway behavior → gateway.go (in this directory) plus pilot/pkg/config/kube/gateway/ for the Kubernetes Gateway API → Istio mapping.

Performance notes

This package contains the hot path. Conventions:

Every new field that affects output must be in the relevant cache key.
Pre-allocate slices/maps with capacity hints.
Use protomarshal.Marshal (pilot/pkg/util/protomarshal/) for stable proto encoding; do not use the standard library directly when caching.
Benchmarks live in *_test.go (BenchmarkBuildXxx); always run make benchtest after a change.

Key source files

File	Purpose
`pilot/pkg/networking/core/configgen.go`	Entry point
`pilot/pkg/networking/core/cluster.go`	CDS top of stack
`pilot/pkg/networking/core/cluster_builder.go`	Per-proxy cluster builder
`pilot/pkg/networking/core/cluster_tls.go`	mTLS / DR.tls
`pilot/pkg/networking/core/cluster_cache.go`	Cluster cache
`pilot/pkg/networking/core/listener.go`	LDS top
`pilot/pkg/networking/core/listener_inbound.go`	Inbound listeners (15006)
`pilot/pkg/networking/core/listener_waypoint.go`	Waypoint listeners
`pilot/pkg/networking/core/httproute.go`	RDS top
`pilot/pkg/networking/core/route/route.go`	Route policy translation
`pilot/pkg/networking/core/networkfilter.go`	TCP network filters
`pilot/pkg/networking/core/tracing.go`	OTel/Zipkin/Datadog tracing config
`pilot/pkg/networking/core/accesslog.go`	Access log config
`pilot/pkg/networking/core/envoyfilter/patch.go`	EnvoyFilter application
`pilot/pkg/networking/core/gateway.go`	Istio Gateway specifics