용량 부족 노드가 클러스터 조인에 실패 권한이 없거나 액세스가 거부됨(kubectl)hostname doesn't match getsockopt: no route to host Instances failed to join the Kubernetes cluster 관리형 노드 그룹 오류 Not authorized for images 노드가 NotReady 상태임 CNI 로그 수집 도구 컨테이너 런타임 네트워크가 준비되지 않음 TLS 핸드셰이크 시간 초과 InvalidClientTokenId VPC 승인 webhook 인증서 만료 컨트롤 플레인을 업데이트하기 전에 노드 그룹이 Kubernetes 버전과 일치해야 합니다.많은 노드를 시작할 때 Too Many Requests 오류가 있습니다.HTTP 401 권한 없음 오류 오래된 플랫폼 버전 클러스터 상태 FAQ 및 오류 코드(해결 경로 포함)

Amazon EKS 문제 해결

이 장에서는 Amazon EKS를 사용하는 동안 발생할 수 있는 몇 가지 일반 오류와 이를 해결하는 방법을 다룹니다. 특정 Amazon EKS 영역의 문제를 해결해야 하는 경우 별도의 IAM 문제 해결. Amazon EKS 커넥터의 문제 해결 및 EKS 추가 기능을 사용하여 ADOT 문제 해결 주제를 참조하세요.

기타 문제 해결 정보는 AWS re:Post의 Amazon 엘라스틱 쿠버네티스 서비스에 대한 지식 센터 콘텐츠를 참조하세요.

용량 부족

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의 서브넷을 사용하여 클러스터를 재생성하십시오.

클러스터가 상주할 수 없는 가용 영역이 있습니다. 서브넷이 있는 가용 영역을 서브넷 요구 사항 및 고려 사항의 가용 영역 목록과 비교합니다.

노드가 클러스터 조인에 실패

노드가 클러스터에 조인하지 못하는 몇 가지 일반적인 원인은 다음과 같습니다.

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

자체 관리형 노드이고 노드의 IAM 역할 ARN에 대한 액세스 항목을 생성하지 않은 경우 관리형 노드에 대해 나열된 것과 동일한 명령을 실행합니다. 노드 IAM 역할의 ARN에 대한 액세스 항목을 생성한 경우 액세스 항목에서 올바르게 구성되지 않을 수 있습니다. aws-auth ConfigMap 항목 또는 액세스 항목에서 노드 IAM 역할 ARN(인스턴스 프로파일 ARN이 아님)이 보안 주체 ARN으로 지정되어야 합니다. 액세스 항목에 대한 자세한 내용은 Amazon EKS 클러스터의 Kubernetes 객체에 대한 IAM 역할 또는 사용자 액세스 허용 섹션을 참조하십시오.
노드 AWS CloudFormation템플릿에서 ClusterName이 조인할 클러스터의 이름과 정확히 일치하지 않습니다. 이 필드에 올바르지 않은 값을 전달하면 노드의 /var/lib/kubelet/kubeconfig 파일의 올바르지 않은 구성이 발생하고, 노드가 클러스터에 조인되지 않습니다.

노드가 클러스터에서 소유하는 것으로 태그가 지정되지 않았습니다. 노드에는 다음 태그가 적용되어야 합니다. 여기서 my-cluster은 클러스터의 이름으로 교체됩니다.

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

노드는 퍼블릭 IP 주소를 사용하여 클러스터에 액세스하지 못할 수 있습니다. 퍼블릭 서브넷에 배포된 노드에 퍼블릭 IP 주소가 할당되었는지 확인합니다. 그렇지 않은 경우 시작 후 탄력적 IP 주소를 노드에 연결할 수 있습니다. 자세한 내용은 실행 중인 인스턴스 또는 네트워크 인터페이스와 탄력적 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:<region>.compute.internal 및 domain-name-servers:AmazonProvidedDNS입니다. 자세한 내용은 Amazon VPC 사용 설명서에서 DHCP 옵션 세트를 참조하세요.
관리형 노드 그룹의 노드가 15분 내에 클러스터에 연결되지 않으면 “NodeCreationFailure”라는 상태 문제가 발생하고 콘솔 상태가 Create failed로 설정됩니다. 시작 시간이 느린 Windows AMI의 경우 빠른 실행을 사용하여 이 문제를 해결할 수 있습니다.

작업자 노드의 클러스터 조인을 방해하는 일반적인 원인을 식별하고 문제를 해결하기 위해 AWSSupport-TroubleshootEKSWorkerNode 실행서를 사용할 수 있습니다. 자세한 내용은 AWS Systems Manager Automation 실행서 참조에서 AWSSupport-TroubleshootEKSWorkerNode를 참조하세요.

권한이 없거나 액세스가 거부됨(`kubectl`)

kubectl 명령을 실행할 때 다음 오류 중 하나가 발생하는 경우 kubectl이 Amazon EKS에 대해 올바르게 구성되지 않았거나 사용하고 있는 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 파일을 업데이트합니다. 자세한 내용은 Amazon EKS 클러스터용 kubeconfig 파일 생성 또는 업데이트 단원을 참조하십시오.
클러스터가 Amazon EKS 클러스터의 Kubernetes 객체에 대한 IAM 역할 또는 사용자 액세스 허용의 사전 조건 섹션에 나온 최소 플랫폼 요구 사항을 충족하는 경우 IAM 보안 주체에 액세스 항목이 존재하지 않습니다. 존재하는 경우 필수 Kubernetes 그룹 이름이 정의되지 않았거나 적절한 액세스 정책이 연결되지 않은 것입니다. 자세한 내용은 Amazon EKS 클러스터의 Kubernetes 객체에 대한 IAM 역할 또는 사용자 액세스 허용 단원을 참조하십시오.
클러스터가 Amazon EKS 클러스터의 Kubernetes 객체에 대한 IAM 역할 또는 사용자 액세스 허용의 최소 플랫폼 요구 사항을 충족하지 않는 경우 IAM 보안 주체가 포함된 항목이 aws-auth ConfigMap에 존재하지 않습니다. 존재하는 경우 필요한 권한을 보유한 Kubernetes Role 또는 ClusterRole에 바인딩된 Kubernetes 그룹 이름에 매핑되지 않은 것입니다. Kubernetes 역할 기반 권한 부여(RBAC) 객체에 대한 자세한 내용은 Kubernetes 설명서에서 Using RBAC authorization을 참조하세요. 다음 명령에서 my-cluster를 클러스터 이름으로 바꾸고 수정된 명령(eksctl get iamidentitymapping --cluster my-cluster)을 실행하여 현재 aws-auth ConfigMap 항목을 확인할 수 있습니다. IAM 보안 주체의 ARN이 포함된 항목이 ConfigMap에 없는 경우 터미널에 eksctl create iamidentitymapping --help를 입력하여 생성 방법을 알아보세요.

AWS CLI를 설치하고 구성하면 사용할 IAM 자격 증명을 구성할 수 있습니다. 자세한 내용은 AWS Command Line Interface 사용 설명서의 AWS CLI 구성을 참조하세요. 클러스터의 Kubernetes 객체에 액세스하기 위해 IAM 역할을 수임하는 경우 IAM 역할을 사용하도록 kubectl을 구성할 수도 있습니다. 자세한 내용은 Amazon EKS 클러스터용 kubeconfig 파일 생성 또는 업데이트 단원을 참조하십시오.

`hostname doesn't match`

시스템의 Python 버전이 2.7.9 이상이어야 합니다. 그렇지 않은 경우 Amazon EKS에 대한 AWS CLI 호출과 함께 hostname doesn't match 오류가 표시됩니다. 자세한 내용은 Python Requests Frequently Asked Questions에서 What are "hostname doesn't match" errors?를 참조하세요.

`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.<nn>.<nn>:10250: getsockopt: no route to host

`Instances failed to join the Kubernetes cluster`

AWS Management Console에서 Instances failed to join the Kubernetes cluster 오류 메시지가 표시되면 클러스터의 프라이빗 엔드포인트 액세스가 활성화되어 있는지 또는 퍼블릭 엔드포인트 액세스에 대해 CIDR 블록을 올바르게 구성했는지 확인합니다. 자세한 내용은 Amazon EKS 클러스터 엔드포인트 액세스 제어 단원을 참조하십시오.

관리형 노드 그룹 오류

관리형 노드 그룹에 하드웨어 상태 문제가 발생하면 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 주소를 사용하여 인터넷에 액세스할 수 있습니다. 노드가 있는 서브넷에 연결된 보안 그룹은 통신을 허용해야 합니다. 자세한 내용은 서브넷 요구 사항 및 고려 사항 및 Amazon EKS 보안 그룹 요구 사항 및 고려 사항 단원을 참조하세요.
노드와 VPC는 프라이빗 클러스터 요구 사항의 요구 사항을 충족해야 합니다.

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 예와 비교합니다.

관리형 노드 그룹 작업을 요청하는 동안 누락되거나 손상된 ClusterRole 또는 ClusterRoleBinding이 AcessDenied 오류의 원인으로 확인된 경우 복원할 수 있습니다. 다음 콘텐츠를 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 EKSWindows AMI를 사용하여Windows 관리형 노드 그룹을 시작하는 것입니다. 새 Windows AMI를 릴리스한 후 AWS에서는 4개월이 지난 AMI를 프라이빗으로 설정하여 더 이상 액세스할 수 없도록 합니다. 관리형 노드 그룹이 프라이빗 Windows AMI를 사용하는 경우 Windows 관리형 노드 그룹 업데이트를 고려해 보세요. 프라이빗으로 설정된 AMI에 대한 액세스 제공을 보장할 수는 없지만 AWS Support에 티켓을 제출하여 액세스를 요청할 수 있습니다. 자세한 내용은 Windows 인스턴스용 Amazon EC2 사용 설명서의 패치, 보안 업데이트 및 AMI ID를 참조하세요.

노드가 `NotReady` 상태임

노드가 NotReady 상태인 경우 해당 노드가 비정상이어서 새 Pods를 예약할 수 없을 가능성이 있습니다. 이는 노드에 CPU 리소스, 메모리 또는 사용 가능한 디스크 공간이 충분하지 않은 등의 다양한 이유로 발생할 수 있습니다.

Amazon EKS 최적화 Windows AMI의 경우 kubelet 구성에 기본적으로 지정된 컴퓨팅 리소스를 예약할 수 없습니다. 리소스 문제를 방지하는 데 도움이 되도록 kubelet에 kube-reserved 및/또는 system-reserved의 구성 값을 제공하여 시스템 프로세스에 컴퓨팅 리소스를 예약할 수 있습니다. 부트스트랩 스크립트의 -KubeletExtraArgs 명령줄 파라미터를 사용하여 이를 수행합니다. 자세한 내용은 Kubernetes 설명서의 Reserve Compute Resources for System Daemons와 이 사용 설명서의 부트스트랩 스크립트 구성 파라미터를 참조하세요.

CNI 로그 수집 도구

Amazon VPC CNI plugin for Kubernetes에는 /opt/cni/bin/aws-cni-support.sh의 노드에서 자체 문제 해결 스크립트를 사용할 수 있습니다. 이 스크립트를 사용하여 지원 사례 및 일반 문제 해결에 대한 진단 로그를 수집할 수 있습니다.

다음 명령을 사용하여 노드에서 스크립트를 실행합니다.


sudo bash /opt/cni/bin/aws-cni-support.sh

참고

해당 위치에 스크립트가 없으면 CNI 컨테이너를 실행할 수 없습니다. 다음 명령을 사용하여 스크립트를 수동으로 다운로드하고 실행할 수 있습니다.


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

이 스크립트는 다음 진단 정보를 수집합니다. 배포한 CNI 버전은 스크립트 버전보다 이전 버전일 수 있습니다.

      This is version 0.6.1. New versions can be found at https://github.com/awslabs/amazon-eks-ami

Trying to collect common operating system logs... 
Trying to collect kernel logs... 
Trying to collect mount points and volume information... 
Trying to collect SELinux status... 
Trying to collect iptables information... 
Trying to collect installed packages... 
Trying to collect active system services... 
Trying to collect Docker daemon information... 
Trying to collect kubelet information... 
Trying to collect L-IPAMD information... 
Trying to collect sysctls information... 
Trying to collect networking information... 
Trying to collect CNI configuration information... 
Trying to collect running Docker containers and gather container data... 
Trying to collect Docker daemon logs... 
Trying to archive gathered information... 

	Done... your bundled logs are located in /var/log/eks_i-0717c9d54b6cfaa19_2020-03-24_0103-UTC_0.6.1.tar.gz

진단 정보는 다음에 수집되고 저장됩니다.


/var/log/eks_i-0717c9d54b6cfaa19_2020-03-24_0103-UTC_0.6.1.tar.gz

컨테이너 런타임 네트워크가 준비되지 않음

다음과 같은 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 역할 항목이 포함되어 있지 않습니다.

노드가 다음 기준 중 하나를 충족하는 경우 이 ConfigMap 항목이 필요합니다.
- Kubernetes 또는 플랫폼 버전을 사용하는 클러스터의 관리형 노드.
- Amazon EKS 클러스터의 Kubernetes 객체에 대한 IAM 역할 또는 사용자 액세스 허용 주제의 사전 조건 섹션에 나열된 플랫폼 버전보다 이전 버전인 클러스터의 자체 관리형 노드.
이 문제를 해결하기 위해 다음 명령에서 my-cluster를 클러스터 이름으로 바꾸고 수정된 명령(eksctl get iamidentitymapping --cluster my-cluster)을 실행하여 ConfigMap에서 기존 항목을 확인합니다. 명령에서 오류 메시지를 받은 경우 클러스터에 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이 아님)을 지정해야 합니다.
자체 관리형 노드는 Amazon EKS 클러스터의 Kubernetes 객체에 대한 IAM 역할 또는 사용자 액세스 허용 주제의 사전 조건에 나열된 최소 버전의 플랫폼 버전에 포함되어 있지만, 노드 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 프로세스가 지속적으로 다시 생성되어 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"

VPC 승인 webhook 인증서 만료

VPC 승인 웹후크에 서명하는 데 사용된 인증서가 만료되면 새 Windows Pod 배포의 상태는 ContainerCreating으로 남아 있습니다.

데이터 영역에 레거시 Windows 지원이 있는 경우 이 문제를 해결하려면 VPC 승인 Webhook 인증서 갱신 부분을 참조하세요. 클러스터 및 플랫폼 버전이 Windows 지원 사전 조건에 나열된 버전보다 이후인 경우 레거시 Windows 지원을 데이터 영역에서 제거하고 컨트롤 플레인에 대해 사용 설정하는 것이 좋습니다. 그러면 웹후크 인증서를 관리할 필요가 없습니다. 자세한 내용은 Amazon EKS 클러스터에 대해 Windows 지원 사용 설정 단원을 참조하십시오.

컨트롤 플레인을 업데이트하기 전에 노드 그룹이 Kubernetes 버전과 일치해야 합니다.

컨트롤 플레인을 새 Kubernetes 버전으로 업그레이드하기 전에 클러스터에 있는 관리형 노드 및 Fargate 노드의 부 버전이 컨트롤 플레인의 현재 버전과 동일해야 합니다. Amazon EKS update-cluster-version API는 모든 Amazon EKS 관리형 노드를 현재 클러스터 버전으로 업그레이드할 때까지 요청을 거부합니다. Amazon EKS는 관리형 노드 업그레이드를 위한 API를 제공합니다. 관리형 노드 그룹의 Kubernetes 버전 업그레이드에 대한 자세한 내용은 관리형 노드 그룹 업데이트 섹션을 참조하세요. Fargate 노드의 버전을 업그레이드하려면 컨트롤 플레인을 업그레이드한 후 노드가 나타내는 pod를 삭제하고 pod를 다시 배포합니다. 자세한 내용은 Amazon EKS 클러스터 Kubernetes 버전 업데이트 단원을 참조하십시오.

많은 노드를 시작할 때 `Too Many Requests` 오류가 있습니다.

많은 노드를 동시에 시작하는 경우 Amazon EC2 사용자 데이터 실행 로그에 Too Many Requests라는 오류 메시지가 표시될 수 있습니다. 컨트롤 플레인이 describeCluster 호출로 오버로드되기 때문일 수 있습니다. 오버로드는 제한, 부트스트랩 스크립트를 실행하지 못하는 노드, 클러스터에 참여하지 못하는 노드를 초래합니다.

--apiserver-endpoint, --b64-cluster-ca 및 --dns-cluster-ip 인수가 노드의 부트스트랩 스크립트에 전달되고 있는지 확인합니다. 이러한 인수를 포함하면 부트스트랩 스크립트가 describeCluster를 호출할 필요가 없으므로 컨트롤 플레인 오버로드를 방지하는 데 도움이 됩니다. 자세한 내용은 Amazon EKS 최적화 Linux/Bottlerocket AMI에 포함된 bootstrap.sh 파일에 인수를 전달하기 위해 사용자 데이터를 제공함 단원을 참조하십시오.

Kubernetes API 서버 요청에 대한 HTTP 401 권한 없음 오류 응답

이러한 오류는 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 이상

오래된 토큰을 사용하는 클러스터의 모든 기존 Pods를 식별할 수 있습니다. 자세한 내용을 알아보려면 Kubernetes 서비스 계정을 참조하세요.

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

Solution

동일한 이름으로 새 클러스터 IAM 역할을 생성합니다.

문제

클러스터 생성 중에 지정된 서브넷이 삭제됨 - 클러스터와 함께 사용할 서브넷이 클러스터 생성 중에 지정되었습니다. 다음 명령을 사용하여 지정된 서브넷을 확인할 수 있습니다. my-cluster를 해당 클러스터의 이름으로 바꿉니다.


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

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

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

Solution

계정에 서브넷 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가 클러스터를 업데이트하도록 하려면 클러스터에서 사용하는 서브넷을 변경해야 합니다. 클러스터를 생성할 때 서브넷을 3개 이상 지정한 경우 Amazon EKS는 새로운 탄력적 네트워크 인터페이스를 생성하기 위해 지정한 서브넷을 무작위로 선택하기 때문입니다. 이러한 네트워크 인터페이스를 사용하면 컨트롤 플레인이 노드와 통신할 수 있습니다. Amazon EKS는 선택한 서브넷이 없는 경우 클러스터를 업데이트하지 않습니다. Amazon EKS가 새 네트워크 인터페이스를 생성하기 위해 선택하는 클러스터 생성 시 지정한 서브넷을 컨트롤할 수 없습니다.

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

문제

클러스터 생성 중에 지정된 보안 그룹이 삭제됨 - 클러스터 생성 중에 보안 그룹을 지정한 경우 다음 명령을 사용하여 보안 그룹의 ID를 볼 수 있습니다. my-cluster를 해당 클러스터의 이름으로 바꿉니다.


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

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

[
    "sg-EXAMPLE1"
]

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

Solution

계정에 이러한 보안 그룹이 있는지 확인합니다.


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가 클러스터를 업데이트하도록 하려면 클러스터에서 사용하는 보안 그룹을 변경해야 합니다. 클러스터 생성 시 지정된 보안 그룹 ID가 없는 경우 Amazon EKS는 클러스터를 업데이트하지 않습니다.

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

Amazon EKS가 클러스터의 플랫폼 버전을 업데이트하지 않는 기타 이유

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

클러스터 상태 FAQ 및 오류 코드(해결 경로 포함)

Amazon EKS는 EKS 클러스터 및 클러스터 인프라에서 문제를 감지하여 클러스터 상태에 저장합니다. 클러스터 상태 정보를 사용하여 클러스터 문제를 더 빠르게 감지하고 해결할 수 있습니다. 이를 통해 보다 안전하고 최신 상태인 애플리케이션 환경을 구축할 수 있습니다. 또한 필요한 인프라 또는 클러스터 구성 문제로 인해 Amazon EKS에서 성능이 저하된 클러스터에 보안 업데이트를 설치하거나 Kubernetes의 최신 버전으로 업그레이드할 수 없습니다. Amazon EKS에서 문제 자체 또는 문제가 해결되었음을 감지하는 데 3시간이 걸릴 수 있습니다.

Amazon EKS 클러스터의 상태에 대해서는 Amazon EKS와 해당 사용자가 공동으로 책임을 집니다. 사용자는 IAM 역할 및 Amazon VPC 서브넷의 필수 인프라와 사전에 제공해야 하는 기타 필수 인프라를 책임져야 합니다. Amazon EKS는 이 인프라 및 클러스터의 구성 변경을 감지합니다.

Amazon EKS 콘솔에서 클러스터 상태에 액세스하려면 Amazon EKS 클러스터 세부 정보 페이지의 개요 탭에서 상태 문제 섹션을 살펴봅니다. 이 데이터는 EKS API에서 DescribeCluster 작업을 직접 호출하여 사용할 수도 있습니다(예: AWS Command Line Interface 내에서 수행).

왜 이 기능을 사용해야 하나요?: 디버깅하거나 AWS 지원 사례를 여는 데 시간을 소비하지 않고도 Amazon EKS 클러스터의 상태를 더 잘 파악하고 문제를 신속하게 진단 및 수정할 수 있습니다. 예: 실수로 Amazon EKS 클러스터의 서브넷을 삭제한 경우 Amazon EKS는 크로스 계정 네트워크 인터페이스 및 Kubernetes AWS CLI 명령(예: kubectl exec) 또는 kubectl 로그를 생성할 수 없습니다. 다음과 같은 오류와 함께 실패합니다. Error from server: error dialing backend: remote error: tls: internal error. 이제 다음과 같은 Amazon EKS 상태 문제가 표시됩니다. subnet-da60e280 was deleted: could not create network interface.
이 기능은 다른 AWS 서비스와 어떻게 관련되었거나 어떻게 작동하나요?: IAM 역할과 Amazon VPC 서브넷은 클러스터 상태에서 문제를 감지하는 필수 인프라의 두 가지 예입니다. 이 기능은 리소스가 제대로 구성되지 않은 경우 자세한 정보를 반환합니다.
상태 문제가 있는 클러스터에서 요금이 발생하나요?: 예. 모든 아마존 EKS 클러스터에는 표준 Amazon EKS 요금이 청구됩니다. 클러스터 상태 기능은 추가 비용 없이 사용할 수 있습니다.
이 기능은 AWS Outposts의 Amazon EKS 클러스터에서 작동하나요?: 예. AWS Outposts의 확장 클러스터 및 AWS Outposts의 로컬 클러스터를 포함하여 AWS 클라우드의 EKS 클러스터에서 클러스터 문제가 감지됩니다. 클러스터 상태에서는 Amazon EKS Anywhere 또는 Amazon EKS Distro(EKS-D) 관련 문제를 감지하지 못합니다.
새로운 문제가 감지되면 알림을 받을 수 있나요?: 아니요. Amazon EKS 콘솔을 확인하거나 EKS DescribeCluster API를 직접 호출해야 합니다.
콘솔에서 상태 문제에 대한 경고를 제공하나요?: 예. 상태 문제가 있는 모든 클러스터에는 콘솔 상단에 배너가 포함됩니다.

처음 두 열은 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가 필수 관리 작업을 수행할 수 있는 충분한 권한을 부여하지 않습니다. 클러스터 역할에 연결된 정책을 확인하고 별도의 거부 정책이 적용되어 있는지 확인합니다.	클러스터 IAM 역할	예
ASSUME_ROLE_ACCESS_DENIED_USING_SLR	Amazon EKS 클러스터 관리 서비스 연결 역할을 수임할 수 없었습니다. 역할이 존재하고 필요한 신뢰 정책이 있는지 확인합니다.	Amazon EKS 서비스 연결 역할	예
PERMISSION_ACCESS_DENIED_USING_SLR	Amazon EKS 클러스터 관리 서비스 연결 역할이 Amazon EKS가 필수 관리 작업을 수행할 수 있는 충분한 권한을 부여하지 않습니다. 클러스터 역할에 연결된 정책을 확인하고 별도의 거부 정책이 적용되어 있는지 확인합니다.	Amazon EKS 서비스 연결 역할	예
OPT_IN_REQUIRED	계정에 Amazon EC2 서비스 구독이 없습니다. 계정 설정 페이지에서 계정 구독을 업데이트합니다.	N/A	예
STS_REGIONAL_ENDPOINT_DISABLED	STS 리전 엔드포인트가 비활성화되었습니다. Amazon EKS의 엔드포인트가 필수 클러스터 관리 작업을 수행할 수 있도록 합니다.	N/A	예
KMS_KEY_DISABLED	클러스터와 연결된 AWS KMS 키가 비활성화되었습니다. 키를 다시 활성화하여 클러스터를 복구합니다.	KMS Key Arn은	예
KMS_KEY_NOT_FOUND	클러스터와 연결된 AWS KMS 키를 찾을 수 없습니다. 클러스터를 삭제하고 다시 생성해야 합니다.	KMS Key ARN은	아니요
KMS_GRANT_REVOKED	클러스터와 연결된 AWS KMS 키에 부여된 권한이 취소됩니다. 클러스터를 삭제하고 다시 생성해야 합니다.	KMS Key Arn은	아니요

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

Amazon Detective

Amazon EKS Connector