[AWS EKS] 클러스터 노드 그룹 생성 관련 NodeCreationFailure "instances failed to join the kubernetes cluster" 문제 해결

 

 ⛈️ 문제 상황

AWS EKS 콘솔에서 클러스터를 성공적으로 생성한 이후 노드 그룹 생성 시 "instances failed to join the kubernetes cluster" 에러가 발생하였다.

 

 

 ☀️ 해결법

관련 내용을 검색도 해보고 AWS EKS 공식 문서도 확인해보니 현재 오류가 다양한 이유로 발생한다는 것을 알게 되었다. 따라서 어떤 이유에서 발생한 건지 하나하나 확인해 볼 필요가 있었다.

 

AWS EKS 공식 문서에 클러스터에 조인이 실패하는 다양한 이유가 정리되어 있다.

 

https://docs.aws.amazon.com/eks/latest/userguide/troubleshooting.html

Troubleshoot problems with Amazon EKS clusters and nodes - Amazon EKS

 

Nodes fail to join cluster

 

There are a few common reasons that prevent nodes from joining the cluster:

• If the nodes are managed nodes, Amazon EKS adds entries to the aws-auth ConfigMap when you create the node group. If the entry was removed or modified, then you need to re-add it. For more information, enter eksctl create iamidentitymapping --help in your terminal. You can view your current aws-auth ConfigMap entries by replacing my-cluster in the following command with the name of your cluster and then running the modified command: eksctl get iamidentitymapping --cluster my-cluster . The ARN of the role that you specify can’t include a path other than /. For example, if the name of your role is development/apps/my-role, you’d need to change it to my-role when specifying the ARN for the role. Make sure that you specify the node IAM role ARN (not the instance profile ARN).
  
  
• If the nodes are self-managed, and you haven’t created access entries for the ARN of the node’s IAM role, then run the same commands listed for managed nodes. If you have created an access entry for the ARN for your node IAM role, then it might not be configured properly in the access entry. Make sure that the node IAM role ARN (not the instance profile ARN) is specified as the principal ARN in your aws-auth ConfigMap entry or access entry. For more information about access entries, see Grant IAM users access to Kubernetes with EKS access entries.
  
  
• The ClusterName in your node AWS CloudFormation template doesn’t exactly match the name of the cluster you want your nodes to join. Passing an incorrect value to this field results in an incorrect configuration of the node’s /var/lib/kubelet/kubeconfig file, and the nodes will not join the cluster.
  
  
• The node is not tagged as being owned by the cluster. Your nodes must have the following tag applied to them, where my-cluster is replaced with the name of your cluster.
  
  
• KeyValue

  kubernetes.io/cluster/my-cluster

  owned

• The nodes may not be able to access the cluster using a public IP address. Ensure that nodes deployed in public subnets are assigned a public IP address. If not, you can associate an Elastic IP address to a node after it’s launched. For more information, see Associating an Elastic IP address with a running instance or network interface. If the public subnet is not set to automatically assign public IP addresses to instances deployed to it, then we recommend enabling that setting. For more information, see Modifying the public IPv4 addressing attribute for your subnet. If the node is deployed to a private subnet, then the subnet must have a route to a NAT gateway that has a public IP address assigned to it.
  
  
• The AWS STS endpoint for the AWS Region that you’re deploying the nodes to is not enabled for your account. To enable the region, see Activating and deactivating AWS STS in an AWS Region.
  
  
• The node doesn’t have a private DNS entry, resulting in the kubelet log containing a node "" not found error. Ensure that the VPC where the node is created has values set for domain-nameand domain-name-servers as Options in a DHCP options set. The default values are domain-name:<region>.compute.internal and domain-name-servers:AmazonProvidedDNS. For more information, see DHCP options sets in the Amazon VPC User Guide.
  
  
• If the nodes in the managed node group do not connect to the cluster within 15 minutes, a health issue of "NodeCreationFailure" will be emitted and the console status will be set to Create failed. For Windows AMIs that have slow launch times, this issue can be resolved using fast launch.

 

 

일단 하나하나 읽어보면서 내 프로젝트의 설정 상황과 비교해 보았다. 많은 사람들이 VPC 관련한 이유로 현재의 문제를 겪는다기에 네트워킹 관련한 부분에 중점을 두고 확인하였다.

 

하지만, 네트워킹 관련 문제는 주로 현재 AWS 계정 관리자가 AWS 내의 다른 자원에서 작업하다가 네크워킹 부분을 건드려서 문제가 발생한 경우가 대부분이었다. 현재 나의 AWS 계정은 예전에 탈퇴했다가 이번에 새로 가입하였고 네트워킹 부분을 손댄 적이 없기에 VPC, Subnet 등의 설정이 꼬였을 확률이 매우 낮았다.

 

실제로 네트워킹 부분을 먼저 자세히 확인하였는데도 문제 되는 부분이 발견되지 않았다.

 

그래서 계속 살펴보던 중 마지막 문단에 눈길이 갔다. 15분 내에 노드 그룹이 클러스터와 연결되지 않으면 문제가 발생한다는 내용이다.

 

콘솔을 확인해 보니 에러 문구가 뜨기까지 15분을 초과한 20분 정도의 시간이 걸린 것을 확인했다.

 

현재 내 프로젝트는 비용을 절감하기 위해서 노드 그룹을 사용할 때 가장 저렴한 모델로 알려진 t3.nano 인스턴스를 사용하고 있었다.

 

생각해 보니 성능이 낮은 인스턴스를 사용하여 노드 그룹을 생성하면 부트 작업에서 낮은 성능의 인스턴스로 인해 처리 시간이 오래 걸릴 것 같아서, 더 좋은 성능의 모델인 t3.small 모델로 변경 후 다시 노드 그룹을 생성해 보니 4분 만에 노드 그룹이 성공적으로 생성되고 생성된 노드들이 콘솔에 정상적으로 떠있었다.....

 

단순히 낮은 성능의 인스턴스를 선택했다는 이유로 이러한 문제가 발생하였을 거라는 생각을 전혀 못했기에, AWS 트러블슈팅 가이드가 없었으면 한참 헤매었을 뻔했다.