이제 베어메탈용 Anthos 클러스터는 베어메탈용 Google Distributed Cloud(소프트웨어 전용)입니다. 자세한 내용은 제품 개요를 참조하세요.

클러스터 업그레이드

새 버전의 bmctl을 설치하면 이전 버전으로 생성된 기존 클러스터를 업그레이드할 수 있습니다. 클러스터를 최신 Google Distributed Cloud 버전으로 업그레이드하면 클러스터에 추가 기능 및 수정사항이 적용됩니다. 또한 클러스터가 지원 상태로 유지됩니다. bmctl upgrade cluster 명령어나 kubectl을 사용하여 관리자, 하이브리드, 독립형, 사용자 클러스터를 업그레이드할 수 있습니다.

업그레이드 프로세스 및 버전 관리 규칙에 대한 자세한 내용은 클러스터 업그레이드 수명 주기 및 단계를 참조하세요.

이 페이지는 기본 기술 인프라 수명 주기를 관리하는 관리자, 설계자, 운영자를 대상으로 합니다. Google Cloud 콘텐츠에서 참조하는 일반 역할과 예시 태스크에 대한 자세한 내용은 일반 GKE Enterprise 사용자 역할 및 태스크를 참조하세요.

업그레이드 계획하기

이 섹션에는 클러스터를 업그레이드하기 전에 고려해야 하는 정보와 해당 링크가 포함되어 있습니다. 클러스터 및 노드 풀의 버전 관리 규칙을 비롯한 업그레이드에 관한 자세한 내용은 클러스터 업그레이드 수명 주기 및 단계를 참고하세요.

권장사항

Google Distributed Cloud 클러스터의 업그레이드 권장사항에서 클러스터 업그레이드를 준비하는 데 도움이 될 정보를 참조하세요.

프리플라이트 검사 업그레이드

실행 전 검사는 클러스터 업그레이드의 일부로 실행되어 클러스터 상태와 노드 상태의 유효성을 검사합니다. 실행 전 검사가 실패하면 클러스터 업그레이드가 진행되지 않습니다. 실행 전 검사에 대한 자세한 내용은 실행 전 검사 이해를 참조하세요.

업그레이드를 실행하기 전 실행 전 검사를 실행하여 클러스터의 업그레이드 준비 상태를 확인할 수 있습니다. 자세한 내용은 업그레이드를 위한 실행 전 검사를 참조하세요.

알려진 문제

클러스터 업그레이드와 관련된 잠재적 문제에 대한 자세한 내용은 베어메탈용 Google Distributed Cloud 알려진 문제를 참조하고 업그레이드 및 업데이트 문제 카테고리를 선택하세요.

업그레이드 옵션 구성

클러스터 업그레이드를 시작하기 전에 업그레이드 프로세스의 작동 방식을 제어하는 다음 업그레이드 옵션을 구성할 수 있습니다.

선택적 워커 노드 풀 업그레이드: 특정 워커 노드 풀을 나머지 클러스터와 별도로 업그레이드합니다.
동시 업그레이드: 노드 그룹 또는 노드 풀을 동시에 업그레이드하도록 업그레이드 프로세스를 구성합니다.

이러한 옵션은 중요 애플리케이션 및 서비스의 중단 위험을 줄이고 전반적인 업그레이드 시간을 크게 줄여줄 수 있습니다. 이러한 옵션은 중요한 워크로드를 실행하는 수많은 노드 및 노드 풀이 있는 대규모 클러스터에 특히 유용합니다. 이러한 옵션의 기능과 사용 방법에 대한 자세한 내용은 다음 섹션을 참조하세요.

선택적 워커 노드 풀 업그레이드

기본적으로 클러스터 업그레이드 작업은 클러스터의 모든 노드와 노드 풀을 업그레이드합니다. 클러스터 업그레이드가 중단되고 시간이 오래 걸릴 수 있으며 이로 인해 각 노드가 드레이닝되고 연결된 모든 포드가 다시 시작되고 예약됩니다. 이 섹션에서는 워크로드 중단을 최소화하기 위해 클러스터 업그레이드에 일부 워커 노드 풀을 포함하거나 제외하는 방법을 설명합니다. 관리자 클러스터에서는 워커 노드 풀을 허용하지 않으므로 이 기능은 사용자, 하이브리드, 독립형 클러스터에만 적용됩니다.

다음과 같은 상황에서 선택적 노드 풀 업그레이드를 사용할 수 있습니다.

워크로드 중단 없이 보안 수정사항 적용: 컨트롤 플레인 노드 (및 부하 분산기 노드)만 업그레이드하면 워커 노드 풀을 중단하지 않고도 Kubernetes 취약점 수정사항을 적용할 수 있습니다.
모든 워커 노드를 업그레이드하기 전에 업그레이드된 워커 노드의 하위 집합이 올바르게 작동하는지 확인: 다른 노드 풀을 업그레이드하기 전에 워커 노드 풀을 선택적으로 업그레이드하여 업그레이드된 노드 풀에서 워크로드가 제대로 실행되는지 확인할 수 있습니다.
유지보수 기간 단축: 대규모 클러스터를 업그레이드하는 데 시간이 많이 걸릴 수 있으며 업그레이드가 완료되는 시점을 정확하게 예측하기 어렵습니다. 클러스터 업그레이드 시간은 업그레이드하는 노드 수에 비례합니다. 노드 풀을 제외하여 업그레이드하는 노드 수를 줄이면 업그레이드 시간이 단축됩니다. 여러 번 업그레이드하지만 유지보수 기간이 더 짧고 예측 가능하면 예약에 도움이 될 수 있습니다.

마이너 버전 노드 풀 버전 편향 2개

버전 1.28 이상 클러스터의 경우 워커 노드 풀 버전은 클러스터 (컨트롤 플레인) 버전보다 최대 2 마이너 버전까지 낮을 수 있습니다. n-2 버전 편향 지원을 사용하면 해당 클러스터 이전의 마이너 버전 2개에서 클러스터와 동일한 마이너 버전으로 워커 노드 풀을 업그레이드할 때 부 출시 버전을 n-2 수도 있습니다.

이처럼 워커 노드 풀에 대한 n-2 버전 편향 지원은 Fleet 업그레이드를 계획할 때 더 많은 유연성을 제공합니다.

예를 들어 버전 1.30 클러스터가 있는 경우 일부 1.30, 1.29, 1.28 버전의 워커 노드 풀을 사용할 수 있습니다.

클러스터를 업그레이드하려면 먼저 모든 워커 노드 풀이 현재 클러스터 버전 및 대상 클러스터 버전과 호환되는 버전이어야 합니다.

예를 들어 클러스터 버전이 1.29이고 워커 노드 풀이 버전 1.29, 버전 1.28, 버전 1.16인 경우 클러스터를 버전 1.30으로 업그레이드하기 전에 버전 1.16 노드 풀을 버전 1.28 또는 1.29로 업그레이드해야 합니다.

지정된 클러스터 버전(버전 1.29 이하에 적용 가능)에서 지원하는 지원되는 워커 노드 풀 버전 목록을 포함한 자세한 내용은 노드 풀 버전 관리 규칙을 참조하세요.

1.30

출시 버전 1.30에서는 워커 노드 풀에 대한 n-2 버전 편향 지원이 모든 클러스터 유형에 정식 버전으로 제공됩니다. 이 기능은 기본적으로 버전 1.30의 클러스터에서 사용 설정됩니다.

노드 풀이 1.28 및 1.29 부 버전의 어느 패치 버전이든 관계없이 노드 풀 버전이 클러스터 버전과 같거나 더 낮은 경우, 1.30 패치 버전으로 노드 풀을 업그레이드할 수 있습니다.

1.29

출시 버전 1.29에서는 워커 노드 풀에 대한 n-2 버전 편향 지원이 모든 클러스터 유형에 정식 버전으로 제공됩니다. 이 기능은 기본적으로 버전 1.29의 클러스터에서 사용 설정됩니다.

이 기능을 공개 미리보기에서 정식 버전으로 전환하더라도 하이브리드 클러스터의 경우 다음과 같은 상황에서 여전히 미리보기 주석이 필요합니다. 버전 1.16.y 워커 노드 풀과 버전 1.28.x 하이브리드 클러스터가 있는 경우, 버전 1.29.z로 업그레이드하기 전에 preview.baremetal.cluster.gke.io/two-minor-version-node-pool: enable 주석을 클러스터에 추가해야 합니다.

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: baremetal-demo
  namespace: cluster-baremetal-demo
  annotations:
    preview.baremetal.cluster.gke.io/two-minor-version-node-pool: enable
spec:
  type: hybrid
  profile: default
  anthosBareMetalVersion: 1.28.400-gke.77
  ...

1.28

워커 노드 풀의 n-2 버전 편향 지원은 출시 버전 1.28에서 미리보기로 제공됩니다. 이 미리보기 기능을 사용 설정하려면 preview.baremetal.cluster.gke.io/two-minor-version-node-pool: enable 주석을 클러스터 구성 파일에 추가합니다.

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: baremetal-demo
  namespace: cluster-baremetal-demo
  annotations:
    preview.baremetal.cluster.gke.io/two-minor-version-node-pool: enable
spec:
...

이 미리보기 기능을 사용 설정하지 않으면 워커 노드 풀과 클러스터 간의 최대 버전 편향은 마이너 버전 하나입니다.

워커 노드 풀을 선택적으로 업그레이드하기 위한 버전 관리 규칙에 대한 자세한 내용은 수명 주기 및 클러스터 업그레이드 단계의 노드 풀 버전 관리 규칙을 참조하세요.

클러스터 컨트롤 플레인과 선택한 노드 풀 업그레이드

초기 클러스터 업그레이드에서 워커 노드 풀을 선택적으로 업그레이드하려면 다음 안내를 따르세요.

클러스터 업그레이드에 포함할 워커 노드 풀의 경우 NodePool 사양을 다음 중 하나로 변경합니다.
- NodePool 사양의 anthosBareMetalVersion을 클러스터 대상 업그레이드 버전으로 설정합니다.
- NodePool 사양에서 anthosBareMetalVersion 필드를 생략하거나 빈 문자열로 설정합니다. 기본적으로 워커 노드 풀은 클러스터 업그레이드에 포함됩니다.
업그레이드에서 제외할 워커 노드 풀의 경우 anthosBareMetalVersion을 클러스터의 현재(업그레이드 전) 버전으로 설정합니다.
클러스터 업그레이드 시작에 설명된 대로 업그레이드를 계속합니다.

클러스터 업그레이드 작업은 다음 노드를 업그레이드합니다.
- 클러스터 컨트롤 플레인 노드
- 부하 분산기 노드 풀(클러스터에서 하나(spec.loadBalancer.nodePoolSpec)를 사용하는 경우). 기본적으로 부하 분산기 노드는 일반 워크로드를 실행할 수 있습니다. 부하 분산기 노드 풀은 선택적으로 업그레이드할 수 없으며, 항상 초기 클러스터 업그레이드에 포함됩니다.
- 업그레이드에서 제외하지 않은 워커 노드 풀

예를 들어 클러스터 버전이 1.29.0이고 워커 노드 풀이 2개(wpool01 및 wpool02) 있다고 가정해 보겠습니다. 또한 컨트롤 플레인과 wpool01을 1.30.100-gke.96으로 업그레이드하되 wpool02를 버전 1.29.0으로 유지하려 한다고 가정해 보겠습니다.

다음 클러스터 구성 파일 발췌문에서는 이 부분 업그레이드를 지원하도록 클러스터 구성을 수정하는 방법을 보여줍니다.

...
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user001
  namespace: cluster-user001
spec:
  type: user
  profile: default
  anthosBareMetalVersion: 1.30.100-gke.96
---
apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool01
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: 1.30.100-gke.96
  nodes:
  - address:  10.200.0.1
  - address:  10.200.0.2
  - address:  10.200.0.3
  ...
  - address:  10.200.0.8

apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool02
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: 1.29.0
  nodes:
  - address:  10.200.1.1
  - address:  10.200.1.2
  - address:  10.200.1.3
  ...
  - address:  10.200.1.12

노드 풀을 현재 클러스터 버전으로 업그레이드

클러스터 업그레이드에서 노드 풀을 제외했다면 노드 풀을 대상 클러스터 버전으로 가져오는 클러스터 업그레이드를 실행할 수 있습니다. 클러스터 업그레이드에서 제외된 워커 노드 풀에는 NodePool 사양의 anthosBareMetalVersion 필드가 이전(업그레이드 전) 클러스터 버전으로 설정되어 있습니다.

워커 노드 풀을 현재 업그레이드된 클러스터 버전으로 가져오려면 다음 안내를 따르세요.

현재 클러스터 버전으로 가져오려는 워커 노드 풀의 클러스터 구성 파일에서 NodePool 사양을 수정합니다. anthosBareMetalVersion을 현재(업그레이드 후) 클러스터 버전으로 설정합니다.

업그레이드 대상으로 여러 워커 노드 풀을 선택한 경우 클러스터 사양의 spec.nodePoolUpgradeStrategy.concurrentNodePools 값에 따라 동시에 업그레이드되는 노드 풀 수가 결정됩니다. 워커 노드 풀을 동시에 업그레이드하지 않으려면 업그레이드할 노드 풀을 한 번에 하나씩 선택하세요.
클러스터 업그레이드 시작에 설명된 대로 업그레이드를 계속합니다.

클러스터 업그레이드 작업은 anthosBareMetalVersion을 현재 업그레이드된 클러스터 버전으로 설정한 이전에 제외된 워커 노드 풀만 업그레이드합니다.

예를 들어 클러스터를 버전 1.30.100-gke.96으로 업그레이드했지만 노드 풀 wpool02는 여전히 업그레이드 전의 이전 클러스터 버전 1.29.0이라고 가정해 보겠습니다. 업그레이드된 노드 풀 wpool01에서 워크로드가 제대로 실행되고 있으므로 이제 wpool02도 현재 클러스터 버전으로 가져오려고 합니다. wpool02를 업그레이드하려면 anthosBareMetalVersion 필드를 삭제하거나 이 필드의 값을 빈 문자열로 설정하면 됩니다.

다음 클러스터 구성 파일 발췌문에서는 이 부분 업그레이드를 지원하도록 클러스터 구성을 수정하는 방법을 보여줍니다.

...
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user001
  namespace: cluster-user001
spec:
  type: user
  profile: default
  anthosBareMetalVersion: 1.30.100-gke.96
---
apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool01
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: 1.30.100-gke.96
  nodes:
  - address:  10.200.0.1
  - address:  10.200.0.2
  - address:  10.200.0.3
  ...
  - address:  10.200.0.8

apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool02
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: ""
  nodes:
  - address:  10.200.1.1
  - address:  10.200.1.2
  - address:  10.200.1.3
  ...
  - address:  10.200.1.12

노드 풀 업그레이드 롤백

워크로드 성능에 영향을 줄 수 있는 kubelet 또는 플러그인과의 호환성 등 많은 종속 항목이 있습니다. 워커 노드 풀을 업그레이드한 후 문제가 발생한 경우 노드 풀을 이전 버전으로 롤백할 수 있습니다.

이 기능은 지원되는 모든 클러스터 버전에서 동일한 출시 단계가 아닙니다.

1.30

버전 1.30 클러스터(버전 1.30의 컨트롤 플레인 노드가 있는 클러스터)의 경우 노드 풀 롤백 기능이 정식 버전이며 기본적으로 사용 설정됩니다.

1.29

노드 풀 롤백 기능은 버전 1.29 클러스터(버전 1.29의 컨트롤 플레인 노드가 있는 클러스터)에서 미리보기로 제공됩니다. 이 기능이 미리보기 상태인 동안에는 다음 주석을 Cluster 리소스에 추가하여 이 기능을 사용 설정해야 합니다.

preview.baremetal.cluster.gke.io/worker-node-pool-upgrade-rollback: enable

1.28

부 버전 1.28 이하의 클러스터에서는 노드 풀 롤백 기능을 사용할 수 없습니다.

노드 풀 업그레이드를 롤백하려면 다음 단계를 따르세요.

`bmctl`

bmctl을 사용하여 노드 풀 업그레이드를 롤백하는 경우 클러스터 구성 파일을 수정하고 bmctl update 명령어로 변경사항을 적용합니다.

이전 버전으로 롤백하려는 워커 노드 풀의 클러스터 구성 파일에서 NodePool 사양을 수정합니다. anthosBareMetalVersion을 이전(업그레이드 전) 클러스터 버전으로 설정합니다.
```
...
---
apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool01
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: 1.29.600-gke.108
  nodes:
  - address:  10.200.0.1
  - address:  10.200.0.2
  - address:  10.200.0.3
  ...
```
롤백 대상으로 여러 워커 노드 풀을 선택한 경우 클러스터 사양의 spec.nodePoolUpgradeStrategy.concurrentNodePools 값에 따라 동시에 롤백되는 노드 풀 수가 결정됩니다. 워커 노드 풀을 동시에 롤백하지 않으려면 롤백할 노드 풀을 한 번에 하나씩 선택하거나 nodePoolUpgradeStrategy 설정을 업데이트합니다. 마찬가지로 NodePool 사양의 spec.upgradeStrategy.parallelUpgrade.concurrentNodes 값이 동시에 롤백되는 노드 수를 결정합니다.
bmctl update를 사용하여 NodePool 사양 변경사항을 적용합니다.
```
bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG
```
다음을 바꿉니다.
- CLUSTER_NAME: 업데이트하려는 클러스터의 이름
- ADMIN_KUBECONFIG: 관리 클러스터(관리자, 하이브리드 또는 독립형)의 kubeconfig 파일 경로
롤백은 자동으로 시작됩니다. bmctl update cluster 명령어는 즉시 종료되지만 롤백이 계속 진행됩니다. 롤백이 진행되는 동안 클러스터에서 다른 작업을 수행하지 마세요.
롤백이 실행되면 Google Distributed Cloud는 각 노드에 대해 다음 활동을 수행합니다.
- 노드를 유지보수 모드로 전환
- 노드에서 재설정 작업을 실행하여 초기 상태로 전환
- 노드에서 머신 실행 전 검사 실행
- 노드에서 machine-init 작업을 실행하여 대상 롤백 (업그레이드 전) 버전에서 다시 설치
- 유지보수 모드에서 노드 삭제
롤백이 성공하면 NodePool 리소스의 nodePool.status.anthosBareMetalVersion 값이 대상 롤백 버전으로 설정됩니다.

클러스터 구성 파일을 수정할 때는 bmctl update와 kubectl apply -f를 같은 의미로 사용하지 마세요. 이러한 명령어를 같은 의미로 사용할 경우 클러스터 사양의 헤더에 의해 채워진 콘텐츠가 의도치 않게 삭제될 수 있습니다. 예를 들어 bmctl update을 사용하여 레지스트리 미러를 구성하도록 클러스터 구성 파일을 업데이트할 수 있습니다. 그러면 조정 후 클러스터에 spec.nodeConfig.registryMirrors가 채워집니다.

그런 다음 kubectl apply -f 명령어로 클러스터 구성을 사용해서 클러스터를 변경하려고 하면 클러스터에서 조정자가 채운 spec.nodeConfig.registryMirrors가 삭제됩니다. 이 동작은 클러스터 구성 사양에 존재하지 않는 구성이 클러스터에 있기 때문에 발생합니다.

`kubectl`

kubectl을 사용하여 NodePool 리소스를 직접 수정하면 노드 풀 업그레이드를 롤백할 수 있습니다.

워커 노드 풀을 롤백하려면 수정할 NodePool 리소스를 엽니다.
```
kubectl edit nodepool NODE_POOL_NAME \
    --namespace CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG
```
다음을 바꿉니다.
- NODE_POOL_NAME: 롤백하려는 노드 풀의 이름
- CLUSTER_NAMESPACE: 노드 풀이 배포되는 네임스페이스의 이름. 클러스터 네임스페이스입니다.
- ADMIN_KUBECONFIG: 관리 클러스터(관리자, 하이브리드 또는 독립형)의 kubeconfig 파일 경로

spec.anthosBareMetalVersion의 값을 이전(업그레이드 전) 버전으로 변경합니다.

...
---
apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool01
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: 1.29.600-gke.108
  nodes:
  - address:  10.200.0.1
  - address:  10.200.0.2
  - address:  10.200.0.3
  ...

편집기에서 NodePool 리소스를 저장하고 닫습니다.

롤백은 자동으로 시작됩니다. 롤백이 진행되는 동안 클러스터에서 다른 작업을 수행하지 마세요.
롤백이 실행되면 Google Distributed Cloud는 각 노드에 대해 다음 활동을 수행합니다.
- 노드를 유지보수 모드로 전환
- 노드에서 재설정 작업을 실행하여 초기 상태로 전환
- 노드에서 머신 실행 전 검사 실행
- 노드에서 machine-init 작업을 실행하여 대상 롤백 (업그레이드 전) 버전에서 다시 설치
- 유지보수 모드에서 노드 삭제
롤백이 성공하면 NodePool 리소스의 nodePool.status.anthosBareMetalVersion 값이 대상 롤백 버전으로 설정됩니다.

동시 업그레이드

일반적인 기본 클러스터 업그레이드에서는 각 클러스터 노드가 한 번에 하나씩 순차적으로 업그레이드됩니다. 이 섹션에서는 클러스터를 업그레이드할 때 여러 노드가 동시에 업그레이드되도록 클러스터 및 워커 노드 풀을 구성하는 방법을 보여줍니다. 노드를 동시에 업그레이드하면 특히 수백 개의 노드가 포함된 클러스터의 경우 클러스터 업그레이드 속도가 크게 빨라집니다.

클러스터 업그레이드 속도를 높이는 데 사용할 수 있는 동시 업그레이드 전략에는 두 가지가 있습니다.

동시 노드 업그레이드: 여러 노드가 동시에 업그레이드되도록 워커 노드 풀을 구성할 수 있습니다. 노드의 동시 업그레이드는 NodePool 사양(spec.upgradeStrategy.parallelUpgrade)에서 구성되며 워커 노드 풀의 노드만 동시에 업그레이드할 수 있습니다. 컨트롤 플레인 또는 부하 분산기 노드 풀의 노드는 한 번에 하나씩만 업그레이드할 수 있습니다. 자세한 내용은 노드 업그레이드 전략을 참조하세요.
동시 노드 풀 업그레이드: 여러 노드 풀이 동시에 업그레이드되도록 클러스터를 구성할 수 있습니다. 워커 노드 풀만 동시에 업그레이드할 수 있습니다. 컨트롤 플레인 및 부하 분산기 노드 풀은 한 번에 하나씩만 업그레이드할 수 있습니다.

노드 업그레이드 전략

여러 노드가 동시에 업그레이드되도록 워커 노드 풀을 구성할 수 있습니다(concurrentNodes). 업그레이드 프로세스 동안 워크로드를 실행할 수 있는 노드 수의 최소 기준점을 설정할 수도 있습니다(minimumAvailableNodes). 이 구성은 NodePool 사양에서 지정합니다. 이러한 필드에 대한 자세한 내용은 클러스터 구성 필드 참조를 확인하세요.

노드 업그레이드 전략은 워커 노드 풀에만 적용됩니다. 컨트롤 플레인 또는 부하 분산기 노드 풀에 노드 업그레이드 전략을 지정할 수 없습니다. 클러스터 업그레이드 중에 컨트롤 플레인과 부하 분산기 노드 풀의 노드는 한 번에 하나씩 순차적으로 업그레이드됩니다. 컨트롤 플레인 노드 풀과 부하 분산기 노드 풀은 클러스터 사양(controlPlane.nodePoolSpec.nodes 및 loadBalancer.nodePoolSpec.nodes)에 지정됩니다.

노드의 동시 업그레이드를 구성할 때는 다음 제한사항에 유의하세요.

concurrentNodes 값은 노드 풀에 있는 노드 수의 50% 또는 고정된 수(15개) 중 더 적은 값을 초과할 수 없습니다. 예를 들어 노드 풀에 노드가 20개 있으면 10보다 큰 값을 지정할 수 없습니다. 노드 풀에 노드가 100개 있으면 지정 가능한 최댓값은 15입니다.
concurrentNodes와 함께 minimumAvailableNodes를 사용하는 경우 결합된 값이 노드 풀의 총 노드 수를 초과할 수 없습니다. 예를 들어 노드 풀에 노드가 20개 있고 minimumAvailableNodes가 18로 설정된 경우 concurrentNodes는 2를 초과할 수 없습니다. 마찬가지로 concurrentNodes가 10으로 설정되면 minimumAvailableNodes는 10을 초과할 수 없습니다.

다음 예시는 노드가 10개인 워커 노드 풀 np1을 보여줍니다. 업그레이드 한 번에 노드가 5개씩 업그레이드되며 업그레이드를 진행하려면 최소 4개의 노드를 계속 사용할 수 있어야 합니다.

apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: np1
  namespace: cluster-cluster1
spec:
  clusterName: cluster1
  nodes:
  - address:  10.200.0.1
  - address:  10.200.0.2
  - address:  10.200.0.3
  - address:  10.200.0.4
  - address:  10.200.0.5
  - address:  10.200.0.6
  - address:  10.200.0.7
  - address:  10.200.0.8
  - address:  10.200.0.9
  - address:  10.200.0.10 
  upgradeStrategy:
    parallelUpgrade:
      concurrentNodes: 5
      minimumAvailableNodes: 4

노드 풀 업그레이드 전략

여러 워커 노드 풀이 동시에 업그레이드되도록 클러스터를 구성할 수 있습니다. 클러스터 사양의 nodePoolUpgradeStrategy.concurrentNodePools 불리언 필드는 클러스터의 모든 워커 노드 풀을 동시에 업그레이드할지 여부를 지정합니다. 기본적으로(1) 노드 풀은 하나씩 순차적으로 업그레이드됩니다. concurrentNodePools를 0으로 설정하면 클러스터의 모든 워커 노드 풀이 동시에 업그레이드됩니다.

컨트롤 플레인과 부하 분산 노드 풀은 이 설정의 영향을 받지 않습니다. 이러한 노드 풀은 항상 한 번에 하나씩 순차적으로 업그레이드됩니다. 컨트롤 플레인 노드 풀과 부하 분산기 노드 풀은 클러스터 사양(controlPlane.nodePoolSpec.nodes 및 loadBalancer.nodePoolSpec.nodes)에 지정됩니다.

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: cluster1
  namespace: cluster-cluster1
spec:
  ...
  nodePoolUpgradeStrategy:
    concurrentNodePools: 0
  ...

동시 업그레이드 수행 방법

이 섹션에서는 동시 업그레이드를 위해 클러스터 및 워커 노드 풀을 구성하는 방법을 설명합니다.

워커 노드 풀과 워커 노드 풀의 노드를 동시에 업그레이드하려면 다음을 수행합니다.

NodePool 사양에 upgradeStrategy 섹션을 추가합니다.

클러스터를 업데이트할 때 이 매니페스트를 별도로 또는 클러스터 구성 파일의 일부로 적용할 수 있습니다.

예를 들면 다음과 같습니다.
```
---
apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: np1
  namespace: cluster-ci-bf8b9aa43c16c47
spec:
  clusterName: ci-bf8b9aa43c16c47
  nodes:
  - address:  10.200.0.1
  - address:  10.200.0.2
  - address:  10.200.0.3
  ...
  - address:  10.200.0.30
  upgradeStrategy:
    parallelUpgrade:
      concurrentNodes: 5
      minimumAvailableNodes: 10
```
이 예시에서 concurrentNodes 필드 값은 5입니다. 즉, 5개 노드가 동시에 업그레이드됩니다. minimumAvailableNodes 필드는 10으로 설정됩니다. 즉, 업그레이드 중에 워크로드에 10개 이상의 노드를 계속 사용할 수 있어야 합니다.

참고: 컨트롤 플레인 또는 부하 분산기 노드 풀에 노드 업그레이드 전략을 지정할 수 없습니다.
클러스터 구성 파일의 클러스터 사양에 nodePoolUpgradeStrategy 섹션을 추가합니다.
```
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-user001
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user001
  namespace: cluster-user001
spec:
  type: user
  profile: default
  anthosBareMetalVersion: 1.30.100-gke.96
  ...
  nodePoolUpgradeStrategy:
    concurrentNodePools: 0
  ...
```
이 예시에서는 concurrentNodePools 필드가 0으로 설정되었습니다. 즉, 클러스터 업그레이드 중에 모든 워커 노드 풀이 동시에 업그레이드됩니다. 노드 풀에 있는 노드의 업그레이드 전략은 NodePool 사양에 정의되어 있습니다.
이전 관리자, 독립형, 하이브리드, 사용자 클러스터 업그레이드 섹션에 설명된 대로 클러스터를 업그레이드합니다.

동시 업그레이드 기본값

동시 업그레이드는 기본적으로 중지되어 있으며, 동시 업그레이드와 관련된 필드는 변경할 수 있습니다. 언제든지 필드를 삭제하거나 기본값으로 설정하여 후속 업그레이드 전에 기능을 중지할 수 있습니다.

다음 표에는 동시 업그레이드 필드와 기본값이 나와 있습니다.

필드	기본값	의미
`nodePoolUpgradeStrategy.concurrentNodePools`(클러스터 사양)	`1`	워커 노드 풀을 하나씩 순차적으로 업그레이드합니다.
`upgradeStrategy.parallelUpgrade.concurrentNodes`(NodePool 사양)	`1`	노드를 하나씩 순차적으로 업그레이드합니다.
`upgradeStrategy.parallelUpgrade.minimumAvailableNodes`(NodePool 사양)	기본 `minimumAvailableNodes` 값은 `concurrentNodes` 값에 따라 달라집니다. `concurrentNodes`를 지정하지 않으면 `minimumAvailableNodes`는 기본적으로 노드 풀 크기의 2/3입니다. `concurrentNodes`를 지정하지 않으면 `minimumAvailableNodes`는 기본적으로 노드 풀 크기에서`concurrentNodes`를 뺀 값입니다.	`minimumAvailableNodes`에 도달하면 업그레이드가 중단되고 사용 가능한 노드 수가 `minimumAvailableNodes`보다 큰 경우에만 계속됩니다.

클러스터 업그레이드 시작

이 섹션에는 클러스터 업그레이드에 대한 안내가 포함되어 있습니다.

`bmctl`

bmctl의 새 버전을 다운로드하여 설치하면 이전 버전으로 만든 관리자, 하이브리드, 독립형, 사용자 클러스터를 업그레이드할 수 있습니다. bmctl의 특정 버전에서는 클러스터를 동일한 버전으로만 업그레이드할 수 있습니다.

사용자 인증 정보를 애플리케이션 기본 사용자 인증 정보(ADC)로 설정합니다.
```
gcloud auth application-default login
```
메시지에 따라 ADC용 Google 계정을 선택합니다. 자세한 내용은 애플리케이션 기본 사용자 인증 정보 설정을 참조하세요.
Google Distributed Cloud 다운로드의 설명대로 최신 bmctl을 다운로드합니다.
클러스터 구성 파일의 anthosBareMetalVersion을 업그레이드 대상 버전으로 업데이트합니다.

업그레이드 대상 버전은 다운로드한 bmctl 파일의 버전과 일치해야 합니다. 다음 클러스터 구성 파일 스니펫은 최신 버전으로 업데이트된 anthosBareMetalVersion 필드를 보여줍니다.
```
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: cluster1
  namespace: cluster-cluster1
spec:
  type: admin
  # Anthos cluster version.
  anthosBareMetalVersion: 1.30.100-gke.96
```
bmctl upgrade cluster 명령어를 사용하여 업그레이드를 완료합니다.
```
bmctl upgrade cluster -c CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG
```
다음을 바꿉니다.
- CLUSTER_NAME: 업그레이드할 클러스터의 이름
- ADMIN_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로
참고: bmctl upgrade 명령어는 클러스터 내 커스텀 리소스의 anthosBareMetalVersion 값과 미리보기 주석만 업데이트합니다. 클러스터 사양의 다른 필드를 수정하려면 bmctl update 명령어를 사용하세요. 자세한 내용은 클러스터 업데이트를 참조하세요.

클러스터 업그레이드 작업에서는 프리플라이트 검사를 실행하여 클러스터 상태와 노드 상태를 검증합니다. 프리플라이트 검사가 실패하면 클러스터 업그레이드가 진행되지 않습니다. 문제 해결 정보는 클러스터 설치 또는 업그레이드 문제 해결을 참조하세요.

모든 클러스터 구성요소가 성공적으로 업그레이드되면 클러스터 업그레이드 작업이 클러스터 상태 점검을 수행합니다. 이 마지막 단계를 통해 클러스터가 정상 작동 상태인지 확인합니다. 클러스터가 모든 상태 점검을 통과하지 못하면 통과할 때까지 계속 실행됩니다. 모든 상태 점검을 통과하면 업그레이드가 성공적으로 완료됩니다.

클러스터 업그레이드 이벤트 시퀀스에 대한 자세한 내용은 클러스터 업그레이드 수명 주기 및 단계를 참조하세요.

`kubectl`

kubectl로 클러스터를 업그레이드하려면 다음 단계를 수행합니다.

클러스터 구성 파일을 수정하여 anthosBareMetalVersion을 업그레이드 대상 버전으로 설정합니다.
업그레이드를 시작하려면 다음 명령어를 실행합니다.
```
kubectl apply -f CLUSTER_CONFIG_PATH
```
CLUSTER_CONFIG_PATH를 수정된 클러스터 구성 파일의 경로로 바꿉니다.

bmctl을 사용하는 업그레이드 프로세스와 마찬가지로 프리플라이트 검사는 클러스터 업그레이드의 일부로 실행되어 클러스터 상태와 노드 상태를 검증합니다. 프리플라이트 검사가 실패하면 클러스터 업그레이드가 중단됩니다. 부트스트랩 클러스터가 생성되지 않으므로 실패를 해결하려면 클러스터 및 관련 로그를 검사합니다. 자세한 내용은 클러스터 설치 또는 업그레이드 문제 해결을 참조하세요.

kubectl로 업그레이드하는 데 최신 버전의 bmctl이 필요하지는 않지만 최신 bmctl을 다운로드하는 것이 좋습니다. 클러스터가 정상 작동을 유지할 수 있도록 상태 점검 및 백업과 같은 다른 태스크를 수행하려면 bmctl이 필요합니다.

업그레이드 일시중지 및 재개

업그레이드 일시중지 및 재개 기능을 사용하면 클러스터 업그레이드가 완료되기 전에 일시중지할 수 있습니다. 클러스터 업그레이드가 일시중지되면 업그레이드가 재개될 때까지 새 워커 노드 업그레이드가 트리거되지 않습니다.

이 기능은 마이너 버전 1.28 이상의 모든 컨트롤 플레인 노드가 있는 클러스터에서 미리보기로 제공됩니다. 마이너 버전 1.29 이상의 모든 컨트롤 플레인 노드가 있는 클러스터에서는 이 기능이 정식 버전으로 지원됩니다.

다음과 같은 이유로 업그레이드를 일시중지할 수 있습니다.

업그레이드 중 클러스터 워크로드에서 문제가 감지되어 문제를 조사하기 위해 업그레이드를 일시중지하려고 합니다.
유지보수 기간이 짧으므로 기간 간의 업그레이드를 일시중지하려고 합니다.

클러스터 업그레이드가 일시중지된 동안에 다음 작업이 지원됩니다.

업그레이드가 일시중지된 동안에 새 노드가 추가되면 업그레이드가 재개되고 완료될 때까지 머신 검사 작업이 실행되지 않습니다.

클러스터 업그레이드가 일시중지된 동안에는 다음 클러스터 작업이 지원되지 않습니다.

활성 클러스터 업그레이드가 일시중지된 동안에는 새 클러스터 업그레이드를 시작할 수 없습니다.

업그레이드 일시중지 및 재개 사용 설정

Google Distributed Cloud 1.30

업그레이드 일시중지 및 재개 기능은 마이너 버전 1.29 이상의 모든 컨트롤 플레인 노드가 있는 클러스터에 기본적으로 사용 설정됩니다.

Google Distributed Cloud 1.29

업그레이드 일시중지 및 재개 기능은 미리보기 상태이지만 클러스터 리소스의 주석으로 이 기능을 사용 설정할 수 있습니다.

업그레이드 일시중지 및 재개를 사용 설정하려면 다음 단계를 수행합니다.

preview.baremetal.cluster.gke.io/upgrade-pause-and-resume 주석을 클러스터 구성 파일에 추가합니다.

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: baremetal-demo
  namespace: cluster-baremetal-demo
  annotations:
    preview.baremetal.cluster.gke.io/upgrade-pause-and-resume
spec:
...

변경사항을 적용하려면 클러스터를 업데이트합니다.
```
bmctl update CLUSTER_NAME
```
nodePoolUpgradeStrategy.pause 필드는 변경 가능합니다. 언제든지 추가하고 업데이트할 수 있습니다.

업그레이드 일시중지

클러스터 사양에서 nodePoolUpgradeStrategy.pause를 true로 설정하여 클러스터 업그레이드를 일시중지합니다.

활성 클러스터 업그레이드를 일시중지하려면 다음 단계를 수행합니다.

nodePoolUpgradeStrategy.pause를 클러스터 구성 파일에 추가하고 true로 설정합니다.
```
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: baremetal-demo
  namespace: cluster-baremetal-demo
  ...
spec:
  ...
  nodePoolUpgradeStrategy:
    pause: true
  ...
```
bmctl을 사용하여 업그레이드를 시작한 경우 다음 단계를 수행하려면 새 터미널 창이 필요합니다.
변경사항을 적용하려면 클러스터를 업데이트합니다.
```
bmctl update CLUSTER_NAME
```
업그레이드 작업이 일시중지됩니다. 새 노드 업그레이드가 트리거되지 않습니다.
bmctl을 사용하여 업그레이드를 시작했고 장기간 일시중지할 계획이라면 Control+C를 눌러 bmctl을 종료합니다. 그렇지 않으면 bmctl이 계속 실행됩니다.

bmctl CLI는 업그레이드 일시중지 상태에서의 변경사항을 감지하지 않으므로 자동으로 종료되지 않습니다. 하지만 bmctl을 종료하면 관리자 워크스테이션의 클러스터 폴더에 있는 cluster-upgrade-TIMESTAMP 로그 파일과 Cloud Logging에 대한 로깅 업그레이드 진행이 중지됩니다. 따라서 일시적인 일시중지의 경우 bmctl을 계속 실행할 수 있습니다. 업그레이드가 일시중지된 동안에 bmctl이 장시간 실행되면 결국 타임아웃됩니다.

일시중지된 업그레이드 재개

클러스터 사양에서 nodePoolUpgradeStrategy.pause를 false로 설정하거나 사양에서 nodePoolUpgradeStrategy.pause를 삭제하여 일시중지된 클러스터 업그레이드를 재개합니다.

일시중지된 클러스터 업그레이드를 재개하려면 다음 단계를 수행합니다.

nodePoolUpgradeStrategy.pause를 클러스터 구성 파일로 설정하고 false로 설정합니다.

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: baremetal-demo
  namespace: cluster-baremetal-demo
  ...
spec:
  ...
  nodePoolUpgradeStrategy:
    pause: false
  ...

또는 pause 필드의 기본값이 false이므로 이 필드를 삭제할 수 있습니다.

변경사항을 적용하려면 클러스터를 업데이트합니다.
```
bmctl update CLUSTER_NAME
```
업그레이드 작업은 중단된 지점부터 재개됩니다.

업그레이드 상태를 확인하려면 먼저 status에 anthosBareMetalVersion이 있는 리소스 목록을 가져옵니다.

kubectl get RESOURCE --kubeconfig ADMIN_KUBECONFIG --all_namespaces

다음을 바꿉니다.

RESOURCE: 가져올 리소스의 이름입니다. Cluster, NodePool, BareMetalMachine 리소스 모두 anthosBareMetalVersion 상태 정보가 포함되어 있습니다.
ADMIN_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로입니다.

다음 샘플에서는 BareMetalMachine 커스텀 리소스의 응답 형식을 보여줍니다. 각 BareMetalMachine은 클러스터 노드에 해당합니다.

NAMESPACE              NAME         CLUSTER        READY   INSTANCEID               MACHINE      ABM VERSION   DESIRED ABM VERSION
cluster-nuc-admin001   192.0.2.52   nuc-admin001   true    baremetal://192.0.2.52   192.0.2.52   1.28.0        1.28.0
cluster-nuc-user001    192.0.2.53   nuc-user001    true    baremetal://192.0.2.53   192.0.2.53   1.16.2        1.16.2
cluster-nuc-user001    192.0.2.54   nuc-user001    true    baremetal://192.0.2.54   192.0.2.54   1.16.2        1.16.2

status.anthosBareMetalVersion(현재 리소스 버전)을 확인하려면 개별 리소스의 세부정보를 검색합니다.

kubectl describe RESOURCE RESOURCE_NAME \
    --kubeconfig ADMIN_KUBECONFIG \
    --namespace CLUSTER_NAMESPACE

다음 샘플에서는 IP 주소가 192.0.2.53인 클러스터 노드의 BareMetalMachine 세부정보를 보여줍니다.

Name:         192.0.2.53
Namespace:    cluster-nuc-user001
...
API Version:  infrastructure.baremetal.cluster.gke.io/v1
Kind:         BareMetalMachine
Metadata:
  Creation Timestamp:  2023-09-22T17:52:09Z
  ...
Spec:
  Address:                    192.0.2.53
  Anthos Bare Metal Version:  1.16.2
  ...
Status:
  Anthos Bare Metal Version:  1.16.2

이 예시에서 노드는 Google Distributed Cloud 버전 1.16.2입니다.