클러스터 또는 노드 풀 수동 업그레이드

기본적으로 자동 업그레이드가 Google Kubernetes Engine(GKE) 클러스터 및 GKE Standard 노드 풀에 사용 설정되어 있습니다.

이 페이지에서는 GKE 클러스터의 제어 영역 또는 노드에 대한 업그레이드 또는 다운그레이드를 수동으로 요청하는 방법을 설명합니다. 다음과 같이 버전을 수동으로 업그레이드할 수 있습니다.

• Autopilot: 컨트롤 플레인 버전을 업그레이드합니다.
• Standard: 제어 영역 버전 및노드 풀 버전을 업그레이드합니다.

클러스터를 업그레이드하기 위해 GKE에서 제어 영역과 노드가 실행하고 있는 버전을 업데이트합니다. 클러스터는 최신 부 버전(예: 1.24~1.25) 또는 최신 패치 버전(예: 1.24.2-gke.100~1.24.5-gke.200)으로 업그레이드됩니다. 자세한 내용은 GKE 버전 관리 및 지원을 참조하세요.

클러스터 자동 및 수동 업그레이드 방법을 자세히 알아보세요. 또한 유지보수 기간 및 유지보수 제외를 구성하여 자동 업그레이드 가능 여부를 제어할 수 있습니다.

새 버전의 GKE는 정기적으로 발표됩니다. 클러스터 알림을 사용하여 특정 클러스터를 업그레이드할 수 있는 새 버전에 대한 알림을 받을 수 있습니다.

사용 가능한 버전에 대한 자세한 내용은 버전 관리를 참조하세요. 클러스터에 대한 자세한 내용은 클러스터 아키텍처를 참조하세요. 클러스터 업그레이드에 대한 안내는 클러스터 업그레이드 권장사항을 참조하세요.

시작하기 전에

시작하기 전에 다음 태스크를 수행했는지 확인합니다.

• Google Kubernetes Engine API를 사용 설정합니다.
Google Kubernetes Engine API 사용 설정
• 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.

영구 디스크에 데이터 저장

보존하려는 모든 데이터가 영구 디스크를 사용하는 영구 볼륨을 통해 포드에 저장되어 있는지 확인한 후에 노드 풀을 업그레이드해야 합니다. 업그레이드 중에는 영구 디스크가 삭제가 아닌 마운트 해제되고, 데이터는 다른 포드로 '전달'됩니다.

영구 디스크와 관련된 제한사항은 다음과 같습니다.

• 포드가 실행되는 노드는 Compute Engine VM이어야 합니다.
• 이러한 VM은 영구 디스크와 동일한 Compute Engine 프로젝트 및 영역에 있어야 합니다.

기존 노드 인스턴스에 영구 디스크를 추가하는 방법은 Compute Engine 문서의 영역 영구 디스크 추가 또는 크기 조절을 참조하세요.

업그레이드 정보

클러스터의 제어 영역과 노드는 별개로 업그레이드됩니다.

클러스터 제어 영역은 클러스터가 출시 채널에 등록되었는지 여부에 관계없이 항상 정기적으로 업그레이드됩니다.

사전에 업그레이드 알림을 받으려면 클러스터 알림 수신을 참조하세요.

제한사항

알파 클러스터는 업그레이드할 수 없습니다.

지원되는 버전

출시 노트는 새 버전의 출시 시기 및 기존 버전의 사용 중단 시기를 안내합니다. 언제든지 다음 명령어를 사용하여 지원되는 클러스터 및 노드 버전의 전체 목록을 확인할 수 있습니다.

gcloud container get-server-config

클러스터가 출시 채널에 등록되면 제어 영역과 동일한 부 버전으로 다른 출시 채널의 패치 버전으로 업그레이드할 수 있습니다. 예를 들어 클러스터를 일반 채널의 버전 1.21.12-gke.1700에서 신속 채널의 버전 1.21.13-gke.900으로 업그레이드할 수 있습니다. 자세한 내용은 최신 채널에서 패치 버전 실행을 참조하세요. 모든 Autopilot 클러스터는 출시 채널에 등록됩니다.

다운그레이드 제한사항

특정 시나리오에서는 클러스터 버전을 이전 버전으로 다운그레이드할 수 있습니다.

실패한 클러스터 제어 영역 업그레이드를 완화하기 위해 버전이 동일한 부 버전 내의 이전 패치 출시 버전인 경우 제어 영역을 이전 패치 출시 버전으로 다운그레이드할 수 있습니다. 예를 들어 클러스터의 제어 영역이 GKE 1.25.3-gke.400을 실행하는 경우 해당 버전을 계속 사용할 수 있으면 제어 영역을 1.25.2-gke.100으로 다운그레이드할 수 있습니다.

Kubernetes 클러스터 컨트롤 플레인을 이전 부 버전으로 다운그레이드할 수 없습니다. 예를 들어 컨트롤 플레인에서 GKE 버전 1.25를 실행하는 경우 1.24로 다운그레이드할 수 없습니다. 이를 수행하려고 시도하면 다음 오류 메시지가 표시됩니다.

ERROR: (gcloud.container.clusters.upgrade) ResponseError: code=400,
message=Master cannot be upgraded to "1.24.3-gke.100": specified version is not
newer than the current version.

클러스터 제어 영역의 부 버전을 다운그레이드할 수 없으므로 새 부 버전을 사용할 수 있게 되었지만 기본 버전이 되기 전에 테스트 환경의 클러스터에서 부 버전 업그레이드를 테스트하고 검증하는 것이 좋습니다. 특히 지원 중단된 API 또는 제거되는 기능과 같이 다음 부 버전의 중요 변경사항으로 인해 클러스터가 영향을 받을 수 있는 경우에 권장됩니다.

실패한 노드 풀 업그레이드를 완화하려면 노드 풀을 이전 패치 출시 버전 또는 부 버전으로 다운그레이드하면 됩니다. 클러스터 컨트롤 플레인 버전보다 마이너 버전 세 개 이상 낮은 버전으로 노드를 다운그레이드하지 않도록 합니다.

클러스터 업그레이드

Google은 클러스터와 노드를 자동으로 업그레이드합니다. 클러스터 및 노드의 자동 업그레이드를 제어하려면 출시 채널에 등록하세요. 모든 Autopilot 클러스터는 출시 채널에 자동으로 등록됩니다.

클러스터의 GKE 버전 관리에 대해 자세히 알아보려면 업그레이드를 참조하세요.

새 버전이 출시되면 언제든지 수동 업그레이드를 시작할 수 있습니다.

수동으로 제어 영역 업그레이드

클러스터 업그레이드를 시작하면 제어 영역에 다시 액세스할 수 있을 때까지 몇 분 동안 클러스터 구성을 수정할 수 없습니다. 제어 영역 업그레이드 중 다운타임을 방지하려면 Autopilot 클러스터 또는 리전별 Standard 클러스터를 사용합니다. 제어 영역 업그레이드 중에도 워커 노드를 계속 사용할 수 있으므로 이 작업은 워크로드가 실행되는 워커 노드의 가용성에는 영향을 미치지 않습니다.

Google Cloud console 또는 Google Cloud CLI를 사용하여 Autopilot 또는 표준 제어 영역을 수동으로 업그레이드할 수 있습니다.

gcloud container get-server-config

gcloud container clusters upgrade CLUSTER_NAME --master

gcloud container clusters upgrade CLUSTER_NAME --master \
    --cluster-version VERSION

표준 제어 영역을 업그레이드하면 노드를 업그레이드할 수 있습니다. 기본적으로 Google Cloud 콘솔을 사용하여 만든 표준 노드에는 자동 업그레이드가 사용 설정되어 있으므로 자동으로 업그레이드됩니다. Autopilot은 항상 노드를 자동으로 업그레이드합니다.

클러스터 다운그레이드

1. 다운그레이드한 후 GKE가 제어 영역을 자동으로 업그레이드하지 못하도록 다운그레이드하기 전에 유지보수 제외를 설정합니다.

2. 클러스터 컨트롤 플레인을 이전 패치 버전으로 다운그레이드합니다.

    gcloud container clusters upgrade CLUSTER_NAME \
        --master --cluster-version VERSION
   

클러스터 자동 업그레이드 사용 중지

인프라 보안은 GKE에서 높은 우선순위로, 이러한 제어 영역이 정기적으로 업그레이드되며 사용 중지할 수 없습니다. 그러나 유지보수 기간 및 유지보수 제외를 적용하여 제어 영역과 노드의 업그레이드를 일시적으로 정지할 수 있습니다.

권장되지는 않지만 노드 자동 업그레이드 사용 중지는 가능합니다.

노드 풀 업그레이드

기본적으로 클러스터 노드는 자동 업그레이드가 사용 설정되어 있으며, 사용 중지하지 않는 것이 좋습니다. 노드 자동 업그레이드를 통해 클러스터의 컨트롤 플레인과 노드 버전이 동기화 상태를 유지하고 컨트롤 플레인이 보장되는 Kubernetes 버전 차이 정책을 준수할 수 있으므로, 컨트롤 플레인이 자신보다 최대 2개 마이너 버전이 낮은 노드와 호환됩니다. 예를 들어 Kubernetes 1.29 컨트롤 플레인은 Kubernetes 1.27 노드와 호환됩니다.

GKE 노드 풀 업그레이드를 사용하면 일시 급증 업그레이드와 블루-그린 업그레이드라는 두 가지 구성 가능한 업그레이드 전략 중에서 선택할 수 있습니다.

전략을 선택하고 매개변수를 사용하여 전략을 조정하여 클러스터 환경의 요구사항에 가장 잘 맞게 조정합니다.

노드가 업그레이드되는 동안 GKE는 새 Pod의 예약을 중지하고 실행 중인 Pod를 다른 노드에 예약합니다. 이는 노드 풀에서 기능을 사용 또는 사용 중지하는 것과 같이 노드를 다시 만드는 다른 이벤트와 유사합니다.

모든 노드가 다시 생성되고 클러스터가 원하는 상태가 될 때 업그레이드가 완료됩니다. 새로 업그레이드된 노드가 컨트롤 플레인에 등록되면 GKE는 노드를 예약 가능으로 표시합니다.

새 노드 인스턴스는 원하는 Kubernetes 버전뿐만 아니라 다음 항목을 실행합니다.

• 노드 이미지
• kubelet
• kube-proxy

노드 풀 수동 업그레이드

노드 풀 버전은 컨트롤 플레인 버전과 일치하도록 업그레이드하거나 계속 지원 중이며 컨트롤 플레인과 호환되는 이전 버전으로 수동 업그레이드할 수 있습니다. 여러 노드 풀을 동시에 수동으로 업그레이드할 수 있지만 GKE는 한 번에 하나의 노드 풀만 자동으로 업그레이드합니다.

노드 풀을 수동으로 업그레이드하면 GKE는 kubectl을 사용하여 개별 노드에 추가한 라벨을 삭제합니다. 이를 방지하려면 대신 노드 풀에 라벨을 적용합니다.

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 컨트롤 플레인과 호환되는 버전으로 노드 풀을 수동으로 업그레이드할 수 있습니다.

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

gcloud container clusters upgrade CLUSTER_NAME \
  --node-pool=NODE_POOL_NAME \
  --cluster-version VERSION

노드 풀 다운그레이드

예를 들어 실패한 노드 풀 업그레이드를 완화하기 위해 노드 풀을 다운그레이드할 수 있습니다. 노드 풀을 다운그레이드하기 전에 제한사항을 검토하세요.

1. 다운그레이드 후 GKE에서 노드 풀을 자동으로 업그레이드하지 못하도록 클러스터에 유지보수 제외를 설정합니다.
2. 노드 풀을 다운그레이드하려면 노드 풀 수동 업그레이드 안내에 따라 이전 버전을 지정합니다.

일시 급증 업그레이드 매개변수 변경

일시 급증 업그레이드 매개변수 변경에 관해 자세히 알아보려면 일시 급증 업그레이드 구성을 참조하세요.

노드 풀 업그레이드 상태 확인

gcloud container operations를 사용하여 업그레이드 상태를 확인할 수 있습니다.

클러스터에서 모든 실행 중인 작업과 완료된 작업의 목록을 확인합니다.

gcloud container operations list

각 작업에는 작업 ID와 작업 유형은 물론 시작 및 종료 시간, 대상 클러스터, 상태가 할당됩니다. 이 목록은 다음 예와 비슷하게 표시됩니다.

NAME                              TYPE                ZONE           TARGET              STATUS_MESSAGE  STATUS  START_TIME                      END_TIME
operation-1505407677851-8039e369  CREATE_CLUSTER      us-west1-a     my-cluster                          DONE    20xx-xx-xxT16:47:57.851933021Z  20xx-xx-xxT16:50:52.898305883Z
operation-1505500805136-e7c64af4  UPGRADE_CLUSTER     us-west1-a     my-cluster                          DONE    20xx-xx-xxT18:40:05.136739989Z  20xx-xx-xxT18:41:09.321483832Z
operation-1505500913918-5802c989  DELETE_CLUSTER      us-west1-a     my-cluster                          DONE    20xx-xx-xxT18:41:53.918825764Z  20xx-xx-xxT18:43:48.639506814Z

특정 작업에 대한 자세한 정보를 보려면 다음 명령어에 표시된 대로 해당 작업 ID를 지정합니다.

gcloud container operations describe OPERATION_ID

예를 들면 다음과 같습니다.

gcloud container operations describe operation-1507325726639-981f0ed6
endTime: '20xx-xx-xxT21:40:05.324124385Z'
name: operation-1507325726639-981f0ed6
operationType: UPGRADE_CLUSTER
selfLink: https://container.googleapis.com/v1/projects/.../kubernetes-engine/docs/zones/us-central1-a/operations/operation-1507325726639-981f0ed6
startTime: '20xx-xx-xxT21:35:26.639453776Z'
status: DONE
targetLink: https://container.googleapis.com/v1/projects/.../kubernetes-engine/docs/zones/us-central1-a/clusters/...
zone: us-central1-a

노드 풀 업그레이드 설정 확인

gcloud container node-pools describe 명령어를 사용하여 노드 풀에 사용 중인 노드 업그레이드 전략에 대한 세부정보를 참조할 수 있습니다. 블루-그린 업그레이드의 경우 명령어가 업그레이드의 현재 단계도 반환합니다.

다음 명령어를 실행합니다.

gcloud container node-pools describe NODE_POOL_NAME \
--cluster=CLUSTER_NAME

다음을 바꿉니다.

• NODE_POOL_NAME: 설명할 노드 풀 이름입니다.
• CLUSTER_NAME: 설명할 노드 풀의 클러스터 이름입니다.

이 명령어는 현재 업그레이드 설정을 출력합니다. 다음 예시에서는 블루-그린 업그레이드 전략을 사용 중인 경우의 출력을 보여줍니다.

upgradeSettings:
  blueGreenSettings:
    nodePoolSoakDuration: 1800s
    standardRolloutPolicy:
      batchNodeCount: 1
      batchSoakDuration: 10s
  strategy: BLUE_GREEN

블루-그린 업그레이드 전략을 사용하는 경우에는 출력에 블루-그린 업그레이드 설정 및 현재 중간 단계에 대한 세부정보도 포함됩니다. 다음 예시는 이와 같은 출력을 보여줍니다.

updateInfo:
  blueGreenInfo:
    blueInstanceGroupUrls:
    - https://www.googleapis.com/compute/v1/projects/{PROJECT_ID}/zones/{LOCATION}/instanceGroupManagers/{BLUE_INSTANCE_GROUP_NAME}
    bluePoolDeletionStartTime: {BLUE_POOL_DELETION_TIME}
    greenInstanceGroupUrls:
    - https://www.googleapis.com/compute/v1/projects/{PROJECT_ID}/zones/{LOCATION}/instanceGroupManagers/{GREEN_INSTANCE_GROUP_NAME} 
    greenPoolVersion: {GREEN_POOL_VERSION}
    phase: DRAINING_BLUE_POOL

노드 풀 업그레이드 취소

언제든지 업그레이드를 취소할 수 있습니다. 일시 급증 업그레이드를 취소하면 어떻게 되는지에 관해 자세히 알아보려면 일시 급증 업그레이드 취소를 참조하세요. 블루-그린 업그레이드를 취소하면 어떻게 되는지에 관해 자세히 알아보려면 블루-그린 업그레이드 취소를 참조하세요.

1. 업그레이드 작업 ID를 가져옵니다.

   gcloud container operations list
   

2. 업그레이드를 취소합니다.

   gcloud container operations cancel OPERATION_ID
   

gcloud container operations cancel 문서를 참조하세요.

노드 풀 업그레이드 재개

업그레이드 수동 시작을 다시 수행하고 원래 업그레이드에서 대상 버전을 지정하여 업그레이드를 재개할 수 있습니다.

예를 들어 업그레이드에 실패했거나 진행 중인 업그레이드를 일시중지한 경우 노드 풀에서 동일한 업그레이드를 다시 시작하고 초기 업그레이드 작업에서 대상 버전을 지정하여 취소된 업그레이드를 재개할 수 있습니다.

업그레이드를 재개하면 어떻게 되는지에 관해 자세히 알아보려면 일시 급증 업그레이드 재개 및 블루-그린 업그레이드를 참조하세요.

업그레이드를 재개하려면 다음 명령어를 사용합니다.

    gcloud container clusters upgrade CLUSTER_NAME \
      --node-pool=NODE_POOL_NAME \
      --cluster-version VERSION

다음을 바꿉니다.

• NODE_POOL_NAME: 노드 풀 업그레이드를 재개하려는 노드 풀 이름입니다.
• CLUSTER_NAME: 업그레이드를 재개하려는 노드 풀의 클러스터 이름입니다.
• VERSION: 취소된 노드 풀 업그레이드의 대상 버전입니다.

자세한 내용은 gcloud container clusters upgrade 문서를 참조하세요.

노드 풀 업그레이드 롤백

노드 풀을 롤백하여 업그레이드된 노드를 노드 풀 업그레이드가 시작되기 전의 원래 상태로 다운그레이드할 수 있습니다.

진행 중인 업그레이드가 취소되었거나 업그레이드가 실패했거나 유지보수 기간 타임아웃으로 인해 업그레이드가 완료되지 않은 경우 rollback 명령어를 사용합니다. 또는 버전을 지정하려면 안내에 따라 노드 풀을 다운그레이드하세요.

노드 풀 업그레이드를 롤백하면 어떻게 되는지에 관해 자세히 알아보려면 일시 급증 업그레이드 롤백 또는 블루-그린 업그레이드 롤백을 참조하세요.

업그레이드를 롤백하려면 다음 명령어를 실행하세요.

gcloud container node-pools rollback NODE_POOL_NAME \
  --cluster CLUSTER_NAME

다음을 바꿉니다.

• NODE_POOL_NAME: 노드 풀 업그레이드를 롤백하려는 노드 풀의 이름
• CLUSTER_NAME: 업그레이드를 롤백하려는 노드 풀의 클러스터 이름

gcloud container node-pools rollback 문서를 참조하세요.

노드 풀 업그레이드 완료

블루-그린 업그레이드 전략을 사용하는 경우 배양(Soak) 시간 중 노드 풀 업그레이드를 완료하고 나머지 배양 시간은 건너뛸 수 있습니다.

노드 풀 업그레이드 완료 방식을 알아보려면 노드 풀 업그레이드 완료를 참조하세요.

블루-그린 업그레이드 전략을 사용할 때 업그레이드를 완료하려면 다음 명령어를 실행합니다.

gcloud container node-pools complete-upgrade NODE_POOL_NAME \
  --cluster CLUSTER_NAME

다음을 바꿉니다.

• NODE_POOL_NAME: 업그레이드를 완료할 노드 풀의 이름입니다.
• CLUSTER_NAME: 업그레이드를 완료할 노드 풀의 클러스터 이름입니다.

gcloud container node-pools complete-upgrade 문서를 참조하세요.

알려진 문제

추가 중단을 허용할 수 없도록 구성된 PodDisruptionBudget 객체가 있으면 반복된 시도 후 노드 업그레이드가 제어 영역 버전으로 업그레이드되지 않을 수 있습니다. 이러한 실패를 방지하려면 PodDisruptionBudget 구성을 지키면서 노드 드레이닝을 허용하도록 Deployment 또는 HorizontalPodAutoscaler를 수직 확장하는 것이 좋습니다.

중단을 허용하지 않는 모든 PodDisruptionBudget 객체를 보려면 다음 안내를 따르세요.

kubectl get poddisruptionbudget --all-namespaces -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.name}/{.metadata.namespace}{"\n"}{end}'

자동 업그레이드 시 문제가 발생할 수 있긴 하지만, 자동 업그레이드 프로세스는 노드를 강제로 업그레이드합니다. 그러나 업그레이드 시 PodDisruptionBudget을 위반하는 istio-system 네임 스페이스의 모든 노드에 대해 추가 시간이 소요됩니다.

문제 해결

완료되지 않은 노드 풀 업그레이드 재개 또는 롤백

GKE에서 노드 풀 업그레이드를 완료하지 않았고 노드가 새 버전으로 부분적으로 업그레이드된 경우 업그레이드를 재개하거나 롤백할 수 있습니다. 이는 노드 업그레이드 전략인 일시 급증 업그레이드 또는 블루/그린 업그레이드를 사용하는 노드 풀 업그레이드와 관련이 있습니다.

다음과 같은 이유로 부분적으로 업그레이드된 노드 풀이 있을 수 있습니다.

• 노드 풀 업그레이드를 취소했습니다.
• 예상치 못한 문제로 인해 업그레이드가 실패했습니다.
• 유지보수 기간 타임아웃으로 인해 업그레이드가 완료되지 않았습니다.

업그레이드를 재개하거나 롤백하는 안내에 따라 노드 풀의 모든 노드가 일관된 버전을 실행하도록 하세요. 아무 조치도 취하지 않으면 GKE는 유지보수 가능 여부에 따라 노드 풀을 다시 업그레이드하려고 시도합니다.

예상보다 높은 노드 CPU 사용량

일부 노드가 실행 중인 포드에서 예상보다 많은 CPU 사용량을 사용하는 문제가 발생할 수 있습니다.

이 문제는 클러스터 또는 노드가 지원되는 버전을 실행하지 않는 경우에 발생할 수 있습니다. 출시 노트를 검토하여 사용 중인 버전이 사용 가능하고 지원되는지 확인합니다. 또한 다음 명령어를 실행하여 지원되는 모든 클러스터 및 노드 버전을 나열할 수 있습니다.

gcloud container get-server-config

다음 단계

• 클러스터 아키텍처 알아보기
• 출시 채널 알아보기