클러스터를 고급 클러스터로 업데이트 또는 업그레이드

이 문서에서는 버전 1.32에서 클러스터를 고급 클러스터로 업데이트하거나 업그레이드하는 방법을 보여줍니다.

중요: 고급이 아닌 클러스터는 1.33에서 고급 클러스터로 자동 업그레이드됩니다.

기본 요건

• gkectl 버전은 대상 클러스터 버전과 동일해야 합니다.

  • 필요한 경우 gkectl 다운로드를 참조하여 지원되는 gkectl 버전을 가져옵니다.

• 고급 클러스터로 업데이트하거나 업그레이드하기 전에 항상 클러스터를 진단하세요.

  • 관리자 및 사용자 클러스터에서 gkectl diagnose cluster를 실행하여 클러스터가 정상인지 확인합니다.
  • 명령어에서 오류나 경고를 보고하는 경우 고급 클러스터로 업데이트하거나 업그레이드하기 전에 이를 해결하세요.

• 클러스터에서 권장 기능만 사용해야 합니다.

• 업데이트 또는 업그레이드를 시작하기 전에 클러스터에서 고급 클러스터에서 지원하지 않는 기능을 사용하지 않는지 확인하세요. 지원되지 않는 기능이 활성화되어 있으면 먼저 업데이트를 사용하여 사용 중지합니다.

  • 고급 클러스터에는 가용성이 높은(HA) 사용자 클러스터가 필요하지만 이 가이드에 따라 HA 이외의 사용자 클러스터를 HA 고급 클러스터로 업데이트하거나 업그레이드할 수 있습니다.

• 사용자 클러스터를 업데이트하거나 업그레이드하기 전에 관리자 클러스터를 고급 클러스터로 업데이트하거나 업그레이드해야 합니다.

• cert-manager 설치 정보: 고급 클러스터에 cert-manager가 자동으로 설치됩니다. 고급이 아닌 클러스터에서 고급 클러스터로 이전하면 통합된 cert-manager가 고객이 설치한 cert-manager 버전을 자동으로 재정의합니다. 고급 클러스터로 업데이트하거나 업그레이드하기 전에 기존 cert-manager에 적용된 중요한 맞춤 구성이나 기능이 없는지 확인하세요. 자세한 내용은 고급 클러스터와 번들로 제공되는 cert-manager로 업그레이드를 참고하세요.

관리자 클러스터를 고급 클러스터로 업데이트 또는 업그레이드

주의: 관리자 클러스터 업데이트 또는 업그레이드가 실패하는 경우 워크스테이션에서 외부 부트스트랩 클러스터를 삭제하지 마세요. 부트스트랩 클러스터에는 업데이트 또는 업그레이드를 재개하는 데 필요한 모든 상태가 포함되어 있습니다. 실패 후 gkectl update admin 또는 gkectl upgrade admin를 다시 실행해야 하는 경우 --reuse-bootstrap-cluster (또는 -r) 플래그를 추가해야 합니다. 이 플래그를 사용하지 않으면 중요한 데이터가 손실되는 심각한 문제가 발생할 수 있습니다.

업데이트

중요: 클러스터 버전이 1.32.0 이상이어야 합니다.

1. 클러스터를 진단하여 정상인지 확인합니다.

   gkectl diagnose cluster \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   • 명령어에서 오류나 경고를 보고하면 클러스터 문제 진단을 참고하여 문제를 해결한 후 계속합니다.

2. 고급 클러스터를 준비합니다.

   gkectl prepare \
       --bundle-path BUNDLE_PATH \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --advanced-cluster
   

   다음을 바꿉니다.

   • BUNDLE_PATH: 번들 파일의 경로입니다. 이 파일은 /var/lib/gke/bundles/의 관리자 워크스테이션에 있습니다. 예를 들면 다음과 같습니다.

     /var/lib/gke/bundles/gke-onprem-vsphere-1.32.0-gke.1085-full.tgz
     

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

3. 관리자 클러스터 구성 파일에서 enableAdvancedCluster를 true로 설정합니다.

4. 관리자 클러스터를 고급 클러스터로 업데이트합니다.

   gkectl update admin \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --config ADMIN_CLUSTER_CONFIG
   

   다음을 바꿉니다.

   • ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로입니다.
   • ADMIN_CLUSTER_CONFIG: 관리자 클러스터 구성 파일의 경로입니다.

   이 명령어는 관리자 클러스터의 모든 노드를 다시 만듭니다.

업그레이드

주의: 클러스터에서 cos 또는 cos_cgv2를 컨트롤 플레인 OS 이미지 유형 또는 노드 풀 OS 이미지 유형으로 사용하는 경우 업그레이드하기 전에 클러스터 버전이 1.32.0 이상인지 확인하세요. 그렇지 않은 경우 클러스터 버전이 1.31.100 이상인지 확인하세요.

1. 필요한 경우 관리자 워크스테이션을 업그레이드합니다.

2. 클러스터를 진단하여 정상인지 확인합니다.

   gkectl diagnose cluster \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   • 명령어에서 오류나 경고를 보고하면 클러스터 문제 진단을 참고하여 문제를 해결한 후 계속합니다.

3. 고급 클러스터를 준비합니다.

   gkectl prepare \
       --bundle-path BUNDLE_PATH \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --advanced-cluster
   

   다음을 바꿉니다.

   • BUNDLE_PATH: 번들 파일의 경로입니다. 이 파일은 /var/lib/gke/bundles/의 관리자 워크스테이션에 있습니다. 예를 들면 다음과 같습니다.

     /var/lib/gke/bundles/gke-onprem-vsphere-1.32.0-gke.1085-full.tgz
     

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

4. 관리자 클러스터 구성 파일에서 enableAdvancedCluster를 true로 설정합니다.

5. 관리자 클러스터 구성 파일의 bundlepath 필드가 업그레이드할 번들의 경로와 일치하는지 확인합니다.

6. 관리자 클러스터를 고급 클러스터로 업그레이드합니다.

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

   다음을 바꿉니다.

   • ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로입니다.
   • ADMIN_CLUSTER_CONFIG: 관리자 클러스터 구성 파일의 경로입니다.

   이 명령어는 관리자 클러스터의 모든 노드 출시를 다시 만듭니다. 출시 다시 만들기 배포 전략을 사용하면 노드가 한 번에 하나씩 업그레이드됩니다. 노드 업그레이드 중에 VM이 삭제된 후 새 버전으로 다시 생성됩니다.

관리자 클러스터가 고급 클러스터로 업데이트되거나 업그레이드된 후에는 다음과 같습니다.

• 기존의 고급이 아닌 사용자 클러스터는 계속 정상적으로 작동합니다.

• 고급 관리자 클러스터에서 관리하는 고급 사용자 클러스터만 만들 수 있습니다.

일관되고 완전한 기능을 갖춘 환경을 유지하려면 모든 사용자 클러스터를 고급 클러스터로 업그레이드하는 것이 좋습니다.

사용자 클러스터를 고급 클러스터로 업데이트 또는 업그레이드

중요: 관리자 클러스터가 이미 고급 클러스터로 업데이트 또는 업그레이드되었는지 확인하세요.

업데이트

중요: 클러스터 버전이 1.32.0 이상이어야 합니다.

1. 클러스터를 진단하여 정상인지 확인합니다.

   gkectl diagnose cluster \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --cluster-name USER_CLUSTER_NAME
   

   • 명령어에서 오류나 경고를 보고하면 클러스터 문제 진단을 참고하여 문제를 해결한 후 계속합니다.

2. 사용자 클러스터 컨트롤 플레인이 고가용성(HA)이 아닌 경우:

   주의: masterNode.replicas 필드에 알려진 문제로 인해 버전 1.32 또는 버전 1.33 HA 이외의 사용자 클러스터를 HA 고급 클러스터로 업데이트하려면 클러스터가 각각 1.32.600 이상 또는 1.33.100 이상이어야 합니다.

   1. masterNode.replicas를 1 ~ 3으로 변경합니다.

   2. 사용자 클러스터 컨트롤 플레인 노드의 고정 IP 주소를 network.controlPlaneIPBlock.ips 섹션에 추가합니다.

3. 고급 클러스터를 준비합니다.

   gkectl prepare \
       --bundle-path BUNDLE_PATH \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --advanced-cluster
   

   다음을 바꿉니다.

   • BUNDLE_PATH: 번들 파일의 경로입니다. 이 파일은 /var/lib/gke/bundles/의 관리자 워크스테이션에 있습니다. 예를 들면 다음과 같습니다.

     /var/lib/gke/bundles/gke-onprem-vsphere-1.32.0-gke.1085-full.tgz
     

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

4. 사용자 클러스터 구성 파일에서 enableAdvancedCluster를 true로 설정합니다.

5. 사용자 클러스터를 고급 클러스터로 업데이트합니다.

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

   다음을 바꿉니다.

   • ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로입니다.
   • USER_CLUSTER_CONFIG: 사용자 클러스터 구성 파일의 경로입니다.

   이 명령어는 사용자 클러스터의 모든 노드 출시를 다시 만듭니다. 출시 다시 만들기 배포 전략을 사용하면 노드가 한 번에 하나씩 업데이트됩니다. 노드 업데이트 중에 VM이 삭제된 후 새 구성으로 다시 생성됩니다.

업그레이드

주의: 클러스터에서 cos 또는 cos_cgv2를 컨트롤 플레인 OS 이미지 유형 또는 노드 풀 OS 이미지 유형으로 사용하는 경우 업그레이드하기 전에 클러스터 버전이 1.32.0 이상인지 확인하세요. 그렇지 않은 경우 클러스터 버전이 1.31.100 이상인지 확인하세요.

1. 클러스터를 진단하여 정상인지 확인합니다.

   gkectl diagnose cluster \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --cluster-name USER_CLUSTER_NAME
   

   • 명령어에서 오류나 경고를 보고하면 클러스터 문제 진단을 참고하여 문제를 해결한 후 계속합니다.

2. 사용자 클러스터 컨트롤 플레인이 고가용성(HA)이 아닌 경우:

   1. masterNode.replicas를 1 ~ 3으로 변경합니다.

   2. 사용자 클러스터 컨트롤 플레인 노드의 고정 IP 주소를 network.controlPlaneIPBlock.ips 섹션에 추가합니다.

3. 고급 클러스터를 준비합니다.

   gkectl prepare \
       --bundle-path BUNDLE_PATH \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --advanced-cluster
   

   다음을 바꿉니다.

   • BUNDLE_PATH: 번들 파일의 경로입니다. 이 파일은 /var/lib/gke/bundles/의 관리자 워크스테이션에 있습니다. 예를 들면 다음과 같습니다.

     /var/lib/gke/bundles/gke-onprem-vsphere-1.32.0-gke.1085-full.tgz
     

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

4. 사용자 클러스터 구성 파일에서 enableAdvancedCluster를 true로 설정합니다.

5. 사용자 클러스터 구성 파일의 gkeOnPremVersion 필드가 업그레이드 대상 버전과 일치하는지 확인합니다.

6. 사용자 클러스터를 고급 클러스터로 업그레이드합니다.

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

   다음을 바꿉니다.

   • ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로입니다.
   • USER_CLUSTER_CONFIG: 사용자 클러스터 구성 파일의 경로입니다.

   이 명령어를 실행하면 사용자 클러스터의 모든 노드가 다시 생성됩니다.

고급 클러스터와 번들로 제공되는 cert-manager

cert-manager는 고급 클러스터의 필수 시스템 관리 구성요소입니다.

고급 클러스터 없이 cert-manager을 사용하는 경우 고급 클러스터로 업그레이드하기 전에 다음을 확인하세요.

• cert-manager에 맞춤 구성이나 기능 플래그가 없습니다.
• cert-manager 버전이 번들 버전과 동일하거나 한 버전 뒤처져 있습니다.

Apigee Hybrid 호환성

번들로 제공되는 cert-manager는 Apigee Hybrid 워크로드와 완전히 호환됩니다. 고급 클러스터로 업그레이드하면 설치 프로그램에서 기존 cert-manager 설치가 대체된다는 경고를 표시할 수 있습니다. 이는 시스템에서 자동으로 처리하는 정상적인 동작입니다.

Apigee 워크로드의 원활한 전환을 위해 다음 단계를 따르세요.

• 업그레이드 전에 기존 cert-manager를 수동으로 제거하지 마세요.
• 맞춤설정 되돌리기: GitOps를 사용하여 cert-manager를 관리하거나 cert-manager 배포에 맞춤 구성을 적용한 경우 구성 드리프트 및 잠재적인 업그레이드 일시중지를 방지하려면 업그레이드 전에 이러한 맞춤설정을 되돌리거나 동기화를 일시중지해야 합니다.

기능 및 제한사항

번들로 제공되는 cert-manager로 다음 작업을 할 수 있습니다.

• Issuer 및 ClusterIssuer 리소스를 만들고 수정합니다.
• 발급자 및 표준 발급자 유형을 참조하는 인증서 리소스를 만들고 수정합니다.
• cert-manager에서 사용하는 표준 Kubernetes 리소스를 만들고 수정합니다.
• API 키가 포함된 Kubernetes 보안 비밀을 만들고 발급자에서 이를 참조합니다.
• 특정 HTTP-01 또는 DNS-01 솔버를 사용하도록 발급자를 구성합니다.

번들로 제공되는 cert-manager에서는 다음을 맞춤설정할 수 없습니다.

• deployment 또는 helm 값을 설정합니다.
• cert-manager 바이너리에 명령줄 인수 또는 플래그를 추가합니다.
• cert-manager 포드의 리소스 한도 또는 노드 선택기를 변경합니다.
• cert-manager 소프트웨어의 설치 로직을 수정합니다.
• 실험용 기능을 사용 설정합니다.
• cert-manager 컨트롤 플레인 포드가 특정 인프라 노드에서 실행되도록 강제합니다.

번들로 제공되는 cert-manager를 사용하지 못하도록 하는 특정 제약 조건이 있는 경우 Google Cloud 지원팀에 문의하여 고급 구성 옵션에 관한 도움을 받으세요.

번들 버전

다음 표에는 VMware용 Google Distributed Cloud (소프트웨어 전용)의 각 버전에 번들로 제공되는 cert-manager 버전이 나와 있습니다.

VMware용 Google Distributed Cloud(소프트웨어 전용)	번들 cert-manager 버전
1.32	1.17
1.33	1.18
1.34	1.19

고급 클러스터로 이동한 후의 주요 차이점

클러스터를 고급 클러스터로 업그레이드하거나 업데이트하면 표준 클러스터와 비교해 몇 가지 주요 차이점이 발생합니다. 고급 클러스터의 주요 변경사항은 다음과 같습니다.

• 리소스 위치: 클러스터 및 머신 리소스가 더 이상 사용자 클러스터에 없습니다. 이러한 리소스는 관리자 클러스터 내에만 있습니다.

• NodeExternalIP: 노드에 NodeExternalIP가 설정되어 있지 않습니다.

• cert-manager 설치: 고급 클러스터에 cert-manager가 자동으로 설치됩니다. 클러스터에 cert-manager를 설치한 경우 고급 클러스터로 업데이트하거나 업그레이드하면 고급 클러스터 버전으로 덮어쓰여집니다.

기능 차이점에 대한 자세한 개요는 기능 비교표를 참조하세요.