Google Kubernetes Engine (GKE) 컨트롤 플레인 또는 노드 풀 업그레이드가 실패하거나, 멈추거나, 예기치 않은 워크로드 동작이 발생하는 경우 프로세스를 문제 해결해야 할 수 있습니다. 제어 플레인과 노드 풀을 최신 상태로 유지하는 것은 보안과 성능에 필수적이며, 문제를 해결하면 환경이 안정적으로 유지됩니다.
일반적인 업그레이드 문제를 해결하는 좋은 첫 번째 단계는 클러스터 업그레이드 프로세스를 모니터링하는 것입니다. 그런 다음 문제를 해결하는 방법에 관한 조언을 확인할 수 있습니다.
- 노드 풀 업그레이드가 평소보다 오래 걸림
- 노드 풀 업그레이드 미완료
- 예기치 않은 자동 업그레이드 동작
- 특정 오류 메시지와 함께 업그레이드가 실패함
- 업그레이드 완료 후 문제
- 버전 호환성 문제
이 정보는 업그레이드 중단 또는 실패의 근본 원인을 진단하고, 유지관리 정책을 관리하고, 버전 비호환성을 해결하려는 플랫폼 관리자 및 운영자에게 중요합니다. 애플리케이션 개발자는 업그레이드 후 워크로드 문제를 해결하는 방법에 관한 안내를 확인하고 PodDisruptionBudgets와 같은 워크로드 구성이 업그레이드 기간에 미치는 영향을 파악할 수 있습니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할과 예시 태스크에 대한 자세한 내용은 일반 GKE 사용자 역할 및 태스크를 참고하세요.
클러스터 업그레이드 프로세스 모니터링
업그레이드 문제를 더 효과적으로 해결하려면 업그레이드 프로세스 중에 발생한 상황을 파악하세요. GKE는 이 프로세스를 파악할 수 있는 여러 도구를 제공합니다.
Google Cloud 콘솔에서 업그레이드 대시보드는 진행 중인 모든 클러스터 업그레이드, 최근 이벤트 타임라인, 활성 유지보수 제외 또는 예정된 버전 지원 중단과 같은 잠재적 차단 요소에 관한 경고를 프로젝트 전체에 걸쳐 보여줍니다. 명령줄 또는 자동 검사의 경우 gcloud
container operations list 명령어를 사용하여 특정 업그레이드 작업의 상태를 가져올 수 있습니다. 자세한 내용은 클러스터 업그레이드에 대한 가시성 확보를 참고하세요.
자세한 조사를 위해 Cloud Logging이 기본 정보 소스입니다. GKE는 Cloud Logging 내에서 컨트롤 플레인 및 노드 풀 업그레이드 프로세스에 관한 세부정보를 기록합니다. 여기에는 주요 업그레이드 작업을 추적하는 상위 수준 감사 로그와 Kubernetes 이벤트 및 노드 구성요소의 로그와 같은 세부적인 로그가 포함되며, 이를 통해 특정 오류에 관한 자세한 정보를 확인할 수 있습니다.
다음 섹션에서는 로그 탐색기 또는 gcloud CLI를 사용하여 이러한 로그를 쿼리하는 방법을 설명합니다. 자세한 내용은 업그레이드 로그 확인을 참고하세요.
감사 로그로 업그레이드 작업 식별
실패한 업그레이드 작업을 모르는 경우 GKE 감사 로그를 사용할 수 있습니다. 감사 로그는 관리 작업을 추적하고 업그레이드가 시작된 시점과 최종 상태에 관한 공신력 있는 기록을 제공합니다. 로그 탐색기에서 다음 쿼리를 사용하여 관련 작업을 찾습니다.
| 이벤트 유형 | 로그 쿼리 |
|---|---|
| 컨트롤 플레인 자동 업그레이드 |
resource.type="gke_cluster" protoPayload.methodName="google.container.internal.ClusterManagerInternal.UpdateClusterInternal" log_id("cloudaudit.googleapis.com/activity") protoPayload.metadata.operationType="UPGRADE_MASTER" resource.labels.cluster_name="CLUSTER_NAME"
이 쿼리는 타겟 컨트롤 플레인 버전과 이전 컨트롤 플레인 버전을 보여줍니다. |
| 컨트롤 플레인 수동 업그레이드 |
resource.type="gke_cluster" log_id("cloudaudit.googleapis.com/activity") protoPayload.response.operationType="UPGRADE_MASTER" resource.labels.cluster_name="CLUSTER_NAME"
|
| 노드 풀 자동 업그레이드 (타겟 버전만 해당) |
resource.type="gke_nodepool" protoPayload.methodName="google.container.internal.ClusterManagerInternal.UpdateClusterInternal" log_id("cloudaudit.googleapis.com/activity") protoPayload.metadata.operationType="UPGRADE_NODES" resource.labels.cluster_name="CLUSTER_NAME" resource.labels.nodepool_name="NODEPOOL_NAME"
|
| 노드 풀 수동 업그레이드 |
resource.type="gke_nodepool" protoPayload.methodName="google.container.v1.ClusterManager.UpdateNodePool" log_id("cloudaudit.googleapis.com/activity") protoPayload.response.operationType="UPGRADE_NODES" resource.labels.cluster_name="CLUSTER_NAME" resource.labels.nodepool_name="NODEPOOL_NAME" 이전 노드 풀 버전을 확인하려면 Kubernetes API 로그를 확인하세요. resource.type="k8s_cluster" resource.labels.cluster_name="CLUSTER_NAME" protoPayload.methodName="nodes.patch" |
GKE 로그에서 자세한 오류 메시지 확인
감사 로그에 실패한 작업과 시간이 표시되면 동일한 시간대의 GKE 구성요소에서 더 자세한 오류 메시지를 검색할 수 있습니다. 이러한 로그에는 잘못 구성된 PodDisruptionBudget 객체와 같은 업그레이드 실패의 구체적인 이유가 포함될 수 있습니다.
예를 들어 감사 로그에서 실패한 UPGRADE_NODES 작업을 찾은 후 타임스탬프를 사용하여 검색 범위를 좁힐 수 있습니다. 로그 탐색기에서 다음 쿼리를 입력한 다음 시간 범위 선택기를 사용하여 장애가 발생한 시간에 집중합니다.
resource.type="k8s_node"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.node_name="NODE_NAME"
severity=ERROR
다음을 바꿉니다.
CLUSTER_NAME: 클러스터 이름입니다.NODE_NAME: 오류를 확인할 클러스터 내 노드의 이름입니다.
gcloud CLI를 사용하여 업그레이드 이벤트 보기
로그 탐색기 외에도 gcloud CLI 명령어를 사용하여 업그레이드 이벤트를 검토할 수 있습니다.
컨트롤 플레인 업그레이드를 찾으려면 다음 명령어를 실행합니다.
gcloud container operations list --filter="TYPE=UPGRADE_MASTER"
출력은 다음과 비슷합니다.
NAME: operation-1748588803271-cfd407a2-bfe7-4b9d-8686-9f1ff33a2a96
TYPE: UPGRADE_MASTER
LOCATION: LOCATION
TARGET: CLUSTER_NAME
STATUS_MESSAGE:
STATUS: DONE
START_TIME: 2025-05-30T07:06:43.271089972Z
END_TIME: 2025-05-30T07:18:02.639579287Z
이 출력에는 다음 값이 포함됩니다.
LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예:us-central1또는us-central1-a)CLUSTER_NAME: 클러스터 이름입니다.
노드 풀 업그레이드를 찾으려면 다음 명령어를 실행합니다.
gcloud container operations list --filter="TYPE=UPGRADE_NODES"
출력은 다음과 비슷합니다.
NAME: operation-1748588803271-cfd407a2-bfe7-4b9d-8686-9f1ff33a2a96
TYPE: UPGRADE_NODES
LOCATION: LOCATION
TARGET: CLUSTER_NAME
STATUS_MESSAGE:
STATUS: DONE
START_TIME: 2025-05-30T07:06:43.271089972Z
END_TIME: 2025-05-30T07:18:02.639579287Z
예: 로그를 사용하여 컨트롤 플레인 업그레이드 문제 해결
다음 예에서는 로그를 사용하여 실패한 제어 영역 업그레이드를 문제 해결하는 방법을 보여줍니다.
Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
쿼리 창에서 다음 쿼리를 입력하여 제어 영역 업그레이드 로그를 필터링합니다.
resource.type="gke_cluster" protoPayload.metadata.operationType=~"(UPDATE_CLUSTER|UPGRADE_MASTER)" resource.labels.cluster_name="CLUSTER_NAME"CLUSTER_NAME을 조사하려는 클러스터의 이름으로 바꿉니다.쿼리 실행을 클릭합니다.
로그 출력에서 다음 정보를 검토합니다.
업그레이드가 시작되었는지 확인: 업그레이드를 시작한 시점의 최근
UPGRADE_MASTER이벤트를 찾습니다. 이러한 이벤트가 있으면 사용자 또는 GKE가 업그레이드 프로세스를 트리거한 것입니다.버전 확인: 다음 필드를 확인하여 이전 버전과 타겟 버전을 확인합니다.
protoPayload.metadata.previousMasterVersion: 업그레이드 전의 컨트롤 플레인 버전을 보여줍니다.protoPayload.metadata.currentMasterVersion: GKE가 컨트롤 플레인을 업그레이드하려고 시도한 버전을 표시합니다.예를 들어 버전 1.30.1-gke.1234로 업그레이드하려고 했지만 실수로 1.30.2-gke.4321 (최신 버전으로 워크로드와 호환되지 않을 수 있음)을 지정한 경우 이 두 필드를 검토하면 이 불일치가 강조 표시됩니다. 또는
currentMasterVersion필드에 장기간이 지난 후에도 이전 버전이 계속 표시되면 업그레이드에서 새 버전을 적용하지 못한 것입니다.
오류 확인: 반복되는
UPGRADE_MASTER이벤트 또는 기타 오류 메시지를 확인합니다. 작업 로그가 완료 또는 실패를 나타내지 않고 중지되면 이 결과는 문제를 나타냅니다.
로그에서 특정 오류나 동작을 식별한 후 이 정보를 사용하여 이 가이드에서 적절한 해결 방법을 찾을 수 있습니다.
노드 풀 업그레이드가 평소보다 오래 걸리는 문제 해결
노드 풀 업그레이드가 예상보다 오래 걸리는 경우 다음 해결 방법을 시도해 보세요.
- 포드의 매니페스트에서
terminationGracePeriodSeconds값을 확인합니다. 이 값은 Kubernetes가 포드가 정상적으로 종료되기를 기다리는 최대 시간을 정의합니다. 값이 높으면 (예: 몇 분) Kubernetes가 각 포드의 전체 기간을 기다리므로 업그레이드 기간이 크게 늘어날 수 있습니다. 이 지연으로 인해 문제가 발생하는 경우 값을 줄이는 것이 좋습니다. PodDisruptionBudget객체를 확인합니다. 노드가 드레이닝될 때 GKE는 노드당 최대 1시간 동안 워크로드를 정상적으로 제거하기를 기다립니다.PodDisruptionBudget객체가 너무 제한적이면 정상적인 제거가 성공하지 못할 수 있습니다. 이 시나리오에서 GKE는 최종적으로 시간이 초과되어 업그레이드가 강제 진행되기 전에 노드를 드레인하려고 전체 1시간의 유예 기간을 사용합니다. 이 지연은 여러 노드에서 반복될 때 전체 클러스터 업그레이드가 느려지는 일반적인 원인입니다. 제한적인PodDisruptionBudget객체가 업그레이드 속도 저하의 원인인지 확인하려면 로그 탐색기를 사용하세요.Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
쿼리 창에 다음 쿼리를 입력합니다.
resource.type=("gke_cluster" OR "k8s_cluster") resource.labels.cluster_name="CLUSTER_NAME" protoPayload.response.message="Cannot evict pod as it would violate the pod's disruption budget." log_id("cloudaudit.googleapis.com/activity")쿼리 실행을 클릭합니다.
로그 출력을 검토합니다.
PodDisruptionBudget객체가 문제의 원인인 경우 출력은 다음과 비슷합니다.resourceName: "core/v1/namespaces/istio-system/pods/POD_NAME/eviction" response: { @type: "core.k8s.io/v1.Status" apiVersion: "v1" code: 429 details: { causes: [ 0: { message: "The disruption budget istio-egressgateway needs 1 healthy pods and has 1 currently" reason: "DisruptionBudget" } ] } kind: "Status" message: "Cannot evict pod as it would violate the pod's disruption budget." metadata: { } reason: "TooManyRequests" status: "Failure" }PodDisruptionBudget객체가 원인임을 확인한 후 모든PodDisruptionBudget객체를 나열하고 설정이 적절한지 확인합니다.kubectl get pdb --all-namespaces출력은 다음과 비슷합니다.
NAMESPACE NAME MIN AVAILABLE MAX UNAVAILABLE ALLOWED DISRUPTIONS AGE example-app-one one_pdb 3 0 1 12d이 예에서
one_pdb이라는 이름의PodDisruptionBudget에는 사용 가능한 포드가 최소 3개 필요합니다. 업그레이드 중에 포드를 제거하면 사용 가능한 포드가 두 개만 남기 때문에 이 작업은 예산을 위반하고 업그레이드가 중단됩니다.PodDisruptionBudget객체가 원하는 대로 작동하는 경우 별도의 조치를 취하지 않아도 됩니다. 그렇지 않은 경우 업그레이드 기간 동안PodDisruptionBudget설정을 완화하는 것이 좋습니다.
노드 어피니티를 확인합니다. 제한적인 규칙은 노드가 필요한 라벨과 일치하지 않는 경우 포드가 사용 가능한 노드로 일정이 변경되지 않도록 하여 업그레이드 속도를 늦출 수 있습니다. 이 문제는 특히 서지 업그레이드 중에 문제가 됩니다. 올바른 라벨이 있는 노드에 새 포드를 호스팅할 클러스터 용량이 충분하지 않으면 노드 선호도가 동시에 업그레이드할 수 있는 노드 수를 제한할 수 있기 때문입니다.
단기 업그레이드 전략을 사용하는지 확인합니다. GKE는 GKE 버전 1.32.2-gke.1652000 이상을 실행하는 클러스터에서 flex-start 노드와 큐에 추가된 프로비저닝만 사용하는 노드에 단기 업그레이드 전략을 사용합니다. 이 업그레이드 전략을 사용하면 업그레이드 작업에 최대 7일이 걸릴 수 있습니다.
기간 연장 포드(Autopilot 클러스터에서 사용 가능)를 사용하는지 확인합니다. 업그레이드 중에 GKE는 프로세스가 완료되기 전에 노드에서 모든 포드를 드레이닝해야 합니다. 하지만 GKE에서 시작한 업그레이드 중에는 GKE에서 최대 7일 동안 연장된 기간 포드를 제거하지 않습니다. 이 보호 기능은 노드가 드레인되는 것을 방지합니다. GKE는 이 기간이 지나야 포드를 강제 종료하며, 단일 노드에 대한 이 상당한 다일 지연으로 인해 Autopilot 클러스터에서 더 많은 노드 업그레이드가 지연될 수 있습니다.
연결된 영구 볼륨은 이러한 볼륨의 수명 주기를 관리하는 데 걸리는 시간으로 인해 업그레이드 프로세스가 평소보다 오래 걸릴 수 있습니다.
클러스터 자동 업그레이드 상태를 확인합니다. 이유가
SYSTEM_CONFIG인 경우 기술 또는 비즈니스와 관련된 이유로 자동 업그레이드가 일시중지됩니다. 이 이유가 표시되면 필요한 경우가 아니라면 수동 업그레이드를 하지 않는 것이 좋습니다.
완료되지 않은 노드 풀 업그레이드 문제 해결
경우에 따라 GKE가 노드 풀 업그레이드를 완료할 수 없어 노드 풀이 부분적으로 업그레이드될 수 있습니다. 업그레이드가 완료되지 않는 데는 여러 가지 이유가 있습니다.
- 업그레이드가 수동으로 취소되었습니다.
- 새 노드 등록 실패, IP 주소 소진, 리소스 할당량 부족과 같은 문제로 인해 업그레이드가 실패했습니다.
- GKE에서 업그레이드를 일시중지했습니다. 이 일시중지는 알려진 문제가 있는 버전으로의 업그레이드를 방지하거나 특정 Google 시작 유지보수 기간 중에 발생할 수 있습니다.
- 자동 업그레이드를 사용하는 경우 업그레이드가 완료되기 전에 유지보수 기간이 종료되었습니다. 또는 업그레이드가 완료되기 전에 유지보수 제외 기간이 시작되었을 수 있습니다. 자세한 내용은 노드 업데이트 완료를 방해하는 유지보수 기간을 참고하세요.
노드 풀이 부분적으로 업그레이드되면 노드가 서로 다른 버전에서 실행됩니다. 이 문제를 해결하고 노드 풀의 모든 노드가 동일한 버전에서 실행되는지 확인하려면 업그레이드를 재개하거나 업그레이드를 롤백하세요.
하지만 일시 급증 업그레이드 전략과 블루-그린 업그레이드 전략은 유지보수 기간과 다르게 상호작용합니다.
- 일시 급증 업그레이드: 업그레이드 작업이 유지보수 기간을 초과하여 실행되면 일시중지됩니다. 업그레이드는 다음 예약된 유지보수 기간에 자동으로 재개됩니다.
- 블루-그린 업그레이드: 업그레이드 작업은 유지보수 기간을 초과하더라도 완료될 때까지 계속됩니다. 블루-그린 업그레이드는 배치 및 노드 풀 소크 시간과 같은 기능을 통해 업그레이드 속도를 세부적으로 제어할 수 있으며, 추가 노드 풀을 통해 워크로드가 계속 작동하도록 지원합니다.
예상치 못한 자동 업그레이드 동작 문제 해결
경우에 따라 클러스터 자동 업그레이드가 예상대로 진행되지 않을 수 있습니다. 다음 섹션에서는 다음 문제를 해결하는 방법을 설명합니다.
노드 자동 업그레이드가 사용 설정된 경우 클러스터 업그레이드 실패
노드 자동 업그레이드를 사용 중지하지 않았는데 업그레이드가 발생하지 않는 경우 다음 해결 방법을 시도해 보세요.
출시 채널을 사용하는 경우 노드 자동 업그레이드가 차단되지 않았는지 확인합니다. 출시 채널에 등록된 클러스터의 경우
maintenancePolicy가 자동 업그레이드를 제어하는 기본 방법입니다. 업그레이드가 시작되지 않도록 하거나 이미 진행 중인 업그레이드를 중단할 수 있습니다. 활성 상태인 유지보수 제외는 업그레이드를 완전히 차단할 수 있으며 유지보수 기간의 타이밍으로 인해 중단이 발생할 수 있습니다.maintenancePolicy를 검토하여 다음 설정 중 하나가 원인인지 확인하세요.gcloud container clusters describe CLUSTER_NAME \ --project PROJECT_ID \ --location LOCATION다음을 바꿉니다.
CLUSTER_NAME: 설명할 노드 풀의 클러스터 이름입니다.PROJECT_ID: 클러스터의 프로젝트 ID입니다.LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예:us-central1또는us-central1-a)
출력은 다음과 비슷합니다.
… maintenancePolicy: maintenanceExclusions: - exclusionName: critical-event-q4-2025 startTime: '2025-12-20T00:00:00Z' endTime: '2026-01-05T00:00:00Z' scope: noUpgrades: true # This exclusion blocks all upgrades window: dailyMaintenanceWindow: startTime: 03:00 # Daily window at 03:00 UTC …출력에서 다음 두 가지 조건을 충족하는지
maintenancePolicy섹션을 검토합니다.- 업그레이드가 차단되었는지 확인하려면
NO_MINOR_OR_NODE_UPGRADES범위가 있는 활성maintenanceExclusion를 찾습니다. 이 설정은 일반적으로 GKE가 새 업그레이드를 시작하지 못하도록 합니다. - 업그레이드가 중단되었는지 확인:
dailyMaintenanceWindow또는maintenanceExclusions일정을 확인합니다. 업그레이드가 예약된 기간을 초과하여 실행되면 GKE는 업그레이드를 일시중지하여 부분 업그레이드가 발생합니다. 부분 업그레이드에 대한 자세한 내용은 불완전한 업그레이드 문제 해결 섹션을 참고하세요.
이 문제를 해결하려면 제외가 종료될 때까지 기다리거나, 제외를 삭제하거나, 업그레이드가 완료될 수 있도록 유지보수 기간을 조정하면 됩니다.
출시 채널을 사용하지 않는 경우 노드 풀에 자동 업그레이드가 사용 설정되어 있는지 확인합니다.
gcloud container node-pools describe NODE_POOL_NAME \ --cluster CLUSTER_NAME \ --location LOCATIONNODE_POOL_NAME을 설명할 노드 풀의 이름으로 바꿉니다.이 노드 풀에 노드 풀 자동 업그레이드가 사용 설정된 경우
autoUpgrade필드의 출력은 다음과 같습니다.management: autoUpgrade: trueautoUpgrade이false로 설정되어 있거나 필드가 없는 경우 자동 업그레이드를 사용 설정합니다.출시 노트에 업그레이드가 언급되었더라도 클러스터가 있는 리전 또는 영역에 업그레이드가 출시되지 않았을 수 있습니다. GKE 업그레이드는 일반적으로 4일 이상에 걸쳐 점진적으로 출시됩니다. 업그레이드가 리전 또는 영역에 도달한 후에는 승인된 유지보수 기간에만 업그레이드가 시작됩니다. 예를 들어 출시가 출시 첫날에 클러스터의 영역에 도달할 수 있지만 클러스터의 다음 유지보수 기간은 7일째까지가 아닙니다. 이 시나리오에서는 7일이 될 때까지 GKE가 클러스터를 업그레이드하지 않습니다. 자세한 내용은 GKE 출시 일정을 참고하세요.
자동 업그레이드가 사용 설정되지 않은 경우 클러스터가 자동으로 업그레이드됨
GKE 환경의 안정성, 가용성, 보안, 성능을 유지하기 위해 자동 업그레이드를 사용하지 않더라도 GKE에서 클러스터를 자동으로 업그레이드할 수 있습니다.
GKE는 다음과 같은 여러 가지 중요한 이유로 유지보수 기간, 제외 또는 사용 중지된 노드 풀 자동 업그레이드를 우회하여 필요한 업그레이드를 실행할 수 있습니다.
- 컨트롤 플레인이 지원 종료 날짜에 도달한 GKE 버전을 실행하는 클러스터 클러스터의 지원 종료 날짜가 다가오는지 확인하려면 출시 채널의 예상 일정을 참고하세요.
- 지원 종료 날짜에 도달한 GKE 버전을 실행하는 클러스터 내 노드
- 실행 중 상태이지만 장기간 활동이 없는 클러스터 예를 들어 GKE는 API 호출이 없고, 네트워크 트래픽이 없고, 서브넷이 활성 상태로 사용되지 않는 클러스터를 폐기된 것으로 간주할 수 있습니다.
- 작동 상태를 반복적으로 순환하는 지속적인 불안정성을 보이는 클러스터 예를 들어 실행 중부터 성능 저하, 복구 또는 일시 중지를 거쳐 해결 없이 다시 실행까지 반복되는 상태입니다.
예상치 못한 자동 업그레이드가 발생하고 이 업그레이드가 클러스터에 미칠 영향이 우려되는 경우 Cloud Customer Care에 문의하여 도움을 받으세요.
업그레이드 실패 문제 해결
업그레이드가 실패하면 GKE에서 오류 메시지를 생성합니다. 다음 섹션에서는 다음 오류의 원인과 해결 방법을 설명합니다.
오류: kube-apiserver이(가) 비정상입니다.
클러스터의 GKE 버전의 수동 컨트롤 플레인 업그레이드를 시작할 때 다음 오류 메시지가 표시될 수 있습니다.
FAILED: All cluster resources were brought up, but: component
"KubeApiserverReady" from endpoint "readyz of kube apiserver is not successful"
is unhealthy.
이 메시지는 gcloud CLI와 gke_cluster 및 gke_nodepool 리소스 유형 로그 항목에 표시됩니다.
이 문제는 일부 사용자 배포 허용 웹훅이 시스템 구성요소가 올바르게 작동하는 데 필요한 권한을 가진 RBAC 역할을 만들지 못하도록 차단할 때 발생합니다.
컨트롤 플레인 업그레이드 중에 GKE는 Kubernetes API 서버 (kube-apiserver) 구성요소를 다시 만듭니다. 웹훅이 API 서버 구성요소에 대한 RBAC 역할을 차단하면 API 서버가 시작되지 않고 클러스터 업그레이드가 완료되지 않습니다. 웹훅이 제대로 작동하는 경우에도 새로 만든 컨트롤 플레인에서 웹훅에 연결할 수 없으므로 클러스터 업그레이드가 실패할 수 있습니다.
Kubernetes는 최신 마이너 버전의 기본 정책으로 기본 시스템 RBAC 역할을 자동 조정합니다. 시스템 역할에 대한 기본 정책은 새 Kubernetes 버전에서 변경되는 경우가 있습니다.
이 조정을 수행하기 위해 GKE는 클러스터에서 ClusterRoles 및 ClusterRoleBindings를 만들거나 업데이트합니다. 기본 RBAC 정책이 사용하는 권한 범위로 인해 생성 또는 업데이트 요청을 가로채고 거부하는 웹훅이 있는 경우 API 서버가 새 마이너 버전에서 작동하지 않습니다.
실패한 웹훅을 식별하려면 다음 정보가 포함된 RBAC 호출에 대해 GKE 감사 로그를 확인하세요.
protoPayload.resourceName="RBAC_RULE"
protoPayload.authenticationInfo.principalEmail="system:apiserver"
이 출력에서 RBAC_RULE은 RBAC 역할의 전체 이름입니다(예: rbac.authorization.k8s.io/v1/clusterroles/system:controller:horizontal-pod-autoscaler).
실패한 웹훅의 이름은 다음 형식으로 로그에 표시됩니다.
admission webhook WEBHOOK_NAME denied the request
이 문제를 해결하려면 다음 솔루션을 시도해 보세요.
- ClusterRole을 검토하여 지나치게 제한적이지 않은지 확인합니다.
정책이 기본
system:접두사로 ClusterRoles를 만들거나 업데이트하려는 GKE의 요청을 차단해서는 안 됩니다. - 시스템 RBAC 역할을 만들고 업데이트하는 요청을 가로채지 않도록 웹훅을 조정합니다.
- 웹훅을 사용 중지합니다.
오류: DeployPatch 실패
클러스터 업그레이드 작업이 다음 오류와 함께 실패하는 경우가 있습니다.
DeployPatch failed
이 오류는 Kubernetes 컨트롤 플레인이 20분 넘게 비정상 상태로 유지되는 경우 발생할 수 있습니다.
컨트롤 플레인이 작업이 성공할 때까지 재시도하므로 이 오류는 일시적인 경우가 많습니다. 이 오류로 인해 업그레이드가 계속 실패하면 Cloud Customer Care에 문의하세요.
업그레이드 완료 후 문제 해결
업그레이드가 완료된 후 예기치 않은 동작이 발생하면 다음 섹션에서 다음과 같은 일반적인 문제에 대한 문제 해결 안내를 확인하세요.
브레이킹 체인지로 인한 예기치 않은 동작
업그레이드가 완료되었지만 업그레이드 후 예기치 않은 동작이 발생하면 GKE 출시 노트에서 클러스터가 업그레이드된 버전과 관련된 버그 및 브레이킹 체인지에 대한 정보를 확인하세요.
Standard 클러스터 업그레이드 후 워크로드 제거됨
다음 조건에 모두 해당하는 경우 클러스터 업그레이드 후 워크로드가 제거될 위험이 있음
- 클러스터의 컨트롤 플레인이 새 GKE 버전을 실행할 때 시스템 워크로드에 더 많은 공간이 필요합니다.
- 기존 노드에 새 시스템 워크로드와 기존 워크로드를 실행하기에 충분한 리소스가 없음
- 클러스터에 클러스터 자동 확장 처리가 사용 중지됨
이 문제를 해결하려면 다음 솔루션을 시도해 보세요.
노드 할당 가능을 구성한 후 포드가 Pending 상태에서 멈춤
노드 할당 가능을 구성한 경우 노드 버전 업그레이드로 인해 Running 상태였던 포드가 Pending 상태로 멈출 수 있습니다. 이러한 변경은 일반적으로 업그레이드된 노드가 약간 다른 시스템 리소스를 사용하거나, 다시 예약된 포드가 이제 더 엄격한 조건에서 새 노드 또는 수정된 노드의 할당 가능한 노드 한도 내에 맞아야 하기 때문에 발생합니다.
업그레이드 후 Pod의 상태가 Pending인 경우 다음 해결 방법을 시도해 보세요.
- 포드의 CPU 및 메모리 요청이 최대 사용량을 초과하지 않는지 확인합니다. GKE에서 오버헤드에 사용할 CPU와 메모리를 예약하는 반면 Pod는 이러한 리소스를 요청할 수 없습니다. Pod가 사용량보다 많은 CPU 또는 메모리를 요청하면 다른 Pod가 이러한 리소스를 요청하지 못하게 되어 클러스터 사용률이 떨어질 수 있습니다. 자세한 내용은 Kubernetes 문서의 리소스 요청이 있는 pod 예약 방법을 참고하세요.
- 클러스터 크기를 늘려 보세요.
- 업그레이드가 이 문제의 원인인지 확인하려면 노드 풀을 다운그레이드하여 업그레이드를 되돌립니다.
- Kubernetes 스케줄러 측정항목을 Cloud Monitoring에 전송하고 스케줄러 측정항목을 확인하도록 클러스터를 구성합니다. 이러한 측정항목을 모니터링하면 포드를 실행하기에 충분한 리소스가 있는지 확인할 수 있습니다.
버전 및 호환성 문제 해결
클러스터의 모든 구성요소에 지원되고 호환되는 버전을 유지하는 것은 안정성과 성능에 필수적입니다. 다음 섹션에서는 업그레이드 프로세스에 영향을 줄 수 있는 버전 관리 및 호환성 문제를 식별하고 해결하는 방법을 안내합니다.
컨트롤 플레인과 노드 버전의 비호환성 확인
컨트롤 플레인과 노드 간의 버전 차이로 인해 클러스터가 불안정해질 수 있습니다. GKE 버전 차이 정책에 따르면 컨트롤 플레인은 최대 2개 부 버전이 낮은 노드와만 호환됩니다. 예를 들어 1.19 컨트롤 플레인은 1.19, 1.18, 1.17 노드와 호환됩니다.
노드가 지원되는 기간을 벗어나면 심각한 호환성 문제가 발생할 수 있습니다. 이러한 문제는 API와 관련된 경우가 많습니다. 예를 들어 이전 노드의 워크로드가 최신 컨트롤 플레인에서 지원 중단되거나 삭제된 API 버전을 사용할 수 있습니다. 또한 호환되지 않는 워크로드가 통신을 중단하면 노드가 클러스터에 등록되지 못하도록 하는 네트워킹 경로가 손상되는 등 더 심각한 오류가 발생할 수도 있습니다.
GKE팀은 사용자를 대신하여 클러스터 컨트롤 플레인의 업그레이드를 주기적으로 수행합니다. 컨트롤 플레인은 안정적인 새 Kubernetes 버전으로 업그레이드됩니다. 노드가 업그레이드된 컨트롤 플레인과 호환되도록 하려면 노드도 최신 상태로 유지해야 합니다. 기본적으로 클러스터 노드에 자동 업그레이드가 사용 설정되어 있으므로 GKE에서 이 업그레이드를 처리하며, 사용 중지하지 않는 것이 좋습니다. 클러스터 노드에 자동 업그레이드가 사용 중지되어 있고 노드를 수동으로 업그레이드하지 않으면 컨트롤 플레인이 결국 노드와 호환되지 않게 됩니다.
컨트롤 플레인과 노드 버전이 호환되지 않는지 확인하려면 클러스터의 컨트롤 플레인과 노드 풀이 실행 중인 Kubernetes 버전을 확인하세요.
gcloud container clusters describe CLUSTER_NAME \
--project PROJECT_ID \
--location LOCATION
다음을 바꿉니다.
CLUSTER_NAME: 설명할 노드 풀의 클러스터 이름입니다.PROJECT_ID: 클러스터의 프로젝트 ID입니다.LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예:us-central1또는us-central1-a)
출력은 다음과 비슷합니다.
…
currentMasterVersion: 1.32.3-gke.1785003
…
currentNodeVersion: 1.26.15-gke.1090000
…
이 예에서는 컨트롤 플레인 버전과 노드 풀 버전이 호환되지 않습니다.
이 문제를 해결하려면 노드 풀을 수동으로 업그레이드하여 컨트롤 플레인과 호환되는 버전으로 업그레이드하세요.
영향을 받는 노드에서 실행되는 워크로드가 업그레이드 프로세스로 인해 중단되는 것이 우려되는 경우 다음 단계를 완료하여 워크로드를 새 노드 풀로 마이그레이션하세요.
- 호환되는 버전으로 새 노드 풀을 만듭니다.
- 기존 노드 풀의 노드를 Cordon합니다.
- (선택사항) 기존 노드 풀에서 실행되는 워크로드를 업데이트하여
cloud.google.com/gke-nodepool:NEW_NODE_POOL_NAME라벨의 nodeSelector를 추가합니다.NEW_NODE_POOL_NAME을 새 노드 풀 이름으로 바꿉니다. 이 작업을 통해 GKE가 새 노드 풀의 노드에 이러한 워크로드를 배치합니다. - 기존 노드 풀을 드레이닝합니다.
- 새 노드 풀에서 워크로드가 성공적으로 실행되는지 확인합니다. 성공적으로 실행될 경우 이전 노드 풀을 삭제할 수 있습니다. 워크로드 중단이 발견되면 기존 노드 풀에서 노드 차단을 취소하고 새 노드를 드레이닝하여 기존 노드에서 워크로드를 다시 예약합니다.
노드 CPU 사용량이 예상보다 높음
일부 노드가 실행 중인 포드에서 예상보다 많은 CPU를 사용하는 문제가 발생할 수 있습니다.
이 문제는 수동 업그레이드를 사용하고 클러스터 또는 노드가 지원되는 버전을 실행하도록 업그레이드되지 않은 경우에 발생할 수 있습니다. 출시 노트를 검토하여 사용 중인 버전이 사용 가능하고 지원되는지 확인합니다.
다음 단계
문서에서 문제 해결 방법을 찾을 수 없으면 지원 받기를 참조하여 다음 주제에 대한 조언을 포함한 추가 도움을 요청하세요.
- Cloud Customer Care에 문의하여 지원 케이스를 엽니다.
- StackOverflow에서 질문하고
google-kubernetes-engine태그를 사용하여 유사한 문제를 검색해 커뮤니티의 지원을 받습니다.#kubernetes-engineSlack 채널에 가입하여 더 많은 커뮤니티 지원을 받을 수도 있습니다. - 공개 Issue Tracker를 사용하여 버그나 기능 요청을 엽니다.