클러스터 업그레이드

공유 표준

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

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

시작하기 전에

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

IAM 역할 요청

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

조직 역할

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

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

프로젝트 역할

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

개발 환경 준비

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

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

• 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 클러스터가 성공적으로 업그레이드된 후에는 클러스터의 모든 하위 구성요소가 정상인지 확인하는 것이 좋습니다.

클러스터에서 하위 구성요소 오류를 확인합니다.

1. ReconciliationError 메시지를 표시하는 하위 구성요소가 없는지 확인합니다.

   kubectl --kubeconfig MANAGEMENT_API_SERVER \
       get subcomponent -n CLUSTER_NAME -o json | jq -r \
       '.items[] |  select(.status.conditions[]?.reason == "ReconciliationError") |
       select(.status.featureDisabled != true) |  "Sub-Component: \(.metadata.name)
       - \(.status.conditions[]?.message)"'
   

   출력에서 하위 구성요소를 반환하는 경우 인프라 운영자 그룹에 문의하여 추가 지원을 받으세요.

2. Reconciling 메시지를 표시하는 하위 구성요소가 없는지 확인합니다.

   kubectl --kubeconfig MANAGEMENT_API_SERVER \
       get subcomponent -n CLUSTER_NAME -o json | jq -r \
       '.items[] |  select(.status.conditions[]?.reason == "Reconciling") |
       select(.status.featureDisabled != true) | select( "\(.status)" |
       contains("PreinstallPending") | not) | "Sub-Component: \(.metadata.name)
       - \(.status.conditions[]?.message)"'
   

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

다음 단계

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