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

이 문서에서는 VMware용 Google Distributed Cloud(소프트웨어 전용)에서 클러스터와 노드 풀을 업그레이드하는 방법을 설명합니다. 이 문서에서는 관리자 워크스테이션, 사용자 클러스터, 관리자 클러스터를 업그레이드하는 단계를 설명합니다. 사용자 클러스터의 경우 이 문서에서는 컨트롤 플레인과 노드 풀을 동시에 또는 별도로 업그레이드하는 단계를 설명합니다.

이 페이지는 기본 기술 인프라의 수명 주기를 관리하는 IT 관리자 및 운영자를 위해 작성되었습니다. Google Cloud 콘텐츠에서 참조하는 일반 역할과 예시 태스크에 대한 자세한 내용은 일반 GKE Enterprise 사용자 역할 및 태스크를 참조하세요.

진행하기 전에 다음 문서를 검토하는 것이 좋습니다.

업그레이드 개요
이 문서에서는 지원되는 버전 차이와 특히 버전 1.28 이상에서 변경된 업그레이드 버전 규칙에 대해 설명합니다.
업그레이드 권장사항
이 문서에서는 클러스터 업그레이드를 위한 체크리스트와 권장사항을 제공합니다.

방화벽 규칙 검토

버전 1.29 이상에서는 서버 측 프리플라이트 검사가 기본적으로 사용 설정됩니다. 서버 측 프리플라이트 검사에는 추가 방화벽 규칙이 필요합니다. 관리자 클러스터의 방화벽 규칙에서 '프리플라이트 검사'를 검색하고 필요한 모든 방화벽 규칙이 구성되었는지 확인합니다.

서버 측 프리플라이트 검사를 사용하면 gkectl을 사용하여 사용자 클러스터를 업그레이드할 때 프리플라이트 검사가 관리자 워크스테이션에서 로컬로 실행되는 대신 관리자 클러스터에서 실행됩니다. Google Cloud 콘솔, Google Cloud CLI, Terraform을 사용하여 클러스터를 업그레이드할 때 관리자 클러스터에서 서버 측 프리플라이트 검사가 실행됩니다.

관리자 클러스터를 업그레이드하면 Google Distributed Cloud는 Docker의 Kubernetes(종류) 클러스터를 배포하여 관리자 클러스터를 업그레이드하는 데 필요한 Kubernetes 컨트롤러를 일시적으로 호스팅합니다. 이러한 임시 클러스터를 부트스트랩 클러스터라고 합니다. 관리자 클러스터를 업그레이드할 때 서버 측 프리플라이트 검사가 부트스트랩 클러스터에서 실행됩니다.

Google API 및 IAM 요구사항

클러스터를 버전 1.28 이상으로 업그레이드하려면 kubernetesmetadata.googleapis.com을 사용 설정하고 로깅-모니터링 서비스 계정에 kubernetesmetadata.publisher IAM 역할을 부여해야 합니다. Cloud Monitoring을 사용하려면 이러한 변경사항이 필요합니다.

kubernetesmetadata.googleapis.com 사용 설정:
```
gcloud services enable --project PROJECT_ID  \
    kubernetesmetadata.googleapis.com
```
PROJECT_ID를 사용자 클러스터가 구성원인 Fleet 호스트 프로젝트의 ID로 바꿉니다. 이 프로젝트는 클러스터를 만들 때 지정된 프로젝트입니다. gkectl을 사용하여 클러스터를 만들었으면 클러스터 구성 파일에서 gkeConnect.projectID 필드의 프로젝트 ID입니다.
조직에서 Google API 및 기타 주소의 트래픽이 프록시 서버를 통과하도록 허용하는 허용 목록이 설정된 경우 허용 목록에 kubernetesmetadata.googleapis.com을 추가합니다.
로깅-모니터링 서비스 계정에 kubernetesmetadata.publisher 역할을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role "roles/kubernetesmetadata.publisher"
```
SERVICE_ACCOUNT_EMAIL을 로깅-모니터링 서비스 계정의 이메일 주소로 바꿉니다.

사용자 클러스터 업그레이드를 위한 IAM 요구사항

사용자 클러스터 업그레이드에 gkectl을 사용하려는 경우 이 섹션을 건너뜁니다.

Google Cloud 콘솔, Google Cloud CLI 또는 Terraform을 사용하여 사용자 클러스터를 업그레이드하려는 경우 프로젝트 소유자가 아니라면 클러스터가 생성된 Google Cloud 프로젝트에 대한 Identity and Access Management 역할 roles/gkeonprem.admin을 부여받아야 합니다. 이 역할에 포함된 권한에 대한 자세한 내용은 IAM 문서의 GKE On-Prem 역할을 참조하세요.

콘솔을 사용하여 클러스터를 업그레이드하려면 최소한 다음 역할도 있어야 합니다.

roles/container.viewer. 이 역할을 통해 사용자는 콘솔에서 GKE 클러스터 페이지와 기타 컨테이너 리소스를 볼 수 있습니다. 이 역할에 포함된 권한에 대한 자세한 내용이나 읽기/쓰기 권한이 있는 역할을 부여하려면 IAM 문서의 Kubernetes Engine 역할을 참조하세요.
roles/gkehub.viewer. 이 역할은 사용자가 콘솔에서 클러스터를 볼 수 있게 해줍니다. 이 역할에 포함된 권한에 대한 자세한 내용이나 읽기/쓰기 권한이 있는 역할을 부여하려면 IAM 문서의 GKE 허브 역할을 참조하세요.

업그레이드 전 또는 후에 구성 변경하기

클러스터의 구성을 변경해야 하는 경우 업그레이드 전이나 후에 클러스터 업데이트를 수행하세요. 업그레이드를 위한 클러스터 구성의 유일한 변경사항은 버전이어야 합니다. 클러스터 버전 및 유형에 따라 다른 구성 변경사항은 자동으로 무시되거나 업그레이드가 실패하게 됩니다. 자세한 내용은 업그레이드가 차단 해제되도록 지원되지 않는 변경사항 삭제를 참조하세요.

관리자 워크스테이션 업그레이드

gkectl을 사용하여 사용자 클러스터를 업그레이드하려면 관리자 워크스테이션을 업그레이드해야 합니다.

콘솔, gcloud CLI 또는 Terraform을 사용해 사용자 클러스터를 업그레이드하려는 경우 지금은 관리자 워크스테이션 업그레이드를 건너뛸 수 있습니다. 하지만 gkectl만 관리자 클러스터 업그레이드를 지원하므로 관리자 클러스터를 업그레이드할 준비가 되면 관리자 워크스테이션을 업그레이드해야 합니다.

관리자 워크스테이션을 업그레이드하는 방법은 만든 방법에 따라 다릅니다(gkeadm 또는 user-managed).

gkeadm

필수 파일 찾기

관리자 워크스테이션을 만들기 전에 gkeadm create config에서 생성한 관리자 워크스테이션 구성 파일을 채웠습니다. 이 파일의 기본 이름은 admin-ws-config.yaml입니다.

또한 워크스테이션에는 정보 파일이 있습니다. 이 파일의 기본 이름은 관리자 워크스테이션의 이름과 동일합니다.

관리자 워크스테이션 구성 파일과 정보 파일을 찾습니다. 업그레이드 단계를 수행하는 데 필요합니다. 이러한 파일이 현재 디렉터리에 있고 이름이 모두 기본값이면 업그레이드 명령어를 실행할 때 이를 지정할 필요가 없습니다. 그러나 이러한 파일이 다른 디렉터리에 있거나 파일 이름이 변경된 경우에는 --config 및 --info-file 플래그를 사용하여 이를 지정해야 합니다.

출력 정보 파일이 없으면 다시 만들 수 있습니다. 누락된 경우 정보 파일 다시 만들기를 참조하세요.

업그레이드

관리자 워크스테이션을 업그레이드하려면 다음 안내를 따르세요.

gkeadm 다운로드:
```
gkeadm upgrade gkeadm --target-version TARGET_VERSION
```
TARGET_VERSION을 업그레이드 대상 버전으로 바꿉니다. X.Y.Z-gke.N. 형식으로 완전한 버전 번호를 지정해야 합니다. Google Distributed Cloud 버전 목록은 버전 관리를 참조하세요.
관리자 워크스테이션 업그레이드:
```
gkeadm upgrade admin-workstation --config AW_CONFIG_FILE \
    --info-file INFO_FILE
```
다음을 바꿉니다.
- AW_CONFIG_FILE는 관리자 워크스테이션 구성 파일의 경로입니다. 파일이 현재 디렉터리에 있고 이름이 admin-ws-config.yaml이면 이 플래그를 생략할 수 있습니다.
- INFO_FILE은 정보 파일의 경로입니다. 파일이 현재 디렉터리에 있으면 이 플래그를 생략할 수 있습니다. 이 파일의 기본 이름은 관리자 워크스테이션의 이름과 동일합니다.

사용자 관리

관리자 워크스테이션에서 gkectl의 새 버전을 설치할 디렉터리로 이동합니다.

gkectl 다운로드:

gcloud storage cp gs://gke-on-prem-release/gkectl/VERSION/gkectl ./
chmod +x gkectl

VERSION을 업그레이드 대상 버전으로 바꿉니다. 예를 들면 1.30.100-gke.96입니다.

Google Distributed Cloud 번들을 다운로드합니다. 버전이 gkectl을 다운로드하는 데 사용한 버전과 일치하는지 확인합니다.

gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/VERSION/gke-onprem-vsphere-VERSION.tgz ./

클러스터 업그레이드에 사용 가능한 버전 확인

다음 명령어를 실행하여 업그레이드할 수 있는 버전을 확인합니다.

gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG

출력에 현재 버전과 업그레이드에 사용할 수 있는 버전이 표시됩니다.

업그레이드에 콘솔, gcloud CLI 또는 Terraform을 사용하는 경우 모든 Google Cloud 리전의 GKE On-Prem API에서 버전을 사용할 수 있기까지 버전 출시 후 약 7~10일이 걸립니다. 콘솔에는 사용자 클러스터 업그레이드에 사용할 수 있는 버전만 나열됩니다. gcloud CLI 또는 Terraform을 사용하여 사용자 클러스터를 업그레이드하는 단계에는 업그레이드에 사용할 수 있는 버전을 가져오기 위해 gcloud container vmware clusters query-version-config를 실행하는 단계가 포함되어 있습니다.

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

gkectl, 콘솔, gcloud CLI 또는 Terraform을 사용하여 사용자 클러스터를 업그레이드할 수 있습니다. 사용할 도구를 결정하는 방법에 대한 자세한 내용은 사용자 클러스터를 업그레이드할 도구 선택을 참조하세요.

gkectl

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

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

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

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

클러스터에 Windows 노드 풀이 있으면 gkectl prepare windows를 실행하고 노드 풀의 osImage 필드를 업데이트합니다. 자세한 안내는 Windows 노드 풀이 있는 사용자 클러스터 업그레이드를 참조하세요.
사용자 클러스터 구성 파일에서 gkeOnPremVersion을 업그레이드 대상 버전으로 설정합니다.
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 명령어에서 업그레이드가 진행되는 동안 관리자 워크스테이션에 상태 메시지를 출력합니다.

비동기 업그레이드

1.16 이상 버전으로 업그레이드하는 경우 이 단계를 건너뜁니다.

사용자 클러스터에 준비된 사용자 인증 정보 및 비공개 레지스트리를 사용하는 경우 사용자 클러스터를 업그레이드하기 전에 비공개 레지스트리 사용자 인증 정보가 준비되었는지 확인합니다. 비공개 레지스트리 사용자 인증 정보를 준비하는 방법에 대한 자세한 내용은 사용자 클러스터에 대해 준비된 사용자 인증 정보 구성을 참조하세요.
관리자 워크스테이션에서 비동기 업그레이드를 시작합니다.
```
gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG \
  --async
```
앞의 명령어가 완료되고 업그레이드가 진행되는 동안 관리자 워크스테이션을 계속 사용할 수 있습니다.
업그레이드 상태를 확인하려면 다음을 실행하세요.
```
gkectl list clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
출력에 클러스터 STATE 값이 표시됩니다. 클러스터가 업그레이드 중인 경우 STATE 값은 UPGRADING입니다. 예를 들면 다음과 같습니다.
```
NAMESPACE             NAME    READY   STATE       AGE   VERSION
my-uc-gkeonprem-mgmt  my-uc   False   UPGRADING   9h    1.30.0-gke.1
```
STATE에 대해 가능한 값은 PROVISIONING, UPGRADING, DELETING ,UPDATING, RUNNING, RECONCILING, ERROR, UNKNOWN입니다.

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

gkectl describe clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --cluster USER_CLUSTER_NAME -v 5

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

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

ControlPlaneUpgrade
MasterNodeUpgrade
AddonsUpgrade
NodePoolsUpgrade

출력 예시:

Events:
Type    Reason                      Age    From                            Message
----     ------                     ----   ----                            -------
Normal  NodePoolsUpgradeStarted     22m    onprem-user-cluster-controller  Creating or updating node pools: pool-2: Creating or updating node pool
Normal  AddonsUpgradeStarted        22m    onprem-user-cluster-controller  Creating or updating addon workloads
Normal  ControlPlaneUpgradeStarted  25m    onprem-user-cluster-controller  Creating or updating cluster control plane workloads: deploying user-kube-apiserver-base, ...: 14/15 pods are ready
Normal  ControlPlaneUpgradeFinished 23m    onprem-user-cluster-controller  Control plane is running

업그레이드가 완료되면 gkectl list clusters에 RUNNING인 STATUS가 표시됩니다.
```
NAMESPACE             NAME    READY   STATE     AGE     VERSION
my-uc-gkeonprem-mgmt  my-uc   True    RUNNING   9h      1.30.0-gke.1
```
또한 업그레이드가 완료되면 gkectl describe clusters에 Status로 Last GKE On Prem Version 필드가 표시됩니다. 예를 들면 다음과 같습니다.
```
Status:
Cluster State:  RUNNING
Last GKE On Prem Version:  1.30.0-gke.1
```

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

일반적으로 시간 초과는 PodDisruptionBudget(PDB)으로 인한 교착 상태의 결과입니다. 이 경우 포드를 이전 노드에서 제거할 수 없고 이전 노드는 드레이닝할 수 없습니다. 포드 제거가 10분 이상 걸릴 경우 OnPremUserCluster 객체에 이벤트를 기록합니다. gkectl describe clusters를 실행하여 이벤트를 캡처할 수 있습니다. 그런 다음 PDB를 조정하여 노드가 드레이닝되도록 할 수 있습니다. 그러면 업그레이드가 진행되고 완료됩니다.

예시 이벤트:

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

또한 업그레이드가 차단되거나 업그레이드에 실패했을 때 gkectl diagnose를 실행하여 일반적인 클러스터 문제를 확인할 수 있습니다. 결과에 따라 수동으로 해결할지 아니면 Anthos 지원팀에 문의하여 추가 지원을 받을지 결정할 수 있습니다.

동기식 업그레이드

gkectl upgrade 명령어는 실행 전 검사를 실행합니다. 실행 전 검사가 실패하면 명령어가 차단됩니다. 실패를 바로잡거나 --skip-preflight-check-blocking 플래그를 사용해야 합니다. 심각한 실패가 없다고 확신하는 경우에만 실행 전 검사를 건너뛰어야 합니다.

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

1.16 이상 버전으로 업그레이드하는 경우 이 단계를 건너뜁니다.

사용자 클러스터에 준비된 사용자 인증 정보 및 비공개 레지스트리를 사용하는 경우 사용자 클러스터를 업그레이드하기 전에 비공개 레지스트리 사용자 인증 정보가 준비되었는지 확인합니다. 비공개 레지스트리 사용자 인증 정보를 준비하는 방법에 대한 자세한 내용은 사용자 클러스터에 대해 준비된 사용자 인증 정보 구성을 참조하세요.

클러스터를 업그레이드합니다.

gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG_FILE

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

추가 노드 풀 업그레이드

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

사용자 클러스터 구성 파일을 수정합니다. 다음 예시에 표시된 것처럼 업그레이드하려는 각 노드 풀에 대해 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

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

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

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

GKE 클러스터로 이동
Google Cloud 프로젝트를 선택한 후 업그레이드하려는 클러스터를 선택합니다.
세부정보 패널에서 추가 세부정보를 클릭합니다.
클러스터 기본사항 섹션에서 업그레이드를 클릭합니다.
대상 버전 선택 목록에서 업그레이드하려는 버전을 선택합니다. 선별된 목록에는 최신 패치 릴리스만 포함됩니다.
업그레이드를 클릭합니다.

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

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

gcloud CLI

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

아직 등록되지 않았으면 GKE On-Prem API에 관리자 클러스터를 등록합니다.
구성요소 번들을 관리자 클러스터에 다운로드하고 배포합니다. 구성요소의 버전이 업그레이드에서 지정한 버전과 일치합니다. 이러한 구성요소를 통해 관리자 클러스터는 해당 버전의 사용자 클러스터를 관리할 수 있습니다.

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

Google Cloud CLI 구성요소를 업데이트합니다.
```
gcloud components update
```
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에 클러스터를 등록할 때 지정한 리전입니다.

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

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 명령어에 지정한 버전과 일치하는 구성요소 번들을 다운로드하고 배포합니다.

클러스터를 업그레이드합니다. 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
```

노드 풀 업그레이드

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

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

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

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

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

Terraform

Google Cloud CLI 구성요소를 업데이트합니다.
```
gcloud components update
```
아직 수행하지 않았으면 GKE On-Prem API에 관리자 클러스터를 등록합니다.. GKE On-Prem API에 클러스터를 등록한 다음에는 이 단계를 다시 수행할 필요가 없습니다.

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

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

새 버전의 구성요소를 다운로드하고 관리자 클러스터에 배포합니다.
```
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --required-platform-version=VERSION
```
이 명령어는 --required-platform-version에 지정하는 구성요소 버전을 관리자 클러스터에 다운로드한 후 구성요소를 배포합니다. 이러한 구성요소를 통해 관리자 클러스터는 해당 버전의 사용자 클러스터를 관리할 수 있습니다.
사용자 클러스터를 만드는 데 사용한 main.tf 파일에서 클러스터 리소스의 on_prem_version을 새 버전으로 변경합니다.
Ubuntu 및 COS 노드 풀만 해당: 사용자 클러스터의 컨트롤 플레인만 업그레이드하고 모든 노드 풀을 현재 버전으로 두려면 클러스터에 다음을 추가합니다.
```
upgrade_policy {
  control_plane_only = true
}
```
Terraform 계획을 초기화하고 만듭니다.
```
terraform init
```
Terraform은 Google Cloud 제공업체와 같은 필요한 라이브러리를 설치합니다.
구성을 검토하고 필요한 경우 변경합니다.
```
terraform plan
```
Terraform 계획을 적용하여 사용자 클러스터를 만듭니다.
```
terraform apply
```

노드 풀 업그레이드

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

업그레이드하려는 각 노드 풀에서 리소스의 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"
}

Terraform 계획을 초기화하고 만듭니다.
```
terraform init
```
구성을 검토하고 필요한 경우 변경합니다.
```
terraform plan
```
Terraform 계획을 적용하여 사용자 클러스터를 만듭니다.
```
terraform apply
```

관리자 클러스터 업그레이드

사용자 클러스터를 업그레이드한 후 관리자 클러스터를 업그레이드할 수 있습니다.

시작하기 전에 다음 사항을 확인하세요.

버전 1.13 이상으로 업그레이드하는 경우 먼저 관리자 클러스터 구성 파일의 gkeConnect 섹션을 작성하여 관리자 클러스터를 등록해야 합니다. 구성 파일 변경사항을 사용하여 gkectl 클러스터 업데이트 명령어를 실행합니다.
gkectl 및 클러스터가 업그레이드에 적합한 버전 수준인지 확인하고 적합한 번들을 다운로드했는지 확인합니다. 관리자 클러스터와 사용자 클러스터 사이의 버전 편향은 Google Distributed Cloud 버전에 따라 다릅니다. 관리자 클러스터를 업그레이드할 수 있는지 확인하려면 관리자 및 사용자 클러스터 버전 차이를 참조하세요.
관리자 클러스터 구성 파일의 bundlepath 필드가 업그레이드할 번들의 경로와 일치하는지 확인합니다.

관리자 클러스터 구성 파일의 필드에 다른 변경사항을 적용하는 경우 이러한 변경사항은 업그레이드 중에 무시됩니다. 이러한 변경사항을 적용하려면 먼저 클러스터를 업그레이드한 다음 구성 파일 변경사항과 함께 클러스터 업데이트 명령어를 실행하여 클러스터에 변경사항을 적용해야 합니다.

`gkectl upgrade admin` 실행

관리자 워크스테이션에서 이 섹션의 단계를 수행합니다. gkectl upgrade admin 명령어에는 두 가지 변형이 있습니다.

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

비동기 업그레이드 요구사항:
- 버전 1.29 이상의 HA 관리자 클러스터에서만 지원됩니다.
- 모든 사용자 클러스터에는 Controlplane V2가 사용 설정되어 있어야 합니다.
동기:
동기 변형을 사용하면 gkectl upgrade admin 명령어에서 업그레이드가 진행되는 동안 관리자 워크스테이션에 상태 메시지를 출력합니다.

비동기 업그레이드

관리자 워크스테이션에서 비동기 업그레이드를 시작합니다.
```
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
```
업그레이드 상태를 확인하려면 다음을 실행하세요.
```
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입니다.

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

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

업그레이드가 완료되면 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 지원팀에 문의하여 추가 지원을 받을지 결정할 수 있습니다.

동기식 업그레이드

다음 명령어를 실행합니다.
```
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 플래그를 사용하여 차단을 해제해야 합니다.
버전 1.14.0 이상으로 업그레이드하는 경우 관리자 클러스터에 대해 기존 파일을 덮어쓰는 새 kubeconfig 파일이 생성됩니다. 파일에서 클러스터 세부정보를 보려면 다음 명령어를 실행합니다.
```
kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```

전체 번들 삭제

전체 번들을 다운로드하고 gkectl prepare 및 gkectl upgrade admin 명령어를 성공적으로 실행한 경우 관리자 워크스테이션의 디스크 공간을 절약하기 위해 전체 번들을 삭제해야 합니다. 다음 명령어를 실행하여 전체 번들을 삭제합니다.

rm /var/lib/gke/bundles/gke-onprem-vsphere-${TARGET_VERSION}-full.tgz

관리자 클러스터 업그레이드 재개

관리자 클러스터 업그레이드가 중단되거나 실패하는 경우 관리자 클러스터 체크포인트에 중단 전 상태를 복원하는 데 필요한 상태가 포함되어 있으면 업그레이드를 재개할 수 있습니다.

경고: 업그레이드 시도 실패 후 gkectl repair admin-master로 관리 마스터를 복구하지 마세요. 이로 인해 관리자 클러스터가 좋지 않은 상태가 됩니다.

다음 단계를 따르세요.

초기 업그레이드 시도를 시작하기 전에 관리자 컨트롤 플레인이 정상인지 확인합니다. 클러스터 문제 진단을 참조하세요. 이 주제의 설명대로 관리자 클러스터에 gkectl diagnose cluster 명령어를 실행합니다.
초기 업그레이드 시도 전에 관리자 컨트롤 플레인이 비정상인 경우 gkectl repair admin-master 명령어로 관리자 컨트롤 플레인을 복구합니다.
업그레이드가 중단되거나 실패한 후 업그레이드 명령어를 다시 실행하는 경우 이전 업그레이드 시도와 동일한 번들 및 대상 버전을 사용하세요.

업그레이드 명령어를 다시 실행하면 재개된 업그레이드가 체크포인트에서 관리자 클러스터 상태를 다시 만들고 전체 업그레이드를 다시 실행합니다. 1.12.0부터 관리자 컨트롤 플레인이 비정상이면 업그레이드 프로세스가 업그레이드 진행 전 소스 버전에서 관리자 클러스터를 복원하려고 시도하지 않고 대상 버전으로 직접 업그레이드합니다.

관리자 클러스터 체크포인트가 사용 가능한 경우 업그레이드가 실패하거나 종료된 시점부터 업그레이드가 다시 시작됩니다. 체크포인트를 사용할 수 없는 경우 업그레이드는 관리자 컨트롤 플레인에 의존합니다. 따라서 업그레이드를 진행하려면 관리자 컨트롤 플레인이 정상 상태여야 합니다. 업그레이드가 성공하면 체크포인트가 다시 생성됩니다.

관리자 클러스터 업그레이드 중에 gkectl가 예기치 않게 종료되면 종류 클러스터가 삭제되지 않습니다. 업그레이드를 재개하기 위해 업그레이드 명령어를 다시 실행하기 전에 종류 클러스터를 삭제합니다.

docker stop gkectl-control-plane && docker rm gkectl-control-plane

종류 클러스터를 삭제한 후 업그레이드 명령어를 다시 실행합니다.

업그레이드 후 관리자 워크스테이션 롤백

관리자 워크스테이션을 업그레이드 전에 사용된 버전으로 롤백할 수 있습니다.

업그레이드하는 동안 gkeadm은 출력 정보 파일에 업그레이드되기 전 버전을 기록합니다. 롤백하는 동안 gkeadm은 나열된 버전을 사용하여 이전 파일을 다운로드합니다.

관리자 워크스테이션을 이전 버전으로 롤백하려면 다음 안내를 따르세요.

gkeadm rollback admin-workstation --config=AW_CONFIG_FILE

관리자 워크스테이션 구성 파일이 기본 admin-ws-config.yaml인 경우 --config=AW_CONFIG_FILE을 생략할 수 있습니다. 그렇지 않으면 AW_CONFIG_FILE을 관리자 워크스테이션 구성 파일의 경로로 바꿉니다.

롤백 명령어는 다음 단계를 수행합니다.

gkeadm의 롤백 버전을 다운로드합니다.
현재 관리자 워크스테이션의 홈 디렉터리를 백업합니다.
gkeadm의 롤백 버전을 사용하여 새 관리자 워크스테이션을 만듭니다.
기존 관리자 워크스테이션을 삭제합니다.

업그레이드를 위해 번들을 다른 버전으로 설치

워크스테이션을 업그레이드하면 해당 버전의 번들이 설치되어 클러스터를 업그레이드할 수 있습니다. 다른 버전을 원하는 경우 다음 단계를 수행하여 업그레이드하려는 버전인 TARGET_VERSION 번들을 설치합니다.

현재 gkectl 및 클러스터 버전을 확인하려면 다음 명령어를 실행합니다. 자세한 내용을 보려면 --details/-d 플래그를 사용합니다.
```
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
```
출력에서 클러스터 버전에 대한 정보를 제공합니다.
출력에 따라 다음 문제를 확인하고 필요에 따라 이를 수정합니다.
- 현재 관리자 클러스터 버전이 TARGET_VERSION보다 낮은 부 버전 두 개 이상이면 모든 클러스터를 TARGET_VERSION보다 낮은 부 버전 하나로 업그레이드합니다.
- gkectl 버전이 1.11보다 낮고 1.12.x로 업그레이드하려면 업그레이드를 여러 번 수행해야 합니다. 1.11.x에 도달할 때까지 한 번에 부 버전 하나를 업그레이드한 후 이 주제의 안내를 따라 진행합니다.
- gkectl 버전이 TARGET_VERSION보다 낮은 경우 TARGET_VERSION으로 관리자 워크스테이션을 업그레이드합니다.
gkectl 및 클러스터 버전이 업그레이드에 적합한 것으로 확인되었으면 번들을 다운로드합니다.

번들 tarball이 관리자 워크스테이션에 이미 있는지 확인합니다.
```
stat /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz
```
관리자 워크스테이션에 번들이 없으면 이를 다운로드합니다.
```
gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz /var/lib/gke/bundles/
```
번들을 설치합니다.
```
gkectl prepare --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
ADMIN_CLUSTER_KUBECONFIG를 kubeconfig 파일의 경로로 바꿉니다. 파일이 현재 디렉터리에 있고 이름이 kubeconfig이면 이 플래그를 생략할 수 있습니다.

참고: 기본적으로 전체 번들이 아닌 일반 번들이 다운로드됩니다. 전체 번들에는 모든 컨테이너 및 VM 이미지가 포함되고, 일반 번들은 설치 중 Google Cloud Platform의 컨테이너 및 VM 이미지를 관리자 워크스테이션으로 다운로드합니다. 대신 전체 번들을 사용하려면 설치 명령어의 번들 경로는 gke-onprem-vsphere-TARGET_VERSION-full.tgz입니다.
사용 가능한 클러스터 버전을 나열하고 대상 버전이 사용 가능한 사용자 클러스터 버전에 포함되었는지 확인합니다.
```
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
```

이제 대상 버전으로 사용자 클러스터를 만들거나 사용자 클러스터를 대상 버전으로 업그레이드할 수 있습니다.

업그레이드 프로세스 문제 해결

권장 업그레이드 프로세스를 따를 때 문제가 발생하면 이러한 권장사항에 따라 문제를 해결합니다. 이러한 제안사항에서는 버전 1.11.x 설정으로 시작했고 권장 업그레이드 프로세스를 진행한다고 가정합니다.

참조: 클러스터 생성 및 업그레이드 문제 해결

사용자 클러스터 업그레이드 문제 해결

사용자 클러스터를 업그레이드할 때 업그레이드 버전에 문제가 있다고 가정해 보겠습니다. Google 지원을 통해 예정된 패치 출시 버전에서 문제가 해결될 것을 확인합니다. 이 경우 다음을 수행하면 됩니다.

프로덕션에 현재 버전을 계속 사용합니다.
패치 버전이 출시될 때 비프로덕션 클러스터에서 패치 출시 버전을 테스트합니다.
확신이 들면 모든 프로덕션 사용자 클러스터를 패치 출시 버전으로 업그레이드합니다.
관리자 클러스터를 패치 출시 버전으로 업그레이드합니다.

관리자 클러스터 업그레이드 문제 해결

관리자 클러스터를 업그레이드할 때 문제가 발생하면 Google 지원에 연락하여 관리자 클러스터 문제를 해결해야 합니다.

그러는 동안 새 업그레이드 흐름에서 관리자 클러스터 업그레이드로 방해되지 않고 새 사용자 클러스터 기능을 계속 활용할 수 있습니다. 따라서 원하는 경우 관리자 클러스터의 업그레이드 빈도를 줄일 수 있습니다. 업그레이드 프로세스는 다음과 같이 진행될 수 있습니다.

프로덕션 사용자 클러스터를 1.12.x로 업그레이드합니다.
관리자 클러스터를 이전 버전으로 유지하고 보안 패치를 계속 수신합니다.
테스트 환경에서 관리자 클러스터 1.11.x에서 1.12.x로 업그레이드를 테스트하고 문제가 있으면 문제를 보고합니다.
1.12.x 패치 출시 버전으로 문제가 해결되면 원하는 경우 프로덕션 관리자 클러스터를 이 패치 출시 버전으로 업그레이드할 수 있습니다.

부록

버전 1.1.0-gke.6에서 사용 설정된 VMware DRS 규칙 정보

버전 1.1.0-gke.6부터 Google Distributed Cloud는 사용자 클러스터 노드에 대해 VMware Distributed Resource Scheduler(DRS) 안티-어피니티 규칙을 자동으로 만들어 데이터 센터에 있는 최소 3개 이상의 물리적 호스트에 분산되도록 합니다. 버전 1.1.0-gke.6부터 이 기능은 새 클러스터와 기존 클러스터에서 자동으로 사용 설정됩니다.

업그레이드하기 전에 vSphere 환경은 다음 조건을 충족해야 합니다.

VMware DRS가 사용 설정되어 있습니다. VMware DRS에는 vSphere Enterprise Plus 라이선스 버전이 필요합니다. DRS를 사용 설정하는 방법은 클러스터에서 VMware DRS 사용 설정을 참조하세요.
사용자 인증 정보 구성 파일에 제공된 vSphere 사용자 이름에는 Host.Inventory.EditCluster 권한이 있습니다.
사용 가능한 물리적 호스트가 3개 이상입니다.

vSphere 환경이 위의 조건을 충족하지 않는 경우에도 업그레이드할 수 있지만 사용자 클러스터를 1.3.x에서 1.4.x로 업그레이드하려면 안티어피니티 그룹을 사용 중지해야 합니다. 자세한 내용은 Google Distributed Cloud 출시 노트의 알려진 문제를 참조하세요.

업그레이드 중 다운타임 정보

리소스	설명
관리자 클러스터	관리자 클러스터가 다운되면 다운타임 원인이 되는 오류의 영향을 받지 않는 한 사용자 클러스터의 컨트롤 플레인과 워크로드는 사용자 클러스터에서 계속 실행됩니다.
사용자 클러스터 컨트롤 플레인	일반적으로 사용자 클러스터 컨트롤 플레인에는 뚜렷한 다운타임이 없어야 합니다. 하지만 Kubernetes API 서버로의 장기 실행 연결이 끊어져 다시 설정해야 할 수 있습니다. 이 경우 API 호출자는 연결을 설정할 때까지 다시 시도해야 합니다. 최악의 경우에는 업그레이드 중에 다운타임이 최대 1분간 발생할 수 있습니다. 참고: 사용자 클러스터 노드가 업그레이드 중에 사용자 컨트롤 플레인에 도달할 수 없으면 새 워크로드는 클러스터에 예약되지 않습니다. 기존 워크로드는 영향을 받지 않습니다.
사용자 클러스터 노드	업그레이드 시 사용자 클러스터 노드를 변경해야 하는 경우 Google Distributed Cloud는 노드를 롤링 방식으로 다시 만들고 이 노드에서 실행 중인 순차적으로 다시 예약합니다. 적절한 PodDisruptionBudgets과 안티어피니티 규칙을 설정하여 워크로드에 대한 영향을 방지할 수 있습니다.

누락된 경우 정보 파일 다시 만들기

관리자 워크스테이션의 출력 정보 파일이 누락된 경우 이 파일을 다시 만들어야 업그레이드를 진행할 수 있습니다. 이 파일은 워크스테이션을 처음 만들 때 생성되었고 업그레이드를 완료한 후에 새 정보로 업데이트되었습니다.

출력 정보 파일 형식은 다음과 같습니다.

Admin workstation version: GKEADM_VERSION
Created using gkeadm version: GKEADM_VERSION
VM name: ADMIN_WS_NAME
IP: ADMIN_WS_IP
SSH key used: FULL_PATH_TO_ADMIN_WS_SSH_KEY
To access your admin workstation:
ssh -i FULL-PATH-TO-ADMIN-WS-SSH-KEY ubuntu@ADMIN-WS-IP

다음은 샘플 출력 정보 파일입니다.

Admin workstation version: v1.10.3-gke.49
Created using gkeadm version: v1.10.3-gke.49
VM name: admin-ws-janedoe
IP: 172.16.91.21
SSH key used: /usr/local/google/home/janedoe/.ssh/gke-admin-workstation
Upgraded from (rollback version): v1.10.0-gke.194
To access your admin workstation:
ssh -i /usr/local/google/home/janedoe/.ssh/gke-admin-workstation ubuntu@172.16.91.21

편집기에서 파일을 만들고 적절한 매개변수를 대체합니다. gkeadm이 실행되는 디렉터리에서 VM 이름과 동일한 파일 이름으로 파일을 저장합니다. 예를 들어 VM 이름이 admin-ws-janedoe인 경우 파일을 admin-ws-janedoe로 저장합니다.

다음 단계

gcloud CLI 참고 문서
Terraform 참고 문서
- google_gkeonprem_vmware_cluster
- google_gkeonprem_vmware_node_pool

클러스터 또는 노드 풀 업그레이드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

방화벽 규칙 검토

Google API 및 IAM 요구사항

사용자 클러스터 업그레이드를 위한 IAM 요구사항

업그레이드 전 또는 후에 구성 변경하기

관리자 워크스테이션 업그레이드

gkeadm

필수 파일 찾기

업그레이드

사용자 관리

클러스터 업그레이드에 사용 가능한 버전 확인

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

gkectl

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

프리플라이트 검사 실행

gkectl upgrade cluster 실행

비동기 업그레이드

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

동기식 업그레이드

추가 노드 풀 업그레이드

업그레이드 재개

콘솔

gcloud CLI

노드 풀 업그레이드

Terraform

노드 풀 업그레이드

관리자 클러스터 업그레이드

시작하기 전에 다음 사항을 확인하세요.

gkectl upgrade admin 실행

비동기 업그레이드

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

동기식 업그레이드

전체 번들 삭제

관리자 클러스터 업그레이드 재개

업그레이드 후 관리자 워크스테이션 롤백

업그레이드를 위해 번들을 다른 버전으로 설치

업그레이드 프로세스 문제 해결

사용자 클러스터 업그레이드 문제 해결

관리자 클러스터 업그레이드 문제 해결

최신 버전의 알려진 문제

데이터 디스크가 거의 가득 찬 경우 관리 워크스테이션 업그레이드가 실패할 수 있음

PodDisruptionBudget으로 워크로드 중단

노드가 업그레이드 절차를 완료하지 못함

부록

버전 1.1.0-gke.6에서 사용 설정된 VMware DRS 규칙 정보

업그레이드 중 다운타임 정보

누락된 경우 정보 파일 다시 만들기

다음 단계

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

`gkectl upgrade cluster` 실행

`gkectl upgrade admin` 실행