pilot-agent

Active contributors: howardjohn, costinm, hzxuzhonghu, ramaraochavali, keithmattix

Purpose

pilot-agent is the per-pod sidecar bootstrap. It is PID 1 in the istio-proxy container and is responsible for: generating Envoy's bootstrap configuration, supervising the Envoy process, running an SDS server that mints and rotates workload certificates, proxying xDS between Envoy and Istiod, exposing local DNS resolution for the mesh, and translating Kubernetes readiness probes into Envoy-aware checks.

The binary is built from pilot/cmd/pilot-agent/main.go (40 lines of cobra plumbing); the long-lived agent code lives in pkg/istio-agent/. The agent is also packaged inside proxyv2, the image that ships Envoy itself.

Directory layout

pilot/cmd/pilot-agent/
├── main.go              # cobra entry point
├── app/                 # CLI commands (root, proxy, request, status)
├── config/              # Bootstrap input gathering
├── status/              # Probe translation, ready/health server
├── metrics/             # Pilot-agent self-metrics
└── options/             # Flag and env-derived options

pkg/istio-agent/
├── agent.go             # The main `Agent` struct (~830 lines)
├── xds_proxy.go         # SoTW xDS proxy from Envoy → Istiod
├── xds_proxy_delta.go   # Delta xDS variant
├── plugins.go           # Plugin registration (e.g. ECDS Wasm)
├── grpcxds/             # gRPC bootstrap helpers (proxyless gRPC)
├── health/              # Application health probes
└── metrics/             # Agent metrics

security/pkg/nodeagent/
├── cache/               # SecretManager: per-resource cert lifecycle
├── caclient/            # CSR client to Istiod / external CA / RA
├── sds/                 # SDS gRPC server over UDS
└── cafile/              # Disk-backed root CA bundle

Key abstractions

Symbol	File	Role
Agent	pkg/istio-agent/agent.go	The orchestrator that owns Envoy, the xDS proxy, and SDS
XdsProxy	pkg/istio-agent/xds_proxy.go	The bidirectional bridge between Envoy and Istiod
Proxy	pkg/istio-agent/agent.go	Lightweight client metadata used in bootstrap
bootstrap.Config	pkg/bootstrap/config.go	Builds the rendered Envoy bootstrap JSON
cache.SecretManager	security/pkg/nodeagent/cache/secretcache.go	Manages cert/key pairs and rotation
caclient.CAClient	security/pkg/nodeagent/caclient/	The CSR client (Istiod default; cert-manager / Vault as alternates)
sds.Server	security/pkg/nodeagent/sds/sdsservice.go	Hosts the SDS gRPC over UDS
envoy.Proxy	pkg/envoy/proxy.go	Process-supervisor wrapper around Envoy

How it works

sequenceDiagram
    participant K as Kubelet
    participant Init as istio-init / CNI
    participant Agent as pilot-agent
    participant Envoy as Envoy
    participant SDS as SDS server (UDS)
    participant CA as Istiod CA
    participant Istiod as Istiod xDS

    K->>Init: PreInit (set iptables redirects)
    K->>Agent: Start istio-proxy container
    Agent->>Agent: Read POD_* env, mesh config, ProxyConfig
    Agent->>Agent: Render envoy-rev0.json from bootstrap template
    Agent->>SDS: Start SDS server on /etc/istio/proxy/SDS
    Agent->>Envoy: exec envoy -c envoy-rev0.json
    Envoy->>Agent: ADS over localhost
    Agent->>Istiod: ADS over mTLS (xds_proxy)
    Envoy->>SDS: SDS request "default"/"ROOTCA"
    SDS->>CA: CSR (signed JWT identity)
    CA-->>SDS: signed cert
    SDS-->>Envoy: cert + key + chain

Subprocesses managed

Agent.Run (in pkg/istio-agent/agent.go) launches the following goroutines and processes:

1. Envoy — supervised via pkg/envoy/proxy.go. Hot restarts use Envoy's drain + parent admin handover. The agent exits if Envoy exits during steady state (so Kubernetes restarts the pod).
2. xDS proxy — XdsProxy.Run opens an mTLS gRPC connection to Istiod and listens on 127.0.0.1:15003 (default). Envoy connects to that local listener for ADS. The proxy:
   • terminates mTLS to Istiod with the workload cert from SDS;
   • retries reconnection with exponential backoff (pkg/backoff/);
   • caches ECDS Wasm modules locally so Envoy doesn't re-fetch on each reload (pkg/wasm/);
   • implements both SoTW (xds_proxy.go) and Delta (xds_proxy_delta.go) variants depending on what Envoy negotiates.
3. SDS server — listens on a Unix Domain Socket, mounts /etc/istio/proxy/SDS. Envoy fetches workload certs and CA roots from here. Implementation: security/pkg/nodeagent/sds/sdsservice.go. The cache (security/pkg/nodeagent/cache/secretcache.go) tracks per-resource expiry and triggers rotation half-way through lifetime.
4. DNS server — when ISTIO_META_DNS_CAPTURE=true, the agent runs a local DNS server (pkg/dns/client/) that handles in-cluster lookups itself, avoiding kube-dns roundtrips.
5. Health probe server — listens on port 15021. Translates Kubernetes readiness probes into Envoy-aware probes by intercepting the manifest probe definitions during sidecar injection and re-issuing them through the agent (pilot/cmd/pilot-agent/status/).
6. gRPC bootstrap — for proxyless gRPC clients, the agent can write a grpc_bootstrap.json (pkg/istio-agent/grpcxds/).
7. Wasm cache — fetches and caches Wasm modules referenced by ECDS configurations.

Bootstrap rendering

The bootstrap is generated from the template tools/packaging/common/envoy_bootstrap.json plus per-pod parameters (POD_NAME, POD_NAMESPACE, mesh config, ProxyConfig, listener IPs). The renderer is in pkg/bootstrap/config.go / bootstrap.go and produces a JSON config that Envoy reads on startup.

The agent re-renders bootstrap on hot restarts and on ProxyConfig updates that change global settings (e.g. tracing).

Identity and certificates

The agent reads its identity from the projected service-account token mounted by Kubernetes (path is configurable; default /var/run/secrets/tokens/istio-token). It uses that token as the CSR caller credential. The CA returns a SPIFFE-formatted certificate (spiffe://<trust-domain>/ns/<ns>/sa/<sa>) that Envoy presents on outbound mTLS. The CA chain is published as the ROOTCA SDS resource.

By default, the CA endpoint is istiod.istio-system.svc:15012 (the same gRPC mTLS port as xDS). Alternates supported:

• Cert-Manager / RA — set CA_PROVIDER=Citadel and point to a cert-manager Issuer. Code in security/pkg/pki/ra/.
• Vault — community-supported via custom CAClient plugins.

Probes

The probe rewriter (pilot/cmd/pilot-agent/status/) intercepts Kubernetes readiness probes at injection time and rewrites them to point at the agent's health port (15021). The agent then forwards the probe to the application via the original target. This avoids the failure mode where Kubernetes probes the workload directly while iptables redirects all traffic through the sidecar.

Integration points

• Reads from: Istiod xDS (gRPC + mTLS) and CA (gRPC + JWT).
• Talks locally to: Envoy (admin port + ADS), the application (probes), the local DNS resolver.
• Mounts: /var/run/secrets/tokens/istio-token (projected SA token), /var/run/secrets/istio (CA root cert), /etc/istio/proxy (writable workdir for bootstrap + UDS), /etc/istio/config (mesh config from ConfigMap).
• Network: the iptables / CNI rules redirect 15001 (outbound) and 15006 (inbound). 15020 is the merged Prom metrics port; 15021 is the health probe port; 15090 is Envoy's Prometheus stats port.

Sub-binaries packaged in the same image

The proxyv2 image contains:

• /usr/local/bin/pilot-agent — this binary
• /usr/local/bin/envoy — the Istio-built Envoy
• The CA root bundle and various certificate utilities

The pilot-agent binary itself has multiple subcommands beyond proxy:

Subcommand	Purpose
proxy	Default. Starts Envoy + agent.
request	Issue an Envoy admin request (pilot-agent request POST listeners)
wait	Block until Envoy is ready
istio-iptables	The istio-init container's job — invokes tools/istio-iptables/ to set up redirects when CNI is not used
istio-clean-iptables	Reverse istio-iptables
version	Build info

Entry points for modification

• For changes to bootstrap rendering, edit pkg/bootstrap/config.go and the template at tools/packaging/common/envoy_bootstrap.json. Goldens live under pkg/bootstrap/testdata/.
• For SDS / CA changes, the right files are security/pkg/nodeagent/cache/secretcache.go (rotation) and security/pkg/nodeagent/caclient/ (CA-specific CSR transport).
• For xDS proxying behaviour (e.g. new metadata, new local interception), pkg/istio-agent/xds_proxy.go. The delta variant lives in xds_proxy_delta.go.
• The build tag agent excludes heavy dependencies. If you import an unrelated subsystem from this package, the agent binary will balloon. Run make show.AGENT_TAGS for the current setting.

Key source files

File	Purpose
pilot/cmd/pilot-agent/main.go	Cobra entry point
pilot/cmd/pilot-agent/app/cmd.go	CLI flags and the proxy command
pkg/istio-agent/agent.go	The Agent lifecycle
pkg/istio-agent/xds_proxy.go	xDS bridge (Envoy ↔ Istiod)
pkg/istio-agent/xds_proxy_delta.go	Delta variant
pkg/bootstrap/config.go	Envoy bootstrap rendering
tools/packaging/common/envoy_bootstrap.json	Bootstrap template
security/pkg/nodeagent/cache/secretcache.go	Workload cert lifecycle
security/pkg/nodeagent/sds/sdsservice.go	SDS server
security/pkg/nodeagent/caclient/	CSR transport implementations
pkg/envoy/proxy.go	Envoy process supervisor
pkg/dns/client/	Local DNS server
pilot/cmd/pilot-agent/status/	Health probe translation

See also

• istiod — what the agent talks to.
• systems/security-ca — the CA the agent calls.
• systems/xds — the protocol the agent proxies.