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

gkectl

사용자 클러스터 업그레이드 준비

관리자 워크스테이션에서 다음 단계를 수행합니다.

1. gkectl prepare를 실행하여 OS 이미지를 vSphere로 가져옵니다.

   gkectl prepare \
     --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
     --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

2. 클러스터에 Windows 노드 풀이 있으면 gkectl prepare windows를 실행하고 노드 풀의 osImage 필드를 업데이트합니다. 자세한 안내는 Windows 노드 풀이 있는 사용자 클러스터 업그레이드를 참조하세요.

3. 사용자 클러스터 구성 파일에서 gkeOnPremVersion을 업그레이드 대상 버전으로 설정합니다.

4. Ubuntu 및 COS 노드 풀만 해당: 업그레이드할 노드 풀을 지정합니다. Ubuntu 및 COS 노드 풀의 경우 컨트롤 플레인과 별도로 노드 풀을 업그레이드할 수 있지만 Windows 노드 풀에서는 이러한 업그레이드가 지원되지 않습니다.

   사용자 클러스터 구성 파일에서 다음과 같이 업그레이드할 노드 풀을 표시합니다.

   • 업그레이드하려는 각 노드 풀에 대해 nodePools.nodePool[i].gkeOnPremVersion 필드를 삭제하거나 빈 문자열로 설정합니다.

   • 업그레이드하지 않을 각 노드 풀에 대해 nodePools.nodePool[i].gkeOnPremVersion을 현재 버전으로 설정합니다.

   예를 들어 사용자 클러스터 버전이 1.15.5-gke.41이고 노드 풀이 두 개(pool-1 및 pool-2) 있다고 가정합니다. 또한 컨트롤 플레인과 pool-1을 1.16.3-gke.45로 업그레이드하되 pool-2를 버전 1.15.5-gke.41로 유지한다고 가정합니다. 사용자 클러스터 구성 파일의 다음 부분에서 이 예시를 지정하는 방법을 보여줍니다.

   gkeOnPremVersion: 1.16.3-gke.45
   
   nodePools:
   - name: pool-1
     gkeOnPremVersion: ""
     cpus: 4
     memoryMB: 8192
     replicas: 3
     osImageType: ubuntu_containerd
   - name: pool-2
     gkeOnPremVersion: 1.15.5-gke.41
     cpus: 4
     memoryMB: 8192
     replicas: 5
     osImageType: ubuntu_containerd
   

프리플라이트 검사 실행

버전 1.29 이상으로 업그레이드하는 경우 사용자 클러스터를 업그레이드하기 전 프리플라이트 검사를 실행할 수 있습니다.

gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG \
  --dry-run

--dry-run 플래그를 사용하면 gkectl upgrade cluster가 프리플라이트 검사를 실행하지만 업그레이드 프로세스를 시작하지는 않습니다. 이전 버전의 Google Distributed Cloud는 프리플라이트 검사를 실행하지만 업그레이드와 별도로 실행할 수는 없습니다. --dry-run 플래그를 추가하면 업그레이드 전 사용자 클러스터에서 프리플라이트 검사가 발견한 모든 문제를 찾고 해결할 수 있습니다.

gkectl upgrade cluster 실행

gkectl upgrade cluster 명령어에는 두 가지 변형이 있습니다.

• 비동기: (권장)
  비동기 변형을 사용하면 명령어가 업그레이드를 시작한 후 완료합니다. 업그레이드 전체 기간 동안 명령어의 출력을 확인할 필요가 없습니다. 대신 gkectl list clusters 및 gkectl describe clusters를 실행하여 업그레이드 진행 상황을 주기적으로 확인할 수 있습니다. 비동기 변형을 사용하려면 명령어에 --async 플래그를 포함합니다.

• 동기:
  동기 변형을 사용하면 gkectl upgrade cluster 명령어에서 업그레이드가 진행되는 동안 관리자 워크스테이션에 상태 메시지를 출력합니다.

Warning  PodEvictionTooLong  96s (x2 over 4m7s)  onprem-user-cluster-controller
Waiting too long(>10m0.00000003s) for (kube-system/coredns-856d6dbfdf-dl6nz) eviction.

추가 노드 풀 업그레이드

사용자 클러스터의 컨트롤 플레인만 업그레이드했거나 컨트롤 플레인과 일부 노드 풀을 업그레이드한 경우 다음 단계를 수행하여 노드 풀을 업그레이드합니다.

1. 사용자 클러스터 구성 파일을 수정합니다. 다음 예시에 표시된 것처럼 업그레이드하려는 각 노드 풀에 대해 nodePools.nodePool[i].gkeOnPremVersion 필드를 삭제하거나 빈 문자열로 설정합니다.

   gkeOnPremVersion: 1.16.3-gke.45
   
   nodePools:
   - name: pool-1
     gkeOnPremVersion: ""
     cpus: 4
     memoryMB: 8192
     replicas: 3
     osImageType: ubuntu_containerd
   - name: pool-2
     gkeOnPremVersion: ""
     cpus: 4
     memoryMB: 8192
     replicas: 5
     osImageType: ubuntu_containerd
   

2. gkectl update cluster를 실행하여 변경사항을 적용합니다.

   gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
     --config USER_CLUSTER_CONFIG
   

   다음을 바꿉니다.

   • ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로

   • USER_CLUSTER_CONFIG: 사용자 클러스터 구성 파일의 경로.

노드 풀을 업그레이드한 후 문제가 발생하면 이전 버전으로 롤백할 수 있습니다. 자세한 내용은 업그레이드 후 노드 풀 롤백을 참조하세요.

업그레이드 재개

사용자 클러스터 업그레이드가 중단되면 --skip-validation-all 플래그로 동일한 업그레이드 명령어를 실행하여 사용자 클러스터 업그레이드를 재개할 수 있습니다.

gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG_FILE \
  --skip-validation-all

콘솔

사용자 클러스터를 업그레이드하려면 관리자 클러스터에 몇 가지 변경사항을 적용해야 합니다. 콘솔에서 자동으로 다음을 수행합니다.

• 아직 등록되지 않았으면 GKE On-Prem API에 관리자 클러스터를 등록합니다.

• 구성요소 번들을 관리자 클러스터에 다운로드하고 배포합니다. 구성요소의 버전이 업그레이드에서 지정한 버전과 일치합니다. 이러한 구성요소를 통해 관리자 클러스터는 해당 버전의 사용자 클러스터를 관리할 수 있습니다.

사용자 클러스터를 업그레이드하려면 다음 안내를 따르세요.

1. 콘솔에서 Google Kubernetes Engine 클러스터 개요 페이지로 이동합니다.

   GKE 클러스터로 이동

2. Google Cloud 프로젝트를 선택한 후 업그레이드하려는 클러스터를 선택합니다.

3. 세부정보 패널에서 추가 세부정보를 클릭합니다.

4. 클러스터 기본사항 섹션에서 edit 업그레이드를 클릭합니다.

5. 대상 버전 선택 목록에서 업그레이드하려는 버전을 선택합니다. 선별된 목록에는 최신 패치 릴리스만 포함됩니다.

6. 업그레이드를 클릭합니다.

클러스터가 업그레이드되기 전 클러스터 상태 및 노드 상태를 검증하기 위해 프리플라이트 검사가 실행됩니다. 프리플라이트 검사가 통과하면 사용자 클러스터가 업그레이드됩니다. 업그레이드를 완료하는 데 약 30분 정도 걸립니다.

업그레이드 상태를 보려면 클러스터 세부정보 탭에서 세부정보 표시를 클릭합니다.

gcloud CLI

사용자 클러스터를 업그레이드하려면 관리자 클러스터에 몇 가지 변경사항을 적용해야 합니다. gcloud container vmware clusters upgrade 명령어는 자동으로 다음을 수행합니다.

• 아직 등록되지 않았으면 GKE On-Prem API에 관리자 클러스터를 등록합니다.

• 구성요소 번들을 관리자 클러스터에 다운로드하고 배포합니다. 구성요소의 버전이 업그레이드에서 지정한 버전과 일치합니다. 이러한 구성요소를 통해 관리자 클러스터는 해당 버전의 사용자 클러스터를 관리할 수 있습니다.

사용자 클러스터를 업그레이드하려면 다음 안내를 따르세요.

1. Google Cloud CLI 구성요소를 업데이트합니다.

   gcloud components update
   

2. Ubuntu 및 COS 노드 풀만 해당: 사용자 클러스터의 컨트롤 플레인만 업그레이드하고 모든 노드 풀을 현재 버전으로 두려면 클러스터에서 업그레이드 정책을 변경합니다.

   gcloud container vmware clusters update USER_CLUSTER_NAME \
     --project=PROJECT_ID \
     --location=REGION \
     --upgrade-policy control-plane-only=True
   

   다음을 바꿉니다.

   • USER_CLUSTER_NAME: 업그레이드할 사용자 클러스터 이름

   • PROJECT_ID: 사용자 클러스터가 구성원인 Fleet 호스트 프로젝트의 ID. 이 프로젝트는 클러스터를 만들 때 지정된 프로젝트입니다. gkectl을 사용하여 클러스터를 만들었으면 클러스터 구성 파일에서 gkeConnect.projectID 필드의 프로젝트 ID입니다.

   • REGION: GKE On-Prem API가 메타데이터를 실행하고 저장하는 Google Cloud 리전. GKE On-Prem API 클라이언트를 사용하여 클러스터를 만든 경우 이 리전은 클러스터를 만들 때 선택한 리전입니다. gkectl을 사용하여 클러스터를 만든 경우 이 리전은 GKE On-Prem API에 클러스터를 등록할 때 지정한 리전입니다.

3. 업그레이드할 수 있는 버전 목록을 가져옵니다.

   gcloud container vmware clusters query-version-config \
     --cluster=USER_CLUSTER_NAME \
     --project=PROJECT_ID \
     --location=REGION
   

   이 명령어 출력은 다음과 비슷합니다.

   versions:
   - version: 1.16.3-gke.45
   - version: 1.16.2-gke.28
   - version: 1.16.1-gke.45
   - version: 1.16.0-gke.669
   - version: 1.15.6-gke.25
   - version: 1.15.5-gke.41
   
   An Anthos version must be made available on the admin cluster ahead of the user
   cluster creation or upgrade. Versions annotated with isInstalled=true are
   installed on the admin cluster for the purpose of user cluster creation or
   upgrade whereas other version are released and will be available for upgrade
   once dependencies are resolved.
   
   To install the version in the admin cluster, run:
   $ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION
   

   버전 목록 다음에 표시되는 메시지는 무시해도 됩니다. 업그레이드할 버전이 관리자 클러스터에 설치되어 있는지 여부는 중요하지 않습니다. upgrade 명령어는 upgrade 명령어에 지정한 버전과 일치하는 구성요소 번들을 다운로드하고 배포합니다.

4. 클러스터를 업그레이드합니다. update 명령어를 실행하여 업그레이드 정책을 control-plane-only=True로 변경한 경우 클러스터의 컨트롤 플레인만 업그레이드됩니다. 그렇지 않다면 클러스터의 컨트롤 플레인과 모든 노드 풀이 업그레이드됩니다.

   gcloud container vmware clusters upgrade USER_CLUSTER_NAME \
     --project=PROJECT_ID \
     --location=REGION \
     --version=VERSION
   

   업그레이드하려는 Google Distributed Cloud 버전으로 VERSION을 바꿉니다. 이전 명령어의 출력에서 버전을 지정합니다. 최신 패치 버전으로 업그레이드하는 것이 좋습니다.

   명령어 출력은 다음과 비슷합니다.

   Waiting for operation [projects/example-project-12345/locations/us-west1/operations/operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179] to complete.
   

   예시 출력에서 operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179 문자열은 장기 실행 작업의 OPERATION_ID입니다. 다른 터미널 창에서 다음 명령어를 실행하여 작업 상태를 찾을 수 있습니다.

   gcloud container vmware operations describe OPERATION_ID \
     --project=PROJECT_ID \
     --location=REGION
   

노드 풀 업그레이드

사용자 클러스터의 컨트롤 플레인만 업그레이드하도록 선택한 경우 다음 단계를 수행하여 사용자 클러스터의 컨트롤 플레인이 업그레이드된 후 노드 풀을 업그레이드합니다.

1. 사용자 클러스터의 노드 풀 목록을 가져옵니다.

   gcloud container vmware node-pools list
     --cluster=USER_CLUSTER_NAME  \
     --project=PROJECT_ID \
     --location=REGION
   

2. 업그레이드하려는 각 노드 풀에 대해 다음 명령어를 실행합니다.

   gcloud container vmware node-pools update NODE_POOL_NAME \
     --cluster=USER_CLUSTER_NAME  \
     --project=PROJECT_ID \
     --location=REGION \
     --version=VERSION
   

Terraform

1. Google Cloud CLI 구성요소를 업데이트합니다.

   gcloud components update
   

2. 아직 수행하지 않았으면 GKE On-Prem API에 관리자 클러스터를 등록합니다.. GKE On-Prem API에 클러스터를 등록한 다음에는 이 단계를 다시 수행할 필요가 없습니다.

3. 업그레이드할 수 있는 버전 목록을 가져옵니다.

   gcloud container vmware clusters query-version-config \
     --cluster=USER_CLUSTER_NAME \
     --project=PROJECT_ID \
     --location=REGION
   

   다음을 바꿉니다.

   • USER_CLUSTER_NAME: 사용자 클러스터의 이름

   • PROJECT_ID: 사용자 클러스터가 멤버인 Fleet 프로젝트의 ID. 이 프로젝트는 클러스터를 만들 때 지정된 프로젝트입니다. gkectl을 사용하여 클러스터를 만들었으면 클러스터 구성 파일에서 gkeConnect.projectID 필드의 프로젝트 ID입니다.

   • REGION: GKE On-Prem API가 메타데이터를 실행하고 저장하는 Google Cloud 리전. 사용자 클러스터를 만드는 데 사용한 main.tf 파일에서 리전은 클러스터 리소스의 location 필드에 있습니다.

   이 명령어 출력은 다음과 비슷합니다.

   versions:
   - version: 1.16.3-gke.45
   - version: 1.16.2-gke.28
   - version: 1.16.1-gke.45
   - version: 1.16.0-gke.669
   - version: 1.15.6-gke.25
   - version: 1.15.5-gke.41
   
   An Anthos version must be made available on the admin cluster ahead of the user
   cluster creation or upgrade. Versions annotated with isInstalled=true are
   installed on the admin cluster for the purpose of user cluster creation or
   upgrade whereas other version are released and will be available for upgrade
   once dependencies are resolved.
   
   To install the version in the admin cluster, run:
   $ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION
   

4. 새 버전의 구성요소를 다운로드하고 관리자 클러스터에 배포합니다.

   gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
     --project=PROJECT_ID \
     --location=REGION \
     --required-platform-version=VERSION
   

   이 명령어는 --required-platform-version에 지정하는 구성요소 버전을 관리자 클러스터에 다운로드한 후 구성요소를 배포합니다. 이러한 구성요소를 통해 관리자 클러스터는 해당 버전의 사용자 클러스터를 관리할 수 있습니다.

5. 사용자 클러스터를 만드는 데 사용한 main.tf 파일에서 클러스터 리소스의 on_prem_version을 새 버전으로 변경합니다.

6. Ubuntu 및 COS 노드 풀만 해당: 사용자 클러스터의 컨트롤 플레인만 업그레이드하고 모든 노드 풀을 현재 버전으로 두려면 클러스터에 다음을 추가합니다.

   upgrade_policy {
     control_plane_only = true
   }
   

7. Terraform 계획을 초기화하고 만듭니다.

   terraform init
   

   Terraform은 Google Cloud 제공업체와 같은 필요한 라이브러리를 설치합니다.

8. 구성을 검토하고 필요한 경우 변경합니다.

   terraform plan
   

9. Terraform 계획을 적용하여 사용자 클러스터를 만듭니다.

   terraform apply
   

노드 풀 업그레이드

사용자 클러스터의 컨트롤 플레인만 업그레이드하도록 선택한 경우 다음 단계를 수행하여 사용자 클러스터의 컨트롤 플레인이 업그레이드된 후 추가 노드 풀을 업그레이드합니다.

1. 업그레이드하려는 각 노드 풀에서 리소스의 main.tf에 다음을 추가합니다.

   on_prem_version = "VERSION"
   

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

   resource "google_gkeonprem_vmware_node_pool" "nodepool-basic" {
   name = "my-nodepool"
   location = "us-west1"
   vmware_cluster = google_gkeonprem_vmware_cluster.default-basic.name
   config {
     replicas = 3
     image_type = "ubuntu_containerd"
     enable_load_balancer = true
   }
   on_prem_version = "1.16.0-gke.0"
   }
   

2. Terraform 계획을 초기화하고 만듭니다.

   terraform init
   

3. 구성을 검토하고 필요한 경우 변경합니다.

   terraform plan
   

4. Terraform 계획을 적용하여 사용자 클러스터를 만듭니다.

   terraform apply
   

비동기 업그레이드

1. 관리자 워크스테이션에서 비동기 업그레이드를 시작합니다.

   gkectl upgrade admin \
     --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
     --config ADMIN_CLUSTER_CONFIG_FILE \
     --async
   

   다음을 바꿉니다.

   • ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터의 kubeconfig 파일 경로

   • ADMIN_CLUSTER_CONFIG_FILE: 관리자 클러스터 구성 파일 경로.

   앞의 명령어가 완료되고 업그레이드가 진행되는 동안 관리자 워크스테이션을 계속 사용할 수 있습니다.

   gkectl upgrade admin을 사용하여 다음 명령어를 실행합니다.

   gkectl upgrade admin -h
   

2. 업그레이드 상태를 확인하려면 다음을 실행하세요.

   gkectl list admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   출력에 클러스터 STATE 값이 표시됩니다. 클러스터가 업그레이드 중인 경우 STATE 값은 UPGRADING입니다. 예를 들면 다음과 같습니다.

   NAME              STATE         AGE    VERSION
   gke-admin-test    UPGRADING     9h     1.30.100-gke.96
   

   STATE에 대해 가능한 값은 RUNNING, UPGRADING, RECONCILING ,ERROR, UNKNOWN입니다.

3. 업그레이드 진행 상태 및 클러스터 이벤트에 대한 세부정보를 확인하려면 다음을 실행합니다.

   gkectl describe admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   출력에는 클러스터 상태, 조건, 이벤트가 포함된 지정된 관리자 클러스터의 OnPremAdminCluster 커스텀 리소스가 표시됩니다.

   Google에서는 각 주요 업그레이드 단계의 시작과 종료에 대한 이벤트를 기록합니다.

   출력 예시:

   Events:
   Type    Reason                             Age   From                             Message
   ----       ------                                  ----     ----                                -------
   Normal  ControlPlaneUpgradeStarted         40m   onprem-admin-cluster-controller  Creating or updating admin cluster API Controller
   Normal  ControlPlaneMachineUpgradeStarted  40m   onprem-admin-cluster-controller  Creating or updating control plane machine
   Normal  StatusChanged                      40m   onprem-admin-cluster-controller  OnPremAdminCluster status changed:
   - New ClusterState condition: UPGRADING
   - New Ready condition: False, CreateOrUpdateControlPlaneMachine, Creating or updating control plane machine
   Normal   StatusChanged      2m                onprem-admin-cluster-controller  OnPremAdminCluster status changed:
   - New ClusterState condition: RUNNING
   - New Ready condition: True, ClusterRunning, Cluster is running
   

4. 업그레이드가 완료되면 gkectl list admin에 RUNNING인 STATUS가 표시됩니다.

   NAME              STATE         AGE    VERSION
   gke-admin-test    RUNNING       9h     1.30.100-gke.96
   

   또한 업그레이드가 완료되면 gkectl describe admin에 Status로 Last GKE On Prem Version 필드가 표시됩니다. 예를 들면 다음과 같습니다.

   Status:
     Cluster State:  RUNNING
     Last GKE On Prem Version:  1.30.0-gke.1
   

비동기 업그레이드 문제 해결

비동기 업그레이드의 경우 제한 시간은 클러스터의 노드 수를 기반으로 합니다. 업그레이드가 제한 시간보다 오래 걸리면 클러스터 상태가 UPGRADING에서 ERROR로 변경되고 업그레이드 작업이 시간 초과되었다는 이벤트가 표시됩니다. 여기서 ERROR 상태는 업그레이드가 예상보다 오래 걸리지만 종료되지 않았음을 의미합니다. 컨트롤러는 조정을 계속하고 작업을 계속 재시도합니다. 업그레이드가 차단되거나 업그레이드에 실패했을 때 gkectl diagnose를 실행하여 일반적인 클러스터 문제를 확인할 수 있습니다. 결과에 따라 수동으로 해결할지 아니면 Google Cloud 지원팀에 문의하여 추가 지원을 받을지 결정할 수 있습니다.

동기식 업그레이드

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

   gkectl upgrade admin \
     --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
     --config ADMIN_CLUSTER_CONFIG_FILE \
   

   다음을 바꿉니다.

   • ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로

   • ADMIN_CLUSTER_CONFIG_FILE: 관리자 클러스터 구성 파일 경로.

   gkectl upgrade 명령어는 실행 전 검사를 실행합니다. 실행 전 검사가 실패하면 명령어가 차단됩니다. 실패를 수정하거나 명령어와 함께 --skip-preflight-check-blocking 플래그를 사용하여 차단을 해제해야 합니다.

2. 버전 1.14.0 이상으로 업그레이드하는 경우 관리자 클러스터에 대해 기존 파일을 덮어쓰는 새 kubeconfig 파일이 생성됩니다. 파일에서 클러스터 세부정보를 보려면 다음 명령어를 실행합니다.

   kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG