Skip to main content
Source

This page is generated from skills/eks-upgrade-check/references/version-validation.md. Edit the source, not this page.

Vendored skill

This skill is sourced from eks-upgrade-check, also maintained by the APEX team.

Version Validation & Upgrade Path

Purpose​

Validate the upgrade path, determine support status, and enforce EKS upgrade rules.

EKS Version Support Calendar (fallback reference, as of June 2026)​

Freshness gate — apply BEFORE using this table:

  1. If the cluster version or target version is NOT in the table below → fetch live data from AWS docs (search_documentation for "EKS Kubernetes versions") before proceeding.
  2. If today's assessment date is past the "Standard Support Until" date for the cluster's current version → that version has moved from STANDARD to EXTENDED support (extended-support pricing and an extended-support INFO finding now apply). The table's STANDARD/EXTENDED labels go stale the moment a standard-support window closes, so verify the row's Status live against AWS docs (EKS kubernetes-versions.html) before reporting.
  3. If today's assessment date is past the "Extended Support Until" date for the cluster's current version → that version's status may have changed to UNSUPPORTED. Verify live before reporting support status.
  4. If live lookup fails or the MCP server is unavailable → use the table as fallback, but add a note in the report: "Support status unverified — table data may be stale."
VersionStandard Support UntilExtended Support UntilStatus
1.36August 2, 2027August 2, 2028✅ STANDARD (latest in this table)
1.35March 27, 2027March 27, 2028✅ STANDARD
1.34December 2, 2026December 2, 2027✅ STANDARD
1.33July 29, 2026July 29, 2027⚠️ EXTENDED (standard support ended July 29, 2026; extended as of 2026-08-05 — verify live)
1.32March 23, 2026March 23, 2027⚠️ EXTENDED
1.31November 26, 2025November 26, 2026⚠️ EXTENDED
1.30July 23, 2025July 23, 2026❌ UNSUPPORTED (extended support ended July 23, 2026; unsupported as of 2026-08-06 — verify live)

Provenance: calendar verified as of 2026-08-06 via https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html — re-verify live per the freshness gate above before reporting.

CRITICAL: The upgradePolicy.supportType field from the API is a CONFIGURATION PREFERENCE, not the current billing status. Always determine actual support status from the calendar above or from live AWS documentation.

Cost impact: Extended support has historically cost ~$0.60/hr vs ~$0.10/hr for standard support. These rates are indicative and subject to change — verify against the current Amazon EKS pricing page before quoting figures to the user.

Cost Calculation Formula (recompute with the current rates, do not hardcode):

extra_cost_per_month = (extended_rate - standard_rate) × 730
total_extended_cost  = extended_rate × 730
total_standard_cost  = standard_rate × 730
# Example with the indicative rates above:
#   extra = (0.60 - 0.10) × 730 = ~$365/month per cluster
#   total_extended = 0.60 × 730 = ~$438/month per cluster

Always use this formula. Do NOT round, estimate, or hallucinate cost figures. 730 = average hours per month (365 days × 24 hours ÷ 12 months).

Checks to Execute​

1.0 — Target Version Existence (MUST run before other checks)​

Why: EKS releases versions incrementally. A target version that doesn't exist on EKS yet cannot be assessed. The arithmetic check (target - current == 1) is necessary but NOT sufficient.

How to check:

  1. Confirm the target version exists in the calendar table above.
  2. If NOT in the table → search AWS docs (search_documentation for "EKS Kubernetes versions") to confirm whether the version has been released on EKS.
  3. If live lookup also finds no evidence the version exists on EKS → ABORT the assessment.

If target version does not exist on EKS — STOP and report:

## Assessment Cannot Proceed

**Target version <target> is not yet available on Amazon EKS.**

The latest supported EKS version is <latest_known>. Kubernetes <target> has not been
released on EKS as of this assessment date (<date>).

**What you can do:**
- Assess upgrade readiness to <latest_known> instead (if your cluster is on <latest - 1>)
- Monitor the EKS release calendar for <target> availability:
  https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html

Do NOT proceed with Steps 1-8. Do NOT produce a readiness score. End the assessment here.

1.1 — Current Version & Support Status​

How to check:

  1. Describe the cluster → get version and platformVersion
  2. Match version against the calendar table above (applying the freshness gate)
  3. Determine the support status. Possible states:
    • STANDARD — within standard support window
    • EXTENDED — past standard support, within extended support window
    • UNSUPPORTED — past extended support end date (see handling below)
  4. Report: version, support status, when current support period ends (or already ended)

UNSUPPORTED version handling:

If the cluster version's Extended Support Until date has passed:

  • Status = UNSUPPORTED
  • Severity = CRITICAL
  • Flag as a blocker in the report (see report-generation.md for template)
  • The cluster no longer receives security patches or bug fixes from AWS
  • AWS automatically upgrades the cluster to the next minor version at the end of extended support (see EKS docs, "extended support" / kubernetes-versions.html); the cluster does not remain on the unsupported version indefinitely
  • Extended support billing (indicative ~$0.60/hr — verify current rate) applies throughout the extended-support window; it ends when the cluster leaves the extended-support version — either by a user-initiated upgrade or by AWS's automatic upgrade at end of extended support
  • Score impact: 15 pts deduction (see report-generation.md §Category 10)

Output: Current version, support tier, cost implications. If UNSUPPORTED, include urgency callout.

1.2 — Upgrade Path Validation​

Rules:

  • EKS requires upgrading one minor version at a time (e.g., 1.30 → 1.31, not 1.30 → 1.32)
  • A downgrade is not an assessment target for this forward-path logic — but reverting is not impossible: EKS Version Rollback (launched 2026-07) can revert the control plane to the previous minor version within 7 days of an in-place upgrade, a single version only (N→N-1), via console/CLI/SDK (aws eks update-cluster-version with the N-1 version → update type VersionRollback), gated by ROLLBACK_READINESS cluster insights.
  • Same-version "upgrades" are invalid

How to check:

  1. Parse current version (from cluster describe) and target version (from user input)
  2. Calculate version difference: target_minor - current_minor
  3. If difference == 1: valid direct upgrade
  4. If difference > 1: show required upgrade path (e.g., 1.29 → 1.30 → 1.31 → 1.32)
  5. If difference <= 0: invalid (same version or downgrade)

Output: Valid/invalid path, required intermediate steps if multi-hop.

1.3 — Version Skew Policy Check​

Rules (Kubernetes version skew policy):

  • kubelet may be up to N-3 minor versions behind the control plane (the N-3 kubelet skew policy; the older N-2 limit applies only to kubelet versions below 1.25) — see the Kubernetes "Version Skew Policy" (kubernetes.io/releases/version-skew-policy), which permits kubelet to be up to 3 minor versions older than kube-apiserver as of Kubernetes 1.28+ (the 2-version limit applied before 1.25)
  • If the control plane is upgraded to the target version, nodes must be within 3 minor versions

How to check:

  1. List all node groups → describe each for Kubernetes version
  2. List nodes via Kubernetes API → get kubelet versions from status.nodeInfo.kubeletVersion
  3. Build the set of DISTINCT kubelet minor versions across ALL nodes — the union of managed node group versions and every node's status.nodeInfo.kubeletVersion. Karpenter-provisioned and self-managed nodes have no node group; checking node groups alone misses them entirely.
  4. For each distinct kubelet minor version, calculate skew against the TARGET version (not current)
  5. Skew > 3: BLOCKER — nodes must be upgraded first (beyond the N-3 skew policy)
  6. Skew == 3: WARNING — at maximum supported skew, upgrade nodes promptly after control plane

Output: Each distinct kubelet minor version (with the node groups / nodes running it), skew against target, blocker/warning status.

Score Impact​

Canonical scoring is defined in references/report-generation.md §Category 3 (Node Readiness) and §Category 10 (Unsupported Version).

FindingSeverityQuick Reference
On extended supportINFO0 pts
Version UNSUPPORTEDCRITICAL15 pts (Category 10)
Multi-hop upgrade neededINFO0 pts
Target version unreleasedN/AAssessment aborted — no score
Node skew == 3 (warning)MEDIUM5 pts per distinct kubelet minor version (across ALL nodes)
Node skew > 3 (blocker)CRITICAL20 pts (caps category)