AWS Outposts의 Amazon EKS에 대한 로컬 클러스터 문제 해결 - Amazon EKS

AWS Outposts의 Amazon EKS에 대한 로컬 클러스터 문제 해결

이 주제에서는 로컬 클러스터를 사용하는 동안 발생할 수 있는 몇 가지 일반적 오류와 문제를 해결하는 방법을 설명합니다. 로컬 클러스터는 클라우드의 Amazon EKS 클러스터와 유사하지만, Amazon EKS 서비스에서 관리하는 방식에는 몇 가지 차이점이 있습니다.

로컬 클러스터는 Amazon EKS API를 통해 생성되지만, 비동기 방식으로 실행됩니다. 즉, Amazon EKS API에 대한 요청이 로컬 클러스터에 즉시 반환됩니다. 그러나 이러한 요청은 성공하거나, 입력 검증 오류로 인해 빠르게 실패하거나, 실패하고 설명이 포함된 검증 오류가 있을 수 있습니다. 이 동작은 Kubernetes API와 유사합니다.

로컬 클러스터는 FAILED 상태로 전환되지 않습니다. Amazon EKS에서는 클러스터 상태를 사용자가 요청한 원하는 상태와 지속적으로 조정하려고 시도합니다. 따라서 로컬 클러스터가 근본적인 문제가 해결될 때까지 장기간 CREATING 상태로 유지될 수도 있습니다.

로컬 클러스터 문제는 describe-cluster Amazon EKS AWS CLI 명령을 사용하여 검색할 수 있습니다. 로컬 클러스터 문제는 describe-cluster 명령 응답의 cluster.health 필드에 표시됩니다. 이 필드에 포함된 메시지에는 오류 코드, 설명이 포함된 메시지 및 관련 리소스 ID가 포함됩니다. 이 정보는 Amazon EKS API와 AWS CLI를 통해서만 제공됩니다. 다음 예제에서 my-cluster를 로컬 클러스터의 이름으로 바꿉니다.

aws eks describe-cluster --name my-cluster --query 'cluster.health'

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

{
    "issues": [
        {
            "code": "ConfigurationConflict",
            "message": "The instance type 'm5.large' is not supported in Outpost 'my-outpost-arn'.",
            "resourceIds": [
                "my-cluster-arn"
            ]
        }
    ]
}

문제를 복구할 수 없는 경우 로컬 클러스터를 삭제하고 새 클러스터를 생성해야 할 수 있습니다. 예를 들어 Outpost에서 사용할 수 없는 인스턴스 유형으로 클러스터를 프로비저닝하려고 합니다. 다음 표에는 일반적인 상태 관련 오류가 포함되어 있습니다.

오류 시나리오 코드 메시지 ResourceIds

제공된 서브넷을 찾을 수 없습니다.

ResourceNotFound

The subnet ID subnet-id does not exist

 제공된 모든 서브넷 ID

제공된 서브넷이 동일한 VPC에 속하지 않습니다.

ConfigurationConflict

Subnets specified must belong to the same VPC

 제공된 모든 서브넷 ID

제공된 일부 서브넷이 지정된 Outpost에 속하지 않습니다.

ConfigurationConflict

Subnet subnet-id expected to be in outpost-arn, but is in other-outpost-arn

 문제가 있는 서브넷 ID

제공된 일부 서브넷이 어느 Outpost에도 속하지 않습니다.

ConfigurationConflict

Subnet subnet-id is not part of any Outpost

 문제가 있는 서브넷 ID

제공된 일부 서브넷에 컨트롤 플레인 인스턴스용 탄력적 네트워크 인터페이스를 생성하기에 충분한 여유 주소가 없습니다.

ResourceLimitExceeded

The specified subnet does not have enough free addresses to satisfy the request.

 문제가 있는 서브넷 ID

지정된 컨트롤 플레인 인스턴스 유형이 Outpost에서 지원되지 않습니다.

ConfigurationConflict

The instance type type is not supported in Outpost outpost-arn

 클러스터 ARN
컨트롤 플레인 Amazon EC2 인스턴스를 종료했거나 run-instance에 성공했지만, 관찰된 상태가 Terminated로 변경됩니다. 이는 Outpost가 다시 연결되고 Amazon EBS 내부 오류로 인해 Amazon EC2 내부 워크플로가 실패한 후 일정 기간 동안 발생할 수 있습니다.

InternalFailure

EC2 instance state "Terminated" is unexpected

 클러스터 ARN

Outpost의 용량이 부족합니다. 이는 Outpost가 AWS 리전에서 연결 해제된 경우 클러스터를 생성 중일 때 발생할 수도 있습니다.

ResourceLimitExceeded

There is not enough capacity on the Outpost to launch or start the instance.

 클러스터 ARN
계정에서 보안 그룹 할당량을 초과했습니다.

ResourceLimitExceeded

 Amazon EC2 API에서 반환된 오류 메시지 대상 VPC ID
계정에서 탄력적 네트워크 인터페이스 할당량을 초과했습니다.

ResourceLimitExceeded

 Amazon EC2 API에서 반환된 오류 메시지 대상 서브넷 ID

컨트롤 플레인 인스턴스가 AWS Systems Manager를 통해 연결되지 않았습니다. 해결 방법은 컨트롤 플레인 인스턴스는 AWS Systems Manager를 통해 연결할 수 없습니다. 섹션을 참조하세요.

ClusterUnreachable

Amazon EKS control plane instances are not reachable through SSM. Please verify your SSM and network configuration, and reference the EKS on Outposts troubleshooting documentation.(Amazon EKS 컨트롤 플레인 인스턴스는 SSM을 통해 연결할 수 없습니다. SSM 및 네트워크 구성을 확인하고 Outposts의 EKS 문제 해결 문서를 참조하세요.)

 Amazon EC2 인스턴스 ID
관리형 보안 그룹 또는 탄력적 네트워크 인터페이스에 대한 세부 정보를 가져오는 동안 오류가 발생했습니다.

Amazon EC2 클라이언트 오류 코드 기준

 Amazon EC2 API에서 반환된 오류 메시지 모든 관리형 보안 그룹 ID
보안 그룹 수신 규칙을 승인하거나 취소하는 동안 오류가 발생했습니다. 이는 클러스터 및 컨트롤 플레인 보안 그룹 모두에 적용됩니다. Amazon EC2 클라이언트 오류 코드 기준 Amazon EC2 API에서 반환된 오류 메시지 문제가 있는 보안 그룹 ID
컨트롤 플레인 인스턴스에 대한 탄력적 네트워크 인터페이스를 삭제하는 동안 오류가 발생했습니다. Amazon EC2 클라이언트 오류 코드 기준 Amazon EC2 API에서 반환된 오류 메시지 문제가 있는 탄력적 네트워크 인터페이스 ID

다음 표에는 describe-cluster 응답의 상태 필드에 표시되는 다른 AWS 서비스의 오류가 나열되어 있습니다.

Amazon EC2 오류 코드 클러스터 상태 문제 코드 설명

AuthFailure

AccessDenied

 이 오류는 여러 가지 이유로 발생할 수 있습니다. 가장 일반적인 이유는 서비스 연결 역할 정책의 범위를 좁히기 위해 서비스에서 사용하는 태그를 컨트롤 플레인에서 실수로 제거했기 때문입니다. 이렇게 되면 Amazon EKS에서 더는 이러한AWS 리소스를 관리하고 모니터링할 수 없습니다.

UnauthorizedOperation

AccessDenied

 이 오류는 여러 가지 이유로 발생할 수 있습니다. 가장 일반적인 이유는 서비스 연결 역할 정책의 범위를 좁히기 위해 서비스에서 사용하는 태그를 컨트롤 플레인에서 실수로 제거했기 때문입니다. 이렇게 되면 Amazon EKS에서 더는 이러한AWS 리소스를 관리하고 모니터링할 수 없습니다.

InvalidSubnetID.NotFound

ResourceNotFound

이 오류는 보안 그룹의 수신 규칙에 대한 서브넷 ID를 찾을 수 없을 때 발생합니다.

InvalidPermission.NotFound

ResourceNotFound

 이 오류는 보안 그룹의 수신 규칙에 대한 권한이 올바르지 않을 때 발생합니다.

InvalidGroup.NotFound

ResourceNotFound

 이 오류는 보안 그룹의 수신 규칙 그룹을 찾을 수 없을 때 발생합니다.

InvalidNetworkInterfaceID.NotFound

ResourceNotFound

 이 오류는 보안 그룹의 수신 규칙에 대한 네트워크 인터페이스 ID를 찾을 수 없을 때 발생합니다.

InsufficientFreeAddressesInSubnet

ResourceLimitExceeded

 이 오류는 서브넷 리소스 할당량을 초과했을 때 발생합니다.

InsufficientCapacityOnOutpost

ResourceLimitExceeded

 이 오류는 출력 용량 할당량을 초과했을 때 발생합니다.

NetworkInterfaceLimitExceeded

ResourceLimitExceeded

이 오류는 탄력적 네트워크 인터페이스 할당량을 초과했을 때 발생합니다.

SecurityGroupLimitExceeded

ResourceLimitExceeded

 이 오류는 보안 그룹 할당량을 초과했을 때 발생합니다.

VcpuLimitExceeded

ResourceLimitExceeded

 이는 새 계정에서 Amazon EC2 인스턴스를 생성할 때 관찰됩니다. 오류는 다음과 비슷할 수 있습니다. "You have requested more vCPU capacity than your current vCPU limit of 32 allows for the instance bucket that the specified instance type belongs to. Please visit http://aws.amazon.com/contact-us/ec2-request to request an adjustment to this limit."

InvalidParameterValue

ConfigurationConflict

지정된 인스턴스 유형이 Outpost에서 지원되지 않는 경우 Amazon EC2가 이 오류 코드를 반환합니다.
기타 모든 오류

InternalFailure

 None

클라우드에서 호스팅되는 Amazon EKS 클러스터와 다른 권한과 정책이 로컬 클러스터에 필요합니다. 클러스터가 생성되지 않고 InvalidPermissions 오류가 발생하면 사용 중인 클러스터 역할에 AmazonEKSLocalOutpostClusterPolicy 관리형 정책이 연결되어 있는지 다시 확인합니다. 다른 모든 API 호출에는 클라우드의 Amazon EKS 클러스터와 동일한 권한 집합이 필요합니다.

로컬 클러스터 생성에 걸리는 시간은 여러 가지 요인에 따라 다릅니다. 네트워크 구성, Outpost 구성 및 클러스터의 구성이 이러한 요인에 포함됩니다. 일반적으로 15~20분 이내에 로컬 클러스터가 생성되고 ACTIVE 상태로 변경됩니다. 로컬 클러스터가 CREATING 상태로 유지되는 경우 cluster.health 출력 필드에서 원인에 대한 정보의 describe-cluster를 호출할 수 있습니다.

가장 일반적인 문제는 다음과 같습니다.

AWS Systems Manager(Systems Manager)에서 다음과 같은 문제가 발생합니다.

  • 클러스터에서 Systems Manager가 있는 AWS 리전의 컨트롤 플레인 인스턴스에 연결할 수 없습니다. 리전 내 Bastion Host에서 aws ssm start-session --target instance-id를 호출하여 이를 확인할 수 있습니다. 명령이 작동하지 않으면 Systems Manager가 컨트롤 플레인 인스턴스에서 실행 중인지 확인합니다. 클러스터를 삭제한 다음에 다시 생성하여 해결하는 방법도 있습니다.

  • Systems Manager 컨트롤 플레인 인스턴스에 인터넷 액세스 권한이 없을 수도 있습니다. 클러스터를 생성할 때 제공한 서브넷에 NAT 게이트웨이와 VPC(인터넷 게이트웨이 포함)가 있는지 확인합니다. VPC 연결성 분석기를 사용하여 컨트롤 플레인 인스턴스가 인터넷 게이트웨이에 연결할 수 있는지 확인합니다. 자세한 내용을 알아보려면 Getting started with VPC Reachability Analyzer(VPC Reachability Analyzer 시작하기)를 참조하세요.

  • 제공한 역할 ARN에 정책이 없습니다. 역할에서 AWS 관리형 정책: AmazonEKSLocalOutpostClusterPolicy가 제거되었는지 확인합니다. AWS CloudFormation 스택이 잘못 구성된 경우에도 이 문제가 발생할 수 있습니다.

클러스터가 생성될 때 여러 서브넷이 잘못 구성되고 지정되었음:

  • 제공된 모든 서브넷이 동일한 Outpost와 연결되어야 하며 서로 연결되어야 합니다. 클러스터가 생성될 때 여러 서브넷이 지정되면 Amazon EKS에서는 컨트롤 플레인 인스턴스를 여러 서브넷에 분산하려고 시도합니다.

  • Amazon EKS 관리형 보안 그룹은 탄력적 네트워크 인터페이스에 적용됩니다. 그러나 NACL 방화벽 규칙과 같은 기타 구성 요소가 탄력적 네트워크 인터페이스의 규칙과 충돌할 수도 있습니다.

VPC 및 서브넷 DNS 구성이 잘못 구성되었거나 누락됨

Amazon EKS 로컬 클러스터 VPC 및 서브넷 요구 사항과 고려 사항 섹션을 검토합니다.

일반적인 원인:

  • AMI 문제:

    • 지원되지 않는 AMI를 사용하고 있습니다. Amazon EKS 최적화 Amazon Linux AMI Amazon EKS 최적화 Amazon Linux에 v20220620 이상을 사용해야 합니다.

    • AWS CloudFormation 템플릿을 사용하여 노드를 생성한 경우 지원되지 않는 AMI를 사용하고 있지 않은지 확인합니다.

  • AWS IAM Authenticator ConfigMap 누락 – 누락된 경우 생성해야 합니다. 자세한 정보는 클러스터에 aws-authConfigMap 적용을 참조하세요.

  • 잘못된 보안 그룹 사용 - 워커 노드의 보안 그룹에 eks-cluster-sg-cluster-name-uniqueid를 사용해야 합니다. 선택한 보안 그룹은 스택이 사용될 때마다 새 보안 그룹을 허용하도록 AWS CloudFormation에 의해 변경됩니다.

  • 예상치 못한 프라이빗 링크 VPC 단계 수행 – 잘못된 CA 데이터(--b64-cluster-ca) 또는 API 엔드포인트(--apiserver-endpoint)가 전달됩니다.

  • 잘못 구성된 Pod 보안 정책:

    • 노드가 클러스터와 조인하고 통신하도록 노드에서 CoreDNS 및 Amazon VPC CNI plugin for Kubernetes Daemonsets가 실행되어야 합니다.

    • Amazon VPC CNI plugin for Kubernetes가 제대로 작동하려면 일부 권한 있는 네트워킹 기능이 필요합니다. kubectl describe psp eks.privileged 명령을 사용하여 권한 있는 네트워킹 기능을 볼 수 있습니다.

    기본 포드 보안 정책을 수정하지 않는 것이 좋습니다. 자세한 내용은 포드 보안 정책 섹션을 참조하세요.

Outpost가 연결된 AWS 리전에서 연결 해제되면 Kubernetes 클러스터는 정상적으로 계속 작동할 수 있습니다. 단, 클러스터가 제대로 작동하지 않는 경우 네트워크 연결 해제 준비의 문제 해결 단계를 따릅니다. 기타 문제가 발생하면 AWS Support에 문의하세요. AWS Support에서는 로그 수집 도구를 다운로드하고 실행하는 방법을 안내할 수 있습니다. 그렇게 하면 Kubernetes 클러스터 컨트롤 플레인 인스턴스에서 로그를 수집하여 추가 조사를 위해 AWS Support 지원에 보낼 수 있습니다.

AWS Systems Manager(Systems Manager)를 통해 Amazon EKS 컨트롤 플레인 인스턴스에 연결할 수 없는 경우 Amazon EKS는 클러스터에 대해 다음 오류를 표시합니다.

Amazon EKS control plane instances are not reachable through SSM. Please verify your SSM and network configuration, and reference the EKS on Outposts troubleshooting documentation.

이 문제를 해결하려면 VPC와 서브넷이 Amazon EKS 로컬 클러스터 VPC 및 서브넷 요구 사항과 고려 사항의 요구 사항을 충족하고 AWS Systems Manager 사용 설명서의 Session Manager 설정 단계를 완료했는지 확인합니다.