Amazon EKS 관리형 노드 그룹 생성 실패에 대한 문제를 해결하려면 어떻게 해야 하나요?

5분 분량

Amazon Elastic Kubernetes Service(Amazon EKS) 관리형 노드 그룹을 만들지 못했습니다. 노드를 클러스터에 조인할 수 없으며 다음과 유사한 오류가 발생했습니다. "Instances failed to join the kubernetes cluster".

간략한 설명

Amazon EKS 관리형 노드 그룹 생성 실패를 해결하려면, 다음 단계를 따르세요.

AWS Systems Manager Automation 런북을 사용하여 일반적인 문제를 식별하세요.
워커 노드 보안 그룹 트래픽 요구 사항을 확인합니다.
워커 노드 Identity and Access Management(IAM) 권한을 확인합니다.
클러스터용 Amazon Virtual Private Cloud(VPC)가 DNS 호스트 이름 및 확인을 지원하는지 확인하세요
워커 노드의 NodeInstanceRole로 aws-auth ConfigMap을 업데이트하세요.
워커 노드의 태그를 설정합니다.
워커 노드의 Amazon VPC 서브넷에 사용 가능한 IP 주소가 있는지 확인합니다.
워커 노드가 클러스터의 API 서버 엔드포인트에 도달할 수 있는지 확인합니다.
Amazon Elastic Compute Cloud(Amazon EC2), Amazon Elastic Container Registry(Amazon ECR) 및 Amazon Simple Storage Service(S3) API 엔드포인트가 AWS 리전에 도달할 수 있는지 확인합니다.

해결 방법

참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하는 경우, 최신 AWS CLI 버전을 사용하고 있는지 확인하세요.

Systems Manager automation 런북을 사용하여 일반적인 문제 식별

AWS Support-TroublesoteksWorkerNode 런북을 사용하여 워커 노드가 클러스터에 조인하지 못하게 하는 일반적인 문제를 찾아보세요.

중요: 자동화가 작동하려면, 워커 노드가 Systems Manager에 액세스할 수 있는 권한이 있어야 하며 Systems Manager가 실행된 상태여야 합니다. 권한을 부여하려면 AmazonSSMManagedInstanceCore AWS 관리형 정책을 EC2 인스턴스 프로파일에 해당하는 IAM 역할에 연결하세요. 이는 eksctl을 통해 생성된 EKS 관리형 노드 그룹의 기본 구성입니다.

런북을 엽니다.
AWS Management Console의 AWS 리전이 클러스터와 동일한 리전으로 설정되어 있는지 확인하세요.
**참고:**런북에 대한 자세한 내용은 런북의 Document details(문서 세부 정보) 섹션을 참조하세요.
Input parameters(입력 파라미터) 섹션에서 ClusterName 필드에 클러스터 이름을 지정하고 WorkerID 필드에 인스턴스 ID를 지정합니다.
(선택 사항) AutomationAssumeRole 필드에서 Systems Manager가 작업을 수행할 수 있도록 허용하는 IAM 역할을 지정합니다. 지정하지 않으면 현재 IAM 엔티티의 IAM 권한이 런북에서 작업을 수행하는 데 사용됩니다.
Execute(실행)을 선택합니다.
Outputs(출력) 섹션에서 워커 노드가 클러스터에 연결되지 않는 이유와 이를 해결하기 위해 취할 수 있는 단계를 확인하세요.

워커 노드 보안 그룹의 트래픽 요구 사항 확인

컨트롤 플레인의 보안 그룹과 워커 노드 보안 그룹이 인바운드 및 아웃바운드 트래픽에 대한 권장 설정으로 구성되어 있는지 확인하세요. 기본적으로 Amazon EKS는 노드 그룹의 인스턴스에 클러스터 보안 그룹을 적용하여 노드와 컨트롤 플레인 간의 통신을 용이하게 합니다. 관리형 노드 그룹의 시작 템플릿에서 사용자 지정 보안 그룹을 지정하는 경우 Amazon EKS는 클러스터 보안 그룹을 추가하지 않습니다.

워커 노드 IAM 권한 확인

워커 노드와 연결된 IAM 인스턴스 역할에 AmazonEKSWorkerNodePolicy 및 AmazonEC2ContainerRegistryReadOnly 정책이 연결되어 있는지 확인하세요.

참고: Amazon 관리형 정책인 AmazonEKS_CNI_Policy를 IAM 역할에 연결해야 합니다. 이를 노드 인스턴스 역할에 연결할 수 있습니다. 그러나 해당 정책을 kube-system 네임스페이스의 aws-node Kubernetes 서비스 계정과 연관된 역할에 연결하는 것이 가장 좋습니다. 자세한 내용은 서비스 계정에 IAM 역할을 사용하도록 Kubernetes용 Amazon VPC CNI 플러그인 구성을 참조하세요.

클러스터용 Amazon VPC가 DNS 호스트 이름 및 확인을 지원하는지 확인

EKS 클러스터 엔드포인트에 대한 프라이빗 액세스를 구성한 후에는 반드시 Amazon VPC의 DNS 호스트 이름 및 DNS 확인을 켜야 합니다. 엔드포인트 프라이빗 액세스를 활성화하면, Amazon EKS에서 Amazon Route 53 프라이빗 호스팅 영역이 생성됩니다. 그러면 Amazon EKS가 이를 클러스터의 Amazon VPC와 연결합니다. 자세한 내용은 Amazon EKS 클러스터 엔드포인트 액세스 제어를 참조하세요.

워커 노드의 NodeInstanceRole을 사용하여 aws-auth ConfigMap을 업데이트

aws-auth ConfigMap이 인스턴스 프로파일이 아닌 워커 노드의 IAM 역할로 올바르게 구성되었는지 확인하세요.

워커 노드의 태그 설정

워커 노드의 Tag(태그) 속성에 대해 key(키)를 Kubernetes.io/cluster/clusterName으로 설정하고 value(값)를 owned(소유됨)로 설정합니다.

워커 노드의 Amazon VPC 서브넷에 사용 가능한 IP 주소가 있는지 확인

Amazon VPC에 IP 주소가 부족한 경우, 보조 CIDR을 기존 Amazon VPC에 연결할 수 있습니다. 자세한 내용은 Amazon EKS VPC 및 서브넷의 요구 사항과 고려 사항을 참조하세요.

Amazon EKS 워커 노드가 클러스터의 API 서버 엔드포인트에 도달할 수 있는지 확인

다음 게이트웨이를 통한 인터넷 경로가 있는 경우, 클러스터 VPC 또는 피어링된 서브넷 내의 모든 서브넷에서 워커 노드를 시작할 수 있습니다.

NAT
인터넷
Transit

워커 노드가 제한된 프라이빗 네트워크에서 시작되는 경우 워커 노드가 Amazon EKS API 서버 엔드포인트에 도달할 수 있는지 확인하세요. 자세한 내용은 Amazon EKS를 아웃바운드 인터넷 액세스 없이 프라이빗 클러스터에서 실행하기 위한 요구 사항을 참조하세요.

참고: NAT 게이트웨이가 지원하는 프라이빗 서브넷에 있는 노드의 경우, 퍼블릭 서브넷에 NAT 게이트웨이를 만드는 것이 가장 좋습니다.

AWS PrivateLink 엔드포인트를 사용하지 않는 경우, 다음 AWS 서비스의 프록시 서버를 통해 API 엔드포인트에 대한 액세스를 확인하세요.

Amazon EC2
Amazon ECR
Amazon S3

워커 노드가 API 서버에 액세스할 수 있는지 확인하려면, SSH를 사용해 워커 노드에 연결하여 다음 netcat 명령을 실행합니다.

nc -vz 9FCF4EA77D81408ED82517B9B7E60D52.yl4.eu-north-1.eks.amazonaws.com 443

참고: 9FCF4EA77D81408ED82517B9B7E60D52.yl4.eu-north-1.eks.amazonaws.com을 API 서버 엔드포인트로 바꿉니다.

다음과 같이 인스턴스에 연결된 상태에서 kubelet 로그를 확인하세요.

journalctl -f -u kubelet

kubelet 로그가 해당 문제의 소스에 대한 정보를 제공하지 않는 경우, 워커 노드에서 kubelet의 상태를 확인하세요.

sudo systemctl status kubelet

추가 문제 해결을 위해 Amazon EKS 로그 및 운영 체제 로그를 수집하세요.

Amazon EC2, Amazon ECR 및 Amazon S3 API 엔드포인트가 귀하의 AWS 리전에 도달할 수 있는지 확인합니다.

SSH를 사용하여 워커 노드 중 하나에 연결한 후 각 서비스에 대해 다음 명령을 실행합니다.

$ nc -vz ec2.region.amazonaws.com 443

$ nc -vz ecr.region.amazonaws.com 443

$ nc -vz s3.region.amazonaws.com 443

**참고:**region(리전)을 워커 노드의 AWS 리전으로 바꿉니다.

워커 노드에 대한 사용자 데이터 구성

지정된 AMI를 사용하는 관리형 노드 그룹의 시작 템플릿의 경우, 워커 노드가 클러스터에 조인할 수 있도록 부트스트랩 명령을 제공해야 합니다. Amazon EKS는 기본 부트스트랩 명령을 사용자 데이터에 병합하지 않습니다. 자세한 내용은 Amazon EKS 관리형 노드 그룹의 시작 템플릿 및 사용자 지정 AMI 지원 소개 및 AMI 지정을 참조하세요.

부트스트랩 명령이 포함된 시작 템플릿의 예시:

#!/bin/bash
set -o xtrace
/etc/eks/bootstrap.sh ${ClusterName} ${BootstrapArguments}

**참고:****${ClusterName}**을 Amazon EKS 클러스터 이름으로 바꿉니다. 필요한 경우 **${BootstrapArguments}**을 추가 부트스트랩 값으로 바꿉니다.