Tooling

The build and developer-tooling stack for istio/istio. This is the meta-layer: what runs make, what generates code, what packages images, and what publishes releases.

Make

The top-level entry is Makefile. It pulls in:

• Makefile.overrides.mk — optional, for per-developer customization (gitignored).
• Makefile.core.mk — the substance of the build (~600 lines).
• tools/proto/proto.mk — proto generation rules.
• tools/istio-docker.mk — Docker image rules.
• tools/packaging/packaging.mk — deb/rpm packaging.
• tests/integration/tests.mk — integration test entry points.
• common/Makefile.common.mk — shared linting and formatting (synced from istio/common-files).

If BUILD_WITH_CONTAINER=1, all targets re-run inside gcr.io/istio-release/build-tools via common/scripts/run.sh. This is the canonical CI path; everything else can be reproduced locally.

The make show.<var> trick prints any Makefile variable. make show.GOPATH, make show.HUB, etc.

Build container

gcr.io/istio-release/build-tools-<sha> is a pinned image with the Go toolchain, protoc, helm, kubectl, kind, golangci-lint, and other build prerequisites. The exact SHA is tracked in common/.commonfiles.sha. To use it:

make shell                # interactive
BUILD_WITH_CONTAINER=1 make build      # any target

Inside the container, your repo is bind-mounted at /work and GOPATH=/go is set. The image is bumped via make update-common, which pulls a fresh copy from istio/common-files.

Code generation

Run everything:

make gen

The gen target is a meta-target that runs:

Target	What it does
mod-download-go	go mod download for caching
go-gen	go generate ./...
mirror-licenses	Refresh licenses/ from go.sum
format	gofumpt + goimports + copyright + YAML/script formatting
update-crds	Run bin/update_crds.sh to regenerate CRD manifests under manifests/charts/base/files/
proto	Run protoc via tools/proto/proto.mk
copy-templates	Sync the egress gateway chart from the ingress chart and stamp profile defaults across all charts
gen-addons	Run manifests/addons/gen.sh
update-golden	Run goldens through the test framework (REFRESH_GOLDEN=true go test ...)

CI runs make gen-check, which runs make gen and then asserts the working tree is clean. PRs that forget to commit generated output fail this gate.

The list of golden directories is in Makefile.core.mk under refresh-goldens:

• operator/...
• pkg/bootstrap/...
• pkg/kube/inject/...
• pilot/pkg/config/kube/gateway/...
• pilot/pkg/security/authz/builder/...
• pilot/pkg/serviceregistry/ambient/...
• cni/pkg/iptables/...
• cni/pkg/plugin/...
• istioctl/pkg/workload/...
• istioctl/pkg/writer/envoy/configdump/...
• istioctl/pkg/writer/ztunnel/configdump/...

Linting

make lint           # everything
make lint-go        # golangci-lint
make lint-helm-global
make lint-yaml
make lint-markdown
make lint-dockerfiles
make lint-licenses
make lint-scripts
make lint-python
make lint-copyright-banner

golangci-lint config: base in common/config/.golangci.yml, repo-specific overrides in tools/golangci-override.yaml. Active linters include gofumpt, goimports, revive, errcheck, unused, staticcheck, plus a few Istio-specific ones.

Custom linters in this repo:

• testlinter — checks for forgotten leaks and improper test fixtures (pkg/test/testlinter/).
• envvarlinter — checks that every env.Register has a description and is documented (tools/envvarlinter/).
• bin/check_samples.sh — validates sample manifests.

Build flags and tags

Two main Go build-tag sets:

• vtprotobuf,disable_pgv — for "standard" binaries (istiod, istioctl, echo). vtprotobuf adds optimized marshalling; disable_pgv strips unused validation.
• agent,disable_pgv,grpcnotrace,retrynotrace — for pilot-agent. Trims dependencies that would otherwise bloat the small per-pod sidecar.

The agent tag is the most pervasive: code paths that should not run in the agent are gated with //go:build !agent or //go:build agent at the file level.

Build-time linker flags:

• Release builds use -extldflags -static -s -w (static link, strip).
• DEBUG=1 switches to -N -l (no optimizations, no inlining) and skips stripping.

Docker images

make docker builds all Istio images locally. Image rules are generated in tools/istio-docker.mk from a list maintained in tools/docker.yaml. The set includes:

• pilot — istiod
• proxyv2 — Envoy + pilot-agent
• install-cni — CNI installer + node agent
• ztunnel — packaged ztunnel binary
• operator — legacy in-cluster operator (kept for compat; CLI is the supported path)

Multi-arch builds use buildx; prow/buildx-create provisions the builder.

The base image (Envoy + Ubuntu rootfs) is pinned via BASE_VERSION in Makefile.core.mk. Bumps to the base version are PRs against this variable; the base image build pipeline lives under docker/.

Release tooling

Release artifacts are built by:

• prow/release-commit.sh — run on every commit to master and release branches; produces nightly/release builds.
• release/ — release packaging scripts (tarballs, container manifests, GCS uploads).
• tools/build-base-images.sh — base image builds.
• tools/gen_istio_image_list.sh — image list generator for offline installs.

The release process is documented at RELEASE_BRANCHES.md. For the day-to-day developer, the only release-tooling interaction is adding YAML files under releasenotes/notes/.

Local helpers

Useful scripts in bin/ (some called from Make, some standalone):

Script	Purpose
bin/init.sh	Bootstrap dependencies (Envoy binary download) on first build
bin/build_ztunnel.sh	Fetch the pinned ztunnel build
bin/update_crds.sh	Regenerate CRD manifests
bin/check_samples.sh	Sample manifest validation
bin/retry.sh	Retry-with-backoff wrapper used by Make
bin/check_license.sh	License header check

The tools/ directory has more:

• tools/docker-builder/ — multi-arch image build orchestrator.
• tools/istio-iptables/ — Go library that programs sidecar iptables rules. Replaces the older istio-iptables.sh.
• tools/istio-nftables/ — nftables variant for newer kernels.
• tools/proto/ — protoc plugin orchestration.
• tools/bug-report/ — the istioctl bug-report data collector.
• tools/packaging/common/envoy_bootstrap.json — the Envoy bootstrap template baked into pilot-agent.
• tools/certs/ — helpers for generating cluster CAs in tests.

CI: Prow

prow/ holds the Prow job configuration: release-commit.sh, benchtest.sh, lib.sh, and the various entry points called by Prow's presubmit and periodic jobs. PR comments like /test pull-istio-integ-pilot-v2-istiodremote-tests map to Prow tide queries defined in the istio/test-infra repo.

Versioning

The current version is in the VERSION file (one line). The Make build appends -dev if VERSION env var is unset. Tags on master are alpha/beta; tags on release-1.X are GA and patch.

istio.deps pins the ztunnel and proxy SHAs that the current build is compatible with. The Automator updates this file ~daily via dependabot-style automation.