EKS Mini Platform

A lightweight, production-minded AWS EKS platform demonstrating end-to-end infrastructure automation — from VPC provisioning with Terraform to containerized service deployment with Kubernetes and a fully automated CI/CD pipeline via GitHub Actions.

---

What This Project Demonstrates

This project covers the full lifecycle of a cloud-native service deployment on AWS:

• Infrastructure as Code — VPC, EKS cluster, managed node group, and ECR repository provisioned with Terraform modules
• Container best practices — non-root user, slim base image, immutable SHA-tagged releases
• Kubernetes reliability patterns — liveness/readiness probes, resource requests/limits, HPA with CPU-based autoscaling
• AWS-native networking — ALB via the AWS Load Balancer Controller, with correct subnet tagging for ELB discovery
• Observability — Prometheus-compatible /metrics endpoint exposed by the application
• CI/CD pipeline — GitHub Actions builds, tags, pushes to ECR, and verifies a rolling deployment on every push to main

---

Architecture

Traffic flow: Internet → AWS ALB (provisioned by ALB Ingress Controller) → Kubernetes Service (ClusterIP) → FastAPI pods in the dev namespace → ECR image pulled at deploy time.

The VPC spans 2 availability zones with public and private subnets. Pods run in private subnets; the NAT Gateway provides outbound internet access for ECR pulls.

---

Project Structure

.
├── app/
│   ├── main.py           # FastAPI service with /healthz, /readyz, /metrics
│   ├── Dockerfile        # Production image — non-root user, slim base
│   └── requirements.txt
├── k8s/
│   ├── namespace.yaml    # Dedicated 'dev' namespace
│   ├── deployment.yaml   # 2 replicas, probes, resource limits
│   ├── service.yaml      # ClusterIP service
│   ├── ingress.yaml      # ALB Ingress (internet-facing, IP target mode)
│   └── hpa.yaml          # HPA: scale 2→6 pods at 60% CPU
├── terraform/
│   ├── 00-providers.tf
│   ├── 00-variables.tf
│   ├── 10-vpc.tf         # VPC, subnets, NAT Gateway, ELB subnet tags
│   ├── 20-ecr.tf         # ECR repository
│   ├── 30-eks.tf         # EKS cluster, managed node group, addons
│   └── 40-outputs.tf
└── .github/
    └── workflows/
        └── deploy.yml    # Build → Push → Deploy → Verify

---

Production-Ready Practices

Practice	Implementation
Non-root container	Dockerfile creates and runs as a dedicated app system user
Immutable image tags	Every release is tagged with the 7-char git SHA
Health checks	Separate /healthz (liveness) and /readyz (readiness) endpoints
Resource budgets	CPU/memory requests and limits defined on every pod
Autoscaling	HPA scales 2→6 replicas at 60% average CPU utilization
Subnet tagging	VPC subnets tagged with kubernetes.io/role/elb for ALB discovery
Observability	/metrics exposes Prometheus-format counters (http_requests_total)
Rollout safety	CI pipeline gates on kubectl rollout status before completing

---

Proof of Deployment

EKS Console — Deployment and Pods

Kubernetes Resources

Load Testing — HPA Scaling Validation

The API response includes the pod hostname, making it easy to confirm that HPA has scaled up and requests are being distributed across multiple replicas.

---

CI/CD Pipeline

On every push to main, GitHub Actions runs a single deploy job:

1. Build — Docker image built from ./app
2. Tag — Image tagged with the 7-char git SHA (immutable, traceable)
3. Push — Image pushed to Amazon ECR
4. Deploy — kubectl set image performs a rolling update
5. Verify — kubectl rollout status blocks until all pods are healthy; fails the pipeline if the rollout stalls

AWS credentials and cluster details are stored as GitHub Secrets (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, EKS_CLUSTER_NAME, ECR_REPO).

---

Local Development

docker build -t api:local ./app
docker run --rm -p 8000:8000 api:local
curl localhost:8000/healthz
curl localhost:8000/metrics

---

Infrastructure Provisioning

cd terraform
terraform init
terraform apply

Provisions:

• VPC across 2 AZs (public + private subnets, single NAT Gateway)
• EKS 1.35 cluster with managed node group (t3.small)
• Core addons: vpc-cni, kube-proxy, coredns (installed before node group)
• ECR repository

---

Application Deployment

kubectl apply -f k8s/

The ALB Ingress Controller automatically provisions an internet-facing Application Load Balancer and wires it to the service.

---

Cleanup

EKS and NAT Gateway incur AWS costs. Destroy all resources when finished:

cd terraform
terraform destroy

---

Notes

• Scoped as a minimal but production-oriented platform demonstrating infrastructure automation, container lifecycle, and Kubernetes reliability patterns.
• A full observability stack (Prometheus + Grafana scraping the /metrics endpoint) is the planned V2 addition.