클러스터 업그레이드

Shared Standard

이 문서에서는 Google Distributed Cloud (GDC) 에어 갭 Kubernetes 클러스터의 Kubernetes 버전을 업그레이드하는 방법을 설명합니다. 최신 Kubernetes 기능과 수정사항이 포함되도록 클러스터의 정기 업그레이드를 계획해야 합니다.

이 문서는 조직 내에서 Kubernetes 리소스를 관리하는 플랫폼 관리자 그룹 내의 IT 관리자, 보안 엔지니어, 네트워크 관리자와 같은 사용자를 대상으로 합니다. 자세한 내용은 GDC 에어 갭 문서 대상을 참조하세요.

시작하기 전에

이 문서의 작업을 완료하려면 필요한 권한을 요청하고 환경을 준비해야 합니다.

IAM 역할 요청

Kubernetes 클러스터를 업그레이드하는 데 필요한 권한을 얻으려면 특정 역할이 있어야 합니다. 프로젝트 및 조직으로 범위가 지정된 역할을 요청해야 합니다.

조직 역할

Kubernetes 클러스터에 사용 가능한 업그레이드 버전을 나열하려면 IAM 조직 관리자에게 사용자 클러스터 관리자(user-cluster-admin) 역할을 부여해 달라고 요청하세요. 이 역할은 네임스페이스에 바인딩되지 않습니다.

표준 클러스터를 관리하고 플랫폼 관리자 그룹에서 사용자 클러스터 관리자 역할을 가져올 수 없는 경우 사용 가능한 Kubernetes 업그레이드 버전 목록을 제공해 달라고 요청해야 합니다.

프로젝트 역할

클러스터 업그레이드를 만들거나 삭제, 수정, 보려면 IAM 프로젝트 관리자에게 표준 클러스터 관리자 (standard-cluster-admin) 역할을 부여해 달라고 요청하세요. 이 역할은 프로젝트 네임스페이스에 바인딩됩니다.

개발 환경 준비

API를 사용하여 Kubernetes 클러스터에 대해 명령어를 실행하려면 다음 리소스가 있는지 확인합니다.

• gdcloud CLI를 다운로드하고 설치합니다.

• kubectl CLI를 설치합니다.

• Kubernetes 클러스터 이름을 찾거나 플랫폼 관리자 그룹 구성원에게 클러스터 이름을 문의합니다.

• Kubernetes 클러스터 이름을 사용하여 이 안내의 CLUSTER_NAME을 바꿉니다.

• 관리 API 서버의 kubeconfig 파일을 로그인하고 생성합니다.

• 관리 API 서버의 kubeconfig 경로를 사용하여 이 안내에서 MANAGEMENT_API_SERVER를 바꿉니다.

Kubernetes 클러스터 업그레이드

UserClusterUpgradeRequest API를 사용하여 기존 Kubernetes 클러스터를 업그레이드합니다.

API를 사용하여 Kubernetes 클러스터를 업그레이드하려면 다음 단계를 따르세요.

1. UserClusterMetadata 객체의 kubernetesVersion 값을 출력하여 사용 가능한 Kubernetes 업그레이드 버전을 나열합니다.

   kubectl --kubeconfig MANAGEMENT_API_SERVER \
       get userclustermetadata -o=custom-columns='TARGET_VERSION:.spec.kubernetesVersion'
   

   MANAGEMENT_API_SERVER를 관리 API 서버의 kubeconfig 파일 경로로 바꿉니다.

   이 명령어는 사용 가능한 Kubernetes 버전 목록을 반환합니다.

   TARGET_VERSION
   1.30.1000-gke.85
   

2. 클러스터를 업그레이드하려는 이전 출력의 Kubernetes 버전을 기록해 둡니다. 다음 단계의 업그레이드 요청에서 지정하는 targetVersion은 이러한 사용 가능한 버전 중 하나여야 합니다.

3. UserClusterUpgradeRequest 리소스를 만들어 클러스터 업그레이드를 요청합니다.

     kubectl --kubeconfig MANAGEMENT_API_SERVER apply -f - <<EOF
     apiVersion: cluster.gdc.goog/v1
     kind: UserClusterUpgradeRequest
     metadata:
       name: CLUSTER_NAME
       namespace: CLUSTER_NAMESPACE
     spec:
       clusterRef:
         name: CLUSTER_NAME
       targetVersion: TARGET_VERSION
     EOF
   

   다음을 바꿉니다.

   • MANAGEMENT_API_SERVER: 관리 API 서버의 kubeconfig 파일 경로
   • CLUSTER_NAME: 업그레이드할 Kubernetes 클러스터의 이름입니다(예: user-vm-2).
   • CLUSTER_NAMESPACE: Kubernetes 클러스터의 네임스페이스입니다. 공유 클러스터의 경우 platform 네임스페이스를 사용합니다. 표준 클러스터의 경우 클러스터의 프로젝트 네임스페이스를 사용합니다.
   • TARGET_VERSION: 이전 단계에서 식별된 업그레이드의 대상 버전입니다(예: 1.30.1000-gke.85).

   Kubernetes 클러스터의 평균 업그레이드 시간은 약 20분입니다.

4. UserClusterUpgradeRequest 리소스를 모니터링하여 클러스터 업그레이드를 확인합니다.

   kubectl --kubeconfig MANAGEMENT_API_SERVER \
       describe userclusterupgraderequest CLUSTER_NAME \
       -n CLUSTER_NAMESPACE
   

   다음을 바꿉니다.

   • MANAGEMENT_API_SERVER: 관리 API 서버의 kubeconfig 파일 경로
   • CLUSTER_NAME: 업그레이드할 Kubernetes 클러스터의 이름입니다(예: user-vm-2).
   • CLUSTER_NAMESPACE: Kubernetes 클러스터의 네임스페이스입니다. 공유 클러스터의 경우 platform 네임스페이스를 사용합니다. 표준 클러스터의 경우 클러스터의 프로젝트 네임스페이스를 사용합니다.

   출력의 Spec 섹션을 검사합니다. 여기에는 Current Version 및 Target Version가 포함됩니다. Current Version와 Target Version가 다르면 업그레이드가 아직 진행 중입니다.

   Spec:
     ...
     Current Version: 1.29.500-gke.60
     Target Version: 1.30.1000-gke.85
   Status:
     Conditions:
     - Message: Upgrade is in progress
       Reason: UpgradeInProgress
       Status: "False"
       Type: Succeeded
   

   Succeeded 조건의 상태가 True이고 Current Version가 Target Version와 일치하면 업그레이드가 완료되고 성공한 것입니다.

   Succeeded 조건의 상태가 False이면 업그레이드가 실패한 것입니다. Kubernetes 클러스터 업그레이드와 관련된 오류가 발생하면 인프라 운영자 그룹에 문의하여 추가 지원을 받으세요.

업그레이드 후 클러스터 상태 확인

Kubernetes 클러스터가 업그레이드된 후 Cluster 리소스 상태를 검사하여 클러스터와 해당 구성요소가 정상인지 확인합니다.

1. Cluster 리소스의 status.conditions 및 status.componentsConditions 필드를 확인합니다.

   kubectl --kubeconfig MANAGEMENT_API_SERVER \
       get cluster CLUSTER_NAME \
       -n CLUSTER_NAMESPACE -o yaml
   

   다음을 바꿉니다.

   • MANAGEMENT_API_SERVER: 관리 API 서버의 kubeconfig 파일 경로
   • CLUSTER_NAME: Kubernetes 클러스터의 이름입니다(예: user-vm-2).
   • CLUSTER_NAMESPACE: Kubernetes 클러스터의 네임스페이스입니다. 공유 클러스터의 경우 platform 네임스페이스를 사용합니다. 표준 클러스터의 경우 클러스터의 프로젝트 네임스페이스를 사용합니다.

2. 출력의 status 섹션에서 다음을 확인합니다.

   • status.conditions에서 Ready 조건에 status가 True이고 Reconciling 조건에 status가 False인지 확인합니다.
   • status.componentsConditions에서 Ready 조건에 status가 True이고 Reconciling 조건에 status가 False이고 reason가 ReconciliationError 또는 Reconciling인 조건이 없는지 확인합니다.

   컨트롤 플레인 노드 3개와 워커 노드 3개가 있는 Kubernetes 클러스터의 경우 업그레이드에 약 20분이 걸립니다. 20분 후에도 클러스터 또는 해당 구성요소가 Reconciling 상태로 유지되거나 조건에 ReconciliationError가 표시되면 인프라 운영자 그룹에 문의하여 추가 지원을 받으세요.

다음 단계

• 워크로드 분리 설계
• Kubernetes 클러스터 유지보수
• 노드 풀 관리