AWS Outposts 로컬 Amazon EKS 클러스터 문제 해결

AWS Outposts 로컬 Amazon EKS 클러스터 문제 해결

이 주제에서는 로컬 클러스터를 사용할 때 볼 수 있는 몇 가지 일반적인 오류와 이를 해결하는 방법을 다룹니다. 로컬 클러스터는 클라우드의 Amazon EKS 클러스터와 유사하지만 Amazon EKS가 관리하는 방식에는 몇 가지 차이점이 있어요.

중요: AWS Support가 명시적으로 지시하지 않는 한 Outpost에서 실행되는 관리형 EKS 로컬 클러스터 Kubernetes 제어 플레인 인스턴스를 절대 종료하지 마세요. 이러한 인스턴스를 종료하면 여러 인스턴스가 동시에 종료될 때 로컬 클러스터 손실을 포함해 로컬 클러스터 서비스 가용성에 위험이 발생합니다. EKS 로컬 클러스터 Kubernetes 제어 플레인 인스턴스는 EC2 인스턴스 콘솔에서 eks-local:controlplane-name 태그로 식별됩니다.

출처: 문서

본문

로컬 클러스터는 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에서 사용할 수 없는 인스턴스 유형으로 클러스터를 프로비저닝하려고 하는 경우입니다. 다음 표에는 일반적인 상태 관련 오류가 포함되어 있습니다.

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

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

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

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

• 클러스터가 Systems Manager가 있는 AWS 리전에서 제어 플레인 인스턴스에 연결할 수 없습니다. 리전 내 배스천 호스트에서 aws ssm start-session --target instance-id를 호출해 이를 확인할 수 있어요. 해당 명령이 작동하지 않으면 Systems Manager가 제어 플레인 인스턴스에서 실행 중인지 확인하세요. 또는 다른 해결 방법으로 클러스터를 삭제한 후 다시 만드는 것입니다.
• EBS 볼륨의 KMS 키 권한으로 인해 제어 플레인 인스턴스가 생성에 실패합니다. 암호화된 EBS 볼륨에 사용자 관리형 KMS 키를 사용하면 키에 액세스할 수 없을 때 제어 플레인 인스턴스가 종료됩니다. 인스턴스가 종료되면 AWS 관리형 KMS 키로 전환하거나 사용자 관리형 키 정책이 클러스터 역할에 필요한 권한을 부여하는지 확인하세요.
• Systems Manager 제어 플레인 인스턴스에 인터넷 액세스가 없을 수 있습니다. 클러스터를 생성할 때 제공한 서브넷에 NAT 게이트웨이와 인터넷 게이트웨이가 있는 VPC가 있는지 확인하세요. VPC reachability analyzer를 사용해 제어 플레인 인스턴스가 인터넷 게이트웨이에 도달할 수 있는지 확인합니다. 자세한 내용은 VPC Reachability Analyzer 시작하기를 참고하세요.
• 제공한 역할 ARN에 정책이 누락되어 있습니다. AWS 관리형 정책: AmazonEKSLocalOutpostClusterPolicy가 역할에서 제거되었는지 확인하세요. AWS CloudFormation 스택이 잘못 구성된 경우에도 발생할 수 있어요.
• 제공된 모든 서브넷은 동일한 Outpost와 연결되어야 하며 서로 연결할 수 있어야 합니다. 클러스터가 생성될 때 여러 서브넷이 지정되면 Amazon EKS는 제어 플레인 인스턴스를 여러 서브넷에 분산하려고 시도합니다.
• Amazon EKS 관리형 보안 그룹은 탄력적 네트워크 인터페이스에 적용됩니다. 그러나 NACL 방화벽 규칙 같은 다른 구성 요소가 탄력적 네트워크 인터페이스의 규칙과 충돌할 수 있어요.
• VPC 및 서브넷 DNS 구성이 잘못 구성되었거나 누락되었습니다. AWS Outposts의 Amazon EKS 클러스터용 VPC 및 서브넷 생성을 검토하세요.

Amazon EKS는 해당 Kubernetes 마이너 버전에 대해 모든 기존 로컬 클러스터를 최신 플랫폼 버전으로 자동 업데이트해요. 플랫폼 버전에 대한 자세한 내용은 AWS Outposts용 Kubernetes 및 Amazon EKS 플랫폼 버전 알아보기를 참고하세요.

자동 플랫폼 버전 롤아웃 중 클러스터 상태가 UPDATING으로 변경됩니다. 업데이트 프로세스는 모든 Kubernetes 제어 플레인 인스턴스를 해당 Kubernetes 마이너 버전에 대해 출시된 최신 보안 패치와 버그 수정이 포함된 새 인스턴스로 교체하는 것으로 구성됩니다. 일반적으로 로컬 클러스터 플랫폼 업데이트 프로세스는 30분 이내에 완료되고 클러스터는 ACTIVE 상태로 다시 변경됩니다. 로컬 클러스터가 오랫동안 UPDATING 상태로 유지되면 cluster.health 출력 필드에서 원인에 대한 정보를 확인하기 위해 describe-cluster를 호출할 수 있어요.

Amazon EKS는 로컬 클러스터 가용성을 유지하고 서비스 중단을 방지하기 위해 Kubernetes 제어 플레인 인스턴스 3개 중 최소 2개가 정상이고 작동하는 클러스터 노드인지 확인합니다. 로컬 클러스터가 UPDATING 상태에서 멈추면 일반적으로 프로세스가 계속될 경우 2개 인스턴스의 최소 가용성이 보장되지 않게 만드는 인프라 또는 구성 문제가 있기 때문입니다. 따라서 업데이트 프로세스는 로컬 클러스터 서비스 중단을 방지하기 위해 진행을 멈춥니다.

UPDATING 상태에서 멈춘 로컬 클러스터를 문제 해결하고 근본 원인을 해결해 업데이트 프로세스가 완료되어 로컬 클러스터가 3개의 Kubernetes 제어 플레인 인스턴스의 고가용성과 함께 ACTIVE 상태로 복원되도록 하는 것이 중요합니다.

AWS Support가 명시적으로 지시하지 않는 한 Outposts의 관리형 EKS 로컬 클러스터 Kubernetes 인스턴스를 종료하지 마세요. 특히 UPDATING 상태에서 멈춘 로컬 클러스터의 경우 다른 제어 플레인 노드가 완전히 정상이 아닐 가능성이 높으므로 잘못된 인스턴스를 종료하면 서비스 중단이 발생하고 로컬 클러스터 데이터 손실 위험이 있으므로 특히 중요합니다.

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

• 로컬 클러스터가 처음 생성된 후 네트워킹 구성 변경으로 인해 하나 이상의 제어 플레인 인스턴스가 Systems Manager에 연결할 수 없습니다. 리전 내 배스천 호스트에서 aws ssm start-session --target instance-id를 호출해 이를 확인할 수 있어요. 해당 명령이 작동하지 않으면 Systems Manager가 제어 플레인 인스턴스에서 실행 중인지 확인하세요.
• EBS 볼륨의 KMS 키 권한으로 인해 새 제어 플레인 인스턴스가 생성에 실패합니다. 암호화된 EBS 볼륨에 사용자 관리형 KMS 키를 사용하면 키에 액세스할 수 없을 때 제어 플레인 인스턴스가 종료됩니다. 인스턴스가 종료되면 AWS 관리형 KMS 키로 전환하거나 사용자 관리형 키 정책이 클러스터 역할에 필요한 권한을 부여하는지 확인하세요.
• Systems Manager 제어 플레인 인스턴스가 인터넷 액세스를 잃었을 수 있습니다. 클러스터를 생성할 때 제공된 서브넷에 NAT 게이트웨이와 인터넷 게이트웨이가 있는 VPC가 있는지 확인하세요. VPC reachability analyzer를 사용해 제어 플레인 인스턴스가 인터넷 게이트웨이에 도달할 수 있는지 확인합니다. 자세한 내용은 VPC Reachability Analyzer 시작하기를 참고하세요. 프라이빗 네트워크에 아웃바운드 인터넷 연결이 없다면 클러스터의 리전 서브넷에 필요한 모든 VPC 엔드포인트와 게이트웨이 엔드포인트가 여전히 존재하는지 확인하세요(서브넷 액세스에 대한 AWS 서비스 참조).
• 제공한 역할 ARN에 정책이 누락되어 있습니다. AWS 관리형 정책: AmazonEKSLocalOutpostClusterPolicy가 역할에서 제거되었는지 확인하세요.
• 새 Kubernetes 제어 플레인 인스턴스 중 하나가 예기치 않은 부트스트래핑 실패를 겪었을 수 있습니다. 이 예외적인 경우 문제 해결 및 로그 수집에 대한 추가 안내를 위해 AWS Support Center에 티켓을 제출하세요.

AMI 문제:

• 호환되지 않는 AMI를 사용하고 있습니다. Amazon EKS 최적화 Amazon Linux 2023 AMI만 지원됩니다. 자세한 내용은 AWS Outposts에서 Amazon Linux 노드 생성을 참고하세요.
• AWS CloudFormation 템플릿을 사용해 노드를 생성했다면 지원되지 않는 AMI를 사용하지 않았는지 확인하세요.
• AWS IAM Authenticator ConfigMap 누락 — 누락된 경우 생성해야 합니다. 자세한 내용은 클러스터에 aws-auth ConfigMap 적용을 참고하세요.
• 잘못된 보안 그룹 사용 — 워커 노드의 보안 그룹에 eks-cluster-sg-cluster-name-uniqueid를 사용해야 합니다. 선택한 보안 그룹은 스택이 사용될 때마다 AWS CloudFormation에 의해 새 보안 그룹을 허용하도록 변경됩니다.
• 예기치 않은 프라이빗 링크 VPC 단계를 따른 경우 — 잘못된 CA 데이터(--b64-cluster-ca) 또는 API 엔드포인트(--apiserver-endpoint)가 전달됩니다.

Outpost가 연결된 AWS 리전에서 연결이 끊기면 Kubernetes 클러스터는 일반적으로 정상적으로 계속 작동합니다. 그러나 클러스터가 제대로 작동하지 않으면 네트워크 단절을 위해 AWS Outposts 로컬 Amazon EKS 클러스터 준비의 문제 해결 단계를 따르세요. 다른 문제가 발생하면 AWS Support에 문의하세요. AWS Support는 로그 수집 도구를 다운로드하고 실행하는 방법을 안내할 수 있어요. 그렇게 하면 Kubernetes 클러스터 제어 플레인 인스턴스에서 로그를 수집해 추가 조사를 위해 AWS Support에 보낼 수 있습니다.

Amazon EKS 제어 플레인 인스턴스가 AWS Systems Manager(Systems Manager)를 통해 연결할 수 없으면 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와 서브넷이 AWS Outposts의 Amazon EKS 클러스터용 VPC 및 서브넷 생성의 요구 사항을 충족하고 AWS Systems Manager 사용 설명서의 Session Manager 설정 단계를 완료했는지 확인하세요.

더 알아보기 (Learn more)

• 공식 문서