Istio — Structure#

Layout pattern#

Custom Monorepo (component sub-trees)

Istio does not follow the canonical Go project layout (single top-level cmd/ + internal/). Instead, each major component owns its own sub-tree at the repo root, each containing its own cmd/ and pkg/ directories (pilot/, cni/, istioctl/, operator/, security/). A large shared library lives at the top-level pkg/. This gives each component team autonomy over their layout while sharing utilities through pkg/. All components share a single go.mod (istio.io/istio), making this a monorepo rather than a multi-module workspace.

Directory map#

istio/
├── pilot/                  # Core control plane (Istiod)
│   ├── cmd/
│   │   ├── pilot-discovery/  # Main Istiod binary (xDS server + service discovery)
│   │   └── pilot-agent/      # Per-pod agent binary (Envoy management)
│   ├── pkg/                  # Control plane libraries
│   │   ├── model/            # Mesh config model, service/endpoint abstractions
│   │   ├── xds/              # xDS push server (LDS/RDS/CDS/EDS)
│   │   ├── networking/       # Envoy config translation (core, plugins)
│   │   ├── serviceregistry/  # Kubernetes + ServiceEntry registries
│   │   ├── bootstrap/        # Istiod startup and wiring
│   │   ├── config/           # Config store implementations (kube, file, memory)
│   │   ├── security/         # mTLS authn/authz policy translation
│   │   └── leaderelection/   # HA leader election
│   └── test/                 # Test helpers and mock xDS
├── security/               # Citadel (certificate authority)
│   ├── pkg/
│   │   ├── pki/              # X.509 cert generation, rotation, validation
│   │   ├── nodeagent/        # Node-level secret/cert fetcher
│   │   ├── k8s/              # Kubernetes CA integration
│   │   └── server/           # Citadel gRPC server
│   └── tools/                # generate_cert, generate_csr utilities
├── cni/                    # Kubernetes CNI plugin
│   ├── cmd/
│   │   ├── istio-cni/        # CNI plugin binary
│   │   └── install-cni/      # CNI installer binary
│   └── pkg/
│       ├── install/          # Installation logic
│       ├── iptables/         # iptables traffic redirect rules
│       ├── nftables/         # nftables traffic redirect rules
│       ├── nodeagent/        # Per-node ztunnel socket management
│       └── repair/           # Repair controller for broken CNI states
├── istioctl/               # CLI tool
│   ├── cmd/istioctl/         # CLI binary entry point
│   └── pkg/                  # 30+ command implementation packages
│       ├── analyze/          # Config analysis and lint
│       ├── install/          # Helm-based installation
│       ├── validate/         # Resource validation
│       ├── waypoint/         # Ambient waypoint management
│       └── ...               # authz, describe, metrics, precheck, etc.
├── operator/               # Istio operator/installer
│   ├── cmd/mesh/             # Operator CLI entry point
│   └── pkg/
│       ├── apis/             # IstioOperator CRD types
│       ├── manifest/         # Manifest generation
│       ├── render/           # Helm value rendering
│       ├── install/          # Installation logic
│       └── helm/             # Helm wrapper
├── pkg/                    # Shared libraries (238+ sub-packages)
│   ├── config/               # Config schema, collection, event types
│   ├── kube/                 # Kubernetes client wrappers, informers
│   ├── security/             # SPIFFE, JWT, cert utilities
│   ├── log/                  # Structured logging
│   ├── monitoring/           # OpenCensus/OTel metrics
│   ├── istio-agent/          # istio-agent bootstrap
│   ├── proxy/                # Envoy binary management
│   ├── wasm/                 # WebAssembly plugin support
│   ├── hbone/                # HTTP/2 tunneling (HBONE protocol)
│   ├── xds/                  # xDS client utilities
│   ├── workloadapi/          # Workload gRPC API types
│   ├── test/                 # Test framework (echo client/server, framework)
│   └── ...                   # 200+ additional utility packages
├── manifests/              # Helm charts and install profiles
│   ├── charts/               # base, default, gateway, istio-cni, ztunnel
│   └── profiles/             # default, minimal, ambient, demo profiles
├── tests/                  # Top-level integration/e2e tests
│   ├── integration/          # Feature-area integration suites
│   │   ├── pilot/            # Traffic management tests
│   │   ├── security/         # mTLS, authz tests
│   │   ├── telemetry/        # Metrics, tracing tests
│   │   └── ambient/          # Ambient mode tests
│   └── fuzz/                 # Fuzz targets
├── architecture/           # Architecture docs (ASCII diagrams)
│   ├── ambient/              # Ambient mode design docs
│   ├── networking/           # Networking architecture
│   └── security/             # Security architecture
├── samples/                # Runnable demo apps (bookinfo, extauthz, etc.)
├── tools/                  # Build/dev tooling
│   ├── docker-builder/       # Custom Docker image build tool (Go)
│   ├── istio-iptables/       # iptables config CLI (standalone)
│   └── istio-nftables/       # nftables config CLI (standalone)
├── common/                 # Shared CI scripts (synced from istio/common-files)
├── docker/                 # Base Dockerfiles
├── bin/                    # Helper shell scripts
├── release/                # Release tooling
├── Makefile                # Entry Makefile (delegates to Makefile.core.mk)
└── Makefile.core.mk        # All build targets

Entry points#

Binary	Path	Purpose
`pilot-discovery`	`pilot/cmd/pilot-discovery/main.go`	Istiod — primary control plane; runs xDS server, service discovery, CA, webhook controller, and config controller in one binary
`pilot-agent`	`pilot/cmd/pilot-agent/main.go`	Per-pod sidecar agent — bootstraps Envoy, manages certs, handles health checks and traffic interception via iptables
`istioctl`	`istioctl/cmd/istioctl/main.go`	CLI — operator tool for install, analyze, debug, waypoint, and mesh management
`istio-cni`	`cni/cmd/istio-cni/main.go`	CNI plugin — intercepts pod network setup and installs iptables/nftables traffic redirect rules
`install-cni`	`cni/cmd/install-cni/main.go`	CNI installer — DaemonSet binary that installs the CNI plugin binary/config on each node
`client`	`pkg/test/echo/cmd/client/main.go`	Test echo client (used in integration tests)
`server`	`pkg/test/echo/cmd/server/main.go`	Test echo server (used in integration tests)
`extauthz`	`samples/extauthz/cmd/extauthz/main.go`	External authorization sample server
`generate_cert`	`security/tools/generate_cert/main.go`	Dev tool for X.509 cert generation
`generate_csr`	`security/tools/generate_csr/main.go`	Dev tool for CSR generation
`docker-builder`	`tools/docker-builder/main.go`	Custom Go tool to build Docker images using crane (avoids docker daemon)

Package organization#

Internal packages: Almost none — only pilot/pkg/autoregistration/internal is formally private. Istio does not use Go’s internal/ convention broadly; everything in pkg/ is intended to be importable.
Public packages (pkg/): The top-level pkg/ is the project’s shared library:
- pkg/config — Config schema, collection management, config change events
- pkg/kube — Kubernetes client, informer factories, multicluster client
- pkg/security — SPIFFE identity, JWT parsing, TLS configuration
- pkg/log — Structured logging (zap-backed) with scope support
- pkg/monitoring — Metrics (OpenCensus/OpenTelemetry integration)
- pkg/hbone — HBONE protocol (HTTP/2 tunnel for ambient mode)
- pkg/wasm — WebAssembly plugin fetching and caching
- pkg/xds — xDS client-side utilities and ADSC (ADS client)
- pkg/test — Integration test framework (framework, echo, fakes)
- pkg/istio-agent — Bootstrap logic for the istio-agent process
- pkg/proxy — Envoy process lifecycle management
- 40+ additional utility packages (slices, maps, queue, backoff, lazy, etc.)

Layering: The layering is roughly:

tests/integration  (e2e, uses public APIs)
     ↓
istioctl/pkg       (user-facing CLI, uses pilot + operator APIs)
     ↓
pilot/pkg/xds      (xDS push server)
     ↓
pilot/pkg/networking  (Envoy config translation)
     ↓
pilot/pkg/model    (core mesh model — central shared type layer)
     ↓
pkg/config         (config schema + store)
     ↓
pkg/kube           (Kubernetes primitives)

There is no strict hexagonal/clean-architecture boundary; the dominant pattern is layered with pilot/pkg/model as the central hub type system.

Build system#

Build tool: GNU Make (Makefile + Makefile.core.mk), with an optional Docker container mode (BUILD_WITH_CONTAINER=1) for hermetic CI builds
Key targets:
- make build — builds all binaries via common/scripts/gobuild.sh (a wrapper around go build with linker flags for version injection)
- make build-linux — cross-compiles for Linux (used for container image builds)
- make build-cni — builds the CNI plugin binaries
- make test — runs unit tests
- make docker — builds Docker images using the custom tools/docker-builder tool
- make push — builds and pushes images to registry
- make generate — runs code generation (proto, CRD types)
- make lint / make format — linting and formatting
Docker: Yes, multi-stage; uses distroless base images (docker/Dockerfile.distroless). Images are built by the custom Go tools/docker-builder which uses github.com/google/go-containerregistry/pkg/crane to avoid requiring a Docker daemon.
Additional tooling: prow/ holds Kubernetes Prow CI job configs; release/ holds release scripts; manifests/charts/ are Helm charts for deployment.

Notable structural decisions#

Component sub-trees instead of flat cmd/: Each major binary group (pilot, cni, istioctl, operator, security) gets its own top-level directory with its own cmd/ and pkg/. This mirrors the team/ownership structure and prevents pilot/ types from accidentally depending on cni/ types. The trade-off is deeper import paths and partial duplication of sub-structure.
No internal/ convention: Istio almost entirely eschews Go’s internal/ package access control. With 238+ sub-packages in pkg/ alone, the project relies on code review and CODEOWNERS conventions rather than compiler-enforced visibility. The single exception (pilot/pkg/autoregistration/internal) shows the pattern exists but was deliberately not generalized.
Architecture docs as first-class artifacts: The architecture/ directory contains ASCII-art and Markdown architecture diagrams (ambient mode, networking, security), unusual for a Go project and reflecting the project’s investment in documenting its own design.
Helm charts co-located with Go code: manifests/charts/ (Helm charts for installation) lives alongside Go source in the same module. This avoids a separate infra repository but means Helm chart changes and Go code changes are coupled in the same PR workflow.
Custom Docker builder: Rather than using docker build or standard tooling like ko, Istio wrote a bespoke tools/docker-builder in Go using go-containerregistry/crane. This allows building and pushing multi-arch images without a Docker daemon, critical for their Prow-based CI environment.
Dual network interception implementation: Both cni/pkg/iptables/ and cni/pkg/nftables/ exist in parallel, with tools/istio-iptables/ and tools/istio-nftables/ as standalone CLI tools for the same. This reflects active migration from iptables to nftables for ambient mode compatibility with modern Linux kernels.