Amazon EKS 클러스터와 노드 그룹의 eksctl 문제를 해결하려면 어떻게 해야 하나요?

간략한 설명

eksctl을 사용하여 Amazon EKS 클러스터나 노드 그룹을 생성 또는 관리할 때 발생할 수 있는 보편적인 문제는 다음과 같습니다.

• eksctl로 클러스터를 생성하는 방법을 모릅니다. Amazon EKS 클러스터 생성의 Amazon EKS 시작하기 - eksctl과 eksctl 섹션을 참조하세요.
• 관리형 노드 그룹의 kubelet 부트스트랩 옵션을 지정하는 방법을 모릅니다. kubelet 부트스트랩 옵션 지정 해결 방법 섹션의 단계를 따르세요.
• 기존 노드 그룹의 인스턴스 유형을 변경하는 방법을 모릅니다. 새 노드 그룹을 생성해야 합니다. 새 노드 그룹으로 마이그레이션과 Nodegroup immutability(노드 그룹 불변성 - eksctl 웹 사이트에서)을 참조하세요.
• AWS 리소스 최대 수에 도달했습니다. 리소스를 확인하여 사용하지 않는 것을 삭제할 수 있는지 확인합니다. 그래도 용량이 더 필요한 경우, 할당량 증가 요청을 참조하세요.
• 용량이 제한된 가용 영역에서 컨트롤 플레인 인스턴스를 시작합니다. Amazon EKS에서 클러스터 생성 오류를 해결하려면 어떻게 해야 하나요?를 참조하세요.
• 노드가 Ready(준비) 상태로 이동되지 못합니다. 작업 제한 시간 문제 해결 해결 방법 섹션의 단계를 따르세요.
• 클러스터에 대하여 내보내기 값이 존재하지 않습니다. 프라이빗 서브넷에 노드 그룹 생성 해결 방법 섹션의 단계를 따르세요.
• 지원되지 않는 인스턴스 유형을 사용하여 클러스터나 노드 그룹을 생성했습니다. 인스턴스 유형이 지원되는지 확인 해결 방법 섹션의 단계를 따르세요.

해결 방법

kubelet 부트스트랩 옵션 지정

기본적으로 eksctl이 부트스트랩 스크립트를 하나 만들어 부트스트랩 프로세스 동안 작업자 노드가 실행하는 시작 템플릿에 이를 추가합니다. 자체적인 kubelet 부트스트랩 옵션을 지정하려면 overrideBootstrapCommand 지정을 사용하여 eksctl 부트스트랩 스크립트를 재정의합니다. 관리형 및 자체 관리형 노드 그룹에는 overrideBootstrapCommand를 사용합니다.

구성 파일 지정:

managedNodeGroups:
  name: custom-ng
  ami: ami-0e124de4755b2734d
  securityGroups:
    attachIDs: ["sg-1234"]
  maxPodsPerNode: 80
  ssh:
    allow: true
  volumeSize: 100
  volumeName: /dev/xvda
  volumeEncrypted: true
  disableIMDSv1: true
  overrideBootstrapCommand: |
  #!/bin/bash
  /etc/eks/bootstrap.sh managed-cluster --kubelet-extra-args '--node-labels=eks.amazonaws.com/nodegroup=custom-ng,eks.amazonaws.com/nodegroup-image=ami-0e124de4755b2734d'

참고: overrideBootstrapCommand는 사용자 지정 AMI를 사용하는 경우에만 쓸 수 있습니다. AMI ID를 지정하지 않으면 클러스터 생성이 실패합니다.

사용자 지정 AMI ID가 지정되지 않음

관리형 노드 그룹을 생성할 때 사용자 지정 AMI ID를 지정하지 않으면 기본적으로 Amazon EKS는 Amazon EKS 최적화 AMI와 부트스트랩 스크립트를 사용합니다. 사용자 지정 사용자 데이터와 함께 Amazon EKS 최적화 AMI를 사용하여 부트스트랩 파라미터를 지정하려면 관리형 노드 그룹 구성에서 AMI ID를 지정합니다.

최신 Amazon EKS 최적화 AMI의 최신 AMI ID를 가져오려면 다음 명령을 실행합니다.

aws ssm get-parameter --name /aws/service/eks/optimized-ami/1.21/amazon-linux-2/recommended/image_id --region Region --query "Parameter.Value" --output text

참고: region을 사용자의 AWS 리전으로 바꿉니다.

작업 제한 시간 문제 해결

노드를 생성할 때 다음 오류가 발생하면 노드 그룹에 시간 초과 문제가 있을 수 있습니다.

waiting for at least 1 node(s) to become ready in "nodegroup"

eksctl을 사용하여 EKS 노드 그룹을 생성하면 eksctl CLI가 API 서버에 연결하여 Kubernetes 노드 상태를 지속적으로 확인합니다. CLI는 노드가 준비(Ready) 상태로 이동하도록 기다리며 노드가 이동에 실패하면 결국은 제한 시간이 초과됩니다.

노드가 준비(Ready) 상태로 이동하지 못하는 이유는 다음과 같습니다.

• kubelet이 부트스트래핑 프로세스 동안 EKS API 서버 엔드포인트와 통신하거나 인증을 주고받지 못합니다.
• aws-node와 kube-proxy 포드가 실행 중(Running) 상태가 아닙니다.
• Amazon Elastic Compute Cloud(Amazon EC2) 작업자 노드 사용자 데이터가 성공적으로 실행되지 않았습니다.

kubelet이 EKS API 서버 엔드포인트와 통신할 수 없음

부트스트래핑 프로세스 동안 kubelet이 EKS API 서버 엔드포인트와 통신할 수 없으면 EKS API 서버 엔드포인트를 가져옵니다.

작업자 노드에서 다음과 같은 명령을 실행합니다.

curl -k https://123456DC0A12EC12DE0C12BC312FCC1A.yl4.us-east-1.eks.amazonaws.com
{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {
    
  },
  "status": "Failure",
  "message": "forbidden: User \"system:anonymous\" cannot get path \"/\"",
  "reason": "Forbidden",
  "details": {
    
  },
  "code": 403
}

앞선 명령이 HTTP 403 상태 코드를 반환해야 합니다. 명령이 제한 시간을 초과하는 경우, EKS API 서버와 작업자 노드 사이에 네트워크 연결 문제가 있을 가능성이 있습니다.

연결 문제를 해결하려면 다음 단계 중 사용 사례와 관련 있는 단계를 완료하면 됩니다.

• 작업자 노드가 프라이빗 서브넷에 속한 경우, EKS API 서버 엔드포인트가 프라이빗 또는 퍼블릭 및 프라이빗 액세스 모드인지 확인합니다.
• EKS API 서버 엔드포인트가 프라이빗으로 설정된 경우, 프라이빗 호스팅 영역에 특정 규칙을 적용해야만 트래픽을 API 서버로 라우팅할 수 있습니다. Amazon Virtual Private Cloud(Amazon VPC) 속성 enableDnsHostnames와 enableDnsSupport가 True로 설정되어 있어야 합니다. 또한 Amazon VPC에 대하여 설정된 DHCP 옵션의 도메인 목록에 AmazonProvideDNS를 포함해야 합니다.
• 퍼블릭 서브넷에서 노드 그룹을 생성한 경우, 해당 서브넷의 IPv4 퍼블릭 주소 속성이 True로 설정되어 있어야 합니다. 속성을 True로 설정하지 않으면 작업자 노드가 퍼블릭 IP 주소에 할당되지 않으며 인터넷에 액세스할 수 없습니다.
• Amazon EKS 클러스터 보안 그룹이 작업자 노드 보안 그룹에서 포트 443으로 수신 요청을 허용하는지 확인합니다.

kubelet이 EKS API 서버 엔드포인트와 인증을 주고받을 수 없음

부트스트래핑 프로세스 동안 kubelet이 EKS API 서버 엔드포인트와 인증을 주고받지 못하는 경우, 다음 단계를 완료하세요.

1.    다음 명령을 실행하여 작업자 노드에 STS 엔드포인트에 대한 액세스 권한이 있는지 확인합니다.

telnet sts.region.amazonaws.com 443

참고: region을 사용자의 AWS 리전으로 바꿉니다.

2.    워커 노드의 AWS Identity and Access Management(IAM) 역할을 aws-auth ConfigMap에 추가했는지 확인하세요.

예를 들면 다음과 같습니다.

apiVersion:v1 kind:ConfigMap metadata:name:aws-auth namespace:kube-system data:mapRoles:|
    - rolearn: ARN of instance role (not instance profile)
      username: system:node:{EC2PrivateDNSName}}
      groups:
        - system:bootstrappers
        - system:nodes

참고: Microsoft Windows 노드 그룹의 경우, 노드 그룹 IAM 역할의 mapRoles 섹션에 eks:kube-proxy-windows RBAC 그룹을 하나 더 추가해야 합니다.

aws-node와 kube-proxy 포드가 실행 중(Running) 상태가 아님

aws-node와 kube-proxy 포드가 실행 중(Running) 상태인지 아닌지 확인하려면 다음과 같은 명령을 실행합니다.

kubectl get pods -n kube-system

aws-node 포드가 실패(Failing) 상태인 경우, 작업자 노드와 Amazon EC2 엔드포인트 사이의 연결 상태를 확인합니다.

ec2.region.amazonaws.com

참고: region을 사용자의 AWS 리전으로 바꿉니다.

AWS 관리형 정책 AmazonEKSWorkerNodePolicy와 AmazonEC2ContainerRegistryReadOnly가 노드 그룹의 IAM 역할에 연결되어 있는지 확인합니다.

노드가 프라이빗 서브넷에 있는 경우 Amazon Elastic Container Registry(Amazon ECR)에서 이미지 가져오기를 허용하도록 Amazon ECR VPC 엔드포인트를 구성합니다.

Amazon VPC CNI에 IRSA를 사용하는 경우 aws-node 포드가 사용하는 IAM 역할에 AmazonEKS_CNI_Policy AWS 관리형 정책을 연결합니다. 또한 노드 그룹에서 IRSA가 없는 IAM 역할에도 이 정책을 연결해야 합니다.

EC2 작업자 노드 사용자 데이터가 성공적으로 실행되지 않음

사용자 데이터를 실행했을 때 오류가 발생했는지 확인하려면 /var/log/cloud-init.log와 /var/log/cloud-init-output.log의 cloud-init 로그를 검토합니다.

더 자세한 정보가 필요하면 워커 노드에서 EKS 로그 수집기 스크립트를 실행합니다.

프라이빗 서브넷에 노드 그룹 생성

노드 그룹을 생성할 때 다음 오류가 발생하면 프라이빗 서브넷에 노드 그룹을 생성하세요.

No export named eksctl--cluster::SubnetsPublic found. Rollack requested by user

Amazon EKS 클러스터를 PrivateOnly 네트워킹으로 생성한 경우, AWS CloudFormation이 퍼블릭 서브넷을 생성할 수 없습니다. 즉 퍼블릭 서브넷에 대한 내보내기 값이 존재하지 않는다는 뜻입니다. 클러스터에 내보내기 값이 존재하지 않으면 노드 그룹 생성이 실패합니다.

이 문제를 해결하려면 eksctl 인라인 명령을 사용할 때 --node-private-networking 플래그를 포함하면 됩니다. 또한 프라이빗 서브넷에서 노드 그룹 생성을 요청할 때 노드 그룹 구성 내부의 privateNetworking: true 지정을 사용할 수도 있습니다.

eksctl 버전을 업데이트하거나 올바른 AWS 리전 지정

다음 오류가 표시되면 AWS 리전을 확인하세요.

no eksctl-managed CloudFormation stacks found for "cluster-name"

0.40.0보다 앞선 버전의 eksctl을 사용할 경우 eksctl로 생성한 Amazon EKS 리소스만 조회하거나 관리할 수 있습니다. eksctl로 생성하지 않은 리소스를 관리하려면 eksctl을 0.40.0 이후 버전으로 업데이트해야 합니다. eksctl로 생성하지 않은 클러스터에 대하여 실행 가능한 명령에 대해 알아보려면 eksctl로 생성하지 않은 클러스터(eksctl 웹 사이트에서)를 참조하세요.

또한 AWS 리전을 잘못 지정하면 eksctl 관리형 CloudFormation 스택을 찾을 수 없습니다. 이 문제를 해결하려면 Amazon EKS 리소스 위치에 해당하는 올바른 리전을 지정해야 합니다.

인스턴스 유형이 지원되는지 확인

클러스터나 노드를 생성할 때 지원되지 않는 인스턴스 유형을 사용한 경우, 다음과 같은 오류가 발생합니다.

You must use a valid fully-formed launch template. The requested configuration is currently not supported. Please check the documentation for supported configurations'

인스턴스 유형이나 다른 구성이 특정 AWS 리전에서 지원되는지 확인하려면 다음과 같은 명령을 실행합니다.

aws ec2 describe-instance-type-offerings --region Region --query 'InstanceTypeOfferings[*].{InstanceType:InstanceType}'

참고: region을 사용자의 AWS 리전으로 바꿉니다.

---