Upgrade a cluster one minor version without an outage, and know before starting how each step is undone.
Read references/cluster-upgrade.md before responding. It holds the scan commands for each place removed APIs hide, the add-on checks, the drain-blocker query, node rotation per pool type, the EKS rollback rules (one minor version, 7 days, in-place upgrades only) and blue/green as the fallback.
This skill is interactive by default. With no arguments, ask for the cluster platform (EKS, AKS, GKE, other), the current and target versions, how nodes are provisioned (managed node groups, Karpenter, self-managed, Auto Mode, Fargate) and how workloads are delivered (Flux, Argo CD, Helm, kubectl), then run plan. Never run update-cluster-version, update-nodegroup-version or a drain yourself: produce the commands, the checks and the rollback, and let the user run them.
Mode dispatch
| Mode | What it does | Mutates anything? |
|---|---|---|
plan | Full phased plan: scans, add-on order, drain blockers, control plane, node rotation, rollback per phase | No |
scan | Removed and deprecated APIs in Git, rendered Helm, deployed releases and the live API, plus EKS upgrade insights | No |
addons | Add-on compatibility for the target version and the upgrade order (before or after the control plane) | No |
drain | PDBs and pods that will block or lose data in a node drain, with fixes | No |
rotate | Node rotation plan per pool, smallest blast radius first | No |
rollback | The right rollback for the phase and time elapsed: EKS version rollback, node pool rollback, add-on downgrade, or blue/green | No |
validate | Post-phase checks | No |
Mode: plan
- Confirm the jump is one minor version. If not, plan each step separately.
- Run
scan,addonsanddrainand fold their findings into one ordered checklist. - For each phase (APIs, add-ons, control plane, nodes), state the blast radius, the validation and the rollback.
- State the rollback window explicitly. On EKS: in-place rollback is available for 7 days after the upgrade completes and only to the previous minor version; after that, rollback means a blue/green cluster. If the plan needs a longer safety window, recommend blue/green from the start.
Mode: scan
Use the commands in the reference's Phase 1 table, all with --target-versions k8s=v<target>:
bashpluto detect-files -d <repo dir> --target-versions k8s=v<target> helm template <release> <chart> -f <values> | pluto detect - --target-versions k8s=v<target> pluto detect-all-in-cluster -o wide --target-versions k8s=v<target> aws eks list-insights --cluster-name <cluster> --filter '{"categories": ["UPGRADE_READINESS"]}'
Report each finding with where it lives (Git path, chart and value, or live object), its replacement apiVersion, and its owner. Flag live-only objects as ownerless: nothing will reconcile them after the upgrade.
Mode: addons
Query, never recall. For EKS managed add-ons use aws eks describe-addon-versions --kubernetes-version <target> --addon-name <name>; for Karpenter, Flux, KEDA, the mesh, CSI drivers and admission webhooks, read each project's compatibility matrix for the target version. Output one table: add-on, current version, minimum version supporting the target, upgrade before or after the control plane, rollback version.
Mode: drain
Run the PDB query from the reference. For each blocker, give the fix (replicas, maxUnavailable, selector, unhealthy workload) and the exact change. List bare pods and pods whose emptyDir data would be lost.
Mode: rotate
Per pool type, from the reference's Phase 5 table. Order pools by blast radius, smallest first. After each pool: no Pending pods, all nodes Ready, GitOps converged.
Mode: rollback
Ask what failed and when the control plane upgrade completed, then choose:
- Node pool only: roll that pool back; keep the control plane.
- Add-on only: downgrade the add-on.
- Control plane, EKS, within 7 days, one step, in-place upgrade: EKS version rollback, in the reference's order: read
ROLLBACK_READINESSinsights, roll nodes back first, downgrade incompatible add-ons, thenaws eks update-cluster-version --kubernetes-version <previous>. State what it does not undo: etcd objects at new apiVersions, add-on versions, node versions. - Anything else: blue/green. Traffic to a cluster at the old version, with a data plan for stateful workloads.
Never recommend --force without naming the specific insight it bypasses and why that insight is a false positive.
Mode: validate
Run the reference's validation block for the phase just finished and report each check as pass or fail.
Output format
Every mode ends with:
- Findings or plan, with exact commands and files
- Blast radius, in one line per phase
- Validation, as commands
- Rollback, for the phase in question, including whether in-place rollback is still available
