Design EKS

EKS Branch Logic

When the compute target preference indicates EKS:

1. For EACH formation resource in the inventory:

   • If config.process_type == "release", skip it and add the same run-once deployment-hook warning used by the EB/Fargate mapping. Do NOT create an EKS Deployment for release commands.
   • Look up dyno type in the eks-pod-sizing.json knowledge (rows.<dyno_type>), matching config.dyno_type case-insensitively.

     • If NOT found: Reject this formation entry. Add to warnings[]:

       “Unsupported dyno type: {dyno_type}. Cannot map to EKS. Please contact support or provide manual sizing.”

       Do NOT produce an EKS mapping for this formation, and do NOT count it toward total_pods for node-group sizing. Continue to the next resource.

     • If found: Extract req_cpu, req_mem, lim_cpu, lim_mem, and the node type per the CPU architecture resolution.

   • Produce an EKS Deployment entry with pod resource requests and limits
   • Set aws_service: "EKS"
   • Preserve dyno quantity as replicas (0–100)
   • If process type is web → include Kubernetes Service (type: LoadBalancer) with AWS LB Controller annotations
   • If process type is NOT web → Deployment only (no Service)

2. Produce single EKS cluster entry (constants from the eks-pod-sizing.json knowledge → its cluster block):

   • cluster_name: from cluster.cluster_name ("heroku-migration-cluster")
   • kubernetes_version: query the latest EKS-supported stable version at generation time (aws eks describe-addon-versions); if the query is unavailable, fall back to cluster.kubernetes_version_fallback. Do not hardcode — EKS deprecates older versions on a rolling basis.
   • Node group type: from cluster.node_group_type_by_pref keyed on the preference (eks-managed → self-managed, more control; eks-or-ecs → managed, less operational burden)
   • Addons: from cluster.addons

3. Node group sizing:

   • Determine the largest dyno type present across all formations.
   • Select instance type using the largest-pod-class-wins rule: use the recommended node_type (or node_type_arm64 when preferences.workshop.cpu_architecture is arm64 and that column exists — see design-mapping.md CPU architecture resolution) for the largest dyno present, ranked by the JSON’s node_size_rank (higher = larger). On a rank tie between m6i.4xlarge and r6i.4xlarge (or their m6g/r6g arm counterparts), prefer the general-purpose family unless a RAM-optimized dyno (*-l-ram) is the only dyno at that rank. All pods from smaller classes fit on those nodes with room to spare.
   • Calculate node count:
     • min_size = 2 (HA)
     • desired_size = max(min_size, ceil(total_pods / 4)) — clamp UP to min_size; AWS rejects desired_size < min_size, which would otherwise happen for small workloads (total_pods <= 4).
     • max_size = desired_size + 2
   • System overhead per node: from the JSON’s system_overhead_per_node (500m CPU, 512Mi memory).

4. Non-formation resources unchanged:

   • Postgres → RDS/Aurora (existing path)
   • Redis → ElastiCache (existing path)
   • Kafka → MSK (existing path)
   • Add-ons → Fast-Path Table (existing path)

All-or-Nothing Rule

When EKS is selected, ALL formation-type resources map to EKS. No mixing of Fargate and EKS for formations within the same migration. This avoids operational complexity of two container orchestrators.

EKS Service Entry in aws-design.json

EKS Cluster Entry in aws-design.json

Error Handling

• Unrecognized dyno type: Same rejection as the Fargate path — reject that formation, warn naming the unsupported type, and continue (see EKS Branch Logic step 1)
• Empty Procfile: Same rejection as Fargate path — at least one process type required
• Node sizing overflow: If no single instance type fits the aggregate, use the largest recommended type and increase node count