istio/istio

Configuration reference

Selected environment variables and MeshConfig knobs that come up most often when operating or modifying Istio. The complete registry is generated at runtime — see "How to find the complete list" below.

Notable istiod environment variables

These are registered via env.Register in pilot/pkg/features/pilot.go (and a few in pkg/features/). Names follow PILOT_*, ISTIOD_*, XDS_*, EXTERNAL_CA, UNSAFE_*.

Push pipeline

Var	Default	Meaning
`PILOT_DEBOUNCE_AFTER`	`100ms`	Wait this long after a config event before pushing
`PILOT_DEBOUNCE_MAX`	`10s`	Max debounce while events keep arriving
`PILOT_PUSH_THROTTLE`	`100`	Concurrent pushes
`PILOT_ENABLE_EDS_DEBOUNCE`	`true`	Debounce EDS-only events
`PILOT_ENABLE_DELTA_XDS`	`true`	Allow delta xDS streams
`PILOT_FILTER_GATEWAY_CLUSTER_CONFIG`	`false`	Trim gateway cluster config
`PILOT_ENABLE_CDS_CACHE` / `..._RDS_CACHE` / `..._LDS_CACHE`	`true`	Per-type xDS cache
`PILOT_XDS_CACHE_SIZE`	`60000`	Cache entry budget
`PILOT_XDS_CACHE_INDEX_CLEAR_INTERVAL`	`5s`	Stale-entry cleanup

Service registry

Var	Default	Meaning
`PILOT_ENABLE_SERVICEENTRY_SELECT_PODS`	`true`	Allow ServiceEntry workloadSelector to match Pods
`PILOT_ENABLE_K8S_SELECT_WORKLOAD_ENTRIES`	`true`	Allow Kubernetes Service to select WE
`PILOT_ENABLE_AMBIENT`	varies	Master switch for Ambient registry path

Security / CA

Var	Default	Meaning
`PILOT_CERT_PROVIDER`	`istiod`	`istiod`, `kubernetes`, `cert-manager`, `none`
`EXTERNAL_CA`	unset	Set to `ISTIOD_RA_KUBERNETES_API` to use cert-manager
`MAX_WORKLOAD_CERT_TTL`	`24h`	Cap on requested cert TTL
`DEFAULT_WORKLOAD_CERT_TTL`	`24h`	Default TTL
`TRUST_DOMAIN`	`cluster.local`	Trust domain for SPIFFE URIs

Tracing / logging

Var	Default	Meaning
`PILOT_TRACE_SAMPLING`	`1`	Sampling percentage when istiod itself emits traces
`LOG_LEVEL`	`info`	Default log level
`LOG_FORMAT`	`text`	`text` or `json`

Misc

Var	Default	Meaning
`JWT_POLICY`	`third-party-jwt`	`third-party-jwt` (projected) or `first-party-jwt` (legacy)
`UNSAFE_PILOT_ENABLE_RUNTIME_ASSERTIONS`	`false`	Panic on cache key collisions and other invariants

Notable pilot-agent environment variables

Set via the injection template (so they apply per-pod):

Var	Default	Meaning
`ISTIO_META_*`	various	Metadata sent to istiod (cluster, mesh ID, network, labels)
`PROXY_CONFIG`	merged ProxyConfig JSON	Per-pod proxy config
`PILOT_ADDRESS`	`istiod.istio-system.svc:15012`	Where to reach istiod
`JWT_POLICY`	`third-party-jwt`	Same as istiod
`CA_ADDR`	`istiod.istio-system.svc:15012`	CA endpoint
`OUTPUT_CERTS`	unset	Path to write certs (debugging only)
`BOOTSTRAP_XDS_AGENT`	`true`	Use the agent's xDS proxy
`PROXY_LOG_LEVEL`	`warning`	Envoy log level
`KUBE_APP_PROBERS`	injected JSON	Original probe config for the rewriter
`PILOT_CERT_PROVIDER`	`istiod`	Same as istiod

MeshConfig

The full schema is at mesh/v1alpha1/config.proto. Highlights:

Field	Purpose
`defaultConfig`	Mesh-wide default `ProxyConfig`
`defaultProviders.{metrics,accessLogging,tracing}`	Default observability backends
`extensionProviders[]`	Define backends (OTel, Zipkin, Datadog, ...)
`trustDomain`	SPIFFE trust domain (e.g. `cluster.local`)
`trustDomainAliases[]`	Additional trust domains accepted as own
`outboundTrafficPolicy.mode`	`ALLOW_ANY` or `REGISTRY_ONLY`
`accessLogFile`	Legacy access log toggle
`enableTracing`	Whether tracing config is rendered
`meshId`	Logical mesh identifier (multi-mesh)
`rootNamespace`	Where mesh-wide policies live (default `istio-system`)
`caCertificates[]`	Additional trust roots
`defaultDestinationRuleExportTo`	Default export scope for DR
`defaultVirtualServiceExportTo`	Default export scope for VS

ProxyConfig

The per-proxy config (mesh-wide default sits inside MeshConfig.defaultConfig; the ProxyConfig CR overrides per workload). Highlights:

Field	Purpose
`concurrency`	Envoy worker count
`drainDuration`	Graceful drain on shutdown
`tracing.zipkin.address`	Tracing backend
`proxyMetadata`	Env vars set on the proxy
`image.imageType`	`default` or `distroless`
`holdApplicationUntilProxyStarts`	Order startup so proxy starts before app
`terminationDrainDuration`	Drain at SIGTERM

How to find the complete list

# All registered env vars in this repo:
rg 'env\.Register' --type go

# All MeshConfig fields:
# Read the proto in istio.io/api at vendor/<...>/mesh/v1alpha1/config.proto
go doc istio.io/api/mesh/v1alpha1.MeshConfig

# At runtime:
kubectl exec -n istio-system deploy/istiod -- pilot-discovery discovery --help 2>&1 | less