From 71a1e7cb9caa7168869e0ff54433fda8a124161b Mon Sep 17 00:00:00 2001 From: Bruno Lopes <37803210+brunokktro@users.noreply.github.com> Date: Sat, 18 Jul 2026 08:31:08 -0300 Subject: [PATCH 1/5] Add eks-version-upgrade-readiness custom transformation Analyzes and transforms Kubernetes manifests, Helm charts, Kustomize overlays, Terraform, and CDK code for Amazon EKS version upgrade compatibility. Detects removed/deprecated APIs, updates apiVersions and resource fields, validates addon compatibility, and generates a migration report with manual action items and a sequential upgrade path. Complements the Upgrade Controller for Amazon EKS (cluster-side execution) by handling the code-side readiness. --- .../eks-version-upgrade-readiness/README.md | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 community-sourced-transformations/eks-version-upgrade-readiness/README.md diff --git a/community-sourced-transformations/eks-version-upgrade-readiness/README.md b/community-sourced-transformations/eks-version-upgrade-readiness/README.md new file mode 100644 index 0000000..347195b --- /dev/null +++ b/community-sourced-transformations/eks-version-upgrade-readiness/README.md @@ -0,0 +1,161 @@ +# EKS Version Upgrade Readiness + +Analyzes and transforms customer code (Kubernetes manifests, Helm charts, Kustomize overlays, Terraform, and CDK) for compatibility with a target Amazon EKS/Kubernetes version — detecting removed/deprecated APIs, updating `apiVersion` fields and resource structures, validating addon compatibility, and producing a migration report with clear manual action items. + +**Supports Kubernetes manifests · Helm charts · Kustomize overlays · Terraform · AWS CDK** + +## Table of Contents + +- [Overview](#overview) +- [The Problem](#the-problem) +- [What This Skill Does](#what-this-skill-does) +- [Skill Architecture](#skill-architecture) +- [Complement to the EKS Upgrade Controller](#complement-to-the-eks-upgrade-controller) +- [Getting Started](#getting-started) +- [Getting Started with AWS Transform Custom](#getting-started-with-aws-transform-custom) +- [Known Limitations](#known-limitations) +- [Documentation & References](#documentation--references) + +## Overview + +Amazon EKS requires sequential minor-version upgrades (one hop at a time), and each hop can remove Kubernetes APIs, deprecate EKS-specific behavior, or break addon compatibility. This skill focuses on the **code** side of that problem: the manifests, charts, and IaC that run on the cluster, not the cluster upgrade itself. + +Given a target EKS version (and optionally a source version), the skill scans the repository, maps every deprecated or removed API against the upgrade path, transforms what it can automatically, and documents everything it cannot with a clear rationale and recommended action. + +## The Problem + +Teams preparing for an EKS version upgrade face: + +- **Removed APIs breaking deploys**: `extensions/v1beta1` Ingress, `policy/v1beta1` PodDisruptionBudget, `batch/v1beta1` CronJob, and dozens of other GroupVersions removed across Kubernetes 1.16-1.36. +- **Structural, not just cosmetic, changes**: replacing `apiVersion` alone isn't enough — Ingress backend structure, CRD schema requirements, and webhook defaults all change shape between versions. +- **EKS-specific breakage not covered by upstream docs**: AL2 AMI discontinuation, StorageClass default annotation removal, new required IAM permissions, anonymous auth restrictions. +- **Addon version drift**: VPC CNI, CoreDNS, EBS CSI Driver, and other addons have minimum version requirements per EKS release that are easy to miss. +- **No single source of truth spanning the full upgrade path**: multi-hop upgrades (e.g., 1.28 -> 1.32) accumulate breaking changes from every intermediate version. + +## What This Skill Does + +1. **Scan** the repository for Kubernetes manifests (`.yaml`/`.yml`), Helm charts (`Chart.yaml`, `templates/`), Kustomize overlays (`kustomization.yaml`), Terraform files (`.tf` with `aws_eks_*` resources), and CDK code (TypeScript/Python EKS constructs). +2. **Detect** incompatibilities for the source -> target version range: + - Removed and soon-to-be-removed API versions + - Structural field changes (renames, new required fields) + - EKS-specific changes (AMI type deprecation, StorageClass defaults, IAM requirements) + - Addon version incompatibilities (VPC CNI, EBS CSI, CoreDNS, kube-proxy, and others) +3. **Transform** automatically: + - Update `apiVersion` fields to the replacement API + - Restructure fields that changed shape (e.g., Ingress backend) + - Add newly required fields with sensible defaults (e.g., `pathType: Prefix`) + - Update Terraform `ami_type` from AL2 to AL2023 for 1.33+ targets + - Update Terraform/CDK cluster version strings +4. **Validate** transformed output: + - `kubectl apply --dry-run=client` on manifests (if kubectl is available) + - `helm template` on charts (if Helm is available) + - `terraform validate` on `.tf` files (if Terraform is available) +5. **Report** — generate `MIGRATION_REPORT.md` with: + - Summary of automatic changes + - Items requiring manual intervention (e.g., PodSecurityPolicy migration) + - Addon compatibility warnings with recommended versions + - Risk assessment (low/medium/high) per change + - An **Upgrade Execution Path** section listing every sequential hop required, since EKS does not support skip-version upgrades + +## Skill Architecture + +```text +Input: Customer repo + target EKS version (via additionalPlanContext) + | + +-- 1. Scan -> identify all manifests/charts/configs + +-- 2. Detect -> map deprecated/removed APIs across the full upgrade path + +-- 3. Transform -> update apiVersions, fields, and configs automatically + +-- 4. Validate -> dry-run / helm template / terraform validate + +-- 5. Report -> MIGRATION_REPORT.md with manual action items +``` + +### Key Design Decisions + +1. **Code readiness, not cluster upgrade.** This skill never touches the running cluster or executes an upgrade — it prepares the code that runs on it. Cluster upgrade orchestration is a separate concern (see below). +2. **Never remove, only transform.** Resources are never deleted. Ambiguous transformations are flagged with a TODO comment and documented in the report rather than guessed. +3. **PodSecurityPolicy is flag-only.** PSP removal (EKS 1.25+) requires a Pod Security Admission design decision that cannot be automated safely — it is always reported, never auto-migrated. +4. **Sequential-hop awareness.** EKS requires upgrading one minor version at a time. The skill always documents every intermediate hop in the target version string, even when transforming code directly to the final target. + +## Complement to the EKS Upgrade Controller + +This skill and the [Upgrade Controller for Amazon EKS](https://gitlab.aws.dev/brunemat/eks-upgrade-controller) solve two different halves of the same problem: + +| | Scope | +|---|---| +| **This skill** | The **code**: manifests, Helm charts, Terraform, CDK — everything that runs on the cluster | +| **Upgrade Controller** | The **cluster**: control plane + data plane version upgrades, staged rollouts, maintenance windows, EKS Upgrade Insights validation | + +Used together they provide end-to-end upgrade readiness: code prepared ahead of time, cluster upgraded through an automated, sequential, validated process. `MIGRATION_REPORT.md` explicitly recommends the Upgrade Controller as the execution mechanism for the documented Upgrade Execution Path. + +## Getting Started + +### Prerequisites + +| Tool | Purpose | +|---|---| +| AWS Transform CLI (`atx`) | Execute the skill | +| `kubectl` (optional) | Manifest dry-run validation | +| `helm` (optional) | Chart template validation | +| `terraform` (optional) | `.tf` validation | + +> If `kubectl`, `helm`, or `terraform` are not installed on the machine running the skill, the corresponding validation step is skipped and reported as unavailable. + +### Getting Started with AWS Transform Custom + +To set up the AWS Transform CLI, configure authentication, and run your first transformation, see the [AWS Transform Custom Getting Started Guide](https://docs.aws.amazon.com/transform/latest/userguide/custom-get-started.html). + +### Cloning the Repo and Publishing the Transformation + +```bash +git clone https://github.com/aws-samples/aws-transform-custom-samples +cd aws-transform-custom-samples/community-sourced-transformations + +atx custom def publish -n eks-version-upgrade-readiness \ + --sd eks-version-upgrade-readiness \ + --description "Analyzes and transforms Kubernetes manifests, Helm charts, Terraform, and CDK code for Amazon EKS version upgrade compatibility" +``` + +### Running the Transformation + +```bash +# Full run: analysis + transform +atx custom def exec \ + -n eks-version-upgrade-readiness \ + -p /path/to/customer-repo \ + -x -t \ + --configuration 'additionalPlanContext=Target EKS version 1.32. Upgrade from 1.28.' + +# Analysis only — no files modified, report only +atx custom def exec \ + -n eks-version-upgrade-readiness \ + -p /path/to/customer-repo \ + -x -t \ + --configuration 'additionalPlanContext=Target EKS version 1.32. Analysis only - do not modify files. Generate report.' +``` + +### Expected Output + +```text +MIGRATION_REPORT.md # summary, manual action items, addon warnings, risk assessment, + # and Upgrade Execution Path (sequential hops) +``` + +Plus the transformed manifests/charts/Terraform/CDK files in place, with ambiguous changes marked via `TODO` comments. + +## Known Limitations + +| Limitation | Notes | +|---|---| +| PodSecurityPolicy migration | Never auto-migrated (requires Pod Security Admission design decisions) — flagged in report only | +| Custom admission webhooks with non-standard defaults | Flagged for manual review, not transformed | +| Skip-version upgrades | Not supported by EKS itself; the skill always documents the full sequential path | +| Cluster-level upgrade execution | Out of scope — use the Upgrade Controller for Amazon EKS for orchestration | + +## Documentation & References + +| File | Description | +|---|---| +| [SKILL.md](SKILL.md) | Complete skill definition — objective, scope, workflow, and validation criteria | +| [references/api-removals-by-version.md](references/api-removals-by-version.md) | Complete table of Kubernetes API removals per version (1.16 through 1.36), plus a quick "upgrading from X to Y" lookup | +| [references/eks-specific-changes.md](references/eks-specific-changes.md) | EKS-specific changes per version, addon compatibility matrix, and Terraform/CDK/Helm update patterns | +| [references/examples-before-after.md](references/examples-before-after.md) | 8 concrete before/after transformation examples covering Ingress, PDB, CronJob, HPA, FlowSchema, CRDs, Terraform node groups, and webhooks | From 479b87d735cdf10d75c96e29b2eb770fd8696074 Mon Sep 17 00:00:00 2001 From: Bruno Lopes <37803210+brunokktro@users.noreply.github.com> Date: Sat, 18 Jul 2026 08:31:44 -0300 Subject: [PATCH 2/5] Add SKILL.md for eks-version-upgrade-readiness --- .../eks-version-upgrade-readiness/SKILL.md | 165 ++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 community-sourced-transformations/eks-version-upgrade-readiness/SKILL.md diff --git a/community-sourced-transformations/eks-version-upgrade-readiness/SKILL.md b/community-sourced-transformations/eks-version-upgrade-readiness/SKILL.md new file mode 100644 index 0000000..9cad7b2 --- /dev/null +++ b/community-sourced-transformations/eks-version-upgrade-readiness/SKILL.md @@ -0,0 +1,165 @@ +--- +name: eks-version-upgrade-readiness +description: >- + Analyzes and transforms Kubernetes manifests, Helm charts, Kustomize + overlays, Terraform, and AWS CDK code for Amazon EKS version upgrade + compatibility. Detects removed and deprecated APIs, updates apiVersions + and resource fields, validates addon compatibility, and generates a + migration report with manual action items and a sequential upgrade path. + Trigger: EKS upgrade, Kubernetes version upgrade, API deprecation, + apiVersion migration, addon compatibility. +--- + +# EKS Version Upgrade Readiness + +## Objective + +Prepare a customer's code (manifests, charts, IaC) for an Amazon EKS/Kubernetes version upgrade by detecting and transforming deprecated or removed APIs, EKS-specific breaking changes, and addon incompatibilities — producing a migration report that documents everything the worker cannot safely automate. + +## Scope + +Analyzes and transforms: +- Kubernetes manifests (`.yaml`, `.yml`) +- Helm charts (`Chart.yaml`, `templates/`) +- Kustomize overlays (`kustomization.yaml`) +- Terraform files (`.tf` with `aws_eks_cluster`, `aws_eks_node_group`, and related resources) +- AWS CDK code (TypeScript/Python EKS constructs) + +Supports upgrades between any EKS versions from 1.16 through 1.36+. + +**Non-Goals** (out of scope for this skill): +1. Executing the actual cluster upgrade (control plane / data plane) — use the Upgrade Controller for Amazon EKS (https://gitlab.aws.dev/brunemat/eks-upgrade-controller) for automated sequential upgrades with maintenance windows, staged rollouts, and EKS Upgrade Insights validation. +2. PodSecurityPolicy migration — removed entirely in Kubernetes 1.25. Requires a Pod Security Admission or third-party webhook design decision that cannot be automated safely. Always flagged in the report, never transformed. +3. Custom admission webhook business logic — only the `admissionregistration.k8s.io` API shape and required defaults are updated; webhook implementation logic is out of scope. +4. Non-EKS Kubernetes distributions — API removal mapping is upstream Kubernetes, but EKS-specific sections (AMI types, addon matrix, IAM requirements) assume Amazon EKS. + +## Constraints + +### Correctness +- Never remove resources — only transform them in place. +- Preserve all comments, labels, and annotations. +- If a transformation is ambiguous, add a `TODO` comment in the code and document the ambiguity in `MIGRATION_REPORT.md` rather than guessing. + +### Sequential Upgrade Awareness +- Amazon EKS requires upgrading one minor version at a time — skip-version upgrades are not supported. +- Terraform/CDK `cluster_version` / `KubernetesVersion` strings are set to the TARGET version in code (the code itself must be forward-compatible), but `MIGRATION_REPORT.md` must always list each intermediate sequential hop required to get there. +- `MIGRATION_REPORT.md` must include a section "Upgrade Execution Path" listing every hop and recommending the Upgrade Controller for Amazon EKS as the execution mechanism — this skill never executes the upgrade itself. + +### Helm-Specific +- Transform templates but preserve the `values.yaml` structure and keys. +- Only update addon image tags in values when the current tag is clearly below the minimum compatible version for the target EKS release (see addon compatibility matrix in `references/eks-specific-changes.md`). + +### Reporting +- Every automatic change and every manual action item must be traceable to a specific file and line. +- Risk assessment (low/medium/high) is required per change in the report — not just a flat list. + +## Workflow + +```text +Phase 0: Detect source and target versions + ├── Read additionalPlanContext for explicit source/target versions + └── If source not specified, detect from existing cluster_version / apiVersion usage + +Phase 1: Scan + ├── Identify all manifests, charts, Kustomize overlays, Terraform, CDK files + └── Build an inventory of resource kinds and current apiVersions per file + +Phase 2: Detect incompatibilities + ├── Map every apiVersion against references/api-removals-by-version.md + │ for each version between source and target (inclusive) + ├── Map EKS-specific changes against references/eks-specific-changes.md + └── Check addon versions (VPC CNI, CoreDNS, kube-proxy, EBS/EFS CSI, + AWS LB Controller, etc.) against the compatibility matrix + +Phase 3: Transform + ├── Update apiVersion fields to the replacement API + ├── Restructure fields that changed shape (see references/examples-before-after.md) + ├── Add newly required fields with sensible defaults + ├── Update Terraform ami_type (AL2 -> AL2023) for 1.33+ targets + └── Update Terraform/CDK cluster version strings to the target version + +Phase 4: Validate + ├── kubectl apply --dry-run=client (if kubectl available) + ├── helm template (if Helm available) + └── terraform validate (if Terraform available) + +Phase 5: Report + └── Generate MIGRATION_REPORT.md: + - Summary of automatic changes + - Manual action items (e.g., PodSecurityPolicy migration) + - Addon compatibility warnings with recommended versions + - Risk assessment (low/medium/high) per change + - Upgrade Execution Path (sequential hops + Upgrade Controller recommendation) +``` + +### Configuration + +Source and target versions are provided via `additionalPlanContext`: +- `"Target EKS version 1.32. Upgrade from 1.28."` +- `"Upgrade to latest EKS version from 1.30."` + +If the source version is not specified, detect it from existing manifests (`apiVersion` usage patterns) or IaC (`cluster_version` / `KubernetesVersion` fields). + +## Worked Examples + +### Example: Ingress (`extensions/v1beta1` -> `networking.k8s.io/v1`) + +**Before (breaks on EKS 1.22+):** +```yaml +apiVersion: extensions/v1beta1 +kind: Ingress +spec: + rules: + - http: + paths: + - path: / + backend: + serviceName: my-app-svc + servicePort: 80 +``` + +**After:** +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +spec: + rules: + - http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: my-app-svc + port: + number: 80 +``` + +Full example set (8 transformations covering Ingress, PodDisruptionBudget, CronJob, HorizontalPodAutoscaler, FlowSchema, CustomResourceDefinition, Terraform node groups, and admission webhooks) is in `references/examples-before-after.md`. + +## Reference Dispatch + +Load reference files on demand based on what the scan finds: + +| Signal | Reference File | +|---|---| +| Any `apiVersion` field in a manifest, chart template, or Kustomize resource | `references/api-removals-by-version.md` | +| `aws_eks_cluster`, `aws_eks_node_group`, `ami_type`, EKS CDK constructs, addon image tags | `references/eks-specific-changes.md` | +| Any detected incompatibility requiring a concrete before/after transformation | `references/examples-before-after.md` | + +## Validation / Exit Criteria + +1. Every `apiVersion` used in the repository is valid for the target EKS version (no removed APIs remain). +2. Every automatic transformation preserves original comments, labels, and annotations. +3. No resource was deleted — only transformed. +4. Ambiguous transformations are marked with a `TODO` comment in code and documented in the report. +5. PodSecurityPolicy usage, if present, is flagged in the report and NOT auto-migrated. +6. `kubectl apply --dry-run=client`, `helm template`, and/or `terraform validate` pass for all transformed files (for whichever tools are available on the host). +7. `MIGRATION_REPORT.md` exists and contains: summary of changes, manual action items, addon compatibility warnings, risk assessment per change, and an Upgrade Execution Path section. +8. The Upgrade Execution Path lists every sequential minor-version hop between source and target and recommends the Upgrade Controller for Amazon EKS as the execution mechanism. + +## Tips + +- EKS does not support skip-version cluster upgrades — always resolve the full source-to-target version range before scanning for API removals, even if you only need to report on the final target. +- AL2 AMIs stopped being released starting with EKS 1.33 — any node group or launch template still using `AL2_x86_64`/`AL2_ARM_64` targeting 1.33+ needs an `ami_type` update to AL2023 or Bottlerocket. +- An empty `policy/v1` PodDisruptionBudget selector (`{}`) selects ALL pods in the namespace — this is a behavior change from `policy/v1beta1` (which selected none) and must be called out explicitly in the report, not just transformed silently. From d1d218d3510b9ab2df70e4c5f5a25a90afb3591c Mon Sep 17 00:00:00 2001 From: Bruno Lopes <37803210+brunokktro@users.noreply.github.com> Date: Sat, 18 Jul 2026 08:33:09 -0300 Subject: [PATCH 3/5] Add reference docs for eks-version-upgrade-readiness - api-removals-by-version.md: Kubernetes API removal table (1.16-1.36) plus quick upgrade-path lookup - eks-specific-changes.md: EKS-specific changes per version and addon compatibility matrix - examples-before-after.md: 8 concrete before/after transformations --- .../references/api-removals-by-version.md | 197 +++++++++ .../references/eks-specific-changes.md | 144 +++++++ .../references/examples-before-after.md | 395 ++++++++++++++++++ 3 files changed, 736 insertions(+) create mode 100644 community-sourced-transformations/eks-version-upgrade-readiness/references/api-removals-by-version.md create mode 100644 community-sourced-transformations/eks-version-upgrade-readiness/references/eks-specific-changes.md create mode 100644 community-sourced-transformations/eks-version-upgrade-readiness/references/examples-before-after.md diff --git a/community-sourced-transformations/eks-version-upgrade-readiness/references/api-removals-by-version.md b/community-sourced-transformations/eks-version-upgrade-readiness/references/api-removals-by-version.md new file mode 100644 index 0000000..3f148b5 --- /dev/null +++ b/community-sourced-transformations/eks-version-upgrade-readiness/references/api-removals-by-version.md @@ -0,0 +1,197 @@ +# Kubernetes API Removals by Version + +Reference for the ATX Custom TD. Source: https://kubernetes.io/docs/reference/using-api/deprecation-guide/ + +## v1.32 + +| Resource | Removed API | Replacement API | Available Since | +|----------|-------------|-----------------|-----------------| +| FlowSchema | `flowcontrol.apiserver.k8s.io/v1beta3` | `flowcontrol.apiserver.k8s.io/v1` | v1.29 | +| PriorityLevelConfiguration | `flowcontrol.apiserver.k8s.io/v1beta3` | `flowcontrol.apiserver.k8s.io/v1` | v1.29 | + +**Notable changes in v1:** +- `spec.limited.nominalConcurrencyShares` only defaults to 30 when unspecified; explicit 0 is NOT changed to 30 + +## v1.29 + +| Resource | Removed API | Replacement API | Available Since | +|----------|-------------|-----------------|-----------------| +| FlowSchema | `flowcontrol.apiserver.k8s.io/v1beta2` | `flowcontrol.apiserver.k8s.io/v1` | v1.29 | +| PriorityLevelConfiguration | `flowcontrol.apiserver.k8s.io/v1beta2` | `flowcontrol.apiserver.k8s.io/v1` | v1.29 | + +**Notable changes:** +- `spec.limited.assuredConcurrencyShares` renamed to `spec.limited.nominalConcurrencyShares` + +## v1.27 + +| Resource | Removed API | Replacement API | Available Since | +|----------|-------------|-----------------|-----------------| +| CSIStorageCapacity | `storage.k8s.io/v1beta1` | `storage.k8s.io/v1` | v1.24 | + +## v1.26 + +| Resource | Removed API | Replacement API | Available Since | +|----------|-------------|-----------------|-----------------| +| FlowSchema | `flowcontrol.apiserver.k8s.io/v1beta1` | `flowcontrol.apiserver.k8s.io/v1beta2` | v1.23 | +| PriorityLevelConfiguration | `flowcontrol.apiserver.k8s.io/v1beta1` | `flowcontrol.apiserver.k8s.io/v1beta2` | v1.23 | +| HorizontalPodAutoscaler | `autoscaling/v2beta2` | `autoscaling/v2` | v1.23 | + +**Notable HPA changes:** +- `targetAverageUtilization` replaced with `target.averageUtilization` + `target.type: Utilization` + +## v1.25 + +| Resource | Removed API | Replacement API | Available Since | +|----------|-------------|-----------------|-----------------| +| CronJob | `batch/v1beta1` | `batch/v1` | v1.21 | +| EndpointSlice | `discovery.k8s.io/v1beta1` | `discovery.k8s.io/v1` | v1.21 | +| Event | `events.k8s.io/v1beta1` | `events.k8s.io/v1` | v1.19 | +| HorizontalPodAutoscaler | `autoscaling/v2beta1` | `autoscaling/v2` | v1.23 | +| PodDisruptionBudget | `policy/v1beta1` | `policy/v1` | v1.21 | +| PodSecurityPolicy | `policy/v1beta1` | Pod Security Admission | v1.25 | +| RuntimeClass | `node.k8s.io/v1beta1` | `node.k8s.io/v1` | v1.20 | + +**Notable PDB changes in policy/v1:** +- Empty `spec.selector` (`{}`) selects ALL pods in namespace (v1beta1 selected none) + +**PodSecurityPolicy:** +- REMOVED entirely. Migrate to Pod Security Admission or 3rd party webhook + +## v1.22 + +| Resource | Removed API | Replacement API | Available Since | +|----------|-------------|-----------------|-----------------| +| MutatingWebhookConfiguration | `admissionregistration.k8s.io/v1beta1` | `admissionregistration.k8s.io/v1` | v1.16 | +| ValidatingWebhookConfiguration | `admissionregistration.k8s.io/v1beta1` | `admissionregistration.k8s.io/v1` | v1.16 | +| CustomResourceDefinition | `apiextensions.k8s.io/v1beta1` | `apiextensions.k8s.io/v1` | v1.16 | +| APIService | `apiregistration.k8s.io/v1beta1` | `apiregistration.k8s.io/v1` | v1.10 | +| TokenReview | `authentication.k8s.io/v1beta1` | `authentication.k8s.io/v1` | v1.6 | +| SubjectAccessReview | `authorization.k8s.io/v1beta1` | `authorization.k8s.io/v1` | v1.6 | +| CertificateSigningRequest | `certificates.k8s.io/v1beta1` | `certificates.k8s.io/v1` | v1.19 | +| Lease | `coordination.k8s.io/v1beta1` | `coordination.k8s.io/v1` | v1.14 | +| Ingress | `extensions/v1beta1`, `networking.k8s.io/v1beta1` | `networking.k8s.io/v1` | v1.19 | +| IngressClass | `networking.k8s.io/v1beta1` | `networking.k8s.io/v1` | v1.19 | +| ClusterRole/Binding | `rbac.authorization.k8s.io/v1beta1` | `rbac.authorization.k8s.io/v1` | v1.8 | +| Role/RoleBinding | `rbac.authorization.k8s.io/v1beta1` | `rbac.authorization.k8s.io/v1` | v1.8 | +| PriorityClass | `scheduling.k8s.io/v1beta1` | `scheduling.k8s.io/v1` | v1.14 | +| CSIDriver | `storage.k8s.io/v1beta1` | `storage.k8s.io/v1` | v1.19 | +| CSINode | `storage.k8s.io/v1beta1` | `storage.k8s.io/v1` | v1.17 | +| StorageClass | `storage.k8s.io/v1beta1` | `storage.k8s.io/v1` | v1.6 | +| VolumeAttachment | `storage.k8s.io/v1beta1` | `storage.k8s.io/v1` | v1.13 | + +**Notable Ingress changes in networking.k8s.io/v1:** +- `spec.backend` renamed to `spec.defaultBackend` +- `serviceName` renamed to `service.name` +- Numeric `servicePort` renamed to `service.port.number` +- String `servicePort` renamed to `service.port.name` +- `pathType` is now REQUIRED (use `ImplementationSpecific` for old behavior) + +**Notable CRD changes in apiextensions.k8s.io/v1:** +- `spec.version` removed; use `spec.versions` +- `spec.validation` removed; use `spec.versions[*].schema` +- `spec.subresources` removed; use `spec.versions[*].subresources` +- `openAPIV3Schema` is REQUIRED +- `spec.preserveUnknownFields: true` disallowed at top level + +**Notable Webhook changes in admissionregistration.k8s.io/v1:** +- `failurePolicy` default changed from `Ignore` to `Fail` +- `matchPolicy` default changed from `Exact` to `Equivalent` +- `timeoutSeconds` default changed from `30s` to `10s` +- `sideEffects` is REQUIRED (only `None` and `NoneOnDryRun` allowed) +- `admissionReviewVersions` is REQUIRED + +## v1.16 + +| Resource | Removed API | Replacement API | Available Since | +|----------|-------------|-----------------|-----------------| +| NetworkPolicy | `extensions/v1beta1` | `networking.k8s.io/v1` | v1.8 | +| DaemonSet | `extensions/v1beta1`, `apps/v1beta2` | `apps/v1` | v1.9 | +| Deployment | `extensions/v1beta1`, `apps/v1beta1`, `apps/v1beta2` | `apps/v1` | v1.9 | +| StatefulSet | `apps/v1beta1`, `apps/v1beta2` | `apps/v1` | v1.9 | +| ReplicaSet | `extensions/v1beta1`, `apps/v1beta1`, `apps/v1beta2` | `apps/v1` | v1.9 | + +**Notable changes in apps/v1:** +- `spec.selector` is REQUIRED and IMMUTABLE after creation +- DaemonSet `updateStrategy.type` defaults to `RollingUpdate` (was `OnDelete`) +- Deployment `progressDeadlineSeconds` defaults to 600s (was no deadline) +- Deployment `revisionHistoryLimit` defaults to 10 (was 2 or unlimited) + +--- + +## v1.34 + +| Resource | Removed/Changed | Details | +|----------|-----------------|----------| +| VolumeAttributesClass | `storage.k8s.io/v1beta1` -> `storage.k8s.io/v1` (GA) | Beta API still served on 1.31-1.33 with AWS-managed sidecars | +| AppArmor | DEPRECATED | Migrate to seccomp or Pod Security Standards | + +**Notable:** +- Containerd updated to 2.1 (check release notes for breaking changes) +- No AL2 AMI released for 1.34+ +- External JWT Signer for SA tokens promoted to Beta (token expiration behavior changes) +- Manual cgroup driver configuration deprecated + +## v1.35 + +| Resource | Removed/Changed | Details | +|----------|-----------------|----------| +| cgroup v1 | REMOVED (kubelet refuses to start) | AL2023 uses cgroup v2 by default. Bottlerocket sets `failCgroupV1: false` | +| containerd 1.x | LAST VERSION supporting it | Must switch to containerd 2.0+ before next upgrade | +| Ingress NGINX | RETIRED upstream (March 2026) | No more security patches. Migrate to Gateway API | +| kubelet flag `--pod-infra-container-image` | REMOVED | Remove from bootstrap scripts/launch templates | +| IPVS mode (kube-proxy) | DEPRECATED | Will be removed in 1.36 | + +## v1.36 + +| Resource | Removed/Changed | Details | +|----------|-----------------|----------| +| IPVS mode (kube-proxy) | REMOVED | Must use iptables or nftables mode | +| gogo protobuf dependency | REMOVED from K8s API types | Consumers of K8s Go types: update code-generator | + +**Notable GA graduations in v1.36:** +- MutatingAdmissionPolicies (CEL-based, replaces webhooks for common cases) +- Volume Group Snapshots +- Fine-grained kubelet API authorization +- External ServiceAccount token signer +- DRA admin access + prioritized lists +- Declarative validation (`validation-gen`) + +--- + +## Quick Lookup: "I'm upgrading from X to Y, what breaks?" + +### From 1.28 to 1.29 +- `flowcontrol.apiserver.k8s.io/v1beta2` FlowSchema/PriorityLevelConfiguration REMOVED + +### From 1.29 to 1.30 +- No API removals (but EKS-specific: gp2 StorageClass no longer default, ec2:DescribeAvailabilityZones required) + +### From 1.30 to 1.31 +- No API removals (but kubelet flag `--keep-terminated-pod-volumes` removed) + +### From 1.31 to 1.32 +- `flowcontrol.apiserver.k8s.io/v1beta3` FlowSchema/PriorityLevelConfiguration REMOVED +- Anonymous auth restricted to health endpoints only +- AL2 AMI deprecated (last version with AL2) + +### From 1.32 to 1.33 +- No API removals +- AL2 AMIs NO LONGER released (must use AL2023 or Bottlerocket) +- Endpoints API deprecated (warnings returned, migrate to EndpointSlices) + +### From 1.33 to 1.34 +- VolumeAttributesClass beta API migrated to GA (`storage.k8s.io/v1`) +- AppArmor deprecated +- Containerd updated to 2.1 +- No AL2 AMI released + +### From 1.34 to 1.35 +- cgroup v1 support REMOVED (kubelet won't start) +- containerd 1.x LAST supported version +- Ingress NGINX RETIRED upstream +- kubelet `--pod-infra-container-image` flag REMOVED +- IPVS mode deprecated + +### From 1.35 to 1.36 +- IPVS mode REMOVED from kube-proxy +- gogo protobuf removed from K8s API types (affects Go clients) diff --git a/community-sourced-transformations/eks-version-upgrade-readiness/references/eks-specific-changes.md b/community-sourced-transformations/eks-version-upgrade-readiness/references/eks-specific-changes.md new file mode 100644 index 0000000..6931f2d --- /dev/null +++ b/community-sourced-transformations/eks-version-upgrade-readiness/references/eks-specific-changes.md @@ -0,0 +1,144 @@ +# EKS-Specific Changes by Version + +Changes that are Amazon EKS-specific (not upstream Kubernetes) and affect customer workloads/configs. + +## EKS 1.33 + +- **AL2 AMIs discontinued** - Amazon Linux 2 AMIs no longer released. Must use AL2023 or Bottlerocket. +- Action: Update launch templates, Terraform `ami_type`, node group configs from `AL2_x86_64`/`AL2_ARM_64` to `AL2023_x86_64_STANDARD`/`AL2023_ARM_64_STANDARD` + +## EKS 1.32 + +- **Anonymous auth restricted** - Only `/healthz`, `/livez`, `/readyz` accessible without auth. All other endpoints return 401 for `system:unauthenticated`. +- Action: Review RBAC policies granting access to `system:unauthenticated` group. Update health check configs if using non-standard endpoints. +- **AL2 AMI deprecation notice** - Last version with AL2 AMIs. Plan migration to AL2023. +- **ServiceAccount enforce-mountable-secrets deprecated** - `metadata.annotations[kubernetes.io/enforce-mountable-secrets]` deprecated. +- Action: Use separate namespaces to isolate access to mounted secrets instead. + +## EKS 1.31 + +- **kubelet flag removed** - `--keep-terminated-pod-volumes` (deprecated since 2017) removed. +- Action: Remove from bootstrap scripts, launch templates, and user data. +- **VolumeAttributesClass beta enabled** - Requires EBS CSI Driver v1.35.0+ for ModifyVolume support. +- **AppArmor GA** - Migrate from annotations to `securityContext.appArmorProfile.type` field. + +## EKS 1.30 + +- **Default StorageClass annotation removed** - New clusters don't have `default` annotation on `gp2` StorageClass. +- Action: Reference StorageClass by name `gp2` explicitly, or deploy EBS CSI default SC with `defaultStorageClass.enabled=true`. +- **AL2023 default for new managed node groups** - New MNGs default to AL2023 (existing unchanged). +- **AZ ID label added** - `topology.k8s.aws/zone-id` label on worker nodes. +- **IAM policy change** - `ec2:DescribeAvailabilityZones` now REQUIRED in cluster IAM role. +- Action: Update cluster IAM role policy. + +## EKS 1.29 + +- **Extended support pricing** - Versions entering extended support incur additional cost. +- **EKS Pod Identity GA** - Recommended over IRSA for new workloads. + +## EKS 1.28 + +- **Metrics changes** - Several kube-scheduler and kube-controller-manager metrics renamed/removed. +- **kubectl events subcommand GA** - `kubectl events` replaces `kubectl get events`. + +## EKS 1.35 + +- **cgroup v1 support removed** - Kubelet refuses to start on cgroup v1 nodes by default. +- Action: AL2023 already uses cgroup v2. If manually configured cgroup v1, set `failCgroupV1: false` or migrate to cgroup v2. +- **containerd 1.x last supported** - Must switch to containerd 2.0+ before upgrading to 1.36. +- Action: Update node AMIs and container runtime configs. +- **Ingress NGINX retired upstream** (March 2026) - No more security patches. +- Action: Migrate to Gateway API, AWS ALB Ingress Controller, or other alternatives. +- **kubelet flag `--pod-infra-container-image` removed** - Custom AMI users must remove from bootstrap scripts. +- **IPVS mode deprecated** - Will be removed in 1.36. Plan migration to iptables or nftables. +- **Windows Server 2025 support added** +- **In-Place Pod Resource Updates GA** - CPU/memory changes without Pod restart. + +## EKS 1.36 + +- **IPVS mode removed from kube-proxy** - Must use iptables or nftables proxy mode. +- Action: Update kube-proxy ConfigMap `mode` field. Remove IPVS-related configs. +- **gogo protobuf removed from K8s API types** - Affects Go clients consuming K8s API types directly. +- Action: Update Go dependencies using `k8s.io/code-generator` instead of `gogo/protobuf`. + +--- + +## Addon Compatibility Matrix (common addons) + +When upgrading EKS, addon versions must also be compatible: + +| Addon | Min version for EKS 1.30+ | Min version for EKS 1.32+ | +|-------|---------------------------|---------------------------| +| VPC CNI | v1.16.0+ | v1.18.0+ | +| CoreDNS | v1.11.1+ | v1.11.3+ | +| kube-proxy | Match cluster version | Match cluster version | +| EBS CSI Driver | v1.28.0+ | v1.35.0+ | +| EFS CSI Driver | v2.0.0+ | v2.1.0+ | +| AWS LB Controller | v2.7.0+ | v2.8.0+ | +| Cert-Manager | v1.14.0+ | v1.15.0+ | +| Ingress-NGINX | v1.10.0+ | v1.11.0+ | +| ArgoCD | v2.10.0+ | v2.12.0+ | +| Karpenter | v0.35.0+ | v1.0.0+ | +| Istio | v1.20+ | v1.22+ | + +**Note:** Always verify exact compatibility in addon release notes. This table is approximate guidance. + +--- + +## Terraform/CDK/Pulumi Patterns to Update + +### Terraform aws_eks_cluster + +```hcl +# Before (pinned old version) +resource "aws_eks_cluster" "main" { + version = "1.28" +} + +# After (target version) +resource "aws_eks_cluster" "main" { + version = "1.32" +} +``` + +### Terraform aws_eks_node_group (AL2 to AL2023) + +```hcl +# Before +resource "aws_eks_node_group" "workers" { + ami_type = "AL2_x86_64" +} + +# After (required for 1.33+) +resource "aws_eks_node_group" "workers" { + ami_type = "AL2023_x86_64_STANDARD" +} +``` + +### CDK EKS Cluster + +```typescript +// Before +new eks.Cluster(this, 'Cluster', { + version: eks.KubernetesVersion.V1_28, +}); + +// After +new eks.Cluster(this, 'Cluster', { + version: eks.KubernetesVersion.V1_32, +}); +``` + +### Helm values (addon versions) + +```yaml +# Before +aws-load-balancer-controller: + image: + tag: v2.6.2 + +# After (compatible with 1.32) +aws-load-balancer-controller: + image: + tag: v2.8.1 +``` diff --git a/community-sourced-transformations/eks-version-upgrade-readiness/references/examples-before-after.md b/community-sourced-transformations/eks-version-upgrade-readiness/references/examples-before-after.md new file mode 100644 index 0000000..bcf85cf --- /dev/null +++ b/community-sourced-transformations/eks-version-upgrade-readiness/references/examples-before-after.md @@ -0,0 +1,395 @@ +# Examples: Before and After Transformations + +## 1. Ingress (extensions/v1beta1 -> networking.k8s.io/v1) + +### Before (breaks on EKS 1.22+) + +```yaml +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + name: my-app + annotations: + kubernetes.io/ingress.class: alb +spec: + rules: + - host: app.example.com + http: + paths: + - path: / + backend: + serviceName: my-app-svc + servicePort: 80 +``` + +### After (compatible with all current EKS versions) + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: my-app +spec: + ingressClassName: alb + rules: + - host: app.example.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: my-app-svc + port: + number: 80 +``` + +**Changes:** +- `apiVersion` updated +- `kubernetes.io/ingress.class` annotation replaced with `spec.ingressClassName` +- `backend.serviceName` -> `backend.service.name` +- `backend.servicePort` -> `backend.service.port.number` +- `pathType` added (REQUIRED in v1) + +--- + +## 2. PodDisruptionBudget (policy/v1beta1 -> policy/v1) + +### Before (breaks on EKS 1.25+) + +```yaml +apiVersion: policy/v1beta1 +kind: PodDisruptionBudget +metadata: + name: my-app-pdb +spec: + minAvailable: 2 + selector: + matchLabels: + app: my-app +``` + +### After + +```yaml +apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: my-app-pdb +spec: + minAvailable: 2 + selector: + matchLabels: + app: my-app +``` + +**Changes:** +- `apiVersion` updated from `policy/v1beta1` to `policy/v1` +- WARNING: empty `spec.selector` (`{}`) now selects ALL pods (was none in v1beta1) + +--- + +## 3. CronJob (batch/v1beta1 -> batch/v1) + +### Before (breaks on EKS 1.25+) + +```yaml +apiVersion: batch/v1beta1 +kind: CronJob +metadata: + name: cleanup +spec: + schedule: "0 2 * * *" + jobTemplate: + spec: + template: + spec: + containers: + - name: cleanup + image: busybox + command: ["/bin/sh", "-c", "echo cleanup"] + restartPolicy: OnFailure +``` + +### After + +```yaml +apiVersion: batch/v1 +kind: CronJob +metadata: + name: cleanup +spec: + schedule: "0 2 * * *" + jobTemplate: + spec: + template: + spec: + containers: + - name: cleanup + image: busybox + command: ["/bin/sh", "-c", "echo cleanup"] + restartPolicy: OnFailure +``` + +**Changes:** +- `apiVersion` updated (no structural changes needed) + +--- + +## 4. HorizontalPodAutoscaler (autoscaling/v2beta2 -> autoscaling/v2) + +### Before (breaks on EKS 1.26+) + +```yaml +apiVersion: autoscaling/v2beta2 +kind: HorizontalPodAutoscaler +metadata: + name: my-app +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: my-app + minReplicas: 2 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + target: + type: Utilization + averageUtilization: 70 +``` + +### After + +```yaml +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: my-app +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: my-app + minReplicas: 2 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + target: + type: Utilization + averageUtilization: 70 +``` + +**Changes:** +- `apiVersion` updated (structure is the same for v2beta2 -> v2) + +--- + +## 5. FlowSchema (flowcontrol.apiserver.k8s.io/v1beta3 -> v1) + +### Before (breaks on EKS 1.32+) + +```yaml +apiVersion: flowcontrol.apiserver.k8s.io/v1beta3 +kind: FlowSchema +metadata: + name: my-flow +spec: + priorityLevelConfiguration: + name: my-priority + matchingPrecedence: 1000 + rules: + - subjects: + - kind: ServiceAccount + serviceAccount: + name: my-sa + namespace: default + resourceRules: + - verbs: ["get", "list"] + apiGroups: [""] + resources: ["pods"] +``` + +### After + +```yaml +apiVersion: flowcontrol.apiserver.k8s.io/v1 +kind: FlowSchema +metadata: + name: my-flow +spec: + priorityLevelConfiguration: + name: my-priority + matchingPrecedence: 1000 + rules: + - subjects: + - kind: ServiceAccount + serviceAccount: + name: my-sa + namespace: default + resourceRules: + - verbs: ["get", "list"] + apiGroups: [""] + resources: ["pods"] +``` + +--- + +## 6. CustomResourceDefinition (apiextensions.k8s.io/v1beta1 -> v1) + +### Before (breaks on EKS 1.22+) + +```yaml +apiVersion: apiextensions.k8s.io/v1beta1 +kind: CustomResourceDefinition +metadata: + name: crontabs.stable.example.com +spec: + group: stable.example.com + version: v1 + scope: Namespaced + names: + plural: crontabs + singular: crontab + kind: CronTab + validation: + openAPIV3Schema: + type: object + properties: + spec: + type: object +``` + +### After + +```yaml +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: crontabs.stable.example.com +spec: + group: stable.example.com + names: + plural: crontabs + singular: crontab + kind: CronTab + scope: Namespaced + versions: + - name: v1 + served: true + storage: true + schema: + openAPIV3Schema: + type: object + properties: + spec: + type: object +``` + +**Changes:** +- `spec.version` replaced with `spec.versions[]` +- `spec.validation` moved to `spec.versions[*].schema` +- `openAPIV3Schema` is REQUIRED +- Must be a structural schema + +--- + +## 7. Terraform: Node Group AL2 -> AL2023 + +### Before (breaks on EKS 1.33+) + +```hcl +resource "aws_eks_node_group" "workers" { + cluster_name = aws_eks_cluster.main.name + node_group_name = "workers" + node_role_arn = aws_iam_role.node.arn + subnet_ids = var.private_subnets + + ami_type = "AL2_x86_64" + + scaling_config { + desired_size = 3 + max_size = 5 + min_size = 1 + } +} +``` + +### After + +```hcl +resource "aws_eks_node_group" "workers" { + cluster_name = aws_eks_cluster.main.name + node_group_name = "workers" + node_role_arn = aws_iam_role.node.arn + subnet_ids = var.private_subnets + + ami_type = "AL2023_x86_64_STANDARD" + + scaling_config { + desired_size = 3 + max_size = 5 + min_size = 1 + } +} +``` + +--- + +## 8. Webhook Configuration (admissionregistration.k8s.io/v1beta1 -> v1) + +### Before (breaks on EKS 1.22+) + +```yaml +apiVersion: admissionregistration.k8s.io/v1beta1 +kind: ValidatingWebhookConfiguration +metadata: + name: my-webhook +webhooks: + - name: validate.example.com + clientConfig: + service: + name: webhook-svc + namespace: default + path: /validate + rules: + - apiGroups: [""] + apiVersions: ["v1"] + operations: ["CREATE"] + resources: ["pods"] +``` + +### After + +```yaml +apiVersion: admissionregistration.k8s.io/v1 +kind: ValidatingWebhookConfiguration +metadata: + name: my-webhook +webhooks: + - name: validate.example.com + admissionReviewVersions: ["v1", "v1beta1"] + sideEffects: None + failurePolicy: Fail + timeoutSeconds: 10 + clientConfig: + service: + name: webhook-svc + namespace: default + path: /validate + rules: + - apiGroups: [""] + apiVersions: ["v1"] + operations: ["CREATE"] + resources: ["pods"] +``` + +**Changes:** +- `admissionReviewVersions` is REQUIRED +- `sideEffects` is REQUIRED (only `None` or `NoneOnDryRun`) +- `failurePolicy` defaults to `Fail` (was `Ignore`) +- `timeoutSeconds` defaults to 10s (was 30s) From 6fb602007b0ddedbc73369fe7682ede10b9cfe82 Mon Sep 17 00:00:00 2001 From: Bruno Lopes Date: Fri, 24 Jul 2026 13:29:31 -0300 Subject: [PATCH 4/5] Address review feedback: remove internal links, add BENCHMARKS.md, Troubleshooting, and Repository Structure - Replace internal GitLab tool references with public EKS upgrade docs (cluster upgrade best practices + EKS Upgrade Insights) - Add BENCHMARKS.md with end-to-end test results: 3 repositories (K8s manifests, Terraform, Helm) run via atx custom def exec, 14/14 detections, 13/13 transformations, all validators passing - Add Troubleshooting section (6 scenarios) - Add Repository Structure tree at the bottom of the README --- .../BENCHMARKS.md | 148 ++++++++++++++++++ .../eks-version-upgrade-readiness/README.md | 46 +++++- .../eks-version-upgrade-readiness/SKILL.md | 8 +- 3 files changed, 191 insertions(+), 11 deletions(-) create mode 100644 community-sourced-transformations/eks-version-upgrade-readiness/BENCHMARKS.md diff --git a/community-sourced-transformations/eks-version-upgrade-readiness/BENCHMARKS.md b/community-sourced-transformations/eks-version-upgrade-readiness/BENCHMARKS.md new file mode 100644 index 0000000..4b013bd --- /dev/null +++ b/community-sourced-transformations/eks-version-upgrade-readiness/BENCHMARKS.md @@ -0,0 +1,148 @@ +# Benchmark Results - EKS Version Upgrade Readiness + +## Executive Summary + +| Metric | Result | +|--------|--------| +| Total repositories tested | 3 (Kubernetes manifests, Terraform, Helm chart) | +| Transformation success rate | 100% (3/3) | +| Deprecated APIs detected | 9/9 planted incompatibilities detected (100%) | +| Automatic transformations | 8/8 applied correctly | +| Flag-only items (PSP) | 1/1 correctly flagged, NOT auto-migrated | +| Control resources (already compatible) | 0 modified (correct - no false positives) | +| Validation | `terraform validate` PASS, `helm template` PASS, YAML parse PASS on all outputs | +| `MIGRATION_REPORT.md` generated | 3/3 runs | +| Total agent minutes | ~95.2 | +| Total estimated cost | ~$3.33 (at $0.035/agent-minute) | + +### Methodology + +Each test repository was seeded with **known deprecated APIs** (documented per run below), committed to git as a baseline, then transformed via: + +```bash +atx custom def exec -n eks-version-upgrade-readiness -p -x -t \ + --configuration 'additionalPlanContext=Target EKS version . Upgrade from .' +``` + +Results were verified against the git diff (what changed), the exit criteria in [SKILL.md](SKILL.md) (what must hold), and external validators (`terraform validate`, `helm template`, YAML parsing). + +### Pricing Note + +Agent minutes = active agent work (planning, reasoning, code modification). Client-side operations (file reads, validation commands) are not billed. Price: **$0.035 / agent minute**. + +--- + +## At-a-Glance Results Table + +| # | Repository | Upgrade Path | Status | Detected | Transformed | Flag-Only | Validation | Agent Min | Cost | +|---|---|---|---|---|---|---|---|---|---| +| 1 | k8s-manifests (4 files, 7 resources) | 1.21 -> 1.32 | ✅ SUCCESS | 5/5 | 4/4 | 1/1 (PSP) | YAML parse PASS | 38.5 | $1.35 | +| 2 | terraform-eks (2 files, cluster + 2 node groups + 4 addons) | 1.28 -> 1.33 | ✅ SUCCESS | 7/7 | 7/7 | - | `terraform validate` PASS | 39.1 | $1.37 | +| 3 | helm-chart (1 chart, 2 templates) | 1.21 -> 1.30 | ✅ SUCCESS | 2/2 | 2/2 | - | `helm template` PASS | 17.7 | $0.62 | +| | **TOTALS** | | **3/3** | **14/14** | **13/13** | **1/1** | **3/3 PASS** | **~95.2** | **~$3.33** | + +--- + +## Detailed Per-Repository Results + +### 1. Kubernetes Manifests - retail store app (1.21 -> 1.32) + +**Input:** 4 manifest files with 5 intentionally deprecated resources + 2 control resources already on current APIs (Deployment `apps/v1`, Service `v1`). + +| Planted Incompatibility | Removed In | Detected | Action Taken | +|---|---|---|---| +| Ingress `extensions/v1beta1` | 1.22 | ✅ | Transformed to `networking.k8s.io/v1`: backend restructured to `service.name`/`service.port.number`, `pathType: Prefix` added, `kubernetes.io/ingress.class` annotation converted to `spec.ingressClassName` | +| PodDisruptionBudget `policy/v1beta1` | 1.25 | ✅ | Transformed to `policy/v1` | +| CronJob `batch/v1beta1` | 1.25 | ✅ | Transformed to `batch/v1` | +| HorizontalPodAutoscaler `autoscaling/v2beta1` | 1.25 | ✅ | Transformed to `autoscaling/v2`: `targetAverageUtilization` restructured to `target.type: Utilization` + `averageUtilization` | +| PodSecurityPolicy `policy/v1beta1` | 1.25 | ✅ | **Flagged only** (per design): TODO comment added pointing to Pod Security Admission, listed as manual action item in report - NOT auto-migrated | + +**Pass/Fail checks:** + +```text +✅ All 4 deprecated resources transformed with comments/labels/annotations preserved +✅ PSP untouched except TODO comment (exit criterion 5) +✅ Control resources (Deployment/Service) byte-identical - zero false positives +✅ All output files parse as valid YAML (7 documents across 4 files) +✅ MIGRATION_REPORT.md generated: summary, PSP manual action item, risk assessment + per change, Upgrade Execution Path (1.21 -> 1.22 -> ... -> 1.32, 11 sequential hops) +``` + +--- + +### 2. Terraform - EKS cluster with AL2 node groups (1.28 -> 1.33) + +**Input:** 2 `.tf` files declaring an EKS cluster on 1.28, two managed node groups on AL2 AMI types (x86 + ARM), and 4 EKS addons pinned below 1.33 minimums. + +| Planted Incompatibility | Detected | Action Taken | +|---|---|---| +| `version = "1.28"` on `aws_eks_cluster` | ✅ | Updated to `"1.33"` | +| `ami_type = "AL2_x86_64"` (AL2 discontinued from EKS 1.33) | ✅ | Updated to `"AL2023_x86_64_STANDARD"` | +| `ami_type = "AL2_ARM_64"` | ✅ | Updated to `"AL2023_ARM_64_STANDARD"` | +| vpc-cni `v1.13.4-eksbuild.1` | ✅ | Updated to `v1.19.2-eksbuild.1` | +| coredns `v1.10.1-eksbuild.4` | ✅ | Updated to `v1.11.4-eksbuild.2` | +| kube-proxy `v1.28.1-eksbuild.1` | ✅ | Updated to `v1.33.0-eksbuild.1` | +| aws-ebs-csi-driver `v1.23.0-eksbuild.1` | ✅ | Updated to `v1.35.0-eksbuild.1` | + +**Pass/Fail checks:** + +```text +✅ terraform validate -> "Success! The configuration is valid." (verified independently + after the run, terraform-provider-aws v6.x) +✅ IAM roles, VPC config, scaling config, tags untouched +✅ MIGRATION_REPORT.md generated with the sequential path 1.28 -> 1.29 -> 1.30 -> + 1.31 -> 1.32 -> 1.33 and addon compatibility rationale +``` + +--- + +### 3. Helm Chart - legacy-api (1.21 -> 1.30) + +**Input:** 1 chart with an Ingress template on `networking.k8s.io/v1beta1` (removed in 1.22) and a PDB template on `policy/v1beta1` (removed in 1.25), plus `values.yaml` and `_helpers.tpl`. + +| Planted Incompatibility | Detected | Action Taken | +|---|---|---| +| Ingress template `networking.k8s.io/v1beta1` | ✅ | Transformed to `networking.k8s.io/v1`: backend restructured, `pathType: Prefix` added, ingress-class annotation converted to `spec.ingressClassName` - all Helm templating expressions (`{{ .Values... }}`, `{{ include ... }}`) preserved intact | +| PDB template `policy/v1beta1` | ✅ | Transformed to `policy/v1` | + +**Pass/Fail checks:** + +```text +✅ helm template renders cleanly post-transformation (verified independently) +✅ values.yaml byte-identical (exit criterion: preserve values structure and keys) +✅ _helpers.tpl untouched +✅ MIGRATION_REPORT.md generated with sequential path and per-change risk assessment +``` + +--- + +## Exit Criteria Compliance (per SKILL.md) + +| # | Exit Criterion | Run 1 | Run 2 | Run 3 | +|---|---|---|---|---| +| 1 | No removed APIs remain for target version | ✅ | ✅ | ✅ | +| 2 | Comments/labels/annotations preserved | ✅ | ✅ | ✅ | +| 3 | No resource deleted | ✅ | ✅ | ✅ | +| 4 | Ambiguous changes marked with TODO + report | ✅ (PSP) | n/a | n/a | +| 5 | PSP flagged, never auto-migrated | ✅ | n/a | n/a | +| 6 | Validators pass (where available) | ✅ YAML | ✅ terraform | ✅ helm | +| 7 | MIGRATION_REPORT.md complete | ✅ | ✅ | ✅ | +| 8 | Upgrade Execution Path with every sequential hop | ✅ (11 hops) | ✅ (5 hops) | ✅ (9 hops) | + +--- + +## Validation Commands Used + +```bash +# Manifest structural validation +python3 -c "import yaml,glob; [list(yaml.safe_load_all(open(f))) for f in glob.glob('manifests/*.yaml')]" + +# Terraform validation (after terraform init) +terraform validate + +# Helm chart rendering +helm template test legacy-api/ + +# Diff audit against the pre-transformation git baseline +git diff HEAD +``` diff --git a/community-sourced-transformations/eks-version-upgrade-readiness/README.md b/community-sourced-transformations/eks-version-upgrade-readiness/README.md index 347195b..870ef13 100644 --- a/community-sourced-transformations/eks-version-upgrade-readiness/README.md +++ b/community-sourced-transformations/eks-version-upgrade-readiness/README.md @@ -10,11 +10,14 @@ Analyzes and transforms customer code (Kubernetes manifests, Helm charts, Kustom - [The Problem](#the-problem) - [What This Skill Does](#what-this-skill-does) - [Skill Architecture](#skill-architecture) -- [Complement to the EKS Upgrade Controller](#complement-to-the-eks-upgrade-controller) +- [Code Readiness vs. Cluster Upgrade Execution](#code-readiness-vs-cluster-upgrade-execution) - [Getting Started](#getting-started) - [Getting Started with AWS Transform Custom](#getting-started-with-aws-transform-custom) +- [Benchmarks](#benchmarks) +- [Troubleshooting](#troubleshooting) - [Known Limitations](#known-limitations) - [Documentation & References](#documentation--references) +- [Repository Structure](#repository-structure) ## Overview @@ -76,16 +79,16 @@ Input: Customer repo + target EKS version (via additionalPlanContext) 3. **PodSecurityPolicy is flag-only.** PSP removal (EKS 1.25+) requires a Pod Security Admission design decision that cannot be automated safely — it is always reported, never auto-migrated. 4. **Sequential-hop awareness.** EKS requires upgrading one minor version at a time. The skill always documents every intermediate hop in the target version string, even when transforming code directly to the final target. -## Complement to the EKS Upgrade Controller +## Code Readiness vs. Cluster Upgrade Execution -This skill and the [Upgrade Controller for Amazon EKS](https://gitlab.aws.dev/brunemat/eks-upgrade-controller) solve two different halves of the same problem: +Preparing for an EKS version upgrade has two distinct halves — this skill covers only the first: | | Scope | |---|---| | **This skill** | The **code**: manifests, Helm charts, Terraform, CDK — everything that runs on the cluster | -| **Upgrade Controller** | The **cluster**: control plane + data plane version upgrades, staged rollouts, maintenance windows, EKS Upgrade Insights validation | +| **Cluster upgrade execution** | The **cluster**: control plane + data plane version upgrades, staged rollouts, maintenance windows — see [EKS cluster upgrade best practices](https://docs.aws.amazon.com/eks/latest/best-practices/cluster-upgrades.html) and [EKS Upgrade Insights](https://docs.aws.amazon.com/eks/latest/userguide/cluster-insights.html) | -Used together they provide end-to-end upgrade readiness: code prepared ahead of time, cluster upgraded through an automated, sequential, validated process. `MIGRATION_REPORT.md` explicitly recommends the Upgrade Controller as the execution mechanism for the documented Upgrade Execution Path. +Used together they provide end-to-end upgrade readiness: code prepared ahead of time, then the cluster upgraded through a sequential, validated process. `MIGRATION_REPORT.md` documents the full sequential Upgrade Execution Path and points to the official EKS upgrade guidance as the execution reference. ## Getting Started @@ -142,14 +145,29 @@ MIGRATION_REPORT.md # summary, manual action items, addon warnings, risk asses Plus the transformed manifests/charts/Terraform/CDK files in place, with ambiguous changes marked via `TODO` comments. -## Known Limitations +## Benchmarks + +End-to-end test results — repositories tested via `atx custom def exec`, what was detected, what was transformed, and what passed/failed — are documented in [BENCHMARKS.md](BENCHMARKS.md). + +## Troubleshooting + +| Symptom | Cause | Fix | +|---|---|---| +| `atx custom def publish` fails with authentication error | AWS Transform CLI not authenticated | Re-run the auth flow from the [Getting Started Guide](https://docs.aws.amazon.com/transform/latest/userguide/custom-get-started.html) and confirm your builder ID / IAM Identity Center session is active | +| Transformation runs but no files are modified | `additionalPlanContext` contains "Analysis only" wording, or no incompatible APIs were found for the target version | Check `MIGRATION_REPORT.md` — if the detection table is empty, the repo is already compatible; otherwise remove the analysis-only instruction | +| Target version not respected (wrong APIs flagged) | Source/target versions missing or ambiguous in `additionalPlanContext` | Pass both explicitly: `additionalPlanContext=Target EKS version 1.32. Upgrade from 1.28.` | +| Validation steps reported as skipped | `kubectl`, `helm`, or `terraform` not installed on the machine running the transformation | Install the missing tool or accept the skip — validation is best-effort and the transform output is unaffected | +| Helm chart values not updated | By design — `values.yaml` structure and keys are preserved; only addon image tags below the minimum compatible version are bumped | Review the addon warnings section of `MIGRATION_REPORT.md` for manual value updates | +| PodSecurityPolicy still present after the run | By design — PSP migration requires a Pod Security Admission decision and is never automated | Follow the manual action item in `MIGRATION_REPORT.md` | + + | Limitation | Notes | |---|---| | PodSecurityPolicy migration | Never auto-migrated (requires Pod Security Admission design decisions) — flagged in report only | | Custom admission webhooks with non-standard defaults | Flagged for manual review, not transformed | | Skip-version upgrades | Not supported by EKS itself; the skill always documents the full sequential path | -| Cluster-level upgrade execution | Out of scope — use the Upgrade Controller for Amazon EKS for orchestration | +| Cluster-level upgrade execution | Out of scope — follow the [EKS cluster upgrade best practices](https://docs.aws.amazon.com/eks/latest/best-practices/cluster-upgrades.html) for orchestration | ## Documentation & References @@ -159,3 +177,17 @@ Plus the transformed manifests/charts/Terraform/CDK files in place, with ambiguo | [references/api-removals-by-version.md](references/api-removals-by-version.md) | Complete table of Kubernetes API removals per version (1.16 through 1.36), plus a quick "upgrading from X to Y" lookup | | [references/eks-specific-changes.md](references/eks-specific-changes.md) | EKS-specific changes per version, addon compatibility matrix, and Terraform/CDK/Helm update patterns | | [references/examples-before-after.md](references/examples-before-after.md) | 8 concrete before/after transformation examples covering Ingress, PDB, CronJob, HPA, FlowSchema, CRDs, Terraform node groups, and webhooks | +| [BENCHMARKS.md](BENCHMARKS.md) | End-to-end test results: repositories tested, detections, transformations, and pass/fail outcomes | + +## Repository Structure + +```text +eks-version-upgrade-readiness/ +├── README.md # This file — overview, getting started, troubleshooting +├── SKILL.md # Skill definition: objective, scope, workflow, exit criteria +├── BENCHMARKS.md # End-to-end test results with real repositories +└── references/ + ├── api-removals-by-version.md # Kubernetes API removals per version (1.16–1.36) + ├── eks-specific-changes.md # EKS-specific changes + addon compatibility matrix + └── examples-before-after.md # 8 before/after transformation examples +``` diff --git a/community-sourced-transformations/eks-version-upgrade-readiness/SKILL.md b/community-sourced-transformations/eks-version-upgrade-readiness/SKILL.md index 9cad7b2..993d790 100644 --- a/community-sourced-transformations/eks-version-upgrade-readiness/SKILL.md +++ b/community-sourced-transformations/eks-version-upgrade-readiness/SKILL.md @@ -28,7 +28,7 @@ Analyzes and transforms: Supports upgrades between any EKS versions from 1.16 through 1.36+. **Non-Goals** (out of scope for this skill): -1. Executing the actual cluster upgrade (control plane / data plane) — use the Upgrade Controller for Amazon EKS (https://gitlab.aws.dev/brunemat/eks-upgrade-controller) for automated sequential upgrades with maintenance windows, staged rollouts, and EKS Upgrade Insights validation. +1. Executing the actual cluster upgrade (control plane / data plane) — follow the EKS cluster upgrade best practices (https://docs.aws.amazon.com/eks/latest/best-practices/cluster-upgrades.html) and validate with EKS Upgrade Insights before each sequential hop. 2. PodSecurityPolicy migration — removed entirely in Kubernetes 1.25. Requires a Pod Security Admission or third-party webhook design decision that cannot be automated safely. Always flagged in the report, never transformed. 3. Custom admission webhook business logic — only the `admissionregistration.k8s.io` API shape and required defaults are updated; webhook implementation logic is out of scope. 4. Non-EKS Kubernetes distributions — API removal mapping is upstream Kubernetes, but EKS-specific sections (AMI types, addon matrix, IAM requirements) assume Amazon EKS. @@ -43,7 +43,7 @@ Supports upgrades between any EKS versions from 1.16 through 1.36+. ### Sequential Upgrade Awareness - Amazon EKS requires upgrading one minor version at a time — skip-version upgrades are not supported. - Terraform/CDK `cluster_version` / `KubernetesVersion` strings are set to the TARGET version in code (the code itself must be forward-compatible), but `MIGRATION_REPORT.md` must always list each intermediate sequential hop required to get there. -- `MIGRATION_REPORT.md` must include a section "Upgrade Execution Path" listing every hop and recommending the Upgrade Controller for Amazon EKS as the execution mechanism — this skill never executes the upgrade itself. +- `MIGRATION_REPORT.md` must include a section "Upgrade Execution Path" listing every hop and pointing to the official EKS upgrade guidance (cluster upgrade best practices + EKS Upgrade Insights) as the execution reference — this skill never executes the upgrade itself. ### Helm-Specific - Transform templates but preserve the `values.yaml` structure and keys. @@ -89,7 +89,7 @@ Phase 5: Report - Manual action items (e.g., PodSecurityPolicy migration) - Addon compatibility warnings with recommended versions - Risk assessment (low/medium/high) per change - - Upgrade Execution Path (sequential hops + Upgrade Controller recommendation) + - Upgrade Execution Path (sequential hops + official EKS upgrade guidance) ``` ### Configuration @@ -156,7 +156,7 @@ Load reference files on demand based on what the scan finds: 5. PodSecurityPolicy usage, if present, is flagged in the report and NOT auto-migrated. 6. `kubectl apply --dry-run=client`, `helm template`, and/or `terraform validate` pass for all transformed files (for whichever tools are available on the host). 7. `MIGRATION_REPORT.md` exists and contains: summary of changes, manual action items, addon compatibility warnings, risk assessment per change, and an Upgrade Execution Path section. -8. The Upgrade Execution Path lists every sequential minor-version hop between source and target and recommends the Upgrade Controller for Amazon EKS as the execution mechanism. +8. The Upgrade Execution Path lists every sequential minor-version hop between source and target and references the official EKS cluster upgrade best practices as the execution guidance. ## Tips From 6932021bfe4135c3ceace8ac4f5e3982857a0c28 Mon Sep 17 00:00:00 2001 From: Bruno Lopes Date: Fri, 24 Jul 2026 15:09:51 -0300 Subject: [PATCH 5/5] Add live EKS 1.35 cluster validation to BENCHMARKS.md kubectl apply --dry-run=server against a real EKS 1.35 control plane: 6/6 transformed resources accepted. Negative confirmation included: the flag-only PSP correctly fails (API removed), validating the design. --- .../eks-version-upgrade-readiness/BENCHMARKS.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/community-sourced-transformations/eks-version-upgrade-readiness/BENCHMARKS.md b/community-sourced-transformations/eks-version-upgrade-readiness/BENCHMARKS.md index 4b013bd..da1179b 100644 --- a/community-sourced-transformations/eks-version-upgrade-readiness/BENCHMARKS.md +++ b/community-sourced-transformations/eks-version-upgrade-readiness/BENCHMARKS.md @@ -10,7 +10,7 @@ | Automatic transformations | 8/8 applied correctly | | Flag-only items (PSP) | 1/1 correctly flagged, NOT auto-migrated | | Control resources (already compatible) | 0 modified (correct - no false positives) | -| Validation | `terraform validate` PASS, `helm template` PASS, YAML parse PASS on all outputs | +| Validation | `terraform validate` PASS, `helm template` PASS, YAML parse PASS, `kubectl apply --dry-run=server` PASS against a live EKS 1.35 cluster (6/6 transformed resources accepted) | | `MIGRATION_REPORT.md` generated | 3/3 runs | | Total agent minutes | ~95.2 | | Total estimated cost | ~$3.33 (at $0.035/agent-minute) | @@ -64,6 +64,12 @@ Agent minutes = active agent work (planning, reasoning, code modification). Clie ✅ PSP untouched except TODO comment (exit criterion 5) ✅ Control resources (Deployment/Service) byte-identical - zero false positives ✅ All output files parse as valid YAML (7 documents across 4 files) +✅ kubectl apply --dry-run=server against a LIVE Amazon EKS 1.35 cluster: + 6/6 transformed resources accepted by the API server (Deployment, Service, + Ingress networking.k8s.io/v1, PDB policy/v1, CronJob batch/v1, HPA autoscaling/v2) +✅ Negative confirmation: applying the untouched PSP against the same cluster fails + with "no matches for kind PodSecurityPolicy in version policy/v1beta1" - proving + the API is truly gone and the flag-only design decision is correct ✅ MIGRATION_REPORT.md generated: summary, PSP manual action item, risk assessment per change, Upgrade Execution Path (1.21 -> 1.22 -> ... -> 1.32, 11 sequential hops) ``` @@ -137,6 +143,10 @@ Agent minutes = active agent work (planning, reasoning, code modification). Clie # Manifest structural validation python3 -c "import yaml,glob; [list(yaml.safe_load_all(open(f))) for f in glob.glob('manifests/*.yaml')]" +# Live cluster validation (Amazon EKS 1.35) +aws eks update-kubeconfig --name --region us-east-1 +kubectl apply --dry-run=server -f manifests/ # 6/6 transformed resources accepted + # Terraform validation (after terraform init) terraform validate