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

8분 분량

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

간략한 설명

워커 노드를 Amazon EKS 클러스터에 조인하려면 다음을 완료해야 합니다.

AWS Systems Manager automation 런북을 사용하여 일반적인 문제를 파악합니다.
Amazon Virtual Private Cloud(VPC)에 대한 DNS 지원이 있는지 확인합니다.
인스턴스 프로파일의 워커 노드에 올바른 권한이 있는지 확인합니다.
워커 노드에 대한 사용자 데이터를 구성합니다.
Amazon VPC 서브넷에 대해 네트워킹이 올바르게 구성되었는지 확인합니다.
워커 노드가 EKS 클러스터와 동일한 VPC에 있는지 확인
aws-auth ConfigMap을 워커 노드의 NodeInstanceRole로 업데이트합니다.
작업자 노드의 보안 그룹 요구 사항을 충족합니다.
작업자 노드에 대한 태그를 설정합니다.
워커 노드가 EKS 클러스터의 API 서버 엔드포인트에 도달할 수 있는지 확인합니다.
EKS 클러스터에 클러스터 역할이 올바르게 구성되었는지 확인합니다.
AWS Security Token Service(AWS STS) 엔드포인트를 지원하는 AWS 리전의 경우, 리전 AWS STS 엔드포인트가 활성화되어 있는지 확인합니다.
AMI가 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 최적화 Linux AMI는 워커 노드를 클러스터에 등록하기 위한 /etc/eks/bootstrap.sh 부트스트랩 스크립트를 포함하여 필요한 모든 구성을 제공합니다.

해결 방법

AWS Systems Manager automation 런북을 사용하여 일반적인 문제를 파악합니다.

AWSSupport-TroubleshootEKSWorkerNode 런북을 사용하여 워커 노드가 클러스터에 결합하지 못하게 하는 일반적인 문제를 찾을 수 있습니다.

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

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

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

DNS 호스트 이름 및 DNS 확인을 포함하는 EKS 클러스터의 Amazon VPC가 활성화되어 있는지 확인합니다.

이러한 특성을 확인하고 켜려면 다음과 같이 하십시오.

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

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

인스턴스 프로파일의 워커 노드에 대한 올바른 권한 얻기

인스턴스 프로파일의 워커 노드와 연결된 역할에 다음 AWS 관리형 정책을 연결합니다.

AmazonEKSWorkerNodePolicy
AmazonEKS_CNI_Policy
AmazonEC2ContainerRegistryReadOnly

역할에 정책을 연결하려면 IAM 자격 증명 권한 추가(콘솔)를 참조하세요.

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

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

관리형 노드 그룹을 사용하여 워커 노드를 시작하는 경우, Amazon EKS에 최적화된 Amazon Linux AMI를 사용하여 사용자 데이터를 구성하지 않아도 됩니다. 사용자 지정 AMI를 사용하여 관리형 노드 그룹을 통해 워커 노드를 시작하는 경우에만 사용자 데이터를 구성해야 합니다.

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

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

필요한 경우 Amazon EKS에 최적화된 Linux/Bottlerocket 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"을 오가는 트래픽을 허용하도록 구성되어 있는지 확인합니다.

워커 노드에 대한 태그 설정

워커 노드의 Tag 속성에서 key를 kubernetes.io/cluster/clusterName으로 설정하고 value를 owned로 설정합니다.

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

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

다음 사항을 고려하세요.

NAT 또는 인터넷 게이트웨이를 통해 API 엔드포인트로 연결되는 경로가 있는 라우팅 테이블과 연결된 서브넷에서 워커 노드를 시작할 수 있습니다.
워커 노드가 제한된 프라이빗 네트워크에서 시작되는 경우에는 워커 노드가 EKS API 서버 엔드포인트에 도달할 수 있는지 확인합니다.
AmazonProvidedDNS 대신, 사용자 지정 DNS를 사용하는 Amazon VPC로 워커 노드를 시작하면 엔드포인트를 해석하지 못할 수 있습니다. 엔드포인트에 대한 퍼블릭 액세스가 비활성화되고 프라이빗 액세스만 활성화된 경우 해석되지 않은 엔드포인트가 발생합니다. 자세한 내용은 Amazon EKS 클러스터 엔드포인트에 대한 DNS 해석 사용을 참조하십시오.

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

클러스터에는 최소 AmazonEKSClusterPolicy 권한이 있는 클러스터 역할이 있어야 합니다. 또한 클러스터의 신뢰 관계가 eks.amazonaws.com 서비스(STS:Assumerole에 대한)를 허용해야 합니다.

예:

{
  "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에 최적화된 Amazon Linux AMI가 아닌 경우 다음 Kubernetes 구성 요소가 활성 상태인지 확인합니다.

kubelet
AWS IAM Authenticator
Docker (Amazon EKS 버전 1.23 및 그 이전)
컨테이너화

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

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

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