Istio Knowledge Patch

Istio Knowledge Patch

Use this skill when configuring, upgrading, operating, or troubleshooting Istio. Determine the deployed Istio and Kubernetes versions before applying advice. Use only guidance introduced at or below the deployed Istio version, and prefer the manifests, rendered charts, CRDs, and observed runtime behavior when they disagree with compatibility guidance.

Reference map

Upgrade workflow

1. Record the current control-plane, gateway, ztunnel, CNI, and sidecar image versions; do not assume they advance atomically.
2. Render every Helm chart with production values and diff cluster-scoped RBAC, webhook, Service, EndpointSlice, NetworkPolicy, and CNI resources.
3. Upgrade external CRDs before the control plane when the target consumes a newer Gateway API version.
4. Review removed APIs, flags, annotations, and telemetry providers in references/upgrades-and-migrations.md.
5. Test mutating webhooks against native sidecars and validate mixed-version ambient behavior before broad rollout.
6. Ensure every ztunnel meets a feature's stated minimum version before enabling new ambient xDS fields.
7. Restart or reconcile workloads when a change depends on pod-time CNI or DNS capture state.
8. Validate Gateway status, proxy configuration, authorization, metrics, and multicluster synchronization after each phase.

Highest-risk upgrade changes

Prepare Kubernetes and Gateway API first

Istio 1.30 requires Kubernetes 1.32 or newer. Before that upgrade, install Gateway API v1.5.x CRDs; otherwise TLSRoute and ReferenceGrant objects in gateway.networking.k8s.io/v1 are invisible to istiod. TLS passthrough can then show attachedRoutes: 0 without programming an Envoy listener.

Use the standard or experimental v1.5 CRD channel consistently with the APIs you deploy. See the exact commands and listener changes in references/upgrades-and-migrations.md.

Migrate removed APIs and settings

• Replace OpenCensus and Lightstep tracing providers with OpenTelemetry.
• Remove reliance on ENABLE_AUTO_SNI.
• Migrate InferencePool resources to v1 and use spec.endpointPickerRef.port.number; specify the port explicitly.
• Migrate BackendTLSPolicy from v1alpha3 to v1.
• Replace METRIC_ROTATION_INTERVAL and METRIC_GRACEFUL_DELETION_INTERVAL with sidecar.istio.io/statsEvictionInterval.
• Replace sidecar.istio.io/statsCompression with ProxyConfig.statsCompression, globally or through a per-pod proxy.istio.io/config override.
• Replace traffic.sidecar.istio.io/kubevirtInterfaces with istio.io/reroute-virtual-interfaces.

Account for data-plane rollout hazards

Eligible injected pods use native sidecars by default beginning with Istio 1.27. Test admission webhooks and controllers that expect istio-proxy to be a regular container.

During an upgrade to 1.28, ServiceEntry resources with resolution: NONE produce a PASSTHROUGH service type that older ztunnels NACK. Existing config stays in place, but new entries can act absent until ztunnel is upgraded.

Do not enable ambient dry-run authorization until every connected ztunnel is at least 1.29. Older ztunnels can fully enforce policy intended only for dry-run.

Review chart-owned object changes

The ztunnel chart briefly derived resource names from the Helm release in 1.25; 1.26 restored static ztunnel names. Pin resourceName deliberately when crossing these releases.

The base chart later stopped creating RBAC and service-account objects that are owned by the istiod chart. Names and suffix rules changed, so automation must not depend on the earlier object names. Also set global.enableReaderRBAC on both base and istiod when disabling multicluster reader resources.

High-value configuration

Ambient enrollment and CNI

DNS capture is on by default for newly enrolled ambient workloads. Existing pods need restart or startup reconciliation; opt a pod out with ambient.istio.io/dns-capture=false. DNS traffic honors outbound IP-range and port exclusions for both TCP and UDP.

Ambient iptables or nftables startup reconciliation became enabled by default in 1.29. Disable it only with cni.ambient.reconcileIptablesOnStartup=false. Safe in-place CNI restart handling separately prevents new pods from starting while the node agent restarts; AMBIENT_DISABLE_SAFE_UPGRADE=true disables that protection.

Use cni.istioOwnedCNIConfig=true when Istio must own a combined primary and Istio conflist. Both ambient and chained CNI must be enabled, and a custom filename must sort before the primary CNI file.

Service discovery and traffic placement

Addressless ServiceEntry resources receive IPs in status.addresses when PILOT_ENABLE_IP_AUTOALLOCATE is enabled, which is the default. Proxies consume them only with DNS proxying. Configure allocation prefixes with PILOT_IP_AUTOALLOCATE_IPV4_PREFIX and PILOT_IP_AUTOALLOCATE_IPV6_PREFIX.

Service.spec.trafficDistribution and the networking.istio.io/traffic-distribution annotation work across data planes. Namespace annotations provide inherited defaults, while a Service setting wins. PreferSameNode and PreferSameZone are supported, and PreferClose ignores subzone when selecting nearby endpoints.

Wildcard DYNAMIC_DNS routing has mode- and version-dependent constraints. Read references/gateways-and-traffic.md before using it, and trust only clients allowed to choose HTTP Host or TLS SNI.

Gateway API and waypoints

Gateway-generated workloads can customize their Service, Deployment, ServiceAccount, HorizontalPodAutoscaler, and PodDisruptionBudget. Generated resources inherit Gateway labels and annotations by default.

Waypoints accept TCPRoute, can route to remote networks, and can receive policy defaults through the istio-waypoint GatewayClass. Namespace-level ingress waypoint selection uses the istio.io/ingress-use-waypoint label.

Gateway API BackendTLSPolicy supports named Service ports and ServiceEntry targets. FrontendTLSValidation is supported, and TLSRoute termination and mixed mode are available with the graduated TLS listener behavior.

Security defaults

FAIL_CLOSE Wasm fetch failure installs deny-all RBAC. Wasm binary limits are enforced after gzip decompression, and bearer-token realm URLs are validated.

JWT rules may omit issuer only when jwksUri is explicit. JWKS CIDR blocking is applied after DNS resolution and across redirects and issuer discovery; blocked or failed fetches reject JWT-authenticated requests.

Debug endpoints are authorized by default. Namespace-scoped access and the DEBUG_ENDPOINT_AUTH_ALLOWED_NAMESPACES allowlist affect monitoring and plaintext xDS tooling; the system namespace remains allowed.

Telemetry defaults

OpenTelemetry is the replacement for removed tracing providers. disableContextPropagation suppresses propagation headers without disabling span reporting, and serviceAttributeEnrichment: OTEL_SEMANTIC_CONVENTIONS adds standard service resource attributes.

Gateway upstream spans default on in newer installations. Zipkin can propagate both B3 and W3C context and supports request timeouts plus literal or environment-sourced headers.

Envoy Prometheus endpoint compression defaults on through ProxyConfig.statsCompression. Circuit-breaker remaining-capacity metrics default off unless legacy behavior is selected.

Operational checks

• Treat headers in istioctl proxy-config all and ztunnel-config all as part of their tabular output contract.
• Use root --kubeclient-timeout for Kubernetes-client calls; it does not alter installation or command-specific timeouts.
• Use --proxy-admin-port with commands that must reach a non-default proxy admin endpoint.
• Watch istiod_remote_cluster_sync_status for remote-cluster synchronization.
• Expect istiod to derive GOMEMLIMIT as 90% of its container limit unless GOMEMLIMIT or AUTOMEMLIMIT overrides it.
• Review references/operations-and-istioctl.md before scripting output or renamed flags.