워커 노드를 Amazon EKS 클러스터에 연결하려면 어떻게 해야 합니까?

7분 분량

워커 노드가 Amazon Elastic Kubernetes Service(Amazon EKS) 클러스터에 연결되지 않습니다. 이 문제를 해결하고 싶습니다.

해결 방법

워커 노드를 Amazon EKS 클러스터에 조인하려면 다음 단계를 완료하십시오.

중요: 다음 단계에는 다음 기준이 충족되지 않는 환경에서 워커 노드를 등록하는 데 필요한 구성이 포함되지 않습니다.

클러스터용 가상 프라이빗 클라우드(VPC)에서 domain-name-servers 구성 파라미터는 AmazonProvidedDNS로 설정됩니다. 자세한 내용은 Amazon Virtual Private Cloud(Amazon VPC)의 DHCP 옵션 세트를 참조하십시오.
Amazon EKS에 최적화된 Linux Amazon Machine Image (AMI)를 사용하여 워커 노드를 시작하고 있습니다. Amazon EKS 최적화 Linux AMI는 /etc/eks/bootstrap.sh 부트스트랩 스크립트를 포함하여 워커 노드를 클러스터에 등록하는 데 필요한 모든 구성을 제공합니다.

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

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

중요: 자동화가 올바르게 작동하려면 AWS Systems Manager가 실행 중이어야 하며 워커 노드에 Systems Manager에 액세스할 수 있는 권한이 있어야 합니다. AWS Systems Manager에 액세스 권한을 부여하려면 AmazonSSMManagedInstanceCore 정책을 AWS Identity and Access Management(IAM) 역할에 연결합니다. 이 IAM 역할은 Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스 프로파일에 해당합니다. 이 구성은 eksctl을 통해 생성하는 Amazon EKS 관리형 노드 그룹의 기본값이기도 합니다.

클러스터 이름에는**[-a-zA-Z0-9]{1,100}$** 형식을 사용합니다.

다음 단계를 완료하십시오.

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

Amazon VPC에 대한 DNS 지원이 있는지 확인

EKS 클러스터용 Amazon VPC에 DNS 호스트 이름과 DNS 해결이 켜져 있는지 확인합니다.

이러한 특성을 확인하고 켜려면 다음 단계를 완료하십시오.

Amazon VPC 콘솔을 엽니다.
탐색 창에서 내 VPC를 선택합니다.
편집할 VPC를 선택합니다.
세부 정보 탭에서 DNS 호스트 이름과 DNS 확인이 켜져 있는지 확인합니다.
켜져 있지 않은 경우 두 속성 모두에 대해 활성화를 선택합니다.
변경 사항 저장을 선택합니다.

자세한 내용은 VPC에서 DNS 속성 보기 및 업데이트를 참조하십시오.

인스턴스 프로필의 워커 노드에 올바른 권한이 있는지 확인

다음 AWS 관리형 정책을 인스턴스 프로필의 워커 노드와 연결된 역할에 연결하십시오:

AmazonEKSWorkerNodePolicy
AmazonEKS_CNI_Policy
AmazonEC2ContainerRegistryReadOnly

정책을 역할에 연결하려면 IAM 자격 권한 추가(콘솔)를 참조하십시오.

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

참고: AWS CloudFormation을 사용하여 워커 노드를 시작하는 경우 워커 노드에 대한 사용자 데이터를 구성할 필요가 없습니다. 대신 AWS Management Console에서 자체 관리형 Amazon Linux 노드 시작 지침을 따르십시오.

관리형 노드 그룹을 사용하여 워커 노드를 시작하는 경우 Amazon EKS 최적화 Amazon Linux AMI를 사용하여 사용자 데이터를 구성할 필요가 없습니다. 사용자 지정 AMI를 사용하여 관리형 노드 그룹을 통해 워커 노드를 시작하는 경우에만 사용자 데이터를 구성해야 합니다.

사용자 지정 시작 템플릿과 함께 Amazon 관리형 노드 그룹을 사용하는 경우 시작 템플릿에 올바른 사용자 데이터를 지정합니다. Amazon EKS 클러스터가 VPC 엔드포인트를 사용하여 연결하는 완전 프라이빗 클러스터인 경우 사용자 데이터에 다음을 지정합니다.

certificate-authority
api-server-endpoint
DNS 클러스터 IP 주소

필요한 경우 사용자 데이터를 제공하여 Amazon EKS에 최적화된 Linux/Botlerocket AMI에 포함된 bootstrap.sh 파일에 인수를 전달합니다.

워커 노드에 대한 사용자 데이터를 구성하려면 Amazon EC2 인스턴스를 시작할 때 사용자 데이터를 지정해야 합니다.

예를 들어 Terraform과 같은 타사 도구를 사용하는 경우 사용자 데이터 필드를 업데이트하여 EKS 워커 노드를 시작하십시오.

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

중요:

**${ClusterName}**을 EKS 클러스터 이름으로 바꿉니다.
**${BootstrapArguments}**를 추가 부트스트랩 값으로 바꾸거나 이 속성을 비워 두십시오.

Amazon VPC 서브넷에 대해 네트워킹이 올바르게 구성되었는지 확인

인터넷 게이트웨이를 사용하는 경우 null 경로로 리디렉션되지 않고 경로 테이블에 올바르게 연결되어 있는지 확인합니다.
NAT 게이트웨이를 사용하는 경우 퍼블릭 서브넷에 올바르게 구성되어 있는지 확인합니다. 또한 경로 테이블에 null 경로가 포함되어 있지 않은지 확인합니다.
완전 프라이빗 클러스터에 VPC 프라이빗 엔드포인트를 사용하는 경우 다음 엔드포인트가 있어야 합니다.
com.amazonaws.region.ec2(인터페이스 엔드포인트)
com.amazonaws.region.ecr.api (인터페이스 엔드포인트)
com.amazonaws.region.ecr.dkr (인터페이스 엔드포인트)
com.amazonaws.region.s3 (게이트웨이 엔드포인트)
com.amazonaws.region.sts (인터페이스 엔드포인트)
서비스 계정용 IAM 역할로 구성한 포드는 AWS Security Token Service (AWS STS) API 호출에서 자격 증명을 획득합니다. 아웃바운드 인터넷 액세스가 없는 경우 VPC에서 AWS STS VPC 엔드포인트를 생성하여 사용해야 합니다.
VPC 엔드포인트의 보안 그룹에는 포트 443으로부터의 트래픽을 허용하는 인바운드 규칙이 있어야 합니다. 자세한 내용은 보안 그룹을 사용하여 AWS 리소스에 대한 트래픽 제어를 참조하세요.
VPC 엔드포인트에 연결된 정책에 필요한 권한이 있는지 확인합니다.

참고: 다른 AWS 서비스를 사용하는 경우 해당 엔드포인트를 만들어야 합니다. 일반적으로 사용되는 몇 가지 서비스 및 엔드포인트를 검토하려면 인터넷 액세스가 제한된 프라이빗 클러스터 배포를 참조하십시오. 또한 사용 사례에 따라 엔드포인트 서비스를 만들 수도 있습니다.

워커 노드가 EKS 클러스터와 동일한 Amazon VPC에 있는지 확인

다음 단계를 완료하십시오.

Amazon EKS 콘솔을 엽니다.
클러스터를 선택한 다음 클러스터를 선택합니다.
네트워킹 섹션에서 클러스터와 연결된 서브넷을 식별합니다.

**참고:**워커 노드를 시작할 여러 서브넷을 구성할 수 있습니다. 서브넷은 동일한 Amazon VPC에 있어야 하며 적절하게 태그가 지정되어야 합니다. Amazon EKS는 클러스터 생성 중에 구성한 서브넷에 대한 태그만 자동으로 관리합니다. 따라서 서브넷에 적절한 태그를 지정해야 합니다.

자세한 내용은 서브넷 요구 사항 및 고려 사항을 참조하십시오.

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

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

워커 노드의 보안 그룹 요구 사항 충족

컨트롤 플레인의 보안 그룹과 워커 노드 보안 그룹이 인바운드 및 아웃바운드 트래픽에 대한 모범 사례 설정으로 구성되어 있는지 확인합니다. 또한 사용자 지정 네트워크 ACL 규칙이 포트 80, 443, 및 1025-65535에 대해 0.0.0.0/0으로 트래픽이 들어 오고 나갈 수 있도록 구성되어 있는지 확인합니다.

워커 노드의 태그 설정

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

자세한 내용은 VPC 요구 사항 및 고려 사항을 참조하십시오.

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

경로 테이블과 연결된 서브넷에서 워커 노드를 시작할 수 있는지 확인합니다. 라우팅 테이블은 NAT 또는 인터넷 게이트웨이를 통해 API 엔드포인트로 라우팅해야 합니다.

제한된 사설망에서 워커 노드를 시작하는 경우 워커 노드가 EKS API 서버 엔드포인트에 도달할 수 있는지 확인합니다.

AmazonProvidedDNS 대신 사용자 지정 DNS를 사용하는 Amazon VPC를 사용하여 워커 노드를 시작하면 노드가 엔드포인트를 확인하지 못할 수 있습니다. 엔드포인트에 대한 퍼블릭 액세스가 비활성화되면 해결되지 않은 엔드포인트가 발생하며 프라이빗 액세스만 활성화됩니다. 자세한 내용은 Amazon EKS 클러스터 엔드포인트의 DNS 해상도 켜기를 참조하십시오.

클러스터 역할이 클러스터에 맞게 구성되었는지 확인

클러스터에는 최소 AmazonEKSClusterPolicy 권한이 있는 클러스터 역할이 있어야 합니다. 또한 클러스터의 신뢰 관계는 다음 예제와 같이 sts:AssumeRole에 대한 eks.amazonaws.com 서비스를 허용해야 합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "eks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

자세한 내용은 Amazon EKS 클러스터 IAM 역할을 참조하십시오.

지역 STS 엔드포인트가 활성화되었는지 확인

클러스터가 STS 엔드포인트를 지원하는 리전에 있는 경우 리전 STS 엔드포인트를 활성화하여 kubelet을 인증합니다. 그러면 kubelet이 노드 오브젝트를 생성할 수 있습니다.

AMI가 EKS와 함께 작동하도록 구성되어 있고 필요한 구성 요소가 포함되어 있는지 확인

워커 노드에 사용되는 AMI가 Amazon EKS optimized Amazon Linux AMI가 아닌 경우 다음 쿠버네티스 구성 요소가 활성 상태인지 확인합니다.

kubelet
AWS IAM 인증기
도커(Amazon EKS 버전 1.23 이하)
컨테이너

SSH를 사용하여 EKS 워커 노드 인스턴스에 연결하고 kubelet 에이전트 로그 확인

kubelet 에이전트는 시스템 서비스로 구성되어 있습니다.

kubelet 로그의 유효성을 검사하려면 다음 명령을 실행합니다.

journalctl -f -u kubelet

문제를 해결하려면 Amazon EKS 문제 해결 가이드에서 일반적인 오류를 확인하십시오.

Amazon EKS 로그 수집기 스크립트를 사용하여 오류 해결

로그 파일 및 운영 체제 로그를 사용하여 Amazon 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