1. 개요
- EKS가 잘 안 될 때 확인해야 할 내용들입니다.
- 특히 Control plane과 Worker node를 연결했는데도 여전히
no resources found처럼 리소스가 보이지 않거나, 노드가 클러스터에 조인되지 않을 때 점검할 항목들입니다.
2. 내용
2-1. Private subnet의 NAT Gateway 연결
Worker node를 Private subnet에 만든다면 NAT Gateway 또는 그에 준하는 외부 통신 경로가 필요합니다. 노드는 클러스터에 조인하는 과정에서 EKS API, ECR, S3 등 AWS 서비스와 통신해야 할 수 있기 때문입니다.
모든 리소스를 Public subnet에 둔다면 이 부분이 문제가 되지 않을 수 있지만, 운영 환경에서는 보통 Worker node를 Private subnet에 두는 구성이 많으므로 라우팅 테이블을 먼저 확인하는 것이 좋습니다.
확인할 내용은 Private subnet의 Route table에 0.0.0.0/0 경로가 NAT Gateway로 향하는지, NAT Gateway가 Public subnet에 있고 Internet Gateway로 나갈 수 있는지입니다.
2-2. Userdata 확인
EKS-optimized AMI를 사용할 때는 bootstrap.sh 관련 Userdata가 제대로 적용되어 있는지 확인합니다. Worker node가 클러스터에 붙지 않는 경우, Userdata 누락이나 클러스터 이름 오타가 원인인 경우가 있습니다.
Launch Template이나 Auto Scaling Group을 사용하는 경우 실제 인스턴스에 적용된 Userdata가 기대한 값인지 확인해야 합니다. 템플릿을 수정했더라도 Auto Scaling Group이 이전 버전의 Launch Template을 계속 사용하고 있을 수 있습니다.
2-3. Security Group 확인
Control plane과 Worker node 간 Security Group 설정을 확인합니다. 세부 포트와 방향은 구성 방식에 따라 달라질 수 있으므로 AWS 공식 문서를 기준으로 맞추는 것이 좋습니다.
기본적으로 Worker node가 Control plane과 통신할 수 있어야 하고, Control plane도 Worker node의 kubelet과 필요한 통신을 할 수 있어야 합니다. 보안 그룹을 너무 좁게 제한했다면 노드 조인이나 파드 상태 조회가 실패할 수 있습니다.
2-4. aws-auth yaml 파일의 Role ARN 확인
aws-auth ConfigMap에 Worker node가 사용하는 IAM Role ARN이 정확히 들어가 있는지 확인합니다. ARN에 오타가 있거나, Role이 아니라 Instance Profile ARN을 넣은 경우 노드가 인증되지 않을 수 있습니다.
다음처럼 현재 설정을 확인해 봅니다.
kubectl get configmap aws-auth -n kube-system -o yaml여기서 mapRoles 항목에 Worker node의 IAM Role ARN이 들어 있는지 확인합니다. 클러스터를 직접 구성했거나 노드 그룹을 수동으로 붙인 경우 특히 이 항목을 놓치기 쉽습니다.
2-5. 간단한 확인 명령
설정 변경 후에는 아래 명령으로 노드가 정상적으로 보이는지 확인합니다.
kubectl get nodes
kubectl get pods -A노드가 계속 보이지 않는다면 EC2 인스턴스의 시스템 로그, Userdata 실행 결과, EKS 클러스터 이벤트, IAM Role 및 Security Group 설정을 함께 확인하는 것이 좋습니다.