EKS 노드 조인 실패

분류: Terraform·프로비저닝 · 환경: Staging EKS · 상태: ✅ 해결

증상

• Terraform으로 EKS 클러스터를 프로비저닝한 뒤 워커 노드(NodeGroup)가 클러스터에 등록되지 않음
• kubectl get nodes에 노드가 나타나지 않거나 NotReady 상태에서 멈춤
• 노드 부트스트랩 로그에서 CNI 초기화 실패 및 네트워크 설정 오류 확인

원인

Terraform apply 순서 문제였음.

EKS NodeGroup이 먼저 프로비저닝되면, 노드가 클러스터에 조인을 시도하는 시점에 VPC CNI 애드온이 아직 준비되어 있지 않음. VPC CNI가 없으면 파드 네트워크가 구성되지 않아 aws-node DaemonSet이 실행되지 않고, 노드가 Ready 상태로 전환되지 못함.

의존 관계:

EKS Addons (vpc-cni, kube-proxy, coredns)
    ↓ 먼저 준비 완료
NodeGroup 프로비저닝
    ↓
노드 부트스트랩 → 클러스터 등록

해결

Terraform apply 순서를 addons 먼저, nodegroup 나중으로 변경.

# 1단계: 클러스터 + 애드온 먼저 적용
terraform apply -target=module.eks -target=module.eks_addons

# 2단계: 애드온 Ready 확인 후 NodeGroup 적용
terraform apply

또는 Terraform 코드에서 명시적 의존성 추가:

resource "aws_eks_node_group" "this" {
  # ...
  depends_on = [
    aws_eks_addon.vpc_cni,
    aws_eks_addon.kube_proxy,
    aws_eks_addon.coredns,
  ]
}

관측 결과

• 적용 순서 변경 후 노드가 정상적으로 클러스터에 등록됨
• kubectl get nodes에서 Ready 상태 확인

향후 모니터링

• 클러스터 재프로비저닝 시 반드시 addons 먼저 apply 후 nodegroup 순서 유지
• Terraform 코드에 depends_on 명시하여 순서 의존성을 코드로 고정

---

← 트러블슈팅 인덱스로