Amazon EKS 문제 해결 - Amazon EKS

Amazon EKS 문제 해결

이 장에서는 Amazon EKS를 사용하는 동안 발생할 수 있는 몇 가지 일반 오류와 이를 해결하는 방법을 다룹니다.

용량 부족

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

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

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

  • aws-auth-cm.yaml 파일에는 노드에 대한 올바른 IAM 역할 ARN이 없습니다. 노드 IAM 역할 ARN(인스턴스 프로파일 ARN이 아님)이 aws-auth-cm.yaml 파일에서 지정되어야 합니다. 자세한 내용은 섹션을 참조하세요자체 관리형 Amazon Linux 노드 시작하기

  • 노드 AWS CloudFormation템플릿에서 ClusterName은 조인할 클러스터의 이름과 정확히 일치하지 않습니다. 이 필드에 올바르지 않은 값을 전달하면 노드의 /var/lib/kubelet/kubeconfig 파일의 올바르지 않은 구성이 발생하고, 노드가 클러스터에 조인되지 않습니다.

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

    kubernetes.io/cluster/<cluster-name>

    owned

  • 노드는 퍼블릭 IP 주소를 사용하여 클러스터에 액세스하지 못할 수 있습니다. 퍼블릭 서브넷에 배포된 노드에 퍼블릭 IP 주소가 할당되었는지 확인합니다. 그렇지 않은 경우 시작 후 탄력적 IP 주소를 노드에 연결할 수 있습니다. 자세한 내용은 실행 중인 인스턴스 또는 네트워크 인터페이스와 탄력적 IP 주소 연결을 참조하세요. 퍼블릭 IP 주소를 배포된 인스턴스에 자동으로 할당하도록 퍼블릭 서브넷이 설정되어 있지 않은 경우, 해당 설정을 사용하도록 설정하는 것이 좋습니다. 자세한 내용은 서브넷의 퍼블릭 IPv4 주소 지정 속성 수정 단원을 참조하십시오. 노드가 프라이빗 서브넷에 배포된 경우, 서브넷에는 퍼블릭 IP 주소가 할당된 NAT 게이트웨이에 대한 경로가 있어야 합니다.

  • 노드를 배포할 리전의 STS 엔드포인트가 계정에 대해 활성화되지 않았습니다. 리전을 활성화하려면 AWS STS 리전에서 AWS 활성화 및 비활성화를 참조하십시오.

  • 작업자 노드에 프라이빗 DNS 항목이 없으므로 node "" not found 오류를 포함하는 kubelet 로그가 발생합니다. 작업자 노드가 생성된 VPC에 대해 DHCP options setdomain-namedomain-name-servers 값이 Options로 설정되어 있어야 합니다. 기본값은 domain-name:<region>.compute.internaldomain-name-servers:AmazonProvidedDNS입니다. 자세한 내용은 Amazon VPC 사용 설명서의 DHCP 옵션 세트를 참조하세요.

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

kubectl 명령을 실행할 때 다음 오류 중 하나가 발생하는 경우 kubectl이 Amazon EKS에 대해 올바르게 구성되지 않았거나, 사용하고 있는 IAM 사용자 또는 역할 자격 증명이 Amazon EKS 클러스터에 충분한 권한이 있는 Kubernetes RBAC 사용자에 매핑되지 않은 것입니다.

  • 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"

이는 클러스터가 AWS 자격 증명 집합(IAM 사용자 또는 역할에서)을 사용해 생성되었고 kubectl은 다른 자격 증명 집합을 사용하고 있기 때문입니다.

Amazon EKS 클러스터가 생성될 때 클러스터를 생성하는 IAM 엔터티(사용자 또는 역할)가 Kubernetes RBAC 권한 부여 표에 관리자(system:masters 권한이 있음)로 추가됩니다. 처음에는 해당 IAM 사용자만 kubectl을 사용하여 Kubernetes API 서버를 호출할 수 있습니다. 자세한 내용은 섹션을 참조하세요클러스터의 사용자 또는 IAM 역할 관리 콘솔을 사용하여 클러스터를 생성하는 경우 클러스터에서 kubectl 명령을 실행할 때 동일한 IAM 사용자 자격 증명이 AWS SDK 자격 증명 체인에 있어야 합니다.

AWS CLI를 설치하고 구성하면 사용자에 대한 IAM 자격 증명을 구성할 수 있습니다. 자세한 내용은 AWS Command Line Interface 사용 설명서AWS CLI 구성을 참조하세요.

Amazon EKS 클러스터를 생성하는 역할을 수임할 경우 kubectl이 동일한 역할을 수임할 수 있도록 구성해야 합니다. 다음 명령을 통해 IAM 역할을 사용할 kubeconfig 파일을 업데이트합니다. 자세한 내용은 섹션을 참조하세요Amazon EKS용 kubeconfig 생성

aws eks update-kubeconfig \ --region <region-code> \ --name <cluster_name> \ --role-arn arn:aws:iam::<aws_account_id>:role/<role_name>

IAM 사용자를 Kubernetes RBAC 사용자에 매핑하려면 클러스터의 사용자 또는 IAM 역할 관리 섹션을 참조하세요.

aws-iam-authenticator 찾을 수 없음

"aws-iam-authenticator": executable file not found in $PATH 오류가 표시되는 경우 Amazon EKS에 대해 kubectl이 구성되지 않았습니다. 자세한 내용은 섹션을 참조하세요aws-iam-authenticator 설치

참고

AWS CLI 버전 1.16.156 이상이 설치되어 있는 경우에는 aws-iam-authenticator가 필요하지 않습니다.

hostname doesn't match

시스템의 Python 버전이 2.7.9 이상이어야 합니다. 그렇지 않은 경우 Amazon EKS에 대한 AWS CLI 호출과 함께 hostname doesn't match 오류가 표시됩니다. 자세한 내용은 Python Requests FAQ의 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

관리형 노드 그룹 오류

AWS Management Console에서 “인스턴스가 kubernetes 클러스터에 조인하지 못했습니다.” 오류 메시지가 표시되면 클러스터의 프라이빗 엔드포인트 액세스가 활성화되어 있는지 또는 퍼블릭 엔드포인트 액세스에 대해 CIDR 블록을 올바르게 구성했는지 확인합니다. 자세한 내용은 섹션을 참조하세요Amazon EKS 클러스터 엔드포인트 액세스 제어

관리형 노드 그룹에 하드웨어 상태 문제가 발생하면 Amazon EKS는 문제 진단에 도움이 되는 오류 메시지를 반환합니다. 이러한 상태 확인은 Amazon EC2 상태 확인을 기반으로 하기 때문에 소프트웨어 문제를 감지하지 못합니다. 오류 메시지 및 관련 설명은 다음과 같습니다.

  • AccessDenied: Amazon EKS 또는 하나 이상의 관리형 노드가 Kubernetes 클러스터 API 서버로 인증하거나 인증하지 못합니다. 이러한 오류에 대한 자세한 내용은 관리형 노드 그룹의 AccessDenied 오류 해결 섹션을 참조하세요.

  • 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 주소를 사용하여 인터넷에 액세스할 수 있어야 제대로 작동합니다. 자세한 내용은 섹션을 참조하세요VPC IP 주소 지정 또한 인터넷에 개방된 포트가 노드에 있어야 합니다. 자세한 내용은 섹션을 참조하세요Amazon EKS 보안 그룹 고려 사항

  • 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 또는 ClusterRoleBindingAcessDenied 오류의 원인으로 확인된 경우 복원할 수 있습니다. 다음 콘텐츠를 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

노드 그룹 작업을 다시 시도하여 문제가 해결되었는지 확인합니다.

CNI 로그 수집 도구

Kubernetes용 Amazon VPC CNI 플러그인에는 /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 IAM Authenticator 구성 맵이 노드에 적용되지 않아서 발생할 가능성이 큽니다. 구성 맵은 노드를 클러스터에 등록할 수 있도록 system:bootstrapperssystem:nodes Kubernetes RBAC 권한을 제공합니다. 자세한 내용은 자체 관리형 Amazon Linux 노드 시작하기자체 관리형 노드 노드 탭에서 노드가 클러스터에 조인하도록 하려면을 참조하세요. 구성 맵에 인스턴스 프로필 ARN이 아니라 인스턴스 역할의 역할 ARN를 지정했는지 확인합니다.

다음 예와 같이 / 이외의 경로가 포함된 경우 인증자가 역할 ARN을 인식하지 못합니다.

arn:aws:iam::<111122223333>:role/<development/apps/prod-iam-role-NodeInstanceRole-621LVEXAMPLE>

/ 이외의 경로를 포함하는 구성 맵에서 역할 ARN을 지정할 경우 경로를 삭제해야 합니다. 위의 ARN은 다음과 같이 지정됩니다.

arn:aws:iam::<111122223333>:role/<prod-iam-role-NodeInstanceRole-621LVEXAMPLE>

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

중국 리전에 배포된 포드 또는 데몬 세트의 서비스 계정에 IAM 역할을 사용하고 사양에 AWS_DEFAULT_REGION 환경 변수를 설정하지 않은 경우 포드 또는 데몬 세트에 다음과 같은 오류가 발생할 수 있습니다.

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

이 문제를 해결하려면 다음 예제 포드 사양에 표시된 것처럼 포드 또는 데몬 세트 사양에 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 승인 webhook에 서명하는 데 사용된 인증서가 만료되면 새 Windows 포드 배포의 상태는 ContainerCreating으로 남아 있습니다. 이 상태가 표시되면 다음 명령을 사용하여 이 상태의 포드에 대한 정보를 봅니다.

kubectl describe pod my-pod -n my-namespace

반환된 출력에 다음 이벤트가 표시됩니다.

Warning FailedCreatePodSandBox 39s kubelet

다음 명령을 사용하여 인증서의 만료 날짜를 확인합니다.

kubectl get secret \ -n kube-system \ vpc-admission-webhook-certs -o json | \ jq -r '.data."cert.pem"' | \ base64 --decode | \ openssl x509 \ -noout \ -enddate | \ cut -d= -f2

결과

May 27 14:23:00 2021 GMT

인증서가 만료된 경우 갱신해야 합니다. 자세한 내용은 섹션을 참조하세요VPC 승인 Webhook 인증서 갱신 새 인증서를 배포한 후에는 ContainerCreating 상태로 멈춘 각 포드를 재배포해야 합니다.