Amazon Elastic Kubernetes Service (EKS) is a fully managed Kubernetes service provided by AWS. It removes the operational overhead of running Kubernetes by managing the control plane for you — including upgrades, patching, and high availability.
This repository is an end-to-end deployment guide for running the classic 2048 puzzle game as a containerized workload on Amazon EKS using AWS Fargate and an Application Load Balancer (ALB). It covers everything from tool setup to cluster creation to live deployment.
2048-eks-deployment/
│
├── README.md ← You are here — project overview & theory
│
├── prerequisites.md ← Step 1: Install required CLI tools
├── installing-eks.md ← Step 2: Create the EKS cluster with Fargate
├── configure-oidc-connector.md ← Step 3: Enable IAM OIDC for the cluster
├── alb-controller-add-on.md ← Step 4: Install the AWS Load Balancer Controller
├── sample-app.md ← Step 5: Deploy a sample Nginx app (optional)
├── 2048-app-deploy-ingress.md ← Step 6: Deploy the 2048 game with ALB Ingress
│
└── assets/
└── 2048-apps.png ← Application screenshot
📘 Reading Order: Follow the numbered steps above in sequence for the smoothest experience. Each guide links to the next.
The diagram below shows how a user request flows from the browser through AWS infrastructure to reach the 2048 game pods running inside EKS on Fargate.
┌────────────────────────────────────────────────────────────────┐
│ AWS Cloud │
│ │
┌──────────┐ HTTPS │ ┌────────────┐ ┌──────────────────────────────────────┐ │
│ 👤 User │ ──────────► │ │ ALB │────►│ EKS Cluster │ │
│ Browser │ │ │ (internet- │ │ ┌──────────┐ ┌───────────────┐ │ │
└──────────┘ │ │ facing) │ │ │ Ingress │───►│ Service │ │ │
│ └────────────┘ │ └──────────┘ └──────┬────────┘ │ │
│ │ │ │ │
│ │ Fargate (game-2048) │ │ │
│ │ ┌──────┐ ┌──────┐ │ │ │
│ │ │🎮 P1 │ │🎮 P2 │◄──────┘ │ │
│ │ └──────┘ └──────┘ │ │
│ └──────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
💻 Developer (eksctl / kubectl / AWS CLI) ──manages──► EKS Cluster
flowchart TD
User(["👤 User / Browser"])
subgraph AWS ["☁️ AWS Cloud"]
ALB["🌐 Application Load Balancer"]
subgraph EKS ["🐳 Amazon EKS Cluster — demo-cluster"]
Ingress["📋 Kubernetes Ingress"]
Service["🔗 Kubernetes Service"]
subgraph Fargate ["⚡ AWS Fargate — game-2048 namespace"]
P1["🎮 2048 Pod 1"]
P2["🎮 2048 Pod 2"]
end
end
end
User -->|"HTTP request"| ALB
ALB -->|"Routes traffic"| Ingress
Ingress -->|"Forwards to"| Service
Service --> P1
Service --> P2
| Step | Guide | What Gets Configured |
|---|---|---|
| 1 | Prerequisites | Install kubectl, eksctl, AWS CLI on local machine |
| 2 | Installing EKS | Create demo-cluster EKS cluster with --fargate flag |
| 3 | Configure OIDC | Associate IAM OIDC provider — enables pods to use IAM roles |
| 4 | ALB Controller | Create IAM policy + role, install ALB Controller via Helm |
| 5 | Fargate Profile | Create alb-sample-app profile for game-2048 namespace |
| 6 | Deploy 2048 | kubectl apply the manifest — creates Deployment, Service, Ingress → ALB auto-provisioned |
| # | Component | Action |
|---|---|---|
| 1 | User | Opens ALB hostname in browser over HTTP |
| 2 | ALB | Receives request, matches Ingress routing rules |
| 3 | Ingress | Forwards traffic to the ClusterIP Service |
| 4 | Service | Load-balances across the 2 Fargate pods |
| 5 | 2048 Pod | Serves the game UI back to the user |
| Component | Configured In | Role |
|---|---|---|
| Amazon EKS | installing-eks.md |
Managed Kubernetes control plane |
| AWS Fargate | installing-eks.md |
Serverless compute — no EC2 nodes needed |
| IAM OIDC Provider | configure-oidc-connector.md |
Lets pods/controllers assume IAM roles securely |
| IAM Policy + Role | alb-controller-add-on.md |
Grants ALB Controller permission to manage AWS load balancers |
| ALB Controller (Helm) | alb-controller-add-on.md |
Watches Ingress resources and provisions the ALB automatically |
| Fargate Profile | 2048-app-deploy-ingress.md |
Routes game-2048 namespace pods to Fargate compute |
| Kubernetes Deployment | 2048-app-deploy-ingress.md |
Runs 2 replicas of the 2048 game container |
| Kubernetes Service | 2048-app-deploy-ingress.md |
Exposes pods internally within the cluster |
| Kubernetes Ingress | 2048-app-deploy-ingress.md |
Triggers ALB provisioning and routes external traffic |
| Application Load Balancer | Auto-provisioned by ALB Controller | Internet-facing entry point for the 2048 game |
Legend:
- Solid arrows (
→) — Live request traffic flow - Dashed arrows (
-.->) — Configuration, setup, and management actions
Follow these 6 steps in order to go from zero to a live 2048 game on EKS:
| Step | Guide | Description | ⏱️ Est. Time |
|---|---|---|---|
| 1 | 📋 Prerequisites | Install kubectl, eksctl, and AWS CLI |
5–10 min |
| 2 | 🛠️ Install EKS | Create the EKS cluster using Fargate | 10–15 min |
| 3 | 🔐 Configure OIDC | Associate an IAM OIDC provider with the cluster | 2–3 min |
| 4 | ⚖️ ALB Controller | Install the AWS Load Balancer Controller add-on | 5–8 min |
| 5 | 📦 Sample App | (Optional) Deploy a sample Nginx app to verify the setup | 3–5 min |
| 6 | 🎮 Deploy 2048 | Deploy the 2048 game with Fargate profile and ALB Ingress | 5–10 min |
🕐 Total estimated time: ~30–50 minutes for a complete end-to-end deployment (excluding tool download time).
Running this demo project incurs real AWS charges. The table below provides a rough estimate for the us-east-1 region based on AWS pricing as of 2026. Always check the AWS Pricing Calculator for the most current rates.
| AWS Service | Component | Approx. Cost |
|---|---|---|
| Amazon EKS | Cluster control plane | ~$0.10 / hour |
| AWS Fargate | vCPU (per pod) | ~$0.04048 / vCPU-hour |
| AWS Fargate | Memory (per pod) | ~$0.004445 / GB-hour |
| Application Load Balancer | ALB provisioning | ~$0.008 / hour + $0.008 / LCU-hour |
| Amazon VPC | NAT Gateway (if used) | ~$0.045 / hour + $0.045 / GB |
| Amazon ECR | Storage + data transfer | ~$0.10 / GB-month (storage) |
| Scenario | Duration | Approx. Cost |
|---|---|---|
| Quick test run | 1–2 hours | < $0.50 |
| Half-day session | ~4 hours | $1.00 – $2.00 |
| Full-day session | ~8 hours | $2.00 – $4.00 |
| Forgotten overnight | ~24 hours | $5.00 – $10.00 |
⚠️ Important: The 2048 demo uses 3 Fargate pods, each requiring minimal CPU and memory. The EKS cluster fee ($0.10/hr) and ALB fee are the primary cost drivers — not the Fargate pods themselves.
- Always delete the cluster when done — the EKS control plane charges $0.10/hour regardless of workloads running.
eksctl delete cluster --name demo-cluster --region us-east-1
- Set a billing alarm — go to AWS Billing → Budgets → Create Budget to get notified if spending exceeds a threshold.
- Use AWS Free Tier — new AWS accounts get some free usage, but EKS and Fargate are not covered under the free tier.
- Check your AWS Cost Explorer — navigate to AWS Console → Cost Explorer to see a real-time breakdown of charges by service.
Choosing between EKS and a self-managed Kubernetes setup is an important architectural decision. The table below summarizes the key trade-offs.
| Feature | Details |
|---|---|
| Managed Control Plane | AWS manages the Kubernetes API server, controller manager, and etcd — including upgrades and high availability. |
| Automated Updates | Kubernetes versions are automatically updated, keeping clusters current with security patches and features. |
| Scalability | EKS auto-scales the control plane to meet workload demands without manual intervention. |
| AWS Integration | Seamlessly integrates with IAM, VPC, Elastic Load Balancers, CloudWatch, ECR, and more. |
| Security & Compliance | Built to meet various security standards and compliance requirements out-of-the-box. |
| Monitoring & Logging | Native integration with Amazon CloudWatch for cluster health metrics and operational visibility. |
| Ecosystem Support | Benefits from the broader Kubernetes open-source community alongside AWS-specific improvements. |
| Cons | Impact |
|---|---|
| 💸 Higher Cost | EKS charges ~$0.10/hour for the managed control plane, which adds up at scale compared to self-managed clusters. |
| 🔒 Less Granular Control | Some Kubernetes configurations and underlying infrastructure settings are abstracted away by AWS. |
| Feature | Details |
|---|---|
| Cost-Effective | Leverage EC2 Spot and Reserved Instances to reduce overall cluster costs. |
| Full Flexibility | Complete control over cluster configuration, networking, and infrastructure customization. |
| AWS-Compatible | Can still integrate with core AWS services like IAM, VPC, S3, and ELB. |
| Experimental Features | Use the latest Kubernetes releases before they are officially supported by EKS. |
| Cons | Impact |
|---|---|
| ⚙️ Complexity | Manual setup and management can be time-consuming, especially for those new to Kubernetes or AWS. |
| 🔧 Maintenance Overhead | You are responsible for control plane upgrades, patches, and ensuring high availability. |
| 📈 Scaling Challenges | Scaling the control plane requires careful planning and manual effort. |
| 🛡️ Security Responsibility | Additional effort is required to implement and maintain security best practices. |
| More manual scripting and intervention increases operational risk compared to a managed service. |
This section covers everything you need to prepare your AWS account and local environment before creating an EKS cluster.
Creating an AWS account is the first step to access Amazon EKS and all related AWS services.
Step 1 — Create an AWS Account:
- Go to https://aws.amazon.com/ and click "Create an AWS Account".
- Provide your email address, choose a password, and fill in the required account details.
- Enter your payment information to verify your identity and configure billing.
Step 2 — Access the AWS Management Console:
- After registration, check your email for a verification link and confirm your account.
- Log in to the AWS Management Console using your credentials.
Step 3 — Enable Multi-Factor Authentication (MFA) (Recommended):
- Navigate to IAM → Security Credentials → Assign MFA Device.
- Use a virtual MFA app (e.g., Google Authenticator) or a hardware MFA device for added security.
Step 4 — Create IAM Users:
- Open the IAM service in the AWS Management Console.
- Click Users in the left navigation pane, then click "Add users".
- Enter a username and select the access type:
- Programmatic Access — For CLI/API usage (generates Access Keys).
- AWS Management Console Access — For web console login.
- Assign permissions by adding the user to an IAM group or attaching policies directly.
- Optionally configure a permissions boundary and add tags. (A permissions boundary limits the maximum permissions a user can have — useful in shared AWS accounts.)
Step 5 — Save Access Keys (for Programmatic Access):
- After user creation, securely save the Access Key ID and Secret Access Key.
⚠️ Warning: These keys are shown only once. Store them in a secure location (e.g., AWS Secrets Manager or a password manager).
Once IAM users are created, configure your local machine to interact with AWS services and EKS clusters.
Step 1 — Install the AWS CLI:
- Follow the official AWS documentation for your operating system: 👉 AWS CLI Installation Guide
Step 2 — Configure AWS CLI Credentials:
Open a terminal or command prompt and run:
aws configureYou will be prompted to enter:
- AWS Access Key ID — From the IAM user created earlier.
- AWS Secret Access Key — From the IAM user created earlier.
- Default region name — e.g.,
us-east-1 - Default output format — e.g.,
json
Step 3 — Install kubectl:
- Download and install
kubectlon your local machine: 👉 kubectl Installation Guide
Step 4 — Configure kubectl for EKS:
Once kubectl is installed, connect it to your EKS cluster using the AWS CLI:
aws eks update-kubeconfig --name demo-clusterReplace demo-cluster if you chose a different cluster name. This updates your ~/.kube/config file automatically.
Step 5 — Verify the Connection:
Confirm that kubectl can communicate with your EKS cluster:
kubectl get nodesA list of your cluster nodes indicates a successful setup.
Before launching an EKS cluster, configure the networking infrastructure to ensure secure and reliable communication within the cluster.
- In the AWS Management Console, navigate to the VPC service.
- Click "Create VPC" and provide:
- VPC name — A descriptive name for your VPC.
- IPv4 CIDR block — e.g.,
10.0.0.0/16
- Create public subnets (for load balancers) and private subnets (for worker nodes) across multiple Availability Zones.
Security Groups act as virtual firewalls, controlling inbound and outbound traffic to your EKS resources.
Step 1 — Create a Security Group:
- Navigate to VPC → Security Groups in the AWS Management Console.
- Click "Create Security Group".
- Provide a name, description, and select the appropriate VPC.
Step 2 — Define Inbound Rules:
- By default, all inbound traffic is denied.
- Add rules to allow required traffic, for example:
- SSH (port 22) — For administrative access.
- Custom TCP — For specific application ports.
- Traffic from specific CIDR blocks or other Security Groups.
Step 3 — Define Outbound Rules:
- By default, all outbound traffic is allowed.
- For stricter security, restrict outbound traffic to only necessary destinations or ports.
Step 4 — Note the Security Group ID:
- After creation, record the Security Group ID. You will use this when launching EKS worker nodes.
Step 5 — Attach Security Group to EKS Worker Nodes:
- When launching worker nodes, specify the Security Group ID in the launch configuration to enforce the defined traffic rules.
An Internet Gateway enables communication between your VPC and the internet — required for worker nodes to pull container images from external registries.
Step 1 — Create an Internet Gateway:
- Navigate to VPC → Internet Gateways in the AWS Management Console.
- Click "Create Internet Gateway", provide a name, and confirm.
Step 2 — Attach the IGW to Your VPC:
- Select the newly created Internet Gateway.
- Click "Attach to VPC" and select your EKS VPC.
Step 3 — Update Route Tables:
- Navigate to VPC → Route Tables.
- Select the Route Table associated with your public subnets.
- Add a new route:
- Destination:
0.0.0.0/0 - Target: The Internet Gateway ID
- Destination:
This allows public subnet resources to communicate with the internet.
IAM Policies define the permissions granted to your EKS worker nodes and other AWS resources.
Step 1 — Create a Custom IAM Policy:
- Navigate to IAM → Policies in the AWS Management Console.
- Click "Create policy" and choose JSON as the policy language.
- Define the required permissions for your cluster. Common permissions include:
- EC2 instance management
- Auto Scaling operations
- Elastic Load Balancing
- Access to ECR (Elastic Container Registry)
Step 2 — Attach the IAM Policy to an IAM Role:
- Navigate to IAM → Roles and select the role your EKS worker nodes will assume.
- Click "Attach policies", find the custom policy created above, and attach it.
Step 3 — Specify the IAM Role for Worker Nodes:
- When launching EKS worker nodes, provide the IAM Role ARN in the launch configuration.
- This allows worker nodes to authenticate with the EKS cluster and access permitted AWS resources.
✅ Result: Your AWS environment is now fully prepared. Continue with the deployment guides below.
This project uses eksctl and AWS Fargate to create and manage the EKS cluster. The dedicated guides cover all the required steps:
| Guide | What It Covers |
|---|---|
| 📋 Prerequisites | Install kubectl, eksctl, and AWS CLI with verification steps |
| 🛠️ Installing EKS | Create a Fargate-backed EKS cluster with a single eksctl command |
| 🔐 Configure OIDC Connector | Associate the IAM OIDC provider — required for the ALB Controller add-on |
💡 Tip: The cluster name used throughout this project is
demo-clusterin regionus-east-1. Adjust these values to match your environment.
Once the cluster is running, the following guides walk you through deploying workloads:
| Guide | What It Covers |
|---|---|
| ⚖️ ALB Controller Add-On | Create IAM role, install Helm chart for the AWS Load Balancer Controller |
| 📦 Sample App | (Optional) Deploy an Nginx Deployment + Service to validate the cluster |
| 🎮 Deploy 2048 App | Create Fargate profile, deploy the 2048 game with Ingress and ALB |
Once deployed, open the ALB hostname in your browser to play the 2048 game:
kubectl get ingress -n game-2048 -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}'
The 2048 puzzle game running as a containerized workload on Amazon EKS with Fargate.
| Resource | Link |
|---|---|
| AWS EKS Documentation | docs.aws.amazon.com/eks |
| Kubernetes Official Docs | kubernetes.io/docs |
| AWS CLI Reference | docs.aws.amazon.com/cli |
| kubectl Reference | kubernetes.io/docs/reference/kubectl |
| eksctl (Cluster Tool) | eksctl.io |
| AWS Fargate for EKS | docs.aws.amazon.com/eks/fargate |
| AWS IAM Best Practices | IAM Best Practices Guide |
| ALB Controller Docs | kubernetes-sigs.github.io |
This section covers the most common errors encountered when setting up EKS, the ALB Controller, and deploying the 2048 application — along with their root causes and fixes.
Symptom:
Error: No IAM OIDC provider found for cluster "demo-cluster"
Root Cause: The IAM OIDC provider was not associated with the cluster before installing the ALB Controller or other IAM-dependent add-ons.
Fix:
# Step 1 — Set your cluster name
export cluster_name=demo-cluster
# Step 2 — Retrieve the OIDC issuer ID
oidc_id=$(aws eks describe-cluster --name $cluster_name \
--query "cluster.identity.oidc.issuer" \
--output text | cut -d '/' -f 5)
# Step 3 — Check if OIDC provider already exists
aws iam list-open-id-connect-providers | grep $oidc_id
# Step 4 — If not found, associate it now
eksctl utils associate-iam-oidc-provider --cluster $cluster_name --approve📘 Reference: Configure OIDC Connector Guide
Symptom: The Ingress resource is created but the ADDRESS field remains blank after several minutes:
kubectl get ingress -n game-2048
# NAME CLASS HOSTS ADDRESS PORTS AGE
# ingress alb * 80 10mRoot Cause: Usually caused by one of: (a) ALB Controller not running, (b) missing IAM permissions, (c) incorrect VPC/subnet tags.
Fix — Step 1: Verify the ALB Controller pods are running:
kubectl get deployment -n kube-system aws-load-balancer-controllerBoth replicas must show READY 2/2. If not, check pod logs:
kubectl logs -n kube-system \
-l app.kubernetes.io/name=aws-load-balancer-controllerFix — Step 2: Verify your subnets have the correct discovery tags. Public subnets require:
Key: kubernetes.io/role/elb
Value: 1
Private subnets require:
Key: kubernetes.io/role/internal-elb
Value: 1
Add these tags via the AWS VPC Console → Subnets.
Fix — Step 3: Ensure the cluster name in the Helm install matches your actual cluster:
helm get values aws-load-balancer-controller -n kube-system📘 Reference: ALB Controller Add-On Guide
Symptom:
kubectl get pods -n game-2048
# NAME READY STATUS RESTARTS AGE
# 2048-xxxx-yyyy 0/1 Pending 0 5mRoot Cause: Fargate cannot schedule the pod — usually due to a missing or misconfigured Fargate profile, or the pod's namespace/labels not matching the profile's selectors.
Fix — Step 1: Describe the pod to see the scheduling error:
kubectl describe pod <pod-name> -n game-2048Look for Events: at the bottom — it will indicate the reason.
Fix — Step 2: Verify the Fargate profile exists and covers the game-2048 namespace:
eksctl get fargateprofile --cluster demo-clusterIf missing, recreate it:
eksctl create fargateprofile \
--cluster demo-cluster \
--region us-east-1 \
--name alb-sample-app \
--namespace game-2048Fix — Step 3: Confirm the pod's namespace matches the Fargate profile namespace exactly:
kubectl get pod <pod-name> -n game-2048 -o jsonpath='{.metadata.namespace}'Symptom:
kubectl get pods -n game-2048
# NAME READY STATUS RESTARTS AGE
# 2048-xxxx 0/1 ImagePullBackOff 0 2mRoot Cause: The Fargate pod cannot pull the container image — either the image URL is wrong, the image doesn't exist, or ECR permissions are missing.
Fix — Step 1: Check the exact error:
kubectl describe pod <pod-name> -n game-2048Fix — Step 2: Verify the IAM role attached to the Fargate profile has ECR read permissions. The role must include the policy AmazonEC2ContainerRegistryReadOnly:
aws iam list-attached-role-policies \
--role-name <fargate-pod-execution-role-name>Fix — Step 3: If using a public image (like the 2048 manifest), ensure the cluster has outbound internet access via the Internet Gateway and Route Tables.
Symptom:
The connection to the server was refused — did you specify the right host or port?
or
error: You must be logged in to the server (Unauthorized)
Root Cause: The kubeconfig file is missing, expired, or pointing to the wrong cluster/region.
Fix — Step 1: Re-run the kubeconfig update command:
aws eks update-kubeconfig --name demo-cluster --region us-east-1Fix — Step 2: Verify the correct context is active:
kubectl config current-contextFix — Step 3: Test connectivity:
kubectl get nodesFix — Step 4: If you receive Unauthorized, confirm your AWS CLI is using credentials for an IAM user/role that has access to the cluster:
aws sts get-caller-identitySymptom:
Waiting for CloudFormation stack... (timeout)
or the command exits with a non-zero error code.
Root Cause: CloudFormation stack rollback — often caused by insufficient IAM permissions for the user running eksctl, or a service quota limit being reached.
Fix — Step 1: Check the CloudFormation events in the AWS Console:
- Navigate to CloudFormation → Stacks → find the
eksctl-demo-cluster-*stack → click Events tab. - Look for
ROLLBACK_IN_PROGRESSorCREATE_FAILEDentries with the specific error message.
Fix — Step 2: Ensure the IAM user running eksctl has sufficient permissions. For testing, the AdministratorAccess policy can be used. For production, scope it down using the eksctl IAM permissions reference.
Fix — Step 3: Check AWS service quotas (e.g., VPC limit, EIP limit) in the Service Quotas Console.
Fix — Step 4: Delete any failed stacks and retry:
# Delete any partial resources
eksctl delete cluster --name demo-cluster --region us-east-1
# Retry creation
eksctl create cluster --name demo-cluster --region us-east-1 --fargate💬 Still stuck? Open an issue in this repository or consult the AWS EKS Troubleshooting Guide.
Contributions, corrections, and suggestions are welcome! Please open an issue or submit a pull request with your proposed changes.
Last updated: June 2026