클러스터 설정 — Fargate+karpenter 토폴로지와 Terraform 리소스

이 페이지는 배경의 결정과 목표버전 1.35 위에서, 클러스터가 무엇인가(토폴로지 + Terraform 리소스)를 다룬다. “어떤 순서로 올리나"는 04 부트스트랩이, EKS managed addon 버전·설정은 03 managed addon이 이어받는다.

1. 목표 토폴로지

Karpenter를 Fargate 위에서 돌리는 것은 karpenter 공식 getting-started가 정식으로 제공하는 옵션(“managedNodeGroups 대신 fargateProfiles 사용”)이다. 이 프로젝트는 그 옵션 위에 CoreDNS까지 얹어 managed nodegroup을 아예 두지 않는 형태로 간다.

managed nodegroup이 없으므로 첫 EC2 노드는 karpenter 자신이 만든다. CoreDNS와 karpenter는 EC2 노드 없이 Fargate에서 뜰 수 있는 유일한 두 컴포넌트이고, 그 둘이 살아나야 나머지(ebs-csi·ALB controller·external-secrets 등)가 착지할 EC2 노드가 생긴다 — 이 “노드 없이 뜨는 2컴포넌트가 나머지의 착지장을 만든다"는 것이 토폴로지의 구조적 핵심이다. 단계별 부트스트랩 순서(닭-달걀 풀기)는 04 부트스트랩이 다룬다. arm64 required affinity를 가진 플랫폼 컴포넌트는 arm64 풀이 system 하나뿐이라 전부 거기로 몰리므로, system 풀 사이징은 이 컴포넌트 총합을 수용해야 한다(§3).

2. Fargate 3대 물리 제약

EKS 공식 문서 기준 아래 세 가지가 설계 전체를 지배한다.

1. amd64 전용(Arm 미지원). CoreDNS·karpenter가 원래 갖고 있던 arm64 required nodeAffinity·toleration을 반드시 제거해야 한다. 지우지 않으면 Fargate 스케줄러가 배치를 시도조차 하지 않아 영구 Pending이 된다.
2. DaemonSet 미지원. Fargate는 파드 하나에 전용 micro-VM 하나를 붙이는 구조라 “노드” 개념이 없고, 노드 기반 DaemonSet이 존재할 자리가 없다. csi-node·datadog·fluentbit·node-exporter·node-local-dns·kube-proxy·aws-node 어느 것도 Fargate 파드에는 안 붙는다(§4).
3. 동적 EBS 마운트 불가. EBS CSI 컨트롤러 자체는 Fargate에서 돌 수 있지만, 실제 볼륨을 붙이는 csi-node DaemonSet은 EC2 전용이다. 그래서 Fargate 파드는 동적 프로비저닝 EBS PV를 쓸 수 없다(EFS 정적 프로비저닝은 예외적으로 가능하나 finance는 EFS를 쓰지 않아 무관).

세 제약 모두 CoreDNS·karpenter에는 문제가 되지 않는다 — 둘 다 EBS가 불필요하고 arm64 고정만 풀면 amd64로 문제없이 뜬다. 제약이 실질적으로 부딪히는 지점은 DaemonSet 공백(§4)이다.

3. 컴포넌트 배치 매트릭스

배치처는 네 가지다 — Fargate(amd64 micro-VM), system pool(arm64 EC2), workload pool(amd64 EC2), DaemonSet(전 EC2 노드).

4. DaemonSet 공백과 대안

Fargate 파드(CoreDNS, karpenter)에는 노드 DaemonSet이 붙지 않으므로, 노드 기반 로그·메트릭 수집기가 이 두 파드를 놓친다.

5. CoreDNS·ebs-csi·karpenter config 변경

이 세 컴포넌트는 기존 값(system-primary 노드그룹·arm64 고정)을 그대로 두면 새 토폴로지에서 동작하지 않는다. Fargate가 강제하는 config 값 변경만 정리한다.

5.1 CoreDNS addon config

5.2 ebs-csi addon config

5.3 karpenter values

karpenter 0.36.2→1.14.0 버전 업그레이드 자체(CRD v1beta1→v1·IAM·배포 절차)는 컴포넌트별 마이그레이션 — karpenter가 이어받는다.

6. 기존 Terraform 자산 실사 — 무엇을 재활용하고 무엇을 버리나

IaC 레포에는 EKS 클러스터를 만드는 모듈이 이미 존재하지만 실제로 쓰이는 것은 거의 없다. 호출 여부(참조 카운트)를 기준으로 재활용 판정을 내린다.

dead code의 시대감각: modules/clusters/eks의 eks_version 기본값이 관리형 노드그룹이 표준이던 시절 값이다. Fargate-only·karpenter-only가 확정된 지금은 “그대로 재활용"이 아니라 골격 참조 후 재작성이 현실적이다.

이미 존재하는 Fargate 프로토타입 (stage)

“Fargate로 coredns+karpenter만” 패턴은 사실 stage에 이미 Terraform으로 작성돼 있다(ring0-blue의 Fargate 패턴을 따랐다는 주석이 남아 있다).

재활용 판정은 높다. cluster_name을 blue 이름으로, subnet 필터를 blue private subnet으로만 바꾸면 그대로 동작한다(stage blue subnet은 이미 선provisioned 상태다). 다만 ⚠️ prod에는 이 Fargate 스택 자체가 없어 stage 패턴을 복제해 신규 작성해야 하고, ⚠️ prod blue 클러스터용 subnet이 아직 어디에도 정의돼 있지 않아 prod 재구축 전에 subnet 확보가 선행돼야 한다. 또 selector는 파드 생성 시점에만 평가되므로 프로필 생성 후 대상 워크로드를 rollout restart해야 하고, coredns의 arm64 nodeAffinity를 먼저 제거해야 한다(§2).

kube-proxy addon mode 변수화 — nftables opt-in 준비

modules/clusters/addons는 configuration_values를 정적 JSON으로 주입하는 구조라 kube-proxy mode도 코드에 박혀 있다. 이번 이관은 iptables를 유지하되(정정 상세는 03 managed addon), 향후 전환을 한 줄 변경으로 끝내기 위해 kube-proxy 블록만 변수화해 둔다.

variable "kube_proxy_mode" {
  description = "kube-proxy 프록시 모드. EKS addon 기본값은 iptables이며, addon v1.31+ 계열부터 nftables opt-in 가능(ipvs는 1.35 deprecated, 코드 삭제는 KEP-5495 기준 ~v1.43 예정)."
  type        = string
  default     = "iptables"
  validation {
    condition     = contains(["iptables", "nftables"], var.kube_proxy_mode)
    error_message = "kube_proxy_mode는 iptables 또는 nftables만 허용한다."
  }
}

기본값은 iptables로 두고, 전환 시 kube_proxy_mode = "nftables"로 apply한 뒤 kubectl -n kube-system rollout restart ds kube-proxy로 기존 규칙셋을 정리한다.

7. CAPA → Terraform 매핑

CAPI 스펙(clusterapi.yaml)이 만들던 것을 Terraform 리소스로 1:1 대응시킨다.

8. karpenter 인프라 신규 작성 — 레포에 전무한 부분

컨트롤러 IRSA·노드 롤·interruption SQS·discovery 태그 어느 것도 이 레포에 존재하지 않는다. karpenter 공식 CloudFormation 레퍼런스와 getting-started를 근거로 전부 신규 작성한다.

8.1 컨트롤러 IRSA role

karpenter 컨트롤러를 Fargate로 호스팅하므로 인증 경로는 IRSA(OIDC) 다 — Pod Identity는 DaemonSet 기반 Agent가 필요해 Fargate를 지원하지 않는다. 트러스트는 신규 OIDC issuer + system:serviceaccount:karpenter:karpenter로 modules/irsa 동적 바인딩 패턴 그대로 작성한다. karpenter 1.14 기준 컨트롤러 정책은 6묶음이다.

NodeLifecyclePolicy       # RunInstances/CreateFleet/CreateLaunchTemplate/TerminateInstances (태그 스코핑)
IAMIntegrationPolicy      # PassRole(노드 롤), CreateInstanceProfile/AddRoleToInstanceProfile — 클러스터명 스코핑
EKSIntegrationPolicy      # eks:DescribeCluster
InterruptionPolicy        # sqs:DeleteMessage/GetQueueUrl/ReceiveMessage
ZonalShiftPolicy          # arc-zonal-shift:GetManagedResource
ResourceDiscoveryPolicy   # ec2:Describe*, ssm:GetParameter, pricing:GetProducts, iam:ListInstanceProfiles(v1.7+)

v1.11+에서 ec2:DescribePlacementGroups, v1.12+에서 ec2:DescribeInstanceStatus가 추가로 필요하다.

8.2 노드 IAM role + instance profile

EC2 trust aws_iam_role + managed policy 4종: AmazonEKSWorkerNodePolicy, AmazonEKS_CNI_Policy, AmazonEC2ContainerRegistryPullOnly(구 ReadOnly 대체), AmazonSSMManagedInstanceCore. instance profile은 karpenter v1.7+가 자동 관리 가능하나 finance는 정적 instance profile 참조 방식을 유지한다. vpc-cni가 스펙에 SA-role이 없는 구조라 노드 롤에는 AmazonEKS_CNI_Policy를 유지하는 편이 안전하다.

8.3 Interruption SQS + EventBridge

aws_sqs_queue(이름은 차트 settings.interruptionQueue 값과 정확히 일치해야 소비된다) + aws_sqs_queue_policy(principal events.amazonaws.com+sqs.amazonaws.com, sqs:SendMessage, aws:SecureTransport:false deny). aws_cloudwatch_event_rule+target 5종을 큐로 연결한다.

8.4 subnet / SG의 discovery 태그

karpenter는 subnet·SG의 karpenter.sh/discovery: ${CLUSTER_NAME} 태그로 프로비저닝 대상을 발견한다(EC2NodeClass의 selectorTerms). 이 태그는 현재 TF에 0건이라 blue subnet·SG에 신규 부착해야 karpenter가 노드를 띄운다. 내부 ALB 전제라 ALB용 kubernetes.io/role/internal-elb=1 태그도 같은 subnet에 함께 붙인다.

8.5 karpenter 노드 롤의 클러스터 접근

access entries를 채택하면(§9) 노드 롤은 **aws_eks_access_entry(type=EC2_LINUX)**로 조인시킨다. 관리형 노드그룹·Fargate profile 롤은 EKS가 access entry를 자동 생성하지만 karpenter가 띄우는 노드는 self-managed 취급이라 이 access entry만은 명시 작성해야 조인한다.

9. 인증 모드 — access entries

CAPA를 쓰지 않으므로 IAMAuthenticator(aws-auth) 강제가 사라진다. AWS는 access entries를 권장 방법으로 명시하고 aws-auth는 deprecated로 표기한다. 신규 클러스터는 **authentication_mode = API_AND_CONFIG_MAP**로 만들고 주체를 access entry로 등록한다.

Fargate pod-exec role은 별도 조치가 필요 없다 — Fargate profile 롤은 access entry가 자동 생성되므로 karpenter 노드 롤(EC2_LINUX)만 명시 작성하면 된다. bootstrapClusterCreatorAdminPermissions는 기본 true라, 감사성 측면에서는 false로 두고 생성 principal을 access entry로 별도 등록하는 편이 낫다.

10. OIDC 이중등록과 IRSA 재바인딩

신규 blue 클러스터는 신규 OIDC issuer URL + provider ARN을 갖는다. 여기가 이 프로젝트에서 가장 파급이 큰 함정이다.

기존 IRSA 롤들은 data.aws_eks_cluster[name].identity[0].oidc.issuer로 동적 바인딩돼 있어 클러스터 이름이 같으면 apply만으로 갱신되지만, OIDC provider lookup은 항상 management 계정에서 수행된다(실사용 IRSA 스택 데이터 소스에 명시). 반면 CAPA가 수행하던 associateOIDCProvider는 워크로드 계정에만 provider를 등록해왔다. 따라서 신규 blue 클러스터는 워크로드 계정 + management 계정 양쪽에 aws_iam_openid_connect_provider를 등록해야 external-secrets 포함 IRSA 전체가 붙는다. 이름이 다른 신규 클러스터(green→blue)라면 클러스터 registry에 신규 이름을 추가해야 재바인딩이 트리거된다.

재바인딩 대상:

• Terraform 관리(동적, apply만으로): 워크로드·management 양쪽의 시크릿 관리용 IRSA 롤 — registry에 신규 클러스터명만 추가하면 자동.
• Terraform 레포 밖(외부 관리, 별도 재발급 경로 확인): karpenter 컨트롤러 IRSA, ALB controller IRSA, argo-rollouts IRSA, fluentbit·datadog·cloudwatch-agent IRSA, 그리고 ebs-csi IRSA(스펙에 SA-Role이 없어 신규 OIDC로 wiring됐는지부터 확인). ebs-csi IRSA는 이 프로젝트의 최대 리스크 — 롤 자체를 이 페이지에서 신규 생성하되, addon 연결·PVC 검증은 03 managed addon에서 확인한다.
• ArgoCD: 신규 blue API endpoint로 클러스터 등록 secret을 새로 발급한다(정적 SA bearerToken). tier-1 허브 push 앱은 하드코딩 endpoint 교체가 선행돼야 한다 → 04 부트스트랩.

11. amiType·IMDS

amiType — AL2_ARM_64에서 AL2023_ARM_64_STANDARD로(필수, blocking). EKS는 AL2 AMI 발행을 중단했고 1.32가 AL2 AMI의 마지막 버전이라 1.33+ 신규 관리형 노드그룹에 AL2 amiType을 아예 선택할 수 없다. karpenter EC2NodeClass는 이미 AL2023 amiFamily라 마이너별 AMI 핀만 목표 버전용으로 갱신한다. 라이브 노드는 이미 AL2023으로 교체가 끝나 OS 리스크는 낮고, 스펙-라이브 정합 문제로만 남는다.

IMDS hop limit = 2(필수). AL2023 신규 노드는 hop limit이 1이면 IRSA 토큰 취득이 실패해 vpc-cni·ebs-csi가 함께 깨진다. 신규 노드그룹/런치템플릿 생성 시 반드시 2로 설정한다.

워크로드 API endpoint가 ArgoCD app-of-apps 레포에 다수 하드코딩돼 있어 클러스터를 세울 때마다 재바인딩해야 하는데, 파일별 분포·정확한 목록·교체 절차는 04 부트스트랩이 다룬다.

12. Terraform 체크리스트

클러스터 코어

• aws_iam_role(클러스터) + AmazonEKSClusterPolicy — CAPA 롤 대체
• aws_eks_cluster — version 1.35, vpc_config(blue subnet + endpoint private-only), enabled_cluster_log_types=["audit"], 노드그룹/런치템플릿 제거
• access_config { authentication_mode = "API_AND_CONFIG_MAP" }
• (선택) encryption_config + aws_kms_key
• aws_iam_openid_connect_provider ×2(워크로드 + management)

Fargate(coredns + karpenter 호스팅)

• aws_iam_role(pod-exec) + AmazonEKSFargatePodExecutionRolePolicy — stage 프로토타입 재활용
• aws_eks_fargate_profile — selector 2종, blue private subnet
• prod Fargate 스택 신규 작성 + prod blue subnet 신규 확보(둘 다 현재 부재)

managed addon 4종 + SA-role

• aws_eks_addon ×4 — addons 모듈 재활용, 버전 1.35, coredns/ebs-csi config 재전달
• modules/irsa → ebs-csi-controller-sa + AmazonEBSCSIDriverPolicyV2, addon service_account_role_arn에 주입
• kube-proxy configuration_values.mode 변수화(기본 iptables)

karpenter 인프라(전부 신규)

• 컨트롤러 IRSA(v1 6정책, 클러스터명 스코핑)
• 노드 IAM role + 4 managed policy + instance profile
• interruption SQS + queue policy + EventBridge 규칙 ×5
• subnet/SG karpenter.sh/discovery=<cluster> 태그
• aws_eks_access_entry(type=EC2_LINUX) 노드 롤

인증/접근

• aws_eks_access_entry(STANDARD) + policy association — CI/admin/개발자
• 클러스터 registry에 신규 클러스터명 추가 → IRSA 재바인딩 트리거

SG/네트워크

• vpc_config.security_group_ids 결정(전용 SG vs 기본)
• security_groups 모듈 — ALB→cluster ingress 규칙
• additionalControlPlaneIngressRules 재현(VPC간 CIDR)
• ALB subnet 태그 kubernetes.io/role/elb·internal-elb

클러스터 밖(Terraform 아님 — 04 부트스트랩이 다룸)

• ArgoCD cluster 등록(정적 SA 토큰), 하드코딩 endpoint 교체, CAPA ApplicationSet에서 finance 분리, green 클러스터 통제 삭제

우리 케이스에서는

Terraform으로 신규 blue 클러스터를 세우는 작업은 “새로 만드는 것"보다 **“CAPA가 암묵적으로 해오던 12가지를 명시적으로 재현하는 것”**에 가깝다. 클러스터 셸·addon 스키마·Fargate 프로필은 기존 자산을 재활용할 수 있지만, karpenter 인프라 전체는 레포에 전무해 처음부터 짜야 한다. 가장 위험한 두 지점은 성격이 다르다 — OIDC 이중등록은 빠뜨리면 cross-account IRSA 전체가 조용히 깨지는 blocking 이슈이고, ebs-csi IRSA 롤은 스펙에 필드가 없어 존재 자체를 놓치기 쉬운 최대 리스크다. 여기에 prod Fargate 스택·prod blue subnet이 아직 없다는 사실까지 더하면, prod 이관은 stage 검증 후에도 별도 신규 작성이 남는다.