Eks Upgrade Check

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

Readiness Score

The skill calculates a weighted readiness score:

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:

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):

Copy code
## 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.

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.

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