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

7분 분량

워커 노드가 Amazon Elastic Kubernetes Service(Amazon EKS) 클러스터에 연결되지 않습니다.

간략한 설명

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

AWS Systems Manager automation 런북을 사용하여 일반적인 문제를 식별하십시오.
Amazon Virtual Private Cloud (Amazon VPC)에 대한 DNS 지원이 있는지 확인하십시오.
인스턴스 프로필의 워커 노드에 올바른 권한이 있는지 확인합니다.
워커 노드의 사용자 데이터를 구성합니다.
Amazon VPC 서브넷에 대해 네트워킹이 올바르게 구성되어 있는지 확인하십시오.
워커 노드가 EKS 클러스터와 동일한 VPC에 있는지 확인합니다.
워커 노드의 NodeInstanceRole을 사용하여 aws-auth ConfigMap을 업데이트하십시오.
워커 노드의 보안 그룹 요구 사항을 충족합니다.
워커 노드의 태그를 설정합니다.
워커 노드가 EKS 클러스터의 API 서버 엔드포인트에 도달할 수 있는지 확인합니다.
클러스터 역할이 EKS 클러스터에 맞게 구성되었는지 확인합니다.
AWS Security Token Service (AWS STS) 엔드포인트를 지원하는 AWS 리전의 경우 리전 AWS STS 엔드포인트가 활성화되었는지 확인하십시오.
AMI가 Amazon EKS와 함께 작동하도록 구성되고 필수 구성 요소가 포함되어 있는지 확인하십시오.
SSH를 사용하여 워커 노드의 Amazon Elastic Compute Cloud (Amazon EC2) 인스턴스에 연결한 다음 kubelet 에이전트 로그를 통해 오류를 검색합니다.
Amazon EKS 로그 수집기 스크립트를 사용하여 오류를 해결하십시오.

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

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

해결 방법

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

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

중요: 자동화가 작동하려면 워커 노드에 Systems Manager에 액세스할 수 있는 권한이 있어야 하며 Systems Manager가 실행 상태여야 합니다. 이 권한을 부여하려면 AmazonSSMManagedInstanceCore 정책을 AWS Identity and Access Management (IAM) 역할에 연결하십시오. Amazon EC2 인스턴스 프로필에 해당하는 IAM 역할입니다. 이는 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 optimized 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 서브넷에 대해 네트워킹이 올바르게 구성되었는지 확인하십시오

인터넷 게이트웨이를 사용하는 경우 블랙홀 없이 라우팅 테이블에 올바르게 연결되었는지 확인하십시오.
NAT 게이트웨이를 사용하는 경우 퍼블릭 서브넷에 올바르게 구성되어 있는지 확인하십시오. 또한 라우팅 테이블에 블랙홀이 없는지 확인하십시오.
완전 프라이빗 클러스터에 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으로부터의 트래픽을 허용하는 인바운드 규칙이 있어야 합니다. 자세한 내용은 보안 그룹을 사용하여 리소스에 대한 트래픽 제어를 참조하십시오.
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가 아닌 경우 다음 쿠버네티스 구성 요소가 활성 상태인지 확인하십시오:

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

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

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

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

journalctl -f -u kubelet

2. 문제를 해결하려면 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