eks-upgrade-check git:20260824.53d8656A

Immutable. This exact content never changes and is served at /api/v1/blob/349c27073e674c67.

---
name: eks-upgrade-check
description: Assess EKS cluster upgrade readiness by running automated checks across
  8 areas (version validation, breaking changes, deprecated APIs, add-on compatibility,
  node readiness, workload risks, AWS Upgrade Insights, upgrade plan), calculate a
  readiness score (0-100%), and generate a detailed report with remediation steps and
  pre-filled AWS CLI commands. Assessment-only - all checks are strictly read-only and
  never modify the cluster. Use this skill when investigating EKS upgrade safety,
  or, in the context of a version upgrade, Kubernetes version skew, deprecated API usage,
  addon compatibility, or Karpenter version; also node upgrade readiness or control plane
  upgrade planning.
---

# EKS Upgrade Readiness Skill

## Overview

This skill assesses a live EKS cluster's readiness for a Kubernetes version upgrade. It connects to the cluster via AWS APIs, runs automated checks across 8 assessment areas, calculates a readiness score (0-100%), and produces a detailed report with prioritized remediation steps and pre-filled AWS CLI commands.

This skill is laser-focused on **upgrade safety** — answering the question: "Is it safe to upgrade this cluster to the next version?"

All operations are **read-only** — this skill does not modify your cluster.

## What Gets Assessed

| # | Section | Key Checks |
|---|---------|------------|
| 01 | Version Validation | Upgrade path validity, version skew policy, support status & cost |
| 02 | Breaking Changes | Version-specific API removals, behavioral changes, resource impact |
| 03 | Deprecated API Detection | Live scan of cluster resources for deprecated/removed APIs |
| 04 | Add-on Compatibility | Core add-on versions, OSS add-on matrix, Karpenter compatibility |
| 05 | Node Readiness | Node version skew, AL2→AL2023 migration, AMI compatibility |
| 06 | Workload Risks | Single replicas, missing PDBs, health probes, resource requests |
| 07 | AWS Upgrade Insights | Official EKS pre-upgrade checks and recommendations |
| 08 | Upgrade Plan | Pre-filled CLI commands, step-by-step upgrade sequence |

## Readiness Score

The skill calculates a weighted readiness score:

| Category | Max Deduction | Rationale |
|----------|--------------|-----------|
| Breaking Changes | 25 pts | Highest risk — can break apps |
| Deprecated APIs | 20 pts | Actionable, fixable pre-upgrade |
| Node Readiness (skew + subnet IPs) | 20 pts | Can block upgrade entirely |
| Unsupported Version | 15 pts | No security patches, urgent upgrade needed |
| Add-on Compatibility | 15 pts | Critical > optional add-ons |
| Karpenter | 10 pts | Only if installed |
| Workload Risks | 10 pts | Best-practice, not blockers |
| AWS Upgrade Insights | 10 pts | Official AWS checks |
| AL2 Nodes / Behavioral | 10 pts | Informational |

**Hard Blocker Override:** If any hard blocker is detected (e.g., incompatible Karpenter,
critical add-on DEGRADED, cluster subnets collectively cannot place control-plane ENIs,
cluster not ACTIVE), the score is capped at ≤ 59% (NOT READY) regardless of other findings.
See `references/report-generation.md` for the full list.

**Score Interpretation:**

| Score | Level | Meaning |
|-------|-------|---------|
| 90-100 | READY | Safe to proceed |
| 80-89 | GOOD | Minor issues, can proceed with caution |
| 70-79 | FAIR | Several issues need attention first |
| 60-69 | RISKY | Significant issues, not recommended yet |
| 0-59 | NOT READY | Critical blockers, must resolve first |

## Assessment Workflow

### Step 0: Pre-flight

> **Execution model — autonomous with hard stops.** This skill runs autonomously
> and does NOT pause for interactive input. It proceeds only when the target cluster
> and version are unambiguous. If any gating criterion below is not met, it performs
> a **HARD STOP**: it does NOT guess, auto-select, or partially assess an ambiguous
> cluster/target — it emits a structured stop message and ends. Never assess a cluster
> or target the user did not unambiguously specify or that cannot be uniquely determined.
> (This gate is about an ambiguous cluster/target; denied reads *during* a valid
> assessment are handled via `## Unassessed`, not a hard stop — see Action 3 below.)

**HARD STOP output format** — whenever a criterion below triggers a hard stop, output
exactly this and end the run (produce no readiness score):

```
## Assessment Halted — <one-line reason>

**Criterion not met:** <which check failed>
**What was found:** <observed state>
**To proceed:** <the specific input needed, e.g., re-run naming the cluster + region + target>
```

**Action 1 — Discover clusters**

Use EKS ListClusters to discover available clusters, then apply this decision table.

> **Region caveat.** EKS ListClusters is **region-scoped** and returns **names only, not regions**.
> A zero-cluster result means "none in this region," NOT "none in the account" — confirm the intended
> region before treating zero clusters as terminal. The "name + region" shown below pairs each returned
> name with the region actually queried, not a region returned by the API.

| Condition | Action |
|-----------|--------|
| User named a cluster in the request | Confirm it exists in the list, then proceed. If it does not exist → HARD STOP. |
| Exactly one cluster found, none named | Proceed. State which cluster is being assessed. |
| More than one cluster found, none named | **HARD STOP.** List all clusters (name + region). Do NOT auto-select by first/newest/any heuristic. |
| Zero clusters found | **HARD STOP.** Report that no clusters were found **in the queried region** (state the region), and note that other regions were not checked. |

**Action 2 — Describe the selected cluster**

Use EKS DescribeCluster and record: cluster name, Kubernetes version, platform version, region, status, account ID.

> **Account ID hygiene:** the account ID is sensitive. If the generated report will be shared outside the account, mask or omit the account ID before sharing.

**Action 2b — Validate cluster status**

If status is NOT `ACTIVE` → **HARD STOP**:
- **CREATING/UPDATING/DELETING** — cluster is in transition; the EKS API will reject an upgrade.
- **FAILED** — cluster must be recovered before an upgrade can be attempted.

Cluster status gates the whole assessment; node group status gates node readiness. If a node group's lifecycle `status == UPDATING` (mid-rotation), the assessment can still run but node readings may be a transient old/new mix — flag it as potentially unstable and recommend re-running after rotation (see `references/node-readiness.md` §5.1).

**Action 3 — Validate permissions (AWS + Kubernetes)**

**3a — AWS API preflight.** Verify access to: ListNodegroups, ListAddons, DescribeAddonVersions
(add-on compatibility — `references/addon-compatibility.md` marks this a MUST-run read), ListInsights,
and EC2 DescribeSubnets (node-readiness subnet-IP hard-blocker input). DescribeCluster / DescribeNodegroup
/ DescribeAddon / DescribeInsight are exercised implicitly by the assessment steps.

**3b — Kubernetes RBAC preflight.** The high-weight categories read Kubernetes objects, not just AWS
APIs. Confirm cluster read access to: Deployments/DaemonSets/StatefulSets (workloads + deprecated-apis),
Validating/MutatingWebhookConfigurations (breaking-changes), HorizontalPodAutoscalers (deprecated-apis),
and `nodepools.karpenter.sh` (node-readiness + add-on compatibility) via a `can-i`-style list check.
If `kubectl auth can-i` itself errors (not a clean yes/no), treat the read as denied.

If any required AWS permission or Kubernetes read is denied → this is NOT a hard stop (the
hard stops in this Step 0 are for an ambiguous cluster/target only — see the execution-model
note above). Instead, proceed as a **partial assessment**:
1. Record exactly which IAM action or RBAC verb/resource is denied.
2. Continue the assessment. Every category whose backing read was denied is reported
   UNKNOWN / not-scored (NOT a clean 0-deduction pass) and listed in `## Unassessed`,
   per `references/report-generation.md`.
3. The headline verdict carries the `(partial — N category/categories unassessed)` marker
   and is capped below READY — a partial assessment can NEVER yield an uncaveated READY.

The guarantee this preflight gives extends only to the reads it actually probes.

**Action 4 — Determine target version**

- **User specified a target version** → use it. Validate the upgrade path per
  `references/version-validation.md`; if the path is invalid (downgrade, same version,
  or the target does not exist on EKS) → **HARD STOP**.
- **No target specified** → default to the immediate next minor version (current + 1).
  This is deterministic (EKS upgrades one minor at a time), so it is a safe default, not
  a guess. State the assumed target explicitly in the report metadata.
- **User requested a multi-hop upgrade** (target > current + 1) → **HARD STOP**. Show the
  required one-hop-at-a-time path (e.g., 1.30 → 1.31 → 1.32) and state that this run
  assesses only a single hop; re-run naming the immediate next version.

**Action 5 — Proceed**

If all criteria above pass, proceed through Steps 1-8 without further pauses.

### Steps 1-8: Run Assessment

For each assessment area, read the corresponding reference file from `references/` and execute the checks described.

| Assessment Area | Reference File |
|---|---|
| Version / upgrade path | `references/version-validation.md` |
| Breaking changes / API removals | `references/breaking-changes.md` |
| Deprecated APIs | `references/deprecated-apis.md` |
| Add-on compatibility / Karpenter | `references/addon-compatibility.md` |
| Node readiness / AL2 / AMI | `references/node-readiness.md` |
| Workload risks / PDB / probes | `references/workload-risks.md` |
| AWS Insights | `references/upgrade-insights.md` |
| Generate report | `references/report-generation.md` |

### Step 9: Calculate Score & Generate Report

Follow the scoring algorithm in `references/report-generation.md` to calculate the final score and produce the report.

## Tool Usage Guidelines

1. **Do NOT hardcode or guess cluster names.** Always discover by listing first.
2. **Do NOT retry a failed API call more than once.**
3. **Always read the relevant reference file before executing checks for that section.**
4. **Use EKS APIs for cluster queries** — DescribeCluster, ListNodegroups, DescribeNodegroup, ListAddons, DescribeAddon, DescribeAddonVersions, ListInsights, DescribeInsight.
5. **Use Kubernetes APIs** for resource scanning — list Deployments, DaemonSets, StatefulSets, Pods, Nodes, PDBs, etc.
6. **Use EC2 DescribeSubnets** for subnet IP capacity checks.

## Data Files

- **OSS Add-on Registry:** `assets/oss_addon_registry.json` — identifiers and authoritative upstream URLs for common OSS add-ons. This file does NOT contain compatibility data. Compatibility is always verified live via the registry's `compatibility_url` and `releases_url` fields.

## Report Output Format

The report is rendered as Markdown **inline in your response** — the DevOps Agent
runtime cannot write files. Use the report-title pattern from
`references/report-generation.md` as the report's title/heading, not as a saved
filename. There is only one delivery path: render the full report inline.

Each report includes:
- Readiness score with breakdown
- Blockers (hard blockers only — these cap the score at ≤59)
- Critical Actions (other HIGH-severity findings, not score-capping)
- Recommended actions
- Informational findings
- Evidence tables (add-ons, nodes, workloads)
- Step-by-step upgrade plan with pre-filled commands
- AWS reference links