EKS Add‑ons를 수동으로 관리하지 않기

I’m happy to translate the article for you, but I’ll need the full text you’d like translated. Could you please paste the content (excluding the source line you already provided) here? Once I have it, I’ll translate it into Korean while preserving the original formatting, markdown, and any code blocks or URLs.

문제

프로덕션 EKS 클러스터를 v1.32 로 업그레이드 준비를 하던 중, 네 개의 핵심 애드‑온이 새로운 EKS 릴리스와 호환되지 않는 버전을 실행하고 있음을 발견했습니다:

버전 고정이 없었고, 변경 이력도 없으며, 안전하게 업그레이드를 테스트할 방법도 없었습니다.
그래서 EKS 애드‑온을 수동으로 관리하는 것을 중단하기로 결정했습니다.

Two categories of EKS add‑ons

If you created a cluster without explicitly enabling managed add‑ons, the VPC CNI, CoreDNS, and kube‑proxy are currently self‑managed.

The fix is straightforward: migrate them to EKS‑managed.
Metrics Server, however, is a plain kubectl‑installed resource and isn’t managed by anything.

모든 애드온을 위한 하나의 Terraform 모듈

단일 eks-addons Terraform 모듈을 구축하여 모든 것을 한 곳에서 관리합니다.

AWS에서 관리 (EKS‑관리)

Helm에서 관리 (Helm‑관리)

왜 단일 모듈인가?
모든 애드온은 동일한 종속성인 EKS 클러스터를 공유합니다. 이를 통합하면 다음과 같습니다:

• 하나의 terragrunt apply 로 모든 것을 배포합니다.
• 하나의 terraform plan 로 모든 애드온의 드리프트를 확인합니다.
• 하나의 PR 로 모든 버전을 업데이트합니다.

EKS‑관리형 애드온을 위한 핵심 Terraform

resource "aws_eks_addon" "vpc_cni" {
  count = var.enable_vpc_cni ? 1 : 0

  cluster_name                 = var.cluster_name
  addon_name                   = "vpc-cni"
  addon_version                = var.vpc_cni_version
  resolve_conflicts_on_create  = "OVERWRITE"
  resolve_conflicts_on_update  = "OVERWRITE"
  preserve                     = true
}

두 가지 중요한 플래그

• resolve_conflicts = "OVERWRITE" – Terraform이 진실의 원천이 되며, 클러스터에서 수동으로 변경한 내용은 다음 apply 시 덮어쓰기됩니다.
• preserve = true – 리소스를 Terraform에서 제거하더라도 애드온은 클러스터에 남아 있습니다. 이는 리팩터링 중에 안전망 역할을 합니다.

EBS CSI Driver – 추가 IAM 작업

EBS CSI Driver는 EBS 볼륨을 생성/첨부하기 위한 IAM 권한이 필요합니다. 권장되는 패턴은 IRSA(IAM Roles for Service Accounts)입니다.

# IAM role for the driver
resource "aws_iam_role" "ebs_csi" {
  count = var.enable_ebs_csi ? 1 : 0
  name  = "${var.cluster_name}-ebs-csi-driver"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Federated = var.oidc_provider_arn }
      Action    = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "${var.oidc_provider}:sub" = "system:serviceaccount:kube-system:ebs-csi-controller-sa"
          "${var.oidc_provider}:aud" = "sts.amazonaws.com"
        }
      }
    }]
  })
}

# Attach the AWS‑managed policy
resource "aws_iam_role_policy_attachment" "ebs_csi" {
  count      = var.enable_ebs_csi ? 1 : 0
  role       = aws_iam_role.ebs_csi[0].name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy"
}

파드에 자격 증명이 없으며, 자동 회전 및 CloudTrail에서 깔끔한 감사 로그를 제공합니다.
IRSA는 Kubernetes 내부에서 AWS API를 호출해야 하는 모든 AWS 서비스에 적합한 패턴입니다.

메트릭스 서버 마이그레이션

1️⃣ 기존 kubectl‑설치 리소스 삭제

kubectl delete deployment metrics-server -n kube-system
kubectl delete service metrics-server -n kube-system
kubectl delete apiservice v1beta1.metrics.k8s.io

2️⃣ Terraform을 통해 Helm 관리 버전 설치

resource "helm_release" "metrics_server" {
  count       = var.enable_metrics_server ? 1 : 0
  name        = "metrics-server"
  repository  = "https://kubernetes-sigs.github.io/metrics-server/"
  chart       = "metrics-server"
  version     = var.metrics_server_chart_version
  namespace   = "kube-system"

  values = [yamlencode({
    replicas = 2
    args = [
      "--kubelet-preferred-address-types=InternalIP",
      "--kubelet-insecure-tls"
    ]
    podDisruptionBudget = {
      enabled      = true
      minAvailable = 1
    }
  })]
}

예상 다운타임: 2‑3분 (kubectl top만 사용할 수 없습니다). 실행 중인 애플리케이션은 영향을 받지 않습니다.

CI/CD 함정

우리의 GitHub Actions 워크플로는 수정된 terragrunt.hcl 파일을 찾아 어떤 스택을 배포할지 결정합니다. common/modules/eks-addons/ 아래의 파일을 변경했을 때, 워크플로가 트리거되었지만 스택이 없음(terragrunt.hcl 변경 없음)으로 아무 작업도 실행되지 않았습니다.

해결책: 모듈 변경을 수동으로 배포합니다.

cd workloads-nonprod/us-east-1/cluster-name/eks-addons
terragrunt init
terragrunt plan   # Should show ~10 resources to add
terragrunt apply

모든 것이 정상인지 확인하기

# Check EKS‑managed add‑on status
for addon in vpc-cni aws-ebs-csi-driver coredns kube-proxy; do
  aws eks describe-addon \
    --cluster-name <cluster-name> \
    --addon-name $addon \
    --query "addon.status" \
    --output text
done

각 애드온에 대해 ACTIVE가 표시되어야 합니다.

요약

• Self‑managed add‑ons는 버전, 호환성 및 보안 패치를 직접 추적해야 합니다.
• EKS‑managed add‑ons는 AWS가 수명 주기를 관리하도록 하여 업그레이드 시 신뢰성을 제공합니다.
• AWS‑managed, Helm‑managed, 사용자 정의 add‑on을 단일 Terraform 모듈에 통합하면 드리프트 감지, 버전 업그레이드 및 CI/CD 연동이 간소화됩니다.

이제 클러스터를 EKS 1.32로 업그레이드해도 이전의 add‑on 호환성 문제에 신경 쓸 필요가 없습니다.

kubectl top nodes

이전

• Self‑managed 모드로 실행되는 네 개의 add‑on
• kubectl로 설치된 하나의 add‑on
• 버전 히스토리 없음
• 드리프트 감지 기능 없음

이후

• Pinned versions와 함께 코드에 정의된 여섯 개의 add‑on 모두
• terraform plan을 실행하면 선언된 상태와 차이가 나는 부분을 즉시 확인 가능
• 롤백은 git revert + terragrunt apply만으로 간단히 수행 가능

EKS 클러스터 업그레이드 체크리스트

1. Terragrunt 구성에서 네 개의 버전 문자열을 업데이트합니다.
2. PR을 엽니다.
3. 병합 – 업그레이드가 자동으로 적용됩니다.

내가 두려워하던 클러스터 업그레이드가 수동 호환성 검증에 하루가 걸릴 줄 알았지만 30 분 정도 걸렸습니다.

EKS 애드‑온 관리 문제에 직면했나요? 연락 주세요—이것이 제가 플랫폼 팀을 위해 수행하는 운영 작업입니다.