Deploying a Fullstack App on EKS

[Browser]
   |
   | HTTPS (Route 53 + ACM)
   v
[ALB] -- AWS Load Balancer Controller
   |
   |-- /          -> [Next.js Pod x N] (SSR + RSC + Server Actions)
   `-- /api/*     -> [FastAPI Pod x M] (REST + Pydantic v2)
                          |
                          | PgBouncer
                          v
                       [RDS PostgreSQL] (Multi-AZ)
                          ^
                          |
                       [External Secrets] <- [AWS Secrets Manager]
                          ^
                          | IRSA
                       [ServiceAccount]

# ADR-0001: The K8s deployment architecture of the fullstack todo system

## Context
The todo system of Next.js (App Router + RSC) + FastAPI + PostgreSQL
must be deployed to a production environment.

## Options
1. ECS Fargate (managed containers)
2. EKS (Kubernetes)
3. Lambda + RDS (serverless)

## Decision
Adopt EKS.

## Rationale
- the two apps (Next.js + FastAPI) have different lifecycles and need isolation
- the autoscaling model of HPA · Karpenter fits the traffic pattern
- GitOps (ArgoCD) matches the operational standard model
- comprehensive validation of the tools from Chapters 1 ~ 30 of this book

## Consequences
- a cost hypothesis of $80 ~ $120 a month, to be verified with the Chapter 28 model
- application of the regular operations calendar cycle (Chapter 26)
- comparison with the ECS Fargate chapter of the AWS book

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  # ... as in Chapter 21
}

module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"

  cluster_name    = "todo-${var.env}"
  cluster_version = "1.32"
  enable_irsa     = true

  cluster_addons = {
    coredns            = { most_recent = true }
    kube-proxy         = { most_recent = true }
    vpc-cni            = { most_recent = true }
    aws-ebs-csi-driver = {
      most_recent              = true
      service_account_role_arn = module.ebs_csi_irsa.iam_role_arn
    }
  }

  # keep only the minimum number of ON_DEMAND nodes; Karpenter handles the rest on demand
  eks_managed_node_groups = {
    system = {
      desired_size   = 2
      min_size       = 2
      max_size       = 3
      instance_types = ["t3.medium"]
      capacity_type  = "ON_DEMAND"
      labels         = { role = "system" }
      taints = [{
        key    = "system"
        value  = "true"
        effect = "NO_SCHEDULE"
      }]
    }
  }
}

module "karpenter" {
  source = "terraform-aws-modules/eks/aws//modules/karpenter"
  cluster_name        = module.eks.cluster_name
  irsa_oidc_provider_arn = module.eks.oidc_provider_arn
}

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: default
spec:
  template:
    spec:
      requirements:
        - key: kubernetes.io/arch
          operator: In
          values: ["amd64", "arm64"]
        - key: karpenter.sh/capacity-type
          operator: In
          values: ["spot", "on-demand"]
        - key: karpenter.k8s.aws/instance-category
          operator: In
          values: ["t", "m", "c"]
        - key: karpenter.k8s.aws/instance-cpu
          operator: In
          values: ["2", "4", "8"]
      nodeClassRef:
        group: karpenter.k8s.aws
        kind: EC2NodeClass
        name: default
  disruption:
    consolidationPolicy: WhenEmptyOrUnderutilized
    consolidateAfter: 30s
    budgets:
      - nodes: "10%"
        duration: 10m
        schedule: "0 9 * * mon-fri"

helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
  -n kube-system --set clusterName=todo-prod --set serviceAccount.create=false

helm install external-dns external-dns/external-dns \
  -n external-dns --create-namespace \
  --set provider=aws --set "domainFilters[0]=todo.example.com"

helm install cert-manager jetstack/cert-manager \
  -n cert-manager --create-namespace --set installCRDs=true

---
apiVersion: v1
kind: Namespace
metadata:
  name: todo-frontend
  labels:
    team: web
    env: prod
    role: frontend
---
apiVersion: v1
kind: Namespace
metadata:
  name: todo-backend
  labels:
    team: backend
    env: prod
    role: backend
---
apiVersion: v1
kind: Namespace
metadata:
  name: todo-data
  labels:
    team: backend
    env: prod
    role: data

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: todo-backend-ingress
  namespace: todo-backend
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: todo-api
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              role: frontend
        - namespaceSelector:
            matchLabels:
              role: backend   # allow other workloads of the same backend too
      ports:
        - port: 8000

apiVersion: v1
kind: ResourceQuota
metadata:
  name: todo-backend-quota
  namespace: todo-backend
spec:
  hard:
    requests.cpu: "10"
    requests.memory: "20Gi"
    limits.cpu: "20"
    limits.memory: "40Gi"
    persistentvolumeclaims: "5"

module "rds" {
  source  = "terraform-aws-modules/rds/aws"
  version = "~> 6.0"

  identifier = "todo-${var.env}"

  engine               = "postgres"
  engine_version       = "16.3"
  major_engine_version = "16"
  instance_class       = var.env == "prod" ? "db.t4g.small" : "db.t4g.micro"

  allocated_storage             = 20
  manage_master_user_password   = true
  multi_az                      = var.env == "prod"
  backup_retention_period       = var.env == "prod" ? 30 : 7
  performance_insights_enabled  = true
  deletion_protection           = var.env == "prod"
}

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: todo-api-db
  namespace: todo-backend
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: aws-secrets-manager
    kind: ClusterSecretStore
  target:
    name: todo-api-db
    template:
      data:
        DATABASE_URL: "postgresql://{{ .username }}:{{ .password }}@pgbouncer.todo-backend.svc:5432/todo?sslmode=disable"
  data:
    - secretKey: username
      remoteRef:
        key: rds!cluster-todo-prod
        property: username
    - secretKey: password
      remoteRef:
        key: rds!cluster-todo-prod
        property: password

FROM python:3.13-slim AS builder
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen --no-dev

FROM python:3.13-slim AS runtime
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY src/ src/
ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8000
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

apiVersion: apps/v1
kind: Deployment
metadata:
  name: todo-api
  namespace: todo-backend
  labels:
    app.kubernetes.io/name: todo-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: todo-api
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app.kubernetes.io/name: todo-api
    spec:
      serviceAccountName: todo-api
      containers:
        - name: api
          image: 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/todo-api:1.0.0
          ports:
            - containerPort: 8000
              name: http
          envFrom:
            - secretRef:
                name: todo-api-db
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi
          readinessProbe:
            httpGet:
              path: /health/ready
              port: http
            initialDelaySeconds: 5
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /health/live
              port: http
            initialDelaySeconds: 30
            periodSeconds: 10
          lifecycle:
            preStop:
              exec:
                command: ["sh", "-c", "sleep 10"]
      terminationGracePeriodSeconds: 60

apiVersion: v1
kind: ServiceAccount
metadata:
  name: todo-api
  namespace: todo-backend
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/todo-prod-api
automountServiceAccountToken: false   # the security pattern from Chapter 16

[Browser]
   |
   | HTTPS
   v
[ALB]
   |
   v
[Next.js Pod]  -- Node.js server (next start)
   |
   | fetch on RSC rendering
   v
[todo-api Service]  -- ClusterIP, points at FastAPI
   |
   v
[todo-api Pod]

apiVersion: apps/v1
kind: Deployment
metadata:
  name: todo-web
  namespace: todo-frontend
spec:
  replicas: 2
  template:
    spec:
      serviceAccountName: todo-web
      containers:
        - name: web
          image: 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/todo-web:1.0.0
          ports:
            - containerPort: 3000
              name: http
          env:
            - name: TODO_API_URL
              value: "http://todo-api.todo-backend.svc.cluster.local:80"
            - name: NODE_ENV
              value: "production"
          resources:
            requests:
              cpu: 200m
              memory: 256Mi   # the memory hypothesis of SSR + RSC
            limits:
              cpu: 1
              memory: 512Mi

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: todo
  namespace: todo-frontend
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
    alb.ingress.kubernetes.io/ssl-redirect: '443'
    alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:...
    alb.ingress.kubernetes.io/group.name: todo
    external-dns.alpha.kubernetes.io/hostname: "todo.example.com,api.todo.example.com"
spec:
  rules:
    - host: todo.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: todo-web
                port:
                  number: 80
    - host: api.todo.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: todo-api.todo-backend
                port:
                  number: 80

charts/
├── todo-web/
│   ├── Chart.yaml
│   ├── values.yaml
│   ├── values-dev.yaml
│   ├── values-prod.yaml
│   └── templates/
│       ├── deployment.yaml
│       ├── service.yaml
│       ├── hpa.yaml
│       └── pdb.yaml
├── todo-api/
│   ├── Chart.yaml
│   ├── values.yaml
│   ├── values-dev.yaml
│   ├── values-prod.yaml
│   └── templates/
│       ├── deployment.yaml
│       ├── service.yaml
│       ├── serviceaccount.yaml
│       ├── externalsecret.yaml
│       ├── hpa.yaml
│       ├── pdb.yaml
│       └── servicemonitor.yaml
└── todo-infra/
    ├── Chart.yaml
    └── templates/
        ├── namespaces.yaml
        ├── networkpolicy.yaml
        ├── resourcequota.yaml
        └── ingress.yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: todo
  namespace: argocd
spec:
  generators:
    - matrix:
        generators:
          - list:
              elements:
                - app: todo-infra
                - app: todo-api
                - app: todo-web
          - list:
              elements:
                - env: dev
                  cluster: https://kubernetes.default.svc
                - env: prod
                  cluster: https://kubernetes.default.svc
  template:
    metadata:
      name: '{{`{{.app}}`}}-{{`{{.env}}`}}'
    spec:
      project: todo
      source:
        repoURL: https://github.com/myorg/todo-manifests.git
        targetRevision: main
        path: charts/{{`{{.app}}`}}
        helm:
          valueFiles:
            - values.yaml
            - values-{{`{{.env}}`}}.yaml
      destination:
        server: '{{`{{.cluster}}`}}'
        namespace: todo-{{`{{.app}}`}}
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: otel
  namespace: monitoring
spec:
  mode: daemonset
  config:
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    exporters:
      prometheus:
        endpoint: 0.0.0.0:8889
      otlp/tempo:
        endpoint: tempo.monitoring.svc:4317
    service:
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [otlp/tempo]
        metrics:
          receivers: [otlp]
          exporters: [prometheus]

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: todo-api
  namespace: todo-backend
  labels:
    release: prometheus
spec:
  groups:
    - name: todo-api.golden-signals
      rules:
        - alert: TodoApiHighErrorRate
          expr: |
            sum(rate(http_requests_total{app="todo-api",status=~"5.."}[5m]))
              / sum(rate(http_requests_total{app="todo-api"}[5m])) > 0.05
          for: 5m
          labels:
            severity: critical
        # ... latency, traffic, saturation are the same

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: todo-api
  namespace: todo-backend
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: todo-api
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 30
    scaleDown:
      stabilizationWindowSeconds: 300

traffic increase
   |
   v
HPA: in 30 seconds, todo-api Pod 2 -> 5 -> 10 -> 20
   |
   | the node runs short on resources
   v
Karpenter: in 30 seconds ~ 1 minute, provisions a new node (spot first)
   |
   v
the Pod that was Pending gets scheduled on the new node

import http from "k6/http";
import { check } from "k6";

export const options = {
  stages: [
    { duration: "2m", target: 50 },
    { duration: "5m", target: 200 },
    { duration: "2m", target: 500 },
    { duration: "5m", target: 500 },
    { duration: "2m", target: 0 },
  ],
};

export default function () {
  const res = http.get("https://todo.example.com/api/todos");
  check(res, {
    "status is 200": (r) => r.status === 200,
    "duration < 500ms": (r) => r.timings.duration < 500,
  });
}

k6 run k6/script.js

helm install opencost opencost/opencost \
  -n opencost --create-namespace

# The todo system operations calendar

## Daily
- check the 5 panels of the todo Grafana dashboard
- review the active alerts in Alertmanager

## Weekly
- ECR Trivy scan results (both todo-api, todo-web)
- review new security patches

## Monthly
- the top 1, 2, 3 costs by team / by workload in OpenCost
- the unreflected workloads of VPA recommendation
- check the OutOfSync state of ArgoCD

## Quarterly
- EKS minor upgrade (the 13 steps of Chapter 30)
- right-sizing signals from RDS Performance Insights
- RBAC audit
- recovery drill (PITR simulation)
- kube-bench CIS checkup

## Semi-annually
- external security audit
- DR simulation (Velero restore)

## Annually
- cluster architecture review
- manifest modernization

# 1. delete the ArgoCD Application (clean up the workloads)
kubectl delete applicationset todo -n argocd

# 2. release RDS deletion_protection then terraform destroy
# (for prod, deletion_protection is on, so set it to false via a terraform variable then apply)

# 3. confirm the automatic cleanup of ALB / Route 53
# external-dns auto-deletes the hostname's A records

# 4. terraform destroy
terraform destroy

# 5. delete the ECR repositories (image remnants)
aws ecr delete-repository --repository-name todo-api --force
aws ecr delete-repository --repository-name todo-web --force