4xx 오류 문제 해결

이 페이지는 Google Kubernetes Engine(GKE)을 사용할 때 발생할 수 있는 400, 401, 403, 404 오류를 해결하는 데 도움이 됩니다.

문제: 인증 및 승인 오류

GKE 클러스터에 연결할 때 HTTP 상태 코드 401 (Unauthorized)가 표시되면서 인증 및 승인 오류가 발생할 수 있습니다. 이 문제는 로컬 환경의 GKE 클러스터에서 kubectl 명령어를 실행하려고 할 때 발생할 수 있습니다.

이 문제의 원인은 다음 중 하나일 수 있습니다.

  • gke-gcloud-auth-plugin 인증 플러그인이 올바르게 설치 또는 구성되지 않았습니다.
  • 클러스터 API 서버에 연결하고 kubectl 명령어를 실행하기 위한 권한이 부족합니다.

원인을 진단하려면 다음 섹션의 단계를 완료합니다.

  1. curl을 사용하여 클러스터에 연결
  2. kubeconfig에서 플러그인 구성

curl을 사용하여 클러스터에 연결

인증 및 승인 오류의 원인을 진단하려면 curl을 사용하여 클러스터에 연결합니다. curl을 사용하면 kubectl 명령줄 도구와 gke-gcloud-auth-plugin 플러그인이 우회됩니다.

  1. 환경 변수를 설정합니다.

    APISERVER=https://$(gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION --format "value(endpoint)")
TOKEN=$(gcloud auth print-access-token)

  2. 액세스 토큰이 유효한지 확인합니다.

    curl https://oauth2.googleapis.com/tokeninfo?access_token=$TOKEN

    유효한 액세스 토큰이 있으면 이 명령어는 요청을 Google의 OAuth 2.0 서버에 보내고 서버는 토큰에 대한 정보로 응답합니다.

  3. API 서버에서 핵심 API 엔드포인트에 연결해 봅니다.

    # Get cluster CA certificate
gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --format "value(masterAuth.clusterCaCertificate)" | \
    base64 -d > /tmp/ca.crt

# Make API call with authentication and CA certificate
curl -s -X GET "${APISERVER}/api/v1/namespaces" \
    --header "Authorization: Bearer $TOKEN" \
    --cacert /tmp/ca.crt

    curl 명령어가 성공하면 네임스페이스 목록이 표시됩니다. kubeconfig에서 플러그인 구성 섹션의 단계를 수행하여 플러그인이 원인인지 확인합니다.

    다음과 비슷한 출력이 표시되면서 curl 명령어가 실패하면 클러스터에 액세스할 수 있는 올바른 권한이 없는 것입니다.

    {
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"status": "Failure",
"message": "Unauthorized",
"reason": "Unauthorized",
"code": 401
}

    이 문제를 해결하려면 관리자에게 문의하여 클러스터에 액세스할 수 있는 올바른 권한을 받으세요.

kubeconfig에서 플러그인 사용 구성

클러스터에 연결할 때 인증 및 승인 오류가 발생하지만 curl을 사용하여 클러스터에 연결할 수 있으면 gke-gcloud-auth-plugin 플러그인을 사용하지 않고도 클러스터에 액세스할 수 있는지 확인합니다.

이 문제를 해결하려면 클러스터에 인증할 때 로컬 환경에서 gke-gcloud-auth-plugin 바이너리를 무시하도록 구성합니다. 버전 1.25 이상을 실행하는 Kubernetes 클라이언트에서는 gke-gcloud-auth-plugin 바이너리가 필수이므로 kubectl 명령줄 도구에 버전 1.24 이하를 사용해야 합니다.

플러그인을 사용하지 않고 클러스터에 액세스하려면 다음 단계를 수행합니다.

  1. curl을 사용하여 버전 1.24 이하의 kubectl 명령줄 도구를 설치합니다. 다음 예시에서는 버전 1.24의 도구를 설치합니다.

    curl -LO https://dl.k8s.io/release/v1.24.0/bin/linux/amd64/kubectl

  2. 텍스트 편집기에서 셸 시작 스크립트 파일을 엽니다. 예를 들어 Bash 셸의 경우 .bashrc를 엽니다.

    vi ~/.bashrc

    macOS를 사용하는 경우 이 안내에서 .bashrc 대신 ~/.bash_profile을 사용합니다.

  3. 시작 스크립트 파일에 다음 줄을 추가하고 저장합니다.

    export USE_GKE_GCLOUD_AUTH_PLUGIN=False

  4. 시작 스크립트를 실행합니다.

    source ~/.bashrc

  5. .kube/config 파일을 설정하는 클러스터의 사용자 인증 정보를 가져옵니다.

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=COMPUTE_LOCATION

    다음을 바꿉니다.

  6. kubectl 명령어를 실행합니다. 예를 들면 다음과 같습니다.

    kubectl cluster-info

    이러한 명령어를 실행한 후 401 오류나 유사한 승인 오류가 발생하면 올바른 권한이 있는지 확인한 후 오류를 반환한 단계를 다시 실행합니다.

오류 400: 노드 풀에 다시 만들기 필요

컨트롤 플레인과 노드를 다시 만드는 작업을 수행하려고 하면 다음 오류가 발생할 수 있습니다.

ERROR: (gcloud.container.clusters.update) ResponseError: code=400, message=Node pool "test-pool-1" requires recreation.

예를 들어 진행 중인 사용자 인증 정보 순환을 완료할 때 이 오류가 발생할 수 있습니다.

백엔드에서 노드 풀이 다시 만들 수 있도록 표시되었지만 실제 다시 만들기 작업이 시작하는 데 시간이 다소 걸릴 수 있습니다. 따라서 GKE에서 아직 클러스터에 노드 풀을 하나 이상 다시 만들지 않았으므로 작업이 실패합니다.

이 문제를 해결하려면 다음 방법 중 하나를 선택합니다.

  • 다시 만들기가 수행될 때까지 기다립니다. 기존 유지보수 기간 및 제외 항목과 같은 요소에 따라 몇 시간, 며칠, 몇 주가 걸릴 수 있습니다.

  • 컨트롤 플레인과 동일한 버전으로 버전 업그레이드를 시작하여 영향을 받는 노드 풀 다시 만들기를 수동으로 시작합니다.

    다시 만들기를 시작하려면 다음 명령어를 실행합니다.

    gcloud container clusters upgrade CLUSTER_NAME \
    --node-pool=POOL_NAME

    업그레이드가 완료된 후 작업을 다시 시도합니다.

오류 403: 권한 부족

gcloud container clusters get-credentials를 사용하여 GKE 클러스터에 연결을 시도하지만 계정에 Kubernetes API 서버에 액세스할 수 있는 권한이 없으면 다음 오류가 발생합니다.

ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Required "container.clusters.get" permission(s) for "projects/<your-project>/locations/<region>/clusters/<your-cluster>".

이 문제를 해결하려면 다음 단계를 완료하시기 바랍니다.

  1. 액세스 문제가 있는 계정을 식별합니다.

    gcloud auth list

  2. Kubernetes API 서버에 인증의 안내에 따라 계정에 필요한 액세스 권한을 부여합니다.

오류 403: 재시도 예산 소진

GKE 클러스터를 만들려고 하면 다음 오류가 발생할 수 있습니다.

Error: googleapi: Error 403: Retry budget exhausted: Google Compute Engine:
Required permission 'PERMISSION_NAME' for 'RESOURCE_NAME'.

이 오류 메시지에는 다음 변수가 적용됩니다.

  • PERMISSION_NAME: 권한 이름입니다(예: compute.regions.get).
  • RESOURCE_NAME: 액세스하려고 하는 Google Cloud 리소스의 경로입니다(예: Compute Engine 리전).

이 오류는 클러스터에 연결된 IAM 서비스 계정에 클러스터를 만드는 데 필요한 최소 권한이 없으면 발생합니다.

이 문제를 해결하려면 다음 단계를 따르세요.

  1. GKE 클러스터를 실행하는 데 필요한 모든 권한이 있는 IAM 서비스 계정을 만들거나 수정합니다. 자세한 내용은 최소 권한 IAM 서비스 계정 사용을 참조하세요.
  2. --service-account 플래그를 사용하여 클러스터 생성 명령어에 업데이트된 IAM 서비스 계정을 지정합니다. 자세한 내용은 Autopilot 클러스터 만들기를 참조하세요.

또는 --service-account 플래그를 생략하여 GKE가 프로젝트에서 기본적으로 필요한 권한이 있는 Compute Engine 기본 서비스 계정을 사용하게 할 수 있습니다.

오류 404: 리소스를 찾을 수 없음

오류 404(리소스를 찾을 수 없음)가 발생하면 gcloud container 명령어를 호출할 때 Google Cloud CLI에 다시 인증하여 문제를 해결합니다.

gcloud auth login

오류 400/403: 계정에 수정 권한 없음

계정 오류(오류 400 또는 403)로 인해 수정 권한이 누락되면 다음 중 하나가 수동으로 삭제되었거나 수정되었음을 나타냅니다.

Compute Engine 또는 Kubernetes Engine API를 사용 설정하면 Google Cloud가 다음 서비스 계정 및 에이전트를 만듭니다.

  • 프로젝트에 대해 수정 권한이 있는 Compute Engine 기본 서비스 계정
  • 프로젝트에 대해 수정 권한이 있는 Google API 서비스 에이전트
  • 프로젝트에 대해 Kubernetes Engine 서비스 에이전트 역할이 있는 Google Kubernetes Engine 서비스 계정

특정 시점에 누군가 이러한 권한을 수정하거나 프로젝트에서 역할 바인딩을 삭제하거나 서비스 계정을 완전히 삭제하거나 API를 중지하면 클러스터 생성 및 모든 관리가 실패합니다.

Google Kubernetes Engine 서비스 계정에 프로젝트에 할당된 Kubernetes Engine 서비스 에이전트 역할이 있는지 확인하려면 다음 단계를 완료합니다.

  1. Google Kubernetes Engine 서비스 계정 이름을 확인합니다. 모든 서비스 계정 형식은 다음과 같습니다.

    service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com

    여기에서 PROJECT_NUMBER를 프로젝트 번호로 바꿉니다.

  2. Google Kubernetes Engine 서비스 계정에 프로젝트에 할당된 Kubernetes Engine 서비스 에이전트 역할이 없는지 확인합니다.

    gcloud projects get-iam-policy PROJECT_ID

    PROJECT_ID를 프로젝트 ID로 바꿉니다.

누군가 Google Kubernetes Engine 서비스 계정에서 Kubernetes Engine 서비스 에이전트 역할을 삭제한 경우 문제를 해결하려면 이 역할을 다시 추가합니다. 그렇지 않으면 다음 안내를 수행하여 Kubernetes Engine API를 다시 사용 설정하여 서비스 계정과 권한을 복원합니다.

콘솔

  1. Google Cloud 콘솔의 API 및 서비스 페이지로 이동합니다.

    API 및 서비스로 이동

  2. 프로젝트를 선택합니다.

  3. API 및 서비스 사용 설정을 클릭합니다.

  4. Kubernetes를 검색한 후 검색 결과에서 API를 선택합니다.

  5. 사용 설정을 클릭합니다. 이전에 API를 사용 설정했으면 먼저 API를 중지했다가 다시 사용 설정해야 합니다. API와 관련 서비스가 사용 설정되는 데 몇 분 정도 걸릴 수 있습니다.

gcloud

gcloud CLI에서 다음 명령어를 실행합니다.

PROJECT_NUMBER=$(gcloud projects describe "PROJECT_ID"
    --format 'get(projectNumber)')
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:service-${PROJECT_NUMBER?}@container-engine-robot.iam.gserviceaccount.com" \
    --role roles/container.serviceAgent

다음 단계

추가 지원이 필요하면 Cloud Customer Care에 문의하세요.