Amazon EKS 클러스터와 노드의 문제 해결

Amazon EKS 클러스터와 노드의 문제 해결

이 장은 Amazon EKS를 사용하면서 볼 수 있는 몇 가지 일반적인 오류와 이를 해결하는 방법을 다룹니다. 특정 Amazon EKS 영역을 문제 해결해야 한다면 별도의 Troubleshooting IAM, Amazon EKS Connector 문제 해결, AWS EKS Add-Ons와 함께한 ADOT 문제 해결 주제를 참고하세요.

다른 문제 해결 정보는 AWS re:Post의 Amazon Elastic Kubernetes Service에 대한 Knowledge Center 콘텐츠를 참고하세요.

출처: 문서

본문

용량 부족 (Insufficient capacity)

Amazon EKS 클러스터를 만들려고 시도하는 동안 다음 오류를 받으면, 지정한 가용 영역 중 하나에 클러스터를 지원할 충분한 용량이 없는 것입니다.

Cannot create cluster 'example-cluster' because region-1d, the targeted Availability Zone, does not currently have sufficient capacity to support the cluster. Retry and choose from these Availability Zones: region-1a, region-1b, region-1c

이 오류 메시지가 반환한 가용 영역에 호스팅된 클러스터 VPC의 서브넷으로 클러스터 생성을 다시 시도하세요.

클러스터가 상주할 수 없는 가용 영역이 있습니다. 서브넷이 있는 가용 영역을 Subnet requirements and considerations의 가용 영역 목록과 비교하세요.

노드가 클러스터에 조인하지 못함

노드가 클러스터에 조인하지 못하게 하는 몇 가지 일반적인 이유가 있습니다.

  • 노드가 관리형 노드라면 Amazon EKS가 노드 그룹을 만들 때 aws-auth ConfigMap에 항목을 추가합니다. 항목이 제거되거나 수정되었다면 다시 추가해야 합니다. 자세한 내용은 터미널에서 eksctl create iamidentitymapping --help를 입력하세요. 다음 명령의 my-cluster를 클러스터 이름으로 바꾸고 실행해서 현재 aws-auth ConfigMap 항목을 볼 수 있습니다: eksctl get iamidentitymapping --cluster my-cluster. 지정하는 역할의 ARN은 / 외의 경로를 포함할 수 없습니다. 예를 들어 역할 이름이 development/apps/my-role이라면 역할의 ARN을 지정할 때 my-role로 변경해야 합니다. 노드 IAM 역할 ARN(인스턴스 프로필 ARN이 아님)을 지정해야 합니다.

  • 노드가 자체 관리형이고 노드 IAM 역할 ARN에 대한 접근 항목을 만들지 않았다면 관리형 노드에 나열된 것과 같은 명령을 실행하세요. 노드 IAM 역할 ARN에 대한 접근 항목을 만들었다면 접근 항목에서 제대로 구성되지 않았을 수 있습니다. aws-auth ConfigMap 항목 또는 접근 항목에서 주요 ARN으로 노드 IAM 역할 ARN(인스턴스 프로필 ARN이 아님)이 지정되어 있는지 확인하세요. 접근 항목에 대한 자세한 내용은 EKS access entries로 IAM 사용자에게 Kubernetes 접근을 부여하는 방법을 참고하세요.

  • 노드 AWS CloudFormation 템플릿의 ClusterName이 노드가 조인하려는 클러스터의 이름과 정확히 일치하지 않습니다. 이 필드에 잘못된 값을 전달하면 노드의 /var/lib/kubelet/kubeconfig 파일 구성이 잘못되어 노드가 클러스터에 조인하지 못합니다.

  • 노드가 클러스터 소유로 태그되지 않았습니다. my-cluster를 클러스터 이름으로 바꾼 다음 노드에 다음 태그를 적용해야 합니다.

    키 값
    kubernetes.io/cluster/my-cluster owned

  • 노드가 공용 IP 주소를 사용해서 클러스터에 접근하지 못할 수 있습니다. 공용 서브넷에 배포된 노드에 공용 IP 주소가 할당되어 있는지 확인하세요. 그렇지 않다면 노드가 시작된 후 Elastic IP 주소를 노드에 연결할 수 있습니다. 자세한 내용은 실행 중인 인스턴스 또는 네트워크 인터페이스에 Elastic IP 주소 연결하기를 참고하세요. 공용 서브넷이 배포된 인스턴스에 공용 IP 주소를 자동으로 할당하도록 설정되어 있지 않다면 해당 설정을 활성화할 것을 권장합니다. 자세한 내용은 서브넷의 공용 IPv4 주소 지정 속성 수정하기를 참고하세요. 노드가 개인 서브넷에 배포된 경우 서브넷에는 공용 IP 주소가 할당된 NAT 게이트웨이로 가는 경로가 있어야 합니다.

  • 노드를 배포 중인 AWS 리전의 AWS STS 엔드포인트가 계정에서 활성화되지 않았습니다. 리전을 활성화하려면 AWS 리전에서 AWS STS 활성화·비활성화를 참고하세요.

  • 노드에 개인 DNS 항목이 없어 kubelet 로그에 node "" not found 오류가 포함됩니다. 노드가 생성된 VPC가 DHCP options set의 Options로 domain-name과 domain-name-servers 값이 설정되어 있는지 확인하세요. 기본값은 domain-name:.compute.internal 및 domain-name-servers:AmazonProvidedDNS입니다. 자세한 내용은 Amazon VPC User Guide의 DHCP options sets를 참고하세요.

  • 관리형 노드 그룹의 노드가 15분 내에 클러스터에 연결되지 않으면 "NodeCreationFailure" 상태 문제가 발생하고 콘솔 상태가 Create failed로 설정됩니다. 시작 시간이 느린 Windows AMI의 경우 Fast Launch를 사용해서 이 문제를 해결할 수 있습니다.

워커 노드가 클러스터에 조인하지 못하게 하는 일반적인 원인을 식별하고 문제를 해결하려면 AWSSupport-TroubleshootEKSWorkerNode 런북을 사용할 수 있습니다. 자세한 내용은 AWS Systems Manager Automation 런북 참조에서 AWSSupport-TroubleshootEKSWorkerNode를 참고하세요.

인가되지 않음 또는 접근 거부 (kubectl)

kubectl 명령을 실행하는 동안 다음 오류 중 하나를 받으면 Amazon EKS용으로 kubectl이 올바르게 구성되지 않았거나, 사용 중인 IAM 주체(역할 또는 사용자)의 자격 증명이 Amazon EKS 클러스터의 Kubernetes 객체에 대한 충분한 권한이 있는 Kubernetes 사용자 이름에 매핑되지 않은 것입니다.

could not get token: AccessDenied: Access denied

error: You must be logged in to the server (Unauthorized)

error: the server doesn't have a resource type "svc"

이는 다음 이유 중 하나 때문일 수 있습니다.

  • 클러스터가 한 IAM 주체의 자격 증명으로 생성되었고 kubectl이 다른 IAM 주체의 자격 증명을 사용하도록 구성되어 있습니다. 해결하려면 클러스터를 생성한 자격 증명을 사용하도록 kube config 파일을 업데이트하세요. 자세한 내용은 kubeconfig 파일을 만들어 kubectl을 EKS 클러스터에 연결하기를 참고하세요.
  • 클러스터가 EKS access entries 문서의 사전 조건 섹션의 최소 플랫폼 요구 사항을 충족한다면, IAM 주체가 있는 접근 항목이 없습니다. 존재한다면 필요한 Kubernetes 그룹 이름이 정의되어 있지 않거나 적절한 접근 정책이 연결되어 있지 않은 것입니다. 자세한 내용은 EKS access entries로 IAM 사용자에게 Kubernetes 접근을 부여하는 방법을 참고하세요.
  • 클러스터가 EKS access entries 문서의 최소 플랫폼 요구 사항을 충족하지 않는다면 aws-auth ConfigMap에 IAM 주체가 있는 항목이 없습니다. 존재한다면 필요한 권한이 있는 Kubernetes Role 또는 ClusterRole에 바인딩된 Kubernetes 그룹 이름에 매핑되지 않은 것입니다. Kubernetes 역할 기반 인증(RBAC) 객체에 대한 자세한 내용은 Kubernetes 문서의 RBAC 인증 사용하기를 참고하세요. 다음 명령의 my-cluster를 클러스터 이름으로 바꾸고 실행해서 현재 aws-auth ConfigMap 항목을 볼 수 있습니다: eksctl get iamidentitymapping --cluster my-cluster. IAM 주체의 ARN이 있는 항목이 ConfigMap에 없으면 터미널에서 eksctl create iamidentitymapping --help를 입력해서 하나를 만드는 방법을 배우세요.
  • AWS CLI를 설치·구성하면 사용하는 IAM 자격 증명을 구성할 수 있습니다. 자세한 내용은 AWS Command Line Interface User Guide의 AWS CLI 구성하기를 참고하세요. 클러스터의 Kubernetes 객체에 접근하기 위해 IAM 역할을 수임한다면 kubectl이 IAM 역할을 사용하도록 구성할 수도 있습니다. 자세한 내용은 kubeconfig 파일을 만들어 kubectl을 EKS 클러스터에 연결하기를 참고하세요.

hostname doesn't match

시스템의 Python 버전이 2.7.9 이상이어야 합니다. 그렇지 않으면 Amazon EKS에 대한 AWS CLI 호출에서 hostname doesn't match 오류가 발생합니다. 자세한 내용은 Python Requests 자주 묻는 질문의 ""hostname doesn't match" 오류는 무엇인가요?"를 참고하세요.

getsockopt: no route to host

Docker는 Amazon EKS 클러스터에서 172.17.0.0/16 CIDR 범위에서 실행됩니다. 클러스터의 VPC 서브넷이 이 범위와 겹치지 않도록 권장합니다. 그렇지 않으면 다음 오류가 발생합니다.

Error: : error upgrading connection: error dialing backend: dial tcp 172.17..:10250: getsockopt: no route to host

Instances failed to join the Kubernetes cluster

AWS Management Console에서 Instances failed to join the Kubernetes cluster 오류를 받으면 클러스터의 프라이빗 엔드포인트 접근이 활성화되었는지, 또는 공용 엔드포인트 접근용 CIDR 블록이 올바르게 구성되었는지 확인하세요. 자세한 내용은 Cluster API server endpoint를 참고하세요.

관리형 노드 그룹 오류 코드

관리형 노드 그룹이 하드웨어 상태 문제를 겪으면 Amazon EKS가 문제를 진단하는 데 도움이 되는 오류 코드를 반환합니다. 이러한 상태 검사는 Amazon EC2 상태 검사에 기반하므로 소프트웨어 문제를 감지하지 않습니다. 다음 목록은 오류 코드를 설명합니다.

  • AccessDenied — Amazon EKS 또는 관리형 노드 하나 이상이 Kubernetes 클러스터 API 서버로 인증·인가하지 못하고 있습니다. 일반적인 원인 해결에 대한 자세한 내용은 관리형 노드 그룹에 대한 AccessDenied 오류의 일반적인 원인 수정하기를 참고하세요. 프라이빗 Windows AMI도 Not authorized for images 오류 메시지와 함께 이 오류 코드를 일으킬 수 있습니다. 자세한 내용은 Not authorized for images를 참고하세요.
  • AmiIdNotFound — 런치 템플릿과 연결된 AMI ID를 찾을 수 없습니다. AMI가 존재하고 계정과 공유되어 있는지 확인하세요.
  • AutoScalingGroupNotFound — 관리형 노드 그룹과 연결된 Auto Scaling 그룹을 찾을 수 없습니다. 같은 설정으로 Auto Scaling 그룹을 다시 만들어 복구할 수 있습니다.
  • ClusterUnreachable — Amazon EKS 또는 관리형 노드 하나 이상이 Kubernetes 클러스터 API 서버와 통신할 수 없습니다. 이는 네트워크 중단이 있거나 API 서버가 요청 처리 시 타임아웃되면 발생할 수 있습니다.
  • Ec2SecurityGroupNotFound — 클러스터의 클러스터 보안 그룹을 찾을 수 없습니다. 클러스터를 다시 만들어야 합니다.
  • Ec2SecurityGroupDeletionFailure — 관리형 노드 그룹의 원격 접근 보안 그룹을 삭제할 수 없습니다. 보안 그룹에서 종속성을 제거하세요.
  • Ec2LaunchTemplateNotFound — 관리형 노드 그룹의 Amazon EC2 런치 템플릿을 찾을 수 없습니다. 복구하려면 노드 그룹을 다시 만들어야 합니다.
  • Ec2LaunchTemplateVersionMismatch — 관리형 노드 그룹의 Amazon EC2 런치 템플릿 버전이 Amazon EKS가 만든 버전과 일치하지 않습니다. Amazon EKS가 만든 버전으로 되돌려 복구할 수 있습니다.
  • IamInstanceProfileNotFound — 관리형 노드 그룹의 IAM 인스턴스 프로필을 찾을 수 없습니다. 같은 설정으로 인스턴스 프로필을 다시 만들어 복구할 수 있습니다.
  • IamNodeRoleNotFound — 관리형 노드 그룹의 IAM 역할을 찾을 수 없습니다. 같은 설정으로 IAM 역할을 다시 만들어 복구할 수 있습니다.
  • AsgInstanceLaunchFailures — Auto Scaling 그룹이 인스턴스 시작을 시도하는 동안 실패를 겪고 있습니다.
  • NodeCreationFailure — 시작된 인스턴스가 Amazon EKS 클러스터에 등록할 수 없습니다. 이 실패의 일반적인 원인은 노드 IAM 역할 권한 부족 또는 노드의 아웃바운드 인터넷 접근 부족입니다. 노드는 다음 요구 사항 중 하나를 충족해야 합니다.
    • 공용 IP 주소를 사용해서 인터넷에 접근할 수 있습니다. 노드가 있는 서브넷과 연결된 보안 그룹이 통신을 허용해야 합니다. 자세한 내용은 Subnet requirements and considerations와 클러스터에 대한 Amazon EKS 보안 그룹 요구 사항 보기를 참고하세요.
    • 노드와 VPC가 Deploy private clusters with limited internet access의 요구 사항을 충족해야 합니다.
  • InstanceLimitExceeded — AWS 계정이 지정된 인스턴스 유형의 인스턴스를 더 이상 시작할 수 없습니다. Amazon EC2 인스턴스 한도 증가를 요청해서 복구할 수 있습니다.
  • InsufficientFreeAddresses — 관리형 노드 그룹과 연결된 서브넷 하나 이상에 새 노드를 위한 충분한 사용 가능한 IP 주소가 없습니다.
  • InternalFailure — 이러한 오류는 보통 Amazon EKS 서버 측 문제로 인해 발생합니다.

관리형 노드 그룹에서 작업을 수행할 때 AccessDenied 오류의 가장 일반적인 원인은 eks:node-manager ClusterRole 또는 ClusterRoleBinding이 없는 것입니다. Amazon EKS는 관리형 노드 그룹 온보딩의 일부로 이러한 리소스를 클러스터에 설정하며, 이는 노드 그룹 관리에 필요합니다.

ClusterRole은 시간이 지나며 변경될 수 있지만 다음 예제와 비슷해야 합니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eks:node-manager
rules:
- apiGroups:
  - ''
  resources:
  - pods
  verbs:
  - get
  - list
  - watch
  - delete
- apiGroups:
  - ''
  resources:
  - nodes
  verbs:
  - get
  - list
  - watch
  - patch
- apiGroups:
  - ''
  resources:
  - pods/eviction
  verbs:
  - create

ClusterRoleBinding은 시간이 지나며 변경될 수 있지만 다음 예제와 비슷해야 합니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks:node-manager
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: eks:node-manager
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: eks:node-manager

eks:node-manager ClusterRole이 존재하는지 확인합니다.

kubectl describe clusterrole eks:node-manager

존재한다면 출력을 이전 ClusterRole 예제와 비교하세요.

eks:node-manager ClusterRoleBinding이 존재하는지 확인합니다.

kubectl describe clusterrolebinding eks:node-manager

존재한다면 출력을 이전 ClusterRoleBinding 예제와 비교하세요.

관리형 노드 그룹 작업을 요청할 때 AccessDenied 오류의 원인이 누락되거나 손상된 ClusterRole 또는 ClusterRoleBinding임을 확인했다면 이를 복원할 수 있습니다. 다음 내용을 eks-node-manager-role.yaml 파일에 저장하세요.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eks:node-manager
rules:
- apiGroups:
  - ''
  resources:
  - pods
  verbs:
  - get
  - list
  - watch
  - delete
- apiGroups:
  - ''
  resources:
  - nodes
  verbs:
  - get
  - list
  - watch
  - patch
- apiGroups:
  - ''
  resources:
  - pods/eviction
  verbs:
  - create
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks:node-manager
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: eks:node-manager
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: eks:node-manager

파일을 적용합니다.

kubectl apply -f eks-node-manager-role.yaml

문제가 해결되었는지 확인하려면 노드 그룹 작업을 다시 시도하세요.

Not authorized for images

Not authorized for images 오류 메시지의 잠재적 원인 중 하나는 프라이빗 Amazon EKS Windows AMI를 사용해서 Windows 관리형 노드 그룹을 시작하는 것입니다. 새 Windows AMI를 릴리스한 후 AWS는 4개월보다 오래된 AMI를 프라이빗으로 만들어 더 이상 접근할 수 없게 합니다. 관리형 노드 그룹이 프라이빗 Windows AMI를 사용한다면 Windows 관리형 노드 그룹을 업데이트하는 것을 고려하세요. 프라이빗으로 만들어진 AMI에 대한 접근을 제공한다고 보장할 수는 없지만, AWS Support에 티켓을 제출해서 접근을 요청할 수 있습니다. 자세한 내용은 Amazon EC2 User Guide의 Patches를 참고하세요.

노드가 NotReady 상태

노드가 NotReady 상태로 들어가면 노드가 비정상이며 새 Pod를 스케줄링할 수 없음을 나타냅니다. 이는 노드에 CPU, 메모리, 또는 사용 가능한 디스크 공간을 위한 충분한 리소스가 없는 것 등 다양한 이유로 발생할 수 있습니다.

Amazon EKS 최적화 Windows AMI의 경우 kubelet 구성에서 기본적으로 컴퓨트 리소스 예약이 지정되어 있지 않습니다. 리소스 문제를 방지하려면 kube-reserved 및/또는 system-reserved에 대한 구성 값을 kubelet에 제공해서 시스템 프로세스용 컴퓨트 리소스를 예약할 수 있습니다. 이는 부트스트랩 스크립트에서 -KubeletExtraArgs 명령줄 파라미터를 사용해서 수행합니다. 자세한 내용은 Kubernetes 문서의 시스템 데몬용 컴퓨트 리소스 예약하기와 이 사용자 가이드의 Bootstrap script 구성 파라미터를 참고하세요.

EKS Log Collector

Amazon EKS 노드 문제를 해결하려면 /etc/eks/log-collector-script/eks-log-collector.sh에 있는 사전 빌드된 스크립트를 노드에서 사용할 수 있습니다. 이 스크립트를 사용해서 지원 케이스 및 일반 문제 해결을 위한 진단 로그를 수집할 수 있습니다.

노드에서 스크립트를 실행하려면 다음 명령을 사용하세요.

sudo bash /etc/eks/log-collector-script/eks-log-collector.sh

참고

해당 위치에 스크립트가 없다면 다음 명령으로 스크립트를 수동으로 다운로드·실행할 수 있습니다.

curl -O https://amazon-eks.s3.amazonaws.com/support/log-collector-script/linux/eks-log-collector.sh
sudo bash eks-log-collector.sh

스크립트는 다음 진단 정보를 수집합니다.

$ sudo bash /etc/eks/log-collector-script/eks-log-collector.sh

      This is version 0.7.8. New versions can be found at https://github.com/awslabs/amazon-eks-ami/blob/main/log-collector-script/

Trying to collect common operating system logs...
Trying to collect kernel logs...
Trying to collect mount points and volume information...
...
...

	Done... your bundled logs are located in /var/log/eks_i-EXAMPLE_2025-03-25_0000-UTC_0.7.8.tar.gz

진단 정보는 다음 위치에 수집·저장됩니다.

/var/log/eks_i-EXAMPLE_2025-03-25_0000-UTC_0.7.8.tar.gz

Bottlerocket 노드의 로그 번들을 검색하려면 Bottlerocket Logs를 참고하세요.

컨테이너 런타임 네트워크 미준비 (Container runtime network not ready)

다음과 유사한 Container runtime network not ready 오류와 인가 오류를 받을 수 있습니다.

4191 kubelet.go:2130] Container runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:docker: network plugin is not ready: cni config uninitialized
4191 reflector.go:205] k8s.io/kubernetes/pkg/kubelet/kubelet.go:452: Failed to list *v1.Service: Unauthorized
4191 kubelet_node_status.go:106] Unable to register node "ip-10-40-175-122.ec2.internal" with API server: Unauthorized
4191 reflector.go:205] k8s.io/kubernetes/pkg/kubelet/kubelet.go:452: Failed to list *v1.Service: Unauthorized

이는 다음 이유 중 하나로 인해 발생할 수 있습니다.

  • 클러스터에 aws-auth ConfigMap이 없거나 노드에 구성한 IAM 역할에 대한 항목이 포함되어 있지 않습니다. 이 문제를 해결하려면 다음 명령의 my-cluster를 클러스터 이름으로 바꾸고 실행해서 ConfigMap의 기존 항목을 확인하세요: eksctl get iamidentitymapping --cluster my-cluster. 명령에서 오류 메시지를 받으면 클러스터에 aws-auth ConfigMap이 없기 때문일 수 있습니다. 다음 명령은 ConfigMap에 항목을 추가합니다. ConfigMap이 없으면 생성도 합니다. 111122223333을 IAM 역할의 AWS 계정 ID로, myAmazonEKSNodeRole을 노드 역할 이름으로 바꾸세요.

    eksctl create iamidentitymapping --cluster my-cluster \
    --arn arn:aws:iam::111122223333:role/myAmazonEKSNodeRole --group system:bootstrappers,system:nodes \
    --username system:node:{{EC2PrivateDNSName}}

    지정하는 역할의 ARN은 / 외의 경로를 포함할 수 없습니다. 예를 들어 역할 이름이 development/apps/my-role이라면 역할의 ARN을 지정할 때 my-role로 변경해야 합니다. 노드 IAM 역할 ARN(인스턴스 프로필 ARN이 아님)을 지정해야 합니다.

  • 자체 관리 노드가 EKS access entries 문서의 사전 조건에 나열된 최소 버전의 플랫폼 버전을 가진 클러스터에 있지만, 노드 IAM 역할에 대한 aws-auth ConfigMap(이전 항목 참고)에 항목이 없거나 역할에 대한 접근 항목이 없습니다. 이 문제를 해결하려면 다음 명령의 my-cluster를 클러스터 이름으로 바꾸고 실행해서 기존 접근 항목을 확인하세요: aws eks list-access-entries --cluster-name my-cluster. 다음 명령은 노드 IAM 역할에 대한 접근 항목을 추가합니다. 111122223333을 IAM 역할의 AWS 계정 ID로, myAmazonEKSNodeRole을 노드 역할 이름으로 바꾸세요. Windows 노드가 있다면 EC2_LINUX를 EC2_Windows로 바꾸세요. 노드 IAM 역할 ARN(인스턴스 프로필 ARN이 아님)을 지정해야 합니다.

    aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/myAmazonEKSNodeRole --type EC2_LINUX

TLS 핸드셰이크 타임아웃

노드가 공용 API 서버 엔드포인트에 연결을 설정할 수 없을 때 다음 오류와 유사한 오류를 볼 수 있습니다.

server.go:233] failed to run Kubelet: could not init cloud provider "aws": error finding instance i-1111f2222f333e44c: "error listing AWS instances: \"RequestError: send request failed\ncaused by: Post  net/http: TLS handshake timeout\""

kubelet 프로세스는 계속 리스폰(respawn)되며 API 서버 엔드포인트를 테스트합니다. 이 오류는 구성 변경이나 버전 업데이트처럼 컨트롤 플레인에서 클러스터의 롤링 업데이트를 수행하는 모든 절차 중에 일시적으로도 발생할 수 있습니다.

이 문제를 해결하려면 라우트 테이블과 보안 그룹을 확인해서 노드의 트래픽이 공용 엔드포인트에 도달할 수 있는지 확인하세요.

InvalidClientTokenId

중국 AWS 리전의 클러스터에 배포된 Pod 또는 DaemonSet에 서비스 계정용 IAM 역할을 사용하고 있으며 스펙에 AWS_DEFAULT_REGION 환경 변수를 설정하지 않았다면, Pod 또는 DaemonSet이 다음 오류를 받을 수 있습니다.

An error occurred (InvalidClientTokenId) when calling the GetCallerIdentity operation: The security token included in the request is invalid

이 문제를 해결하려면 다음 예제 Pod 스펙과 같이 Pod 또는 DaemonSet 스펙에 AWS_DEFAULT_REGION 환경 변수를 추가해야 합니다.

apiVersion: v1
kind: Pod
metadata:
  name: envar-demo
  labels:
    purpose: demonstrate-envars
spec:
  containers:
  - name: envar-demo-container
    image: gcr.io/google-samples/node-hello:1.0
    env:
    - name: AWS_DEFAULT_REGION
      value: "region-code"

컨트롤 플레인 업그레이드 전에 노드 그룹이 Kubernetes 버전과 일치해야 함

컨트롤 플레인을 새 Kubernetes 버전으로 업그레이드하기 전에 클러스터의 관리형 및 Fargate 노드의 마이너 버전이 컨트롤 플레인의 현재 버전과 같아야 합니다. Amazon EKS update-cluster-version API는 모든 Amazon EKS 관리형 노드를 현재 클러스터 버전으로 업그레이드할 때까지 요청을 거부합니다. Amazon EKS는 관리형 노드를 업그레이드하는 API를 제공합니다. 관리형 노드 그룹의 Kubernetes 버전 업그레이드에 대한 정보는 Update a managed node group for your cluster를 참고하세요. Fargate 노드의 버전을 업그레이드하려면 노드가 나타내는 Pod를 삭제하고 컨트롤 플레인 업그레이드 후 Pod를 재배포하세요. 자세한 내용은 Update existing cluster to new Kubernetes version을 참고하세요.

많은 노드를 시작할 때 Too Many Requests 오류

많은 노드를 동시에 시작하면 Amazon EC2 user data 실행 로그에 Too Many Requests라고 하는 오류 메시지가 나타날 수 있습니다. 이는 컨트롤 플레인이 describeCluster 호출로 과부하되어 발생할 수 있습니다. 과부하로 인해 스로틀링이 발생하고, 노드가 부트스트랩 스크립트를 실행하지 못하며, 노드가 전혀 클러스터에 조인하지 못하게 됩니다.

--apiserver-endpoint, --b64-cluster-ca, --dns-cluster-ip 인수가 노드의 부트스트랩 스크립트에 전달되고 있는지 확인하세요. 이러한 인수를 포함하면 부트스트랩 스크립트가 describeCluster 호출을 할 필요가 없어 컨트롤 플레인이 과부하되는 것을 방지하는 데 도움이 됩니다. 자세한 내용은 Specifying an AMI를 참고하세요.

Kubernetes API 서버 요청에 대한 HTTP 401 unauthorized 오류 응답

클러스터에서 Pod의 서비스 계정 토큰이 만료된 경우 이러한 오류가 표시됩니다.

Amazon EKS 클러스터의 Kubernetes API 서버는 90일보다 오래된 토큰이 있는 요청을 거부합니다. 이전 Kubernetes 버전에서는 토큰에 만료가 없었습니다. 이는 이러한 토큰에 의존하는 클라이언트가 1시간 내에 토큰을 새로 고쳐야 한다는 뜻입니다. 잘못된 토큰으로 인해 Kubernetes API 서버가 요청을 거부하는 것을 방지하려면 워크로드가 사용하는 Kubernetes 클라이언트 SDK 버전이 다음 버전과 같거나 이후여야 합니다.

  • Go 버전 0.15.7 이상
  • Python 버전 12.0.0 이상
  • Java 버전 9.0.0 이상
  • JavaScript 버전 0.10.3 이상
  • Ruby master 브랜치
  • Haskell 버전 0.3.0.0
  • C# 버전 7.0.5 이상

클러스터에서 오래된 토큰을 사용하는 기존 Pod를 모두 식별할 수 있습니다. 자세한 내용은 Service account tokens를 참고하세요.

Amazon EKS 플랫폼 버전이 현재 플랫폼 버전보다 두 버전 이상 뒤처짐

이는 Amazon EKS가 클러스터의 플랫폼 버전을 자동으로 업데이트할 수 없을 때 발생할 수 있습니다. 이에는 많은 원인이 있지만 일반적인 원인 중 일부는 다음과 같습니다. 이러한 문제 중 하나라도 클러스터에 적용된다면 클러스터는 계속 작동할 수 있지만, 플랫폼 버전은 Amazon EKS가 업데이트하지 않습니다.

문제: 클러스터 IAM 역할 삭제됨 – 이 역할은 클러스터 생성 시 지정되었습니다. 다음 명령으로 어떤 역할이 지정되었는지 확인할 수 있습니다. my-cluster를 클러스터 이름으로 바꾸세요.

aws eks describe-cluster --name my-cluster --query cluster.roleArn --output text | cut -d / -f 2

예제 출력은 다음과 같습니다.

eksClusterRole

해결책: 같은 이름으로 새 클러스터 IAM 역할을 만듭니다.

문제: 클러스터 생성 시 지정된 서브넷이 삭제됨 – 클러스터와 함께 사용할 서브넷은 클러스터 생성 시 지정되었습니다. 다음 명령으로 어떤 서브넷이 지정되었는지 확인할 수 있습니다. my-cluster를 클러스터 이름으로 바꾸세요.

aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.subnetIds

예제 출력은 다음과 같습니다.

[
"subnet-EXAMPLE1",
"subnet-EXAMPLE2"
]

해결책: 서브넷 ID가 계정에 존재하는지 확인합니다.

vpc_id=$(aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.vpcId --output text)
aws ec2 describe-subnets --filters "Name=vpc-id,Values=$vpc_id" --query "Subnets[*].SubnetId"

예제 출력은 다음과 같습니다.

[
"subnet-EXAMPLE3",
"subnet-EXAMPLE4"
]

출력에서 반환된 서브넷 ID가 클러스터 생성 시 지정된 서브넷 ID와 일치하지 않으면, Amazon EKS가 클러스터를 업데이트하기를 원한다면 클러스터가 사용하는 서브넷을 변경해야 합니다. 클러스터를 만들 때 두 개 이상의 서브넷을 지정했다면 Amazon EKS가 새 탄력적 네트워크 인터페이스를 만들 서브넷을 무작위로 선택하기 때문입니다. 이러한 네트워크 인터페이스는 컨트롤 플레인이 노드와 통신할 수 있게 합니다. Amazon EKS는 선택한 서브넷이 존재하지 않으면 클러스터를 업데이트하지 않습니다. Amazon EKS가 클러스터 생성 시 지정한 서브넷 중 어느 서브넷에 새 네트워크 인터페이스를 만들지 선택하는지는 제어할 수 없습니다.

클러스터의 Kubernetes 버전 업데이트를 시작할 때 같은 이유로 업데이트가 실패할 수 있습니다.

문제: 클러스터 생성 시 지정된 보안 그룹이 삭제됨 – 클러스터 생성 시 보안 그룹을 지정했다면 다음 명령으로 그 ID를 볼 수 있습니다. my-cluster를 클러스터 이름으로 바꾸세요.

aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.securityGroupIds

예제 출력은 다음과 같습니다.

[
    "sg-EXAMPLE1"
]

[]가 반환되면 클러스터 생성 시 보안 그룹이 지정되지 않은 것이며 누락된 보안 그룹이 문제가 아닙니다. 보안 그룹이 반환되면 보안 그룹이 계정에 존재하는지 확인합니다.

해결책: 이 보안 그룹이 계정에 존재하는지 확인합니다.

vpc_id=$(aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.vpcId --output text)
aws ec2 describe-security-groups --filters "Name=vpc-id,Values=$vpc_id" --query "SecurityGroups[*].GroupId"

예제 출력은 다음과 같습니다.

[
"sg-EXAMPLE2"
]

출력에서 반환된 보안 그룹 ID가 클러스터 생성 시 지정된 보안 그룹 ID와 일치하지 않으면, Amazon EKS가 클러스터를 업데이트하기를 원한다면 클러스터가 사용하는 보안 그룹을 변경해야 합니다. Amazon EKS는 클러스터 생성 시 지정된 보안 그룹 ID가 존재하지 않으면 클러스터를 업데이트하지 않습니다.

클러스터의 Kubernetes 버전 업데이트를 시작할 때 같은 이유로 업데이트가 실패할 수 있습니다.

  • 클러스터를 만들 때 지정한 각 서브넷에 사용 가능한 IP 주소가 최소 6개(권장은 16개) 없습니다. 서브넷에 사용 가능한 IP 주소가 충분하지 않다면 서브넷의 IP 주소를 확보하거나, 사용 가능한 IP 주소가 충분한 서브넷을 사용하도록 클러스터가 사용하는 서브넷을 변경해야 합니다.
  • 클러스터를 만들 때 비밀 암호화를 활성화했고 지정한 AWS KMS 키가 삭제되었습니다. Amazon EKS가 클러스터를 업데이트하기를 원한다면 새 클러스터를 만들어야 합니다.

클러스터 상태 FAQ와 해결 경로가 있는 오류 코드

Amazon EKS는 EKS 클러스터와 클러스터 인프라의 문제를 감지해서 EKS 클러스터 리소스의 health 객체에 저장합니다. 클러스터 상태 정보의 도움으로 클러스터 문제를 더 빠르게 감지·해결·대응할 수 있습니다. 이를 통해 더 안전하고 최신 상태의 애플리케이션 환경을 만들 수 있습니다. 또한 필요한 인프라나 클러스터 구성의 문제로 인해 손상된 클러스터에서는 새 Kubernetes 버전으로 업그레이드하거나 Amazon EKS가 보안 업데이트를 설치하는 것이 불가능할 수 있습니다. Amazon EKS는 문제를 감지하거나 문제가 해결되었음을 감지하는 데 3시간이 걸릴 수 있습니다.

Amazon EKS 클러스터의 상태는 Amazon EKS와 사용자 간의 공동 책임입니다. IAM 역할과 Amazon VPC 서브넷의 사전 조건 인프라와 기타 필요한 인프라는 미리 제공해야 하며 사용자 책임입니다. Amazon EKS는 이 인프라와 클러스터의 구성 변경을 감지합니다.

Amazon EKS 콘솔에서 클러스터 상태에 접근하려면 Amazon EKS 클러스터 상세 페이지에서 접근하는 Observability 대시보드의 Cluster health issues 탭에서 Health Issues라는 표를 찾으면 됩니다. 이 데이터는 예를 들어 AWS Command Line Interface 안에서처럼 EKS API의 DescribeCluster 작업을 호출해서도 사용할 수 있습니다.

이 기능을 왜 사용해야 하나요?

Amazon EKS 클러스터의 상태에 대한 더 큰 가시성을 얻고, 디버깅에 시간을 쓰거나 AWS 지원 케이스를 여는 일 없이 문제를 빠르게 진단·수정할 수 있습니다. 예를 들어 Amazon EKS 클러스터의 서브넷을 실수로 삭제하면 Amazon EKS는 교차 계정 네트워크 인터페이스를 만들 수 없고, kubectl exec 또는 kubectl logs 같은 Kubernetes AWS CLI 명령이 Error from server: error dialing backend: remote error: tls: internal error. 오류로 실패합니다. 이제 subnet-da60e280 was deleted: could not create network interface라고 하는 Amazon EKS 상태 문제가 보일 것입니다.

이 기능은 다른 AWS 서비스와 어떻게 관련되거나 작동하나요?

IAM 역할과 Amazon VPC 서브넷은 클러스터 상태가 문제를 감지하는 사전 조건 인프라의 두 예입니다. 이 기능은 해당 리소스가 제대로 구성되지 않으면 자세한 정보를 반환합니다.

상태 문제가 있는 클러스터는 요금이 부과되나요?

예, 모든 Amazon EKS 클러스터는 표준 Amazon EKS 가격으로 청구됩니다. 클러스터 상태 기능은 추가 비용 없이 사용할 수 있습니다.

이 기능은 AWS Outposts의 Amazon EKS 클러스터에서 작동하나요?

예, AWS Cloud의 EKS 클러스터(AWS Outposts의 확장 클러스터와 AWS Outposts의 로컬 클러스터 포함)에 대해 클러스터 문제가 감지됩니다. 클러스터 상태는 Amazon EKS Anywhere나 Amazon EKS Distro (EKS-D)의 문제는 감지하지 않습니다.

새 문제가 감지되면 알림을 받을 수 있나요?

예. AWS는 새 클러스터 상태 문제가 감지되면 이메일과 Personal Health Dashboard 알림을 보냅니다.

콘솔이 상태 문제에 대한 경고를 주나요?

예, 상태 문제가 있는 모든 클러스터는 콘솔 상단에 배너가 표시됩니다.

처음 두 열은 API 응답 값에 필요한 것입니다. Health ClusterIssue 객체의 세 번째 필드는 resourceIds이며, 그 반환은 문제 유형에 따라 다릅니다.

코드 메시지 ResourceIds 클러스터 복구 가능?
SUBNET_NOT_FOUND 클러스터와 현재 연결된 서브넷 하나 이상을 찾을 수 없습니다. Amazon EKS update-cluster-config API를 호출해서 서브넷을 업데이트하세요. 서브넷 ID 예
SECURITY_GROUP_NOT_FOUND 클러스터와 현재 연결된 보안 그룹 하나 이상을 찾을 수 없습니다. Amazon EKS update-cluster-config API를 호출해서 보안 그룹을 업데이트하세요. 보안 그룹 ID 예
IP_NOT_AVAILABLE 클러스터와 연결된 서브넷 하나 이상에 Amazon EKS가 클러스터 관리 작업을 수행하기에 충분한 사용 가능한 IP 주소가 없습니다. 서브넷에서 주소를 확보하거나 Amazon EKS update-cluster-config API를 사용해서 다른 서브넷을 클러스터에 연결하세요. 서브넷 ID 예
VPC_NOT_FOUND 클러스터와 연결된 VPC를 찾을 수 없습니다. 클러스터를 삭제하고 다시 만들어야 합니다. VPC ID 아니요
ASSUME_ROLE_ACCESS_DENIED 클러스터가 Amazon EKS 서비스 연결 역할을 사용하지 않고 있습니다. 필요한 Amazon EKS 관리 작업을 수행하기 위해 클러스터와 연결된 역할을 수임할 수 없었습니다. 역할이 존재하고 필요한 신뢰 정책이 있는지 확인하세요. 클러스터 IAM 역할 예
PERMISSION_ACCESS_DENIED 클러스터가 Amazon EKS 서비스 연결 역할을 사용하지 않고 있습니다. 클러스터와 연결된 역할이 Amazon EKS가 필요한 관리 작업을 수행하기에 충분한 권한을 부여하지 않습니다. 클러스터 역할에 연결된 정책과 별도의 deny 정책이 적용되었는지 확인하세요. 클러스터 IAM 역할 예
ASSUME_ROLE_ACCESS_DENIED_USING_SLR Amazon EKS 클러스터 관리 서비스 연결 역할을 수임할 수 없었습니다. 역할이 존재하고 필요한 신뢰 정책이 있는지 확인하세요. Amazon EKS 서비스 연결 역할 예
PERMISSION_ACCESS_DENIED_USING_SLR Amazon EKS 클러스터 관리 서비스 연결 역할이 Amazon EKS가 필요한 관리 작업을 수행하기에 충분한 권한을 부여하지 않습니다. 클러스터 역할에 연결된 정책과 별도의 deny 정책이 적용되었는지 확인하세요. Amazon EKS 서비스 연결 역할 예
OPT_IN_REQUIRED 계정에 Amazon EC2 서비스 구독이 없습니다. 계정 설정 페이지에서 계정 구독을 업데이트하세요. N/A 예
STS_REGIONAL_ENDPOINT_DISABLED STS 리전 엔드포인트가 비활성화되었습니다. Amazon EKS가 필요한 클러스터 관리 작업을 수행할 수 있도록 엔드포인트를 활성화하세요. N/A 예
KMS_KEY_DISABLED 클러스터와 연결된 AWS KMS Key가 비활성화되었습니다. 클러스터를 복구하려면 키를 다시 활성화하세요. KMS Key ARN 예
KMS_KEY_NOT_FOUND 클러스터와 연결된 AWS KMS 키를 찾을 수 없습니다. 클러스터를 삭제하고 다시 만들어야 합니다. KMS Key ARN 아니요
KMS_GRANT_REVOKED 클러스터와 연결된 AWS KMS Key에 대한 그랜트가 철회되었습니다. 클러스터를 삭제하고 다시 만들어야 합니다. KMS Key ARN 아니요
ETCD_DB_SIZE_EXCEEDED Amazon EKS 클러스터가 etcd 데이터베이스 크기 한도를 초과했습니다. etcd는 Kubernetes 컨트롤 플레인에서 실행되며 클러스터의 구성과 상태를 유지하는 키-값 데이터 저장소입니다. 클러스터가 손상 상태로 들어가는 것을 방지하려면 불필요한 Kubernetes 객체를 제거해서 etcd 데이터베이스 크기를 줄이세요. 데이터베이스 크기에 기여하는 객체를 식별·정리하는 지침은 Amazon EKS 클러스터에서 etcd 데이터베이스 크기 관리하기를 참고하세요. 정리 후에도 문제가 계속되면 AWS Support에 문의하세요. 클러스터 ARN 예

더 알아보기 (Learn more)