Eks Ingress Migration

EKS Ingress Migration Skill

Overview

This skill assesses your live EKS cluster's current Ingress architecture and evaluates migration options. It discovers what ingress controllers are running, maps the routing topology, identifies risks, and presents the findings so your team can decide the best migration path.

This is an assessment tool, not a decision-maker. The skill presents findings and options — the migration strategy and readiness decision belongs to the user's DevOps team.

Migration options assessed:

Workflow

Pre-flight → Assess (7 sections) → Current Architecture Topology → Dual Report (md + html) → Export Materials

1. Pre-flight — Discover cluster, validate permissions
2. Assessment — Run 7 sections, collect findings and topology data
3. Current Architecture — Compile topology data into JSON for the HTML report's interactive 3D view (nodes, controllers, ingresses, services)
4. Dual Report — Automatically generate both:
   • Markdown (detailed) — full findings, ratings, options, CLI commands
   • HTML (visual summary) — interactive dashboard with 3D Routing Diagram view, collapsible sections
   • Both lead with the Migration Difficulty Score (0–100) — a deterministic roll-up of the per-finding Impact ratings (high = easy to leave NGINX, low = hard / high business impact). See references/report-generation.md Step 1.
5. Export Materials — Generate ready-to-apply YAML files:
   • current/ — existing Ingress resources (clean, no status fields)
   • target/gateway-api/ — Gateway API resources (GatewayClass, Gateway, HTTPRoute) in apply order
   • target/alb/ — ALB Controller Ingress resources (converted annotations)

Important: After assessment completes, proceed directly to report generation and manifest export. Do NOT pause to ask the user — generate all outputs automatically.

What Gets Assessed

Report Structure (5 Navigation Pages)

Reference Files

Before executing checks for any section, read the corresponding reference file from the references/ directory.

Tool Usage Rules

1. Do NOT call any tools when this skill is first activated. Wait for the user to ask.
2. Do NOT hardcode or guess cluster names. Always discover by listing first.
3. Do NOT retry a failed MCP tool call more than once.
4. Always load the relevant reference file before executing checks.
5. Only rate based on what was actually observed — never assume.
6. If a check fails or returns no data, mark UNKNOWN.
7. Every high-impact (4–5) finding must have a specific, actionable recommendation.
8. Collect topology data during assessment — every Ingress host, path, backend, controller, namespace, and the nodes (EC2 instances). This feeds the 3D Routing Diagram view.
9. Do NOT paste raw YAML/config in findings. Summarize what was found.
10. Use tables for all structured data. No prose lists of facts.
11. No filler text. Go straight to content.
12. Every finding cell: max 2 sentences.
13. No ASCII art diagrams. The HTML has the 3D routing diagram.
14. No ID column in tables. Remove all "ID" columns.
15. Multi-value cells: use <br> for line breaks, not commas.
16. Executive Summary must be bullet points — precise and comprehensive.

Skill Home Directory

All relative paths in this skill are relative to this skill's directory (the directory containing this SKILL.md).

When the skill says references/ingress-discovery.md, read <skill-dir>/references/ingress-discovery.md. When the skill says tools/report_to_html.py, run <skill-dir>/tools/report_to_html.py.

Reports are written to ~/ingress_migration/.

The assessment logic (references/*.md), the HTML report tool (tools/report_to_html.py), and the ATX Transform Definition and before/after samples (references/atx/, references/samples/) all live inside this skill directory. The skill does not require a project-root .mcp.json — live-cluster access is provided by the EKS MCP server (see the eks-mcp-server skill for setup).

Prerequisites

1. AWS credentials configured with EKS read access
2. Python 3.10+ installed (report tool uses only stdlib — no pip packages needed)
3. EKS MCP server for live-cluster reads (list_k8s_resources, etc.) — apex ships no project-root .mcp.json; see the eks-mcp-server skill for setup. Falls back to aws CLI + kubectl where possible.
4. AWS CLI or AWS MCP tools available (for eks, acm, route53, iam, elbv2 calls)
5. Required AWS Permissions:
   • eks:DescribeCluster, eks:ListClusters, eks:ListAddons, eks:DescribeAddon
   • elasticloadbalancing:DescribeLoadBalancers, elasticloadbalancing:DescribeTargetGroups
   • iam:GetRole, iam:ListAttachedRolePolicies
   • acm:ListCertificates
   • route53:ListHostedZones

Assessment Workflow

Input

The user provides an AWS Account ID (12-digit number). The skill discovers all EKS clusters across regions and assesses each one.

If the user provides a cluster name instead, skip discovery and assess that single cluster.

Step 0: Pre-flight

Action 1 — Verify account access

aws sts get-caller-identity --output json

Confirm the account ID matches what the user provided.

Action 2 — Discover all EKS clusters across regions

Enumerate the account's enabled regions, then scan each for clusters:

aws ec2 describe-regions --query 'Regions[].RegionName' --output text

For each region:

aws eks list-clusters --region <region> --output json

Compile a discovery table:

• If 0 clusters found → STOP. Tell the user no EKS clusters exist in this account.
• If 1 cluster found → Confirm and proceed with that cluster.
• If multiple clusters found → Show the table. Ask: "Assess all clusters, or select specific ones?"

Action 3 — For each selected cluster, describe it

aws eks describe-cluster --name <cluster> --region <region> --output json

Action 4 — Validate permissions (per cluster)

Optional permissions (degrades gracefully if missing):

Action 5 — Verify MCP connectivity

list_k8s_resources(cluster_name="<cluster>", kind="Node", api_version="v1")

Action 6 — Cluster health gate (read-only) — REQUIRED before assessing

An assessment of an unhealthy cluster is misleading. Verify, read-only:

1. Nodes Ready: kubectl get nodes — flag any not Ready (Auto Mode may have 0 nodes until a workload schedules; note that separately).
2. Ingress controllers healthy: for each controller Deployment, confirm availableReplicas > 0 and no pods in ImagePullBackOff / ErrImagePull / CrashLoopBackOff. If a controller is unhealthy, verify before you conclude it is dead: for ingress-nginx confirm all replicas are down (a multi-replica controller can serve while one pod crashloops); for the AWS LB Controller check the ALB/target-group state (the ALB keeps serving while the pod is down). A broken controller with bound routes is a suspected active outage — surface it first, as an urgent flag, outside the migration score; with zero bound routes it is tech debt (1). Either way its routing claims cannot be trusted until verified.
3. Egress sanity (if pods can't pull): cluster-wide ImagePullBackOff usually means broken node egress. Optionally inspect the node subnets' route table for a blackhole default route (deleted NAT gateway) via aws ec2 describe-route-tables. Report it as an environment caveat — do not attempt to fix it (read-only).

Action 7 — Detect EKS Auto Mode (read-only)

aws eks describe-cluster --name <cluster> --query 'cluster.computeConfig' --output json

Auto Mode is enabled when computeConfig.enabled = true. On Auto Mode, recognize the managed load-balancing IngressClass eks.amazonaws.com/alb (parameters apiGroup: eks.amazonaws.com, kind: IngressClassParams) and loadBalancerClass: eks.amazonaws.com/nlb — these are built-in, not a self-managed AWS LB Controller. Record Auto Mode status in Current Configuration; it changes Migration Options guidance (ALB path needs no LBC install).

Steps 1–7: Run Assessment (per cluster)

For each cluster, run the full assessment:

1. Read each steering file in order
2. Execute the checks
3. Score each item by Impact (0–5) per the Impact Indicator
4. Collect topology data — Ingress resources, controllers, backend services, and Node information (instance IDs, instance types)

Step 8: Current Architecture Topology (per cluster)

1. Compile topology data collected during Steps 1–7
2. Write JSON: ~/ingress_migration/<cluster>-topology.json
3. Briefly show topology summary, then proceed to Step 9

Topology JSON schema:

CRITICAL — controller naming contract: Every controllers[].name MUST be exactly equal to the value used in ingresses[].controller (i.e. the IngressClass name: nginx, alb, nginx-legacy, etc.). The 3D view links each ingress to its controller by exact name match — if they differ, the ingress will render unlinked (the renderer no longer falls back to the first controller). Use displayName for the human-readable deployment name (e.g. ingress-nginx-controller); the 3D label prefers displayName when present.

{
  "cluster": "name",
  "region": "ap-southeast-1",
  "nodes": [
    { "name": "ip-10-0-1-100.ec2.internal", "instanceId": "i-0abc123def456", "instanceType": "m5.xlarge", "zone": "ap-southeast-1a" }
  ],
  "controllers": [
    { "name": "nginx", "displayName": "ingress-nginx-controller", "namespace": "ingress-nginx", "version": "1.9.6", "type": "deployment" }
  ],
  "ingresses": [
    {
      "name": "my-app", "namespace": "default", "controller": "nginx",
      "hosts": ["app.example.com"],
      "paths": [{ "path": "/api", "pathType": "Prefix", "backend": "api-svc", "port": 80 }],
      "tls": true, "annotations": {"key": "value"}
    }
  ],
  "services": [
    { "name": "api-svc", "namespace": "default", "type": "ClusterIP", "ports": [80] }
  ],
  "gatewayApi": {
    "crdsInstalled": true,
    "gatewayClasses": [],
    "gateways": [],
    "httpRoutes": []
  }
}

Step 9: Generate Dual Report (per cluster)

Read references/report-generation.md and produce a markdown report per cluster:

~/ingress_migration/EKS-Ingress-Migration-<cluster>-<YYYY-MM-DD>-<HHMM>.md

After ALL cluster markdown reports are written, generate a single combined HTML report:

python3 tools/report_to_html.py \
  ~/ingress_migration/report-cluster-a.md ~/ingress_migration/report-cluster-b.md \
  --topology ~/ingress_migration/cluster-a-topology.json ~/ingress_migration/cluster-b-topology.json \
  --manifests ~/ingress_migration/cluster-a-manifests ~/ingress_migration/cluster-b-manifests \
  -o ~/ingress_migration/EKS-Ingress-Migration-<YYYY-MM-DD>-<HHMM>.html

The HTML report has a cluster dropdown in the left nav — selecting a cluster switches all content and the 3D routing diagram.

Always generate both. Markdown files are the source of truth; the HTML is for presentation.

Step 10: Export Materials (per cluster)

For each cluster that has Ingress resources, generate manifest files:

Output directory: ~/ingress_migration/<cluster>-manifests/

<cluster>-manifests/
├── current/
│   └── <namespace>-<ingress-name>.yaml
└── target/
    ├── 00-gateway-api-crds.yaml
    ├── 01-gatewayclass.yaml
    ├── 02-gateway.yaml
    ├── 03-httproute-<name>.yaml
    └── 04-referencegrant-<name>.yaml  (only if needed)

Rules:

1. current/ — Each Ingress as clean YAML (strip status, managedFields, resourceVersion, uid, creationTimestamp, generation)
2. target/gateway-api/ — Generated Gateway API manifests in numbered apply order with comments
3. target/alb/ — Generated ALB Controller Ingress manifests (annotation-converted)
4. 00-gateway-api-crds.yaml — Comment-only file with install command
5. All manifests must be valid kubectl apply -f ready
6. Skip clusters with 0 Ingress resources (nothing to export)
7. For ALB target, apply annotation mapping from references/alb-migration.md

Rating Rubric

Score every finding by Impact 0–5 using the Impact Indicator rubric (defined in the report, before Assessment Summary). Set severity by priority order: (1) business logic / revenue — the live traffic at stake · (2) security / reputation · (3) effort to remediate. Effort is NOT a severity driver — never move a score because a fix looks easy or hard. Presence is decided by estate state: an absent controller / empty estate / orphaned dead config is a non-event (0); a present-but-broken controller with zero bound routes is tech debt (1) + cleanup note, while broken with bound routes is a suspected active outage flagged urgently outside the 0–100 score. Carve-out: a running controller with a control-plane CVE (e.g. an admission-webhook RCE) is a security finding even at zero routes. Security anchors on exposure/blast-radius, business on live traffic.

Easy-to-deploy prerequisites (e.g. installing CRDs) are Low even if they block a path — effort never sets severity. Never use GREEN/AMBER/RED.

Migration Difficulty Score

Every report leads with a single Migration Difficulty Score (0–100) plus a separate Re-architecture Gate badge:

• High score = little change (easy); low score = much change (hard). It measures the amount of the estate that must change, rolled up from the per-finding Impact ratings — not a manday estimate and not a remediation-effort index (we cannot know who implements, and effort never sets severity).
• Empty / non-migratable estate = 100. No controller + no IngressClass + no Ingress → 100 / TRIVIAL with a "nothing to migrate" note (cluster/node upgrades are out of scope, not counted as migration). This also applies when the only controller present is a healthy migration-target controller (e.g. AWS LB Controller) with nothing bound to migrate and it is not CVE/EOL-affected — a reachable vulnerable controller is a security finding even at zero routes, so do not short-circuit it (see references/report-generation.md §1.0-A). Orphaned Ingress objects with no controller = dead config = 0 with a loud "Migration Crew Alert" note (headline is 100 / TRIVIAL only if there are no other live findings). See references/report-generation.md §1.0.
• Presence vs. absence. Absent controller = 0 (non-event). Present-but-broken (CrashLoopBackOff/unreachable) with zero bound routes = 1 tech-debt deduction + mandatory cleanup note; with bound routes = suspected active outage, flagged urgently outside the 0–100 score. Neither replaces the migration-difficulty of that controller's config (its routes remain migratable). Verify "no traffic" by read-only evidence (all nginx replicas down; ALB/target-group state for the LBC) — if you cannot verify, treat the estate as live.
• Deduction model, no artificial cap. Start at 100, subtract weighted points per finding (Impact 5→10, 4→6, 3→4, 2→2, 1→1, non-event 0), cap per category, score = max(0, 100 − Σ). The score is never locked at a ceiling — a single hard route no longer flattens it.
• Re-architecture Gate (separate, informational): routes and non-route conditions needing redesign/approval — routes (Lua/snippet/mirror, TLS passthrough/mTLS, cross-namespace ownership, plus any Tier-B feature escalated to Tier-A — e.g. CORS, or Basic-Auth→OIDC with non-interactive callers, on a closed/unmodifiable backend) plus conditions (no-rollback cutover, EOL/CVE control-plane exposure, Auto Mode LB ownership race) — are reported as a ⛔ N blocker(s) need(s) redesign / approval badge next to the score (a blocker is any such route or condition); they do not overwrite the number. Score = "how much work?"; gate = "does anything need a redesign decision?".
• Clean routes count at 0 effort: an Ingress already on the ALB controller, Gateway API, or a supported 3rd-party controller contributes 0 and is excluded from the Volume work-count, so "X of N already done" is visible and lifts the score.
• Feature-gap is tiered: features with no native ALB annotation but a standard workaround — CORS (app middleware), IP allowlist (Security Group / WAF), rate-limit (WAF), Basic Auth → OIDC (app-level credential validation) — are Impact 2 (performance/hardening) or 3 (business-logic-entangled) while that workaround can be applied. They escalate to Tier-A (4–5) only when the workaround cannot be applied — the backend is a closed third-party/SaaS app you cannot modify (no app-layer shim) and no platform layer replicates it — and the loss degrades a live business flow; for Basic Auth → OIDC escalation additionally requires non-interactive callers. No-workaround features (Lua/snippet/mirror/regex-capture) score heavy by default. See report-generation.md §1.3 for the rule.
• Bands: 90–100 TRIVIAL · 80–89 EASY · 70–79 MODERATE · 60–69 HARD · 0–59 VERY HARD.
• The score is derived from the findings, not a separate judgement — it never overrides the team's choice of migration path. Full deterministic algorithm, category weights, gate logic, tiering rules, and the mandatory Score Breakdown table live in references/report-generation.md Step 1.

Report Output

All files go to ~/ingress_migration/ organized by cluster:

~/ingress_migration/
├── <cluster>/
│   ├── report.md                    # Detailed markdown report
│   ├── topology.json                # Topology data for 3D view
│   └── manifests/
│       ├── current/                 # Existing Ingress YAML (backup)
│       │   └── <ns>-<ingress>.yaml
│       └── target/
│           ├── gateway-api/         # Gateway API resources (apply order)
│           │   ├── 00-gateway-api-crds.yaml
│           │   ├── 01-gatewayclass.yaml
│           │   ├── 02-gateway.yaml
│           │   └── 03-httproute-<name>.yaml
│           └── alb/                 # ALB Controller Ingress (converted)
│               └── <ns>-<ingress>.yaml
└── EKS-Ingress-Migration-<YYYY-MM-DD>-<HHMM>.html  # Combined HTML (all clusters)

The single HTML report contains all clusters with a dropdown selector in the left nav. Switching clusters swaps the content and 3D routing diagram. The References section includes an Export Materials topic with download buttons for Gateway API and ALB Controller manifests.

CLI usage:

# Single cluster
python3 tools/report_to_html.py ~/ingress_migration/<cluster>/report.md \
  --topology ~/ingress_migration/<cluster>/topology.json \
  --manifests ~/ingress_migration/<cluster>/manifests/

# Multiple clusters — one HTML with dropdown
python3 tools/report_to_html.py \
  ~/ingress_migration/cluster-a/report.md ~/ingress_migration/cluster-b/report.md \
  --topology ~/ingress_migration/cluster-a/topology.json ~/ingress_migration/cluster-b/topology.json \
  --manifests ~/ingress_migration/cluster-a/manifests ~/ingress_migration/cluster-b/manifests \
  -o ~/ingress_migration/EKS-Ingress-Migration-<YYYY-MM-DD>-<HHMM>.html