Architecture

Istio splits responsibilities across a control plane (istiod) and a data plane (Envoy sidecars, gateways, and Ambient-mode ztunnels). This page walks through the components in this repo, how they talk to each other, and how a request flows through the mesh.

Component map

graph TB
    subgraph K8s["Kubernetes API"]
      api[Services / Endpoints / Pods<br/>VirtualService / DestinationRule<br/>Gateway / HTTPRoute<br/>PeerAuthentication / AuthorizationPolicy<br/>WorkloadEntry / ServiceEntry<br/>Telemetry / WasmPlugin]
    end

    subgraph CP["Control plane: istiod (pilot-discovery)"]
      sd[Service Discovery<br/>pilot/pkg/serviceregistry]
      cs[ConfigStore<br/>crd / xds / files]
      pc[PushContext<br/>pilot/pkg/model]
      gen[Generators<br/>pilot/pkg/networking/core<br/>pilot/pkg/xds]
      ca[Citadel CA<br/>security/pkg/pki]
      inj[Sidecar Injector<br/>pkg/kube/inject]
      val[Admission Webhooks<br/>pkg/webhooks]
    end

    subgraph DP["Data plane"]
      agent[pilot-agent<br/>pkg/istio-agent + SDS]
      envoy[Envoy<br/>sidecar / gateway]
      ztunnel[ztunnel<br/>per-node L4 proxy<br/>istio/ztunnel repo]
      cni[istio-cni node agent<br/>cni/pkg/nodeagent]
    end

    api --> sd
    api --> cs
    sd --> pc
    cs --> pc
    pc --> gen
    gen -->|xDS| agent
    gen -->|xDS| envoy
    gen -->|wDS / CDS<br/>workloadapi| ztunnel
    ca -->|CSR / cert| agent
    inj -->|sidecar injection| envoy
    cni -->|programs iptables<br/>captures pod traffic| ztunnel
    agent -->|local xDS| envoy
    agent -->|SDS certs| envoy

Control plane (istiod)

Istiod is a single Go binary (pilot/cmd/pilot-discovery) that bundles what used to be Pilot, Citadel, and Galley. It is structured as a modular monolith. The wiring lives in pilot/pkg/bootstrap/server.go (~1400 lines), which constructs a Server and starts the following subsystems:

Subsystem	Code	Role
Config ingestion	pilot/pkg/config/, pilot/pkg/serviceregistry/	Watches Kubernetes (and optionally files / xDS) for Istio CRDs, core resources (Services, Endpoints, Pods), and ServiceEntry/WorkloadEntry.
Push context builder	pilot/pkg/model/push_context.go	Snapshots the world into an immutable, indexed view used by translation.
Networking core	pilot/pkg/networking/core/	Translates the snapshot into Envoy listeners, clusters, routes, endpoints, secrets.
xDS server	pilot/pkg/xds/	gRPC/MTLS endpoints serving ADS, CDS, EDS, LDS, RDS, SDS, ECDS, NDS, plus the workload API (wDS) for ztunnels.
CA / Citadel	security/pkg/pki/, security/pkg/server/ca/	Signs CSRs from agents and ztunnels, issues short-lived workload certs (SPIFFE identities).
Sidecar injection	pkg/kube/inject/	Mutating webhook that adds the istio-proxy container, istio-init (or CNI), and SDS volumes to pods.
Validation	pkg/webhooks/validation/, pkg/config/validation/	Validating admission webhook for Istio APIs.
Status reporting	pilot/pkg/status/	Writes status conditions back to CRDs (e.g. attached gateways, distribution status).
Multi-cluster	pkg/kube/multicluster/	Watches secret-mounted kubeconfigs to extend service discovery across clusters.

The bootstrap also spins up an admin port (default 15014) for Prometheus metrics, a debug HTTP server (/debug/configz, /debug/syncz, /debug/edsz, …), profiling, ControlZ, and the gRPC ports for xDS (15010 plain, 15012 mTLS, 15017 webhook, 8080 monitoring).

Push pipeline

graph LR
    ev[Resource event<br/>Service/CR/Endpoint] --> deb[Debouncer<br/>PILOT_DEBOUNCE_AFTER]
    deb --> pcb[PushContext<br/>builder]
    pcb --> pq[PushQueue<br/>per-proxy]
    pq --> gen[Generators]
    gen --> cache[XDS cache<br/>encoded protobuf.Any]
    cache --> ads[ADS streams]

Updates are debounced (default 100ms-10s window) so a burst of changes folds into one PushContext rebuild. The push queue (pilot/pkg/xds/pushqueue.go) coalesces per-proxy work, and proxy_dependencies.go lets generators skip proxies the change cannot affect. A binary-protobuf cache (pilot/pkg/networking/core/cluster_cache.go and similar) stores already-encoded Any payloads keyed by the inputs that contributed to them.

Data plane: sidecar mode

sequenceDiagram
    participant App as App container
    participant Iptables as iptables (init or CNI)
    participant Envoy as istio-proxy (Envoy)
    participant Agent as pilot-agent
    participant Istiod as istiod
    Iptables->>Envoy: redirect inbound to :15006, outbound to :15001
    Agent->>Istiod: ADS stream (mTLS, cert from SDS)
    Agent->>Agent: SDS server signs CSR<br/>via Istiod CA
    Agent->>Envoy: local xDS / SDS over UDS
    App->>Envoy: outbound TCP/HTTP
    Envoy->>Envoy: route lookup (RDS) → cluster (CDS) → endpoint (EDS)
    Envoy->>Envoy: mTLS to peer Envoy

Pods are mutated by Istiod's sidecar injector or by istioctl kube-inject to add the istio-proxy container plus an istio-init container that sets up iptables. When the istio-cni plugin is installed, the init container is skipped and CNI does the redirection.

pilot-agent (binary built from pilot/cmd/pilot-agent/, library in pkg/istio-agent/) is PID 1 in the istio-proxy container. It:

• Generates envoy-rev0.json from tools/packaging/common/envoy_bootstrap.json and pkg/bootstrap/.
• Spawns and supervises Envoy (pkg/envoy/).
• Runs an SDS server on a UDS that mints and rotates workload certificates (security/pkg/nodeagent/sds, security/pkg/nodeagent/cache).
• Acts as an xDS proxy between Envoy and Istiod (pkg/istio-agent/xds_proxy.go), which lets Envoy use a local connection while the agent handles long-lived control-plane connectivity, retries, and ECDS WASM caching.
• Runs Pilot health probes that translate Kubernetes readiness probes into Envoy-friendly checks.

Data plane: Ambient mode

In Ambient mode there are no sidecars. Two new components take over:

• ztunnel — a Rust per-node L4 proxy (lives in istio/ztunnel, vendored binary). Provides HBONE tunneling, mTLS termination/origination, and L4 authorization. It receives workload state from Istiod over the workload API (pkg/workloadapi/) and ZDS from the local CNI (pkg/zdsapi/).
• istio-cni node agent — runs as a DaemonSet (cni/cmd/istio-cni, cni/cmd/install-cni, cni/pkg/nodeagent/). It installs a CNI plugin, watches pods labeled with istio.io/dataplane-mode=ambient, enters their netns, and programs iptables/nftables to redirect traffic to a Unix socket whose other end is in the local ztunnel pod. Architecture details: architecture/ambient/ztunnel-cni-lifecycle.md.
• Waypoint proxies — optional per-namespace or per-service-account Envoy deployments that handle L7 features (HTTP routing, AuthZ, retries) for Ambient workloads. Configured via the Kubernetes Gateway API and rendered by Istiod's networking core (pilot/pkg/networking/core/listener_waypoint.go, cluster_waypoint.go).

graph TB
    subgraph Node1["Kubernetes node"]
      app1[App pod A] -.iptables in netns.-> ztA[ztunnel pod]
      app2[App pod B] -.iptables in netns.-> ztA
      cni[istio-cni node agent<br/>DaemonSet]
      cni -.programs.-> app1
      cni -.programs.-> app2
      cni <-.ZDS.-> ztA
    end
    ztA <-->|HBONE mTLS| ztB[ztunnel on other node]
    ztA -->|L7 redirect| wp[Waypoint proxy<br/>Envoy Deployment]
    istiod[istiod] -->|workload API<br/>+ XDS| ztA
    istiod -->|XDS| wp

Configuration sources

Istio reads roughly 25+ resource kinds. Schema declarations live in pkg/config/schema/. The most-used:

Kind	Purpose
VirtualService, DestinationRule, Gateway, ServiceEntry, WorkloadEntry, Sidecar, EnvoyFilter	Istio networking APIs
PeerAuthentication, RequestAuthentication, AuthorizationPolicy	Istio security APIs
Telemetry, WasmPlugin, ProxyConfig	Telemetry and proxy extension
Service, Endpoints, EndpointSlice, Pod, Node, Namespace	Core Kubernetes
Gateway, HTTPRoute, TLSRoute, TCPRoute, GRPCRoute (gateway.networking.k8s.io)	Kubernetes Gateway API
IstioOperator	Install-time configuration
MeshConfig	Global runtime config (mounted as ConfigMap)

Mesh-wide settings are merged from MeshConfig, ProxyConfig, the istio ConfigMap, and per-namespace/per-pod annotations (see reference/configuration.md).

Important file landmarks

File	Why it matters
pilot/pkg/bootstrap/server.go	The 1400-line wiring of istiod. Reading the constructor order tells you the dependency graph.
pilot/pkg/model/push_context.go	The snapshot type the rest of the system reads from.
pilot/pkg/xds/discovery.go, pilot/pkg/xds/ads.go	The xDS server: stream lifecycle, push triggers, dispatch to generators.
pilot/pkg/networking/core/configgen.go	Entry point for the listener/cluster/route generators.
pkg/istio-agent/agent.go, pkg/istio-agent/xds_proxy.go	The pilot-agent main loop and xDS proxying.
pkg/kube/krt/collection.go	The home-grown declarative controller framework most Ambient code is built on.
cni/pkg/nodeagent/server.go	Ambient pod redirection state machine on the node.
manifests/charts/istio-control/istio-discovery/templates/deployment.yaml	What istiod looks like when deployed.