일반적인 문제 해결

이 페이지에서는 AWS용 GKE의 일반적인 문제를 해결하는 방법을 보여줍니다.

추가 지원이 필요하면 Cloud Customer Care에 연락합니다.

일반적인 오류 메시지

다음 섹션에서는 몇 가지 일반적인 오류 메시지의 원인과 해결 방법을 설명합니다.

서버에 리소스가 없음

error: the server doesn't have a resource type "services"와 같은 오류는 클러스터에 실행 중인 노드 풀이 없거나 Connect 게이트웨이가 노드 풀에 연결할 수 없을 때 발생할 수 있습니다. 노드 풀의 상태를 확인하려면 다음 명령어를 실행하세요.

gcloud container aws node-pools list \
    --cluster-name CLUSTER_NAME \
    --location LOCATION

다음을 바꿉니다.

  • CLUSTER_NAME: 클러스터 이름
  • LOCATION: 클러스터를 관리하는 Google Cloud 위치입니다.

출력에는 클러스터의 노드 풀 상태가 포함됩니다. 만일 노드 풀이 나열되지 않으면 노드 풀을 만드세요.

금지된 사용자

사용자 이름에 클러스터에 대한 관리자 액세스 권한이 없으면 다음 오류가 발생합니다.

Error from server (Forbidden): users "administrator@example.com" is forbidden:
User "system:serviceaccount:gke-connect:connect-agent-sa" cannot impersonate
resource "users" in API group "" at the cluster scope

클러스터를 만들 때 --admin-users 플래그를 전달하여 추가 사용자를 구성할 수 있습니다.

Connect 게이트웨이를 사용하고 있으며 클러스터에 연결할 수 없으면 다음 단계를 수행해 봅니다.

  1. 클러스터의 승인된 사용자를 가져옵니다.

    gcloud container aws clusters describe CLUSTER_NAME \
    --format 'value(authorization.admin_users)'

    CLUSTER_NAME을 클러스터 이름으로 바꿉니다.

    출력에 클러스터에 대한 관리자 액세스 권한이 있는 사용자 이름이 포함됩니다. 예를 들면 다음과 같습니다.

    {'username': 'administrator@example.com'}

  2. 현재 Google Cloud CLI로 인증된 사용자 이름을 가져옵니다.

    gcloud config get-value account

    출력에는 Google Cloud CLI로 인증된 계정이 포함됩니다. gcloud containers aws clusters describe 및 gcloud config get-value account의 출력이 일치하지 않으면 gcloud auth login을 실행하고 클러스터에 대한 관리 액세스 권한이 있는 사용자 이름으로 인증합니다.

kubectl 명령어 관련 문제

다음 섹션에서는 응답하지 않거나 실패한 kubectl 명령어 관련 문제를 해결하는 방법을 안내합니다.

kubectl 명령어가 응답하지 않음

클러스터에서 Kubernetes 1.25 이전 버전을 실행하고 kubectl 명령어가 응답하지 않거나 타임아웃되는 경우 가장 일반적인 원인은 아직 노드 풀을 만들지 않은 것입니다. 기본적으로 AWS용 GKE에서 Connect 게이트웨이를 인터넷에 연결할 수 있는 엔드포인트로 사용하는 kubeconfig 파일을 생성합니다. 이 작업을 수행하려면 gke-connect-agent 배포가 클러스터의 노드 풀에서 실행되어야 합니다.

자세한 진단 정보를 보려면 다음 명령어를 실행합니다.

kubectl cluster-info -v=9

실행 중인 노드 풀이 없으면 404 cannot find active connections for cluster 오류가 표시되면서 connectgateway.googleapis.com 요청이 실패합니다.

Kubernetes 버전이 1.25 이상인 클러스터의 경우 gke-connect-agent가 제어 영역에서 실행되며 노드 풀이 필요하지 않습니다. kubectl 명령어가 응답하지 않으면 Cloud Logging을 사용하여 제어 영역 구성요소 로그를 확인합니다.

kubectl exec, attach, port-forward 명령어 실패

Connect 게이트웨이를 사용할 때 error: unable to upgrade connection 메시지가 표시되면서 kubectl exec, kubectl attach, kubectl port-forward 명령어가 실패할 수 있습니다. 이는 Connect 게이트웨이를 Kubernetes API 서버 엔드포인트로 사용하는 경우 적용되는 제한사항입니다.

이 문제를 해결하려면 클러스터의 비공개 엔드포인트를 지정하는 kubeconfig를 사용합니다. 비공개 엔드포인트를 통해 클러스터에 액세스하는 방법은 kubectl의 클러스터 액세스 구성을 참조하세요.

kubectl 로그가 remote error: tls: Internal error와 함께 실패

제어 영역 API 역할에 권한이 없으면 이 문제가 발생할 수 있습니다. 예를 들어 AWS 역할에 ec2:DescribeDhcpOptions 권한이 없으면 이 문제가 발생할 수 있습니다. 이 경우 노드의 인증서 서명 요청을 승인할 수 없으며 워커 노드에 유효한 인증서가 없습니다.

이것이 문제인지 확인하려면 다음 명령어를 사용하여 승인되지 않은 인증서 서명 요청이 보류 중인지 확인하면 됩니다.

kubectl get csr

이 문제를 해결하려면 AWS 역할이 요구사항과 일치하는지 확인하세요.

일반 kubectl 문제 해결

Connect 게이트웨이를 사용하는 경우:

  • Google Cloud 프로젝트에서 Connect 게이트웨이를 사용 설정했는지 확인합니다.

    gcloud services enable connectgateway.googleapis.com

  • Kubernetes 버전이 1.25 이전인 클러스터의 경우 하나 이상의 Linux 노드 풀이 실행 중이고 gke-connect-agent가 실행 중인지 확인하세요. 자세한 내용은 클러스터 연결 문제 해결을 참조하세요.

  • Kubernetes 버전이 1.25 이상인 클러스터의 경우 Cloud Logging을 사용하여 gke-connect-agent 로그를 확인하세요.

Kubernetes 서비스(LoadBalancer) 또는 Kubernetes 인그레스가 작동하지 않음

AWS Elastic Load Balancer(ELB/NLB/ALB)가 생성되었지만 예상대로 작동하지 않는 경우 이 문제는 서브넷 태그 지정으로 인해 발생할 수 있습니다. 자세한 내용은 부하 분산기 서브넷을 참조하세요.

ARM 노드의 포드가 비정상 종료됨

다음 문제는 ARM 노드에 포드를 배포할 때 컨테이너 이미지가 ARM 아키텍처용으로 빌드되지 않은 경우에 발생합니다.

문제를 식별하려면 다음 태스크를 완료합니다.

  1. 포드 상태를 가져옵니다.

    kubectl get pods

  2. 비정상 종료되는 포드의 로그를 가져옵니다.

    kubectl logs POD_NAME

    POD_NAME을 비정상 종료 포드의 이름으로 바꿉니다.

    포드 로그의 오류 메시지는 다음과 비슷합니다.

    exec ./hello-app: exec format error

이 문제를 해결하려면 컨테이너 이미지에서 Arm 아키텍처가 지원되는지 확인합니다. 멀티 아키텍처 이미지를 빌드하는 것이 좋습니다.

클러스터를 삭제할 수 없음

클러스터를 삭제하려고 할 때 다음과 유사한 오류가 발생하면 GKE Multi-Cloud API 역할이 없는 경우일 수 있습니다.

ERROR: (gcloud.container.aws.clusters.delete) FAILED_PRECONDITION: Could not
assume role
"arn:aws:iam::ACCOUNT_NUMBER:role/gke123456-anthos-api-role"
through service account
"service-123456789@gcp-sa-gkemulticloud.iam.gserviceaccount.com".
Please make sure the role has a trust policy allowing the GCP service agent to
assume it: WebIdentityErr failed to retrieve credentials

문제를 해결하려면 GKE Multi-Cloud API 역할 만들기의 단계를 따르세요. 동일한 이름과 권한으로 역할을 다시 만들 경우 명령어를 다시 시도할 수 있습니다.

다음 단계