shweshi/istio-upgrade-skill
Use when the user asks about upgrading Istio, checking Istio version compatibility, planning an Istio migration, performing pre-upgrade checks, preparing for a version bump, or creating an Istio upgrade plan. Checks CRD compatibility and storage version changes, validates sidecar proxy version skew against control-plane skew limits, reviews EnvoyFilter deprecated xDS API usage and Wasm ABI compatibility, analyzes east-west gateway upgrade ordering in multi-cluster environments, assesses federation controller compatibility and trust bundle exchange, identifies breaking changes across all intermediate Istio releases, and produces a scored upgrade readiness assessment with a go/no-go recommendation and rollback strategy.
84
97%
Does it follow best practices?
Impact
96%
1.18xAverage score across 1 eval scenario
Advisory
Suggest reviewing before use
SECURITY_ANALYSIS.mdreferences/
Security Analysis Reference
Commands
kubectl get peerauthentication -A -o yaml
kubectl get authorizationpolicy -A -o yaml
kubectl get requestauthentication -A -o yamlmTLS Compatibility Rules
| Scenario | Severity |
|---|---|
| Global STRICT mTLS + proxy skew >= N+2 | HIGH RISK -- old proxy cannot complete mTLS handshake with new istiod cert |
| PERMISSIVE mode across upgrade window | PASS -- plaintext fallback absorbs handshake failures |
| DISABLE on any namespace + cross-namespace AuthorizationPolicy | WARNING -- policy enforcement may change with new proxy |
| Per-port STRICT mode with version-specific cipher changes | HIGH RISK -- verify cipher suite compatibility in target Envoy changelog |
Rule: If running STRICT mTLS, rolling restart of all proxies must complete within the N-1 skew window before removing the old revision.
AuthorizationPolicy Changes by Version
Known Breaking Patterns (check against target release notes)
- Istio 1.22+:
source.principalmatching is case-sensitive by default -- policies using mixed-case SPIFFE URIs may silently stop matching. - Istio 1.23+:
action: CUSTOMpolicies require explicit provider configuration inmeshConfig; missing providers cause DENY by default. - Istio 1.24+: L7 policies on TCP ports are rejected at admission (previously silently ignored) -- may block
kubectl applyin CI.
Decision Logic
- Identify global and per-namespace PeerAuthentication modes.
- If STRICT mode: verify proxy skew is <= N-1 before cutover or switch to PERMISSIVE for the upgrade window.
- Audit AuthorizationPolicy
actiontypes: flag anyCUSTOMpolicies and verify provider config exists in meshConfig for target version. - Check for
source.principalpatterns containing uppercase SPIFFE URIs if upgrading to 1.22+. - Check for L7 policies applied to TCP ports if upgrading to 1.24+.
- Run
istioctl analyze -Aagainst target CRDs to surface validation failures before applying.
JWT / RequestAuthentication Rules
- OIDC issuer URL must remain reachable from all sidecars during upgrade -- not an Istio concern but commonly overlooked during cluster-level changes.
- If JWKs cache TTL is short and OIDC endpoint is unavailable during upgrade: requests fail with 401 -> WARNING.
forwardOriginalToken: truebehaviour is unchanged across versions -- PASS.
Risk Classification
| Scenario | Severity |
|---|---|
| STRICT mTLS + proxy skew > N-1 | HIGH RISK |
| CUSTOM action policy, no provider config | CRITICAL |
| Mixed-case SPIFFE URIs, upgrading to 1.22+ | HIGH RISK |
| L7 policy on TCP port, upgrading to 1.24+ | HIGH RISK |
| PERMISSIVE mode across all namespaces | LOW |
| No AuthorizationPolicies deployed | PASS |