EKS 노드 클러스터 조인 실패 점검지

문제 상황#

EKS 노드 그룹이 생성되었으나 클러스터에 조인되지 않음
kubectl get nodes 결과 노드가 보이지 않음
EC2 인스턴스는 Running 상태

점검 항목#

1. VPC DNS 설정#

설정	필수값	확인
`enable_dns_hostnames`	`true`
`enable_dns_support`	`true`

확인 방법:

resource "aws_vpc" "main" {
  enable_dns_hostnames = true
  enable_dns_support   = true
}

2. 서브넷 태그#

EKS 컨트롤러가 서브넷을 인식하려면 특정 태그 필요

서브넷	태그	확인
Public	`kubernetes.io/role/elb = 1`
Private	`kubernetes.io/role/internal-elb = 1`
공통	`kubernetes.io/cluster/<클러스터명> = shared`

확인 방법:

# modules/vpc/main.tf - Public Subnet
tags = {
  "kubernetes.io/role/elb"                        = "1"
  "kubernetes.io/cluster/${var.eks_cluster_name}" = "shared"
}

# modules/vpc/main.tf - Private Subnet
tags = {
  "kubernetes.io/role/internal-elb"               = "1"
  "kubernetes.io/cluster/${var.eks_cluster_name}" = "shared"
}

3. 서브넷 설정#

서브넷	설정	필수값	확인
Public	`map_public_ip_on_launch`	`true`
Private	`map_public_ip_on_launch`	`false` (기본값)

4. 보안 그룹 통신#

노드 <-> 컨트롤 플레인 간 필수 포트

방향	포트	용도
노드 → 컨트롤 플레인	443	API Server
컨트롤 플레인 → 노드	10250	Kubelet
노드 <-> 노드	전체	Pod 통신

terraform-aws-modules/eks 사용 시:

# 자동으로 필요한 SG 규칙 생성됨
attach_cluster_primary_security_group = true

5. 클러스터 엔드포인트 설정#

설정	권장값	설명	확인
`cluster_endpoint_private_access`	`true`	Private 노드가 내부망으로 API 접근
`cluster_endpoint_public_access`	`true`	외부에서 kubectl 접근

주의: private_access = false이면 노드가 NAT → 공인망 경유해야 하므로 복잡해짐

6. VPC Endpoints (AL2023 필수)#

eks-auth VPC Endpoint (PrivateLink)#

항목	설명
서비스명	`com.amazonaws.<region>.eks-auth`
타입	Interface (PrivateLink)
필수 여부	AL2023 AMI 사용 시 필수

원인:

AL2023은 nodeadm 사용 (기존 bootstrap.sh 대체)
nodeadm은 EKS Pod Identity 인증 사용
eks-auth API는 PrivateLink 전용 (NAT Gateway로 접근 불가)

증상:

노드 부트스트랩 로그에 nodeadm: done! 출력
하지만 클러스터에 노드 등록 안 됨

해결:

# config.yaml
vpc_endpoints:
  - eks-auth

기타 VPC Endpoints#

엔드포인트	타입	NAT 대체	비용
S3	Gateway	가능	무료
ECR (ecr.api, ecr.dkr)	Interface	가능	유료
STS	Interface	가능	유료
eks-auth	Interface	불가	유료

결론: NAT Gateway 사용 시 eks-auth만 필수, 나머지는 선택

7. AMI 타입 및 User Data#

AL2 vs AL2023 차이#

항목	AL2	AL2023
부트스트랩	`bootstrap.sh`	`nodeadm`
인증 방식	IAM Role	EKS Pod Identity
eks-auth 필요	X	O (필수)
AMI 타입	`AL2_ARM_64`	`AL2023_ARM_64_STANDARD`

User Data 충돌 확인#

커스텀 user_data 사용 시 AL2023 부트스트랩과 충돌 가능
terraform-aws-modules/eks 사용 시 자동 처리되므로 건드리지 않는 것이 좋음

확인:

# modules/eks/main.tf - Node Group
infra = {
  ami_type = "AL2023_ARM_64_STANDARD"
  # user_data 또는 launch_template 커스텀 없어야 함
}

8. IAM 정책#

노드 IAM Role에 필요한 정책

정책	용도	확인
`AmazonEKSWorkerNodePolicy`	기본 노드 정책	(모듈 자동)
`AmazonEKS_CNI_Policy`	VPC CNI	(모듈 자동)
`AmazonEC2ContainerRegistryReadOnly`	ECR Pull	(모듈 자동)
`AmazonEKSWorkerNodeMinimalPolicy`	AL2023 최소 권한
`AmazonEBSCSIDriverPolicy`	EBS CSI

9. EKS Access Entries#

EKS 1.30+ API 인증 방식

타입	용도
`EC2_LINUX`	노드 그룹 (자동 생성)
`STANDARD`	사용자/역할 접근

SSO 접근 설정:

# config.yaml
eks:
  access_entries:
    devops_sso:
      enabled: true
      role_arn: "arn:aws:iam::ACCOUNT_ID:role/aws-reserved/sso.amazonaws.com/REGION/AWSReservedSSO_..."

디버깅 명령어#

EC2 인스턴스 로그 확인#

# SSM으로 노드 접속
aws ssm start-session --target <instance-id>

# 부트스트랩 로그
sudo journalctl -u nodeadm -f
sudo cat /var/log/cloud-init-output.log

# kubelet 상태
sudo systemctl status kubelet
sudo journalctl -u kubelet -f

클러스터 상태 확인#

# 노드 목록
kubectl get nodes

# 클러스터 정보
kubectl cluster-info

# Access Entries 확인
aws eks list-access-entries --cluster-name <cluster-name>

최종 체크리스트#

VPC DNS 설정 (enable_dns_hostnames, enable_dns_support)
서브넷 태그 (kubernetes.io/role/elb, kubernetes.io/cluster/...)
Public 서브넷 map_public_ip_on_launch = true
보안 그룹 443, 10250 포트 허용
cluster_endpoint_private_access = true
eks-auth VPC Endpoint 생성 (AL2023 필수)
AMI 타입 확인 (AL2023_ARM_64_STANDARD)
User Data 커스텀 없음
IAM 정책 (AmazonEKSWorkerNodeMinimalPolicy 포함)

참고#

EKS 1.35 + AL2023 조합에서 eks-auth VPC Endpoint 누락이 주요 원인
NAT Gateway만으로는 eks-auth API 접근 불가 (PrivateLink 전용)
terraform-aws-modules/eks v20.x는 대부분 자동 설정됨