Getting started

This page covers the local developer loop for istio/istio: prerequisites, building the binaries, running unit and integration tests, and finding your way around make targets.

Prerequisites

• Go: the version pinned in go.mod (go 1.25.7 at the time of writing). The project tracks recent Go releases closely; older versions will not build.
• Docker (or a Docker-API-compatible runtime). Many make targets — including the integration tests, image builds, and the build container — assume Docker is available.
• Make. The top-level Makefile delegates most work to Makefile.core.mk.
• Linux kernel features for the CNI / iptables / nftables tests (network namespaces, unshare, iptables binaries). If you are on macOS or Windows, use the build container (make BUILD_WITH_CONTAINER=1 ... or make shell).
• Optional: kubectl, helm, kind, and a working Kubernetes cluster for end-to-end tests.

The repository's developer guide on the GitHub wiki — Preparing for Development — has additional platform-specific notes.

Layout of the source tree

istio/
├── pilot/                 # Istiod control plane and pilot-agent (sidecar bootstrap)
│   ├── cmd/
│   │   ├── pilot-discovery/   # istiod main
│   │   └── pilot-agent/       # sidecar agent main
│   └── pkg/                   # control-plane libraries (xds, model, networking, ...)
├── istioctl/              # CLI binary (cmd + pkg)
├── operator/              # IstioOperator install/render library used by istioctl install
├── cni/                   # CNI plugin and ambient node agent
├── security/              # Citadel CA, node-agent SDS code
├── pkg/                   # Cross-cutting libraries (config, kube, krt, monitoring, ...)
├── manifests/             # Helm charts and profiles
├── tools/                 # Build tooling, packaging, iptables/nftables wrappers, protoc
├── tests/                 # Integration test framework and suites
├── samples/               # Bookinfo and other example apps
├── architecture/          # Design docs (markdown)
├── releasenotes/          # Per-PR release-note YAMLs
└── common/                # Shared scripts/Makefile pulled from istio/common-files

The Applications, Systems, and Features sections of this wiki dive into each area in depth.

Building binaries

The simplest path:

# Build all binaries for the host OS/arch under out/<os>_<arch>/
make build

That target compiles, in parallel:

Binary	Source	Used by
pilot-discovery	pilot/cmd/pilot-discovery/	The istiod container
pilot-agent	pilot/cmd/pilot-agent/	The istio-proxy / istio-init container
istioctl	istioctl/cmd/istioctl/	The user CLI
client, server	pkg/test/echo/cmd/	Echo apps used by tests
extauthz	samples/extauthz/cmd/	Sample external authz server

Linux-only binaries (the CNI plugin, install-cni) build via:

make build-linux        # cross-compiles to Linux
make build-cni          # CNI plugins only

The CNI plugin requires Linux because it links netlink and netns syscalls; non-Linux builds are intentionally limited.

If you need an istio-agent binary trimmed for size, the build uses the agent,disable_pgv,grpcnotrace,retrynotrace Go build tags (AGENT_TAGS in Makefile.core.mk). Standard binaries use vtprotobuf,disable_pgv for faster protobuf marshaling.

Building inside the build container

Set BUILD_WITH_CONTAINER=1 (or use export BUILD_WITH_CONTAINER=1) and the top-level Makefile re-runs everything inside gcr.io/istio-release/build-tools-.... This is the supported way to build on macOS / Windows or to match CI exactly:

BUILD_WITH_CONTAINER=1 make build
make shell                    # interactive build container

Building container images

make docker            # build all images locally
make docker.push       # build and push to $HUB:$TAG
HUB=docker.io/me TAG=dev make docker

Image build rules are in tools/istio-docker.mk. The set of images built is governed by the IMAGES family of variables and tools/skip-image.sh.

Generated code

A lot of code in the tree is generated. To regenerate everything (protos, CRDs, golden outputs, license metadata, formatting):

make gen

This is the gate for make gen-check, which CI runs to make sure no one forgot to commit generated artifacts. Targeted re-generators include:

• make proto — re-runs protoc via tools/proto/proto.mk.
• make update-crds — refreshes CRD manifests.
• make refresh-goldens (or make update-golden) — rewrites the test golden files for operator, bootstrap, kube-inject, gateway, authz builder, ambient registry, CNI iptables, istioctl writers, and more.
• make copy-templates — keeps the egress gateway chart in sync with the ingress chart and stamps profile defaults.

Tests

make test is an alias for make racetest, which invokes:

go test -race -tags=assert ./...

Pieces:

• -tags=assert flips on the runtime assertion paths. The xDS cache, for example, will panic if a key is overwritten with a different value (UNSAFE_PILOT_ENABLE_RUNTIME_ASSERTIONS=true). Always run tests with this on locally.
• A JUnit report is written to $JUNIT_OUT (out/.../junit.xml).
• Use make test PKG=./pilot/pkg/networking/core/... (for instance) to scope the run.
• make benchtest runs benchmarks under ./pilot/.... Output is compared against the previous run by prow/benchtest.sh.

Integration tests live in tests/integration/ and are orchestrated by the framework in pkg/test/framework/. They require a Kubernetes cluster (real, kind, or fake) and are typically run in CI rather than locally. The integration Makefile snippets are pulled in via include tests/integration/tests.mk.

For details, see how-to-contribute/testing.md.

Linting and formatting

make precommit         # format + lint, the recommended pre-PR step
make format            # gofumpt, goimports, prettier-style YAML, copyright headers
make lint              # all linters
make lint-go           # Go only (golangci-lint via common/Makefile.common.mk)
make lint-helm-global  # helm lint over manifests/
make lint-yaml         # yamllint
make lint-markdown     # mdl + markdown link check

The combined config for golangci-lint is common/config/.golangci.yml plus repo overrides in tools/golangci-override.yaml.

Useful environment variables

These variables apply at build/test time. For runtime variables consumed by istiod and pilot-agent, see reference/configuration.md.

Variable	Effect
HUB, TAG	Docker repository and tag for make docker.push. Default istio and the current git SHA.
BUILD_WITH_CONTAINER	Set to 1 to run make inside the build-tools container.
DEBUG	Set to 1 to build with debug info (-N -l) and skip dead-code stripping.
GOOS, GOARCH	Cross-compilation target.
BUILD_ALL	Default true; set to false to skip the all-binary linking shortcut for single-image builds.
T	Extra go test flags. Useful as T='-run TestFoo -v'.
PKG	Restrict make test to a package path. Default ./....
JUNIT_OUT	Override the JUnit output path.
BASE_VERSION	Pinned base image (gcr.io/istio-release tag) used by make docker.

Where binaries land

After make build:

out/
└── linux_amd64/
    ├── pilot-discovery
    ├── pilot-agent
    ├── istioctl
    ├── client
    ├── server
    └── release/
        ├── istioctl-linux-amd64
        ├── istioctl-osx
        └── ...

out/<os>_<arch>/ is also the default ARTIFACTS directory; the JUnit report and any logs the build emits go under it.

First contribution checklist

1. Run make build && make test to make sure your environment is sane.
2. Make your change. Add or update tests in the same package.
3. Add a release note YAML under releasenotes/notes/ if your change is user-visible. Use the template in releasenotes/template.yaml.
4. Run make precommit gen-check before pushing.
5. Open the PR using the template in .github/pull_request_template.md. Read how-to-contribute/development-workflow.md for the full review/merge process.