워커 노드가 Amazon EKS 클러스터에 조인하지 못한 이유는 무엇입니까?
워커 노드를 Amazon Elastic Kubernetes Service(Amazon EKS) 클러스터에 조인하려고 했습니다. 오류 메시지를 받았거나 노드가 클러스터에 조인하지 않았습니다.
간략한 설명
워커 노드를 Amazon EKS 클러스터에 조인하려고 하면 다음 문제 중 하나가 발생할 수 있습니다.
- EKS 클러스터에서 관리형 노드 그룹을 만들면 관리형 노드 그룹이 생성 실패 상태가 됩니다. 워커 노드는 EKS 클러스터에 조인하지 않으며 ‘Instances failed to join the kubernetes cluster’라는 오류 메시지가 표시됩니다.
- EKS 클러스터에서 관리형 노드 그룹을 업그레이드하면 새 워커 노드가 EKS 클러스터에 조인하지 못합니다.
해결 방법
참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하면 AWS CLI의 오류 해결을 참조하십시오. 또한 최신 AWS CLI 버전을 사용하고 있는지 확인하십시오.
Systems Manager 자동화 런북 사용
AWSSupport-TroubleshootEKSWorkerNode 런북을 사용하여 워커 노드가 클러스터에 조인하지 않는 이유를 확인하십시오.
중요: 자동화가 작동하려면 워커 노드에 AWS Systems Manager에 액세스하고 실행할 수 있는 권한이 있어야 합니다. 권한을 부여하려면 AmazonSSMManagedInstanceCore AWS 관리형 정책을 Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스 프로파일의 AWS Identity and Access Management(IAM) 역할에 연결하십시오. eksctl을 통해 만든 Amazon EKS 관리형 노드 그룹의 기본 구성으로 AmazonSSMManagedInstanceCore 정책을 사용하십시오. 클러스터 이름에는 [-a-zA-Z0-9]{1,100}$ 형식을 사용하십시오.
자동화를 실행하려면 다음 단계를 완료하십시오.
- Systems Manager 콘솔에서 AWSSupport-TroubleshootEKSWorkerNode 런북을 엽니다.
- 참고: 런북에 대한 자세한 내용은 런북의 문서 세부 정보 섹션을 참조합니다.
- AWS 리전을 클러스터와 동일한 리전으로 설정했는지 확인합니다.
- 입력 파라미터 섹션에서 ClusterName 필드에 클러스터 이름을 입력하고 WorkerID 필드에 Amazon EC2 인스턴스 ID를 입력합니다.
- (선택 사항) AutomationAssumeRole 필드에 자동화가 사용자를 대신하여 작업을 수행하도록 허용하는 IAM 역할의 Amazon 리소스 이름(ARN)을 입력합니다. IAM 역할을 지정하지 않으면 자동화는 런북을 시작하는 사용자의 권한을 사용합니다.
- 실행을 선택합니다.
- 출력 섹션을 검토하여 문제의 원인과 문제 해결을 위해 취할 수 있는 단계를 확인합니다.
Amazon VPC에 대한 DNS 지원 확인
Amazon Virtual Private Cloud(Amazon VPC)에서 EKS 클러스터의 DNS 호스트 이름 및 DNS 확인을 활성화했는지 확인합니다.
인스턴스 프로파일의 워커 노드에 올바른 권한이 있는지 확인
인스턴스 프로파일의 워커 노드와 연결된 역할에 다음 AWS 관리형 정책을 연결하십시오.
조직 또는 계정 수준의 권한 경계 또는 서비스 제어 정책(SCP)이 워커 노드의 API 호출을 제한하지 않는지 확인하십시오.
워커 노드에 대한 사용자 데이터 구성
참고: AWS CloudFormation을 사용하여 워커 노드를 시작하는 경우 워커 노드의 사용자 데이터를 구성할 필요가 없습니다. 대신 CloudFormation 콘솔을 사용하여 자체 관리형 Amazon Linux 노드를 시작하십시오.
관리형 노드 그룹을 사용하여 워커 노드를 시작하는 경우 Amazon EKS 최적화 Amazon Linux Amazon Machine Image(AMI)를 통해 사용자 데이터를 구성할 필요가 없습니다. 사용자 지정 AMI를 사용하여 관리형 노드 그룹을 통해 워커 노드를 시작하는 경우에만 사용자 데이터를 구성하십시오.
사용자 지정 시작 템플릿과 함께 Amazon EKS 관리형 노드 그룹을 사용하는 경우 시작 템플릿에 올바른 사용자 데이터를 지정합니다. Amazon EKS 클러스터가 VPC 엔드포인트를 사용하여 연결하는 완전 프라이빗 클러스터인 경우 사용자 데이터를 업데이트해야 합니다. 사용자 데이터에 인증 기관(CA), API 서버 엔드포인트 및 DNS 클러스터 IP 주소를 지정합니다.
사용자 데이터 구성 예시:
#!/bin/bash set -ex B64_CLUSTER_CA=CA-CERT API_SERVER_URL=ENDPOINT K8S_CLUSTER_DNS_IP=IP-ADDRESS /etc/eks/bootstrap.sh ${ClusterName} ${BootstrapArguments} —b64-cluster-ca $B64_CLUSTER_CA —apiserver-endpoint $API_SERVER_URL —dns-cluster-ip $K8S_CLUSTER_DNS_I
참고: CA-CERT, ENDPOINT, IP-ADDRESS를 인스턴스 값으로 바꾸십시오. 또한 필요한 경우 **${ClusterName}**을 EKS 클러스터 이름으로 바꾸고 **${BootstrapArguments}**를 추가 부트스트랩 값으로 바꾸십시오.
Amazon EKS에 최적화된 Linux/Bottlerocket AMI의 bootstrap.sh 파일에 인수를 전달하기 위해 사용자 데이터를 제공해야 하는 경우 시작 템플릿의 ImageField에 AMI ID를 지정하십시오.
워커 노드에 대한 사용자 데이터를 구성하려면 EC2 인스턴스를 시작할 때 사용자 데이터를 지정합니다.
예를 들어 Terraform과 같은 타사 도구를 사용하는 경우 사용자 데이터 필드를 업데이트하여 EKS 워커 노드를 시작하십시오.
사용자 데이터 구성 예시:
#!/bin/bash set -o xtrace /etc/eks/bootstrap.sh ${ClusterName} ${BootstrapArguments}
참고: 필요한 경우 **${ClusterName}**을 EKS 클러스터 이름으로 바꾸고 **${BootstrapArguments}**를 추가 부트스트랩 값으로 바꾸십시오.
Amazon Linux 2023 AMI를 사용하는 경우 다음 형식으로 사용자 데이터에 필요한 최소 파라미터를 추가합니다.
MIME-Version: 1.0Content-Type: multipart/mixed; boundary="//" --// Content-Type: application/node.eks.aws --- apiVersion: node.eks.aws/v1alpha1 kind: NodeConfig spec: cluster: apiServerEndpoint: https://example.com certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk= cidr: 10.100.0.0/16 name: my-cluster --//--
Amazon VPC 서브넷의 네트워킹을 올바르게 구성했는지, 워커 노드가 EKS 클러스터와 동일한 Amazon VPC에 있는지 확인
인터넷 게이트웨이를 사용하는 경우 라우팅 테이블에 올바르게 연결했는지 확인하십시오.
NAT 게이트웨이를 사용하는 경우 퍼블릭 서브넷에 올바르게 구성했는지 확인하십시오. 또한 라우팅 테이블을 올바르게 구성했는지 확인하십시오.
완전 프라이빗 클러스터에 VPC 프라이빗 엔드포인트를 사용하는 경우 다음 인터페이스 엔드포인트가 있는지 확인하십시오.
- com.amazonaws.region.ec2
- com.amazonaws.region.ecr.api
- com.amazonaws.region.ecr.dkr
- com.amazonaws.region.sts
또한 게이트웨이 엔드포인트인 com.amazonaws.region.s3가 있는지 확인하십시오.
Amazon ECR에 대한 Amazon Simple Storage Service(Amazon S3) 게이트웨이 VPC 엔드포인트 정책을 제한할 수 있습니다. 자세한 내용은 Amazon ECR에 대한 최소 Amazon S3 버킷 권한을 참조하십시오.
서비스 계정의 IAM 역할로 구성하는 포드는 AWS Security Token Service(AWS STS) API 호출에서 자격 증명을 가져옵니다. 아웃바운드 인터넷 액세스가 없는 경우 VPC에서 AWS STS VPC 엔드포인트를 만들어 사용해야 합니다.
VPC 엔드포인트의 보안 그룹에는 포트 443으로부터의 트래픽을 허용하는 인바운드 규칙이 있어야 합니다. 자세한 내용은 보안 그룹을 사용하여 AWS 리소스에 대한 트래픽 제어를 참조하십시오.
VPC 엔드포인트에 연결된 정책에 특정 서비스에 대한 API 호출을 수행하는 데 필요한 권한이 있는지 확인하십시오.
EKS 클러스터의 네트워킹 섹션에서 클러스터와 연결된 서브넷을 식별합니다. 동일한 VPC에 속하는지 확인합니다.
사용하는 AWS 서비스마다 별도의 엔드포인트를 만들어야 합니다. 일반 AWS 서비스의 엔드포인트 목록은 포드 요구 사항에 나온 표를 참조하십시오. 사용 사례에 따라 엔드포인트 서비스를 만들 수도 있습니다.
또한 워커 노드를 시작할 여러 서브넷을 구성할 수 있습니다. 서브넷은 동일한 Amazon VPC에 있어야 하며 서브넷에 적절하게 태그를 지정해야 합니다. Amazon EKS는 클러스터를 만드는 중에 구성한 서브넷에 대한 태그만 자동으로 관리합니다. 자세한 내용은 서브넷 요구 사항 및 고려 사항을 참조하십시오.
워커 노드의 NodeInstanceRole을 사용하여 aws-auth ConfigMap 업데이트
인스턴스 프로파일이 아닌 워커 노드의 IAM 역할로 aws-auth ConfigMap을 올바르게 구성했는지 확인합니다.
다음 명령을 실행합니다.
kubectl describe configmap -n kube-system aws-auth
aws-auth ConfigMap을 올바르게 구성하지 않은 경우 다음과 같은 오류 메시지가 표시됩니다.
"571 reflector.go:153] k8s.io/kubernetes/pkg/kubelet/kubelet.go:458 : Failed to list *v1.Node: Unauthorized"
EKS API 인증 방법을 사용하는 경우 NodeInstanceRole에 대한 액세스 항목을 만드십시오. 유형에서 EC2_linux를 선택합니다.
워커 노드의 보안 그룹 요구 사항 충족
인바운드 및 아웃바운드 트래픽에 필요한 설정으로 컨트롤 플레인의 보안 그룹과 워커 노드 보안 그룹을 구성했는지 확인합니다. 또한 포트 80, 443 및 1025-65535에 대해 0.0.0.0/0으로 들어오고 나가는 트래픽을 허용하도록 네트워크 액세스 제어 목록(네트워크 ACL) 규칙을 구성했는지 확인하십시오.
워커 노드의 태그 설정
워커 노드의 태그 속성에 대해 키를 Kubernetes.io/cluster/clusterName으로 설정하고 값을 소유됨으로 설정합니다.
자세한 내용은 VPC 요구 사항 및 고려 사항을 참조하십시오.
워커 노드가 EKS 클러스터의 API 서버 엔드포인트에 도달할 수 있는지 확인
NAT 또는 인터넷 게이트웨이를 통해 API 엔드포인트로 라우팅되는 라우팅 테이블과 연결된 서브넷에서 워커 노드를 시작합니다. 제한된 프라이빗 네트워크에서 워커 노드를 시작하는 경우 워커 노드가 EKS API 서버 엔드포인트에 도달할 수 있는지 확인합니다. AmazonProvidedDNS 대신 사용자 지정 DNS를 사용하는 Amazon VPC에서 워커 노드를 시작하는 경우 워커 노드가 엔드포인트를 확인하지 못할 수 있습니다.
참고: 엔드포인트에 대한 퍼블릭 액세스를 비활성화하고 프라이빗 액세스만 활성화하면 엔드포인트가 확인되지 않습니다. 자세한 내용은 Amazon EKS 클러스터 엔드포인트의 DNS 확인 사용을 참조하십시오.
kubelet이 필요한 엔드포인트에 도달할 수 있는지 확인
다음 명령을 실행하여 kubelet이 엔드포인트에 도달할 수 있는지 테스트합니다.
$ nc -vz ec2.region.amazonaws.com 443
$ nc -vz dkr.ecr.region.amazonaws.com 443
$ nc -vz api.ecr.region.amazonaws.com 443
$ nc -vz s3.region.amazonaws.com 443
참고: region을 해당 리전으로 바꾸십시오.
클러스터 역할을 올바르게 구성했는지 확인
AmazonEKSClusterPolicy를 Amazon EKS 클러스터 IAM 역할에 연결해야 합니다. 또한 클러스터의 신뢰 관계가 sts:AssumeRole에 대한 eks.amazonaws.com 서비스를 허용해야 합니다.
신뢰 정책 예시:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "eks.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
리전 STS 엔드포인트를 활성화했는지 확인
클러스터가 STS 엔드포인트를 지원하는 리전에 있는 경우 리전 STS 엔드포인트를 활성화하여 kubelet을 인증합니다. 그러면 kubelet이 노드 객체를 생성할 수 있습니다.
EKS와 함께 작동하도록 AMI를 구성했는지, AMI에 필수 구성 요소가 포함되어 있는지 확인
Amazon EKS에 최적화된 Amazon Linux AMI에는 EKS 클러스터와 함께 작동하는 데 필요한 구성 요소가 포함되어 있습니다. 워커 노드의 AMI가 Amazon EKS에 최적화된 Amazon Linux AMI가 아닌 경우 다음 Kubernetes 구성 요소가 활성 상태인지 확인합니다.
- kubelet
- AWS IAM 인증기
- 도커(Amazon EKS 버전 1.23 이하)
- containerd
SSH를 사용하여 EKS 워커 노드 인스턴스에 연결하고 kubelet 에이전트 로그 확인
kubelet 에이전트를 EKS 워커 노드 인스턴스에서 systemd 서비스로 구성했는지 확인하십시오.
kubelet 로그를 검증하려면 다음 명령을 실행합니다.
journalctl -f -u kubelet
문제를 해결하려면 Amazon EKS 클러스터 및 노드 관련 문제 해결을 참조하십시오.
Amazon EKS 로그 수집기 스크립트를 사용하여 오류 해결
로그 파일 및 운영 체제(OS) 로그를 사용하여 Amazon EKS 클러스터의 문제를 해결하십시오. Amazon EKS 클러스터 워커 노드는 cloud-init 초기화 로그를 /var/log/cloud-init-output.log 및 /var/log/cloud-init.log 파일에 저장합니다.
EKS 로그 수집기 스크립트를 사용하여 로그를 수집하려면 SSH를 사용하여 문제가 있는 워커 노드에 연결해야 합니다. 그 후 다음 스크립트를 실행합니다.
curl -O https://raw.githubusercontent.com/awslabs/amazon-eks-ami/master/log-collector-script/linux/eks-log-collector.sh sudo bash eks-log-collector.sh
워커 노드의 Amazon VPC 서브넷에 사용 가능한 IP 주소가 있는지 확인
Amazon VPC에 사용 가능한 IP 주소가 없는 경우 보조 CIDR을 기존 Amazon VPC에 연결할 수 있습니다. 자세한 내용은 VPC 및 서브넷에 대한 Amazon EKS 네트워킹 요구 사항 보기를 참조하십시오. EKS 최적화 AMI에는 EKS 클러스터와 함께 작동하는 데 필요한 구성 요소가 포함되어 있습니다.
- 언어
- 한국어
관련 콘텐츠
질문됨 2년 전
