Istio

Istio is an open-source service mesh that layers transparently onto distributed applications, mostly Kubernetes-based ones. It provides traffic management, mTLS-based security, and observability for service-to-service communication, and ships both the original sidecar-based data plane (Envoy) and the newer sidecar-less Ambient mode (ztunnel + waypoints).

This wiki covers the istio/istio repository, which is the main Go code repo for the project. It hosts the Istio control plane (istiod), the sidecar bootstrap agent (pilot-agent), the CNI node agent, the istioctl CLI, the operator/install tooling, the security CA, Helm charts, and integration tests. Companion repositories such as istio/api, istio/proxy (Envoy filters), and istio/ztunnel (Rust ambient proxy) live elsewhere and are pulled in via dependencies and an istio.deps pin file.

What it ships

• Istiod — the control plane. A modular monolith that watches Kubernetes resources, builds an in-memory model of the mesh, signs workload certificates, runs admission webhooks, and serves Envoy configuration over xDS.
• pilot-agent — the per-pod bootstrap. It generates Envoy's bootstrap config, supervises the Envoy process, runs an SDS server that mints workload certificates, multiplexes xDS to Istiod, and runs application health probes.
• istio-cni node agent — installs a CNI plugin on every node and, in Ambient mode, programs in-pod iptables/nftables rules to redirect workload traffic to the local ztunnel.
• istioctl — the CLI for installing Istio, inspecting Envoy/ztunnel config, debugging routing, generating Gateway/Sidecar manifests, analyzing configuration, and rolling out canary upgrades via revision tags.
• operator CLI — the renderer that turns the IstioOperator API plus profiles and Helm overlays into the install manifest. Used by istioctl install.
• Helm charts and profiles — manifests/charts/ (base, istio-discovery, gateway, gateways, istio-cni, ztunnel) plus manifests/profiles/ (default, demo, minimal, ambient, openshift, etc.).

What's in this wiki

Section	What you'll find
Architecture	Control-plane vs data-plane, sidecar mode vs Ambient, request lifecycle, component diagrams
Getting started	Prerequisites, building, running tests, where binaries land
Glossary	Project-specific vocabulary (Pilot, ztunnel, waypoint, sidecar, krt, PushContext, …)
By the numbers	Codebase size, churn, language breakdown
Lore	Eras of Istio's evolution: Mixer, Galley, the operator pivot, Ambient mode
How to contribute	Workflows, testing, debugging, conventions
Applications	The deployable binaries this repo produces
Systems	Internal subsystems that span multiple binaries (xDS, service discovery, networking core, CA, krt, …)
Features	User-facing capabilities (traffic management, mTLS, multicluster, Ambient)
Reference	Mesh config, environment variables, dependencies
Maintainers	CODEOWNERS-derived ownership map

Where to start

If you have never read this codebase before, the most efficient order is:

1. Architecture — understand the control plane / data plane split and where the boundaries are.
2. Glossary — Istio terminology is dense; skim before diving in.
3. applications/istiod — the largest single component. The bootstrap server in pilot/pkg/bootstrap/server.go is the wiring diagram for almost everything else.
4. systems/xds — once you know the components, see how config gets served to proxies.
5. systems/service-discovery and systems/networking-core — the input and output sides of Istiod's translation pipeline.

External resources you will want bookmarked:

• istio.io — user-facing documentation.
• istio/istio GitHub Wiki — historical developer notes, "Preparing for Development", "Development Conventions".
• architecture/ — design docs that ship in this repo.