풀스택 앱 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: 풀스택 todo 시스템의 K8s 배포 아키텍처

## 컨텍스트
Next.js (App Router + RSC) + FastAPI + PostgreSQL 의 todo 시스템을
운영 환경에 배포해야 함.

## 옵션
1. ECS Fargate (매니지드 컨테이너)
2. EKS (Kubernetes)
3. Lambda + RDS (서버리스)

## 결정
EKS 채택.

## 근거
- 두 앱 (Next.js + FastAPI) 의 결이 다르고, 라이프사이클 격리 필요
- HPA · Karpenter 의 오토스케일링 결이 트래픽 패턴에 맞음
- GitOps (ArgoCD) 의 운영 표준 모델 활용
- 본 책의 1 ~ 30 장 모든 도구의 종합 검증

## 결과
- 한 달 $80 ~ $120 의 비용 가설 (28장 모델로 검증 예정)
- 운영 캘린더 (26장) 의 정기 사이클 적용
- AWS 책의 ECS Fargate 챕터와 비교 학습 가능

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  # ... 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
    }
  }

  # 최소 노드만 ON_DEMAND 로 유지, 나머지는 Karpenter 가 즉석에서
  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   # 같은 backend 의 다른 워크로드도 허용
      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   # 16장의 보안 결

[Browser]
   |
   | HTTPS
   v
[ALB]
   |
   v
[Next.js Pod]  -- Node.js 서버 (next start)
   |
   | RSC 렌더링 시 fetch
   v
[todo-api Service]  -- ClusterIP, 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   # 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 도 동일

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

트래픽 증가
   |
   v
HPA: 30 초 만에 todo-api Pod 2 -> 5 -> 10 -> 20
   |
   | 노드의 자원 부족
   v
Karpenter: 30 초 ~ 1 분 만에 새 노드 (spot 우선) 프로비저닝
   |
   v
Pending 이었던 Pod 가 새 노드에 스케줄링됨

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

# todo 시스템 운영 캘린더

## 매일
- Grafana 의 todo 대시보드 5 패널 점검
- Alertmanager 의 활성 알람 검토

## 매주
- ECR Trivy 스캔 결과 (todo-api, todo-web 모두)
- 신규 보안 패치 검토

## 매월
- OpenCost 의 팀 / 워크로드별 비용 1, 2, 3 위
- VPA recommendation 의 미반영 워크로드
- ArgoCD 의 OutOfSync 상태 점검

## 분기
- EKS 마이너 업그레이드 (30장의 13 단계)
- RDS Performance Insights 의 right-sizing 신호
- RBAC audit
- 복구 훈련 (PITR 시뮬레이션)
- kube-bench CIS 점검

## 반기
- 외부 보안 감사
- DR 시뮬레이션 (Velero restore)

## 연
- 클러스터 아키텍처 리뷰
- 매니페스트 현대화

# 1. ArgoCD Application 삭제 (워크로드 정리)
kubectl delete applicationset todo -n argocd

# 2. RDS deletion_protection 해제 후 terraform destroy
# (prod 의 경우 deletion_protection 이 켜져 있으므로 terraform 변수로 false 후 apply)

# 3. ALB / Route 53 의 자동 정리 확인
# external-dns 가 hostname 의 A 레코드를 자동 삭제

# 4. terraform destroy
terraform destroy

# 5. ECR repository 삭제 (이미지 잔재)
aws ecr delete-repository --repository-name todo-api --force
aws ecr delete-repository --repository-name todo-web --force