GKE On-Prem API 클라이언트를 사용하여 관리자 또는 사용자 클러스터 업그레이드

이 페이지에서는 Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 GKE On-Prem API에 등록된 Google Distributed Cloud 관리자 또는 사용자 클러스터를 업그레이드하는 방법을 설명합니다. Terraform을 사용하여 사용자 클러스터를 만든 경우 Terraform으로 사용자 클러스터를 업그레이드할 수 있습니다. 업그레이드 요구사항, 권장사항, 업그레이드 프로세스에 대한 추가 정보는 업그레이드 권장사항 및 클러스터 업그레이드의 수명 주기 및 단계를 참조하세요

GKE On-Prem API란?

GKE On-Prem API는 Terraform 및 표준 Google Cloud 도구를 사용하여 온프레미스 클러스터의 수명 주기를 관리할 수 있게 해주는 Google Cloud 호스팅 API입니다. GKE On-Prem API는 Google Cloud 인프라에서 실행됩니다. Terraform, Google Cloud 콘솔, Google Cloud CLI는 API의 클라이언트이며 API를 사용하여 데이터 센터에서 클러스터를 생성, 업데이트, 업그레이드, 삭제합니다. 표준 클라이언트를 사용하여 클러스터를 만든 경우 클러스터가 GKE On-Prem API에 등록됩니다. 즉, 표준 클라이언트를 사용하여 클러스터의 수명 주기를 관리할 수 있습니다(일부 예외 있음). bmctl을 사용하여 클러스터를 만든 경우 표준 클라이언트를 사용할 수 있는 GKE On-Prem API에서 클러스터를 등록할 수 있습니다.

시작하기 전에

gcloud CLI 설정

gcloud CLI 또는 Terraform을 사용하여 클러스터를 업그레이드하려면 다음 안내를 따르세요.

최신 버전의 gcloud CLI가 있는지 확인합니다. 필요한 경우 gcloud CLI 구성요소를 업데이트합니다.
```
gcloud components update
```

IAM 요구사항

프로젝트 소유자가 아닌 경우 클러스터가 생성된 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 허브 역할을 참조하세요.

버전 요구사항

Google Distributed Cloud 출시 후 GKE On-Prem API에서 버전을 사용할 수 있기까지 약 7~10일이 걸립니다.

동일한 부 출시 버전 또는 다음 부 출시 버전에 속하는 모든 버전으로 직접 업그레이드할 수 있습니다. 예를 들어 1.29.100에서 1.29.200으로 업그레이드하거나 1.28.100에서 1.29.200으로 업그레이드할 수 있습니다. 설치된 버전보다 부 버전 하나를 넘는 버전으로는 업그레이드가 허용되지 않습니다.

관리자 클러스터는 동일하거나 이전 부 버전에 있는 사용자 클러스터를 관리할 수 있습니다. 관리되는 사용자 클러스터는 관리자 클러스터보다 부 버전이 둘 이상 낮아지면 안 됩니다. 따라서 관리자 클러스터를 새 부 버전으로 업그레이드하기 전에 모든 관리되는 사용자 클러스터가 관리자 클러스터와 동일한 부 버전에 있는지 확인하세요.

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

콘솔

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

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

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

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

gcloud CLI

필요한 경우 프로젝트에 등록된 모든 관리자 클러스터를 나열하여 클러스터 이름과 리전을 확인합니다.
```
gcloud container bare-metal admin-clusters list \
  --project=PROJECT_ID \
  --location=-
```
- PROJECT_ID를 클러스터가 구성원인 Fleet 호스트 프로젝트의 ID로 바꿉니다. bmctl을 사용하여 클러스터를 만들었으면 클러스터 구성 파일에서 gkeConnect.projectID 필드의 프로젝트 ID입니다.
- --location=-을 설정하면 모든 리전의 모든 클러스터가 나열됩니다. 목록의 범위를 좁혀야 하는 경우 --location을 특정 리전으로 설정합니다.
PERMISSION_DENIED 오류가 발생하면 입력한 프로젝트 ID를 다시 확인합니다. 프로젝트 ID가 올바르면 gcloud auth login을 실행하여 프로젝트에 액세스 권한이 있는 계정으로 Google Cloud CLI에 로그인합니다.
업그레이드할 수 있는 버전 목록을 가져옵니다.
```
gcloud container bare-metal admin-clusters query-version-config \
  --admin-cluster=ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION
```
다음을 바꿉니다.
- ADMIN_CLUSTER_NAME: 관리자 클러스터 이름
- PROJECT_ID: 클러스터가 구성원인 Fleet 호스트 프로젝트의 ID입니다.
- REGION: GKE On-Prem API가 클러스터 메타데이터를 실행하고 저장하는 Google Cloud 리전입니다.
관리자 클러스터를 업그레이드합니다.
```
gcloud container bare-metal admin-clusters update ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION
```
VERSION을 업그레이드하려는 Google Distributed Cloud 버전으로 바꿉니다. 이전 명령어의 출력에서 버전을 지정합니다. 최신 패치 버전으로 업그레이드하는 것이 좋습니다.

명령어 출력은 다음과 비슷합니다.
```
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입니다.

작업 상태를 확인하려면 출력에서 OPERATION_ID를 다음 명령어로 복사합니다. 다른 터미널 창을 열고 명령어를 실행합니다.
```
gcloud container bare-metal operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION
```

클러스터 크기에 따라 업그레이드를 완료하는 데 30분 이상 걸립니다. 클러스터가 업그레이드되는 동안 이전 명령어를 가끔씩 실행하여 현재 상태를 확인할 수 있습니다.

업그레이드가 완료되면 gcloud ... update 명령어를 실행한 터미널 창이 다음과 비슷하게 표시됩니다.

Updated Anthos on bare metal Admin Cluster [https://gkeonprem.googleapis.com/v1/projects/example-project-1234/locations/us-central1/bareMetalAdminClusters/abm-admin-cluster].
NAME               LOCATION     VERSION     MEMBERSHIP         STATE
abm-admin-cluster  us-central1  1.29.100-gke.251      abm-admin-cluster  RUNNING

필드 및 플래그에 대한 자세한 내용은 gcloud container bare-metal admin-clusters 참조를 확인하세요.

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

콘솔

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

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

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

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

gcloud CLI

원하는 경우 프로젝트에 등록된 모든 사용자 클러스터를 나열하여 클러스터 이름과 리전을 확인합니다.
```
gcloud container bare-metal clusters list \
  --project=PROJECT_ID \
  --location=-
```
- PROJECT_ID를 클러스터가 구성원인 Fleet 호스트 프로젝트의 ID로 바꿉니다. bmctl을 사용하여 클러스터를 만들었으면 클러스터 구성 파일에서 gkeConnect.projectID 필드의 프로젝트 ID입니다.
- --location=-을 설정하면 모든 리전의 모든 클러스터가 나열됩니다. 목록의 범위를 좁혀야 하는 경우 --location을 특정 리전으로 설정합니다.
이 명령어 출력은 다음과 비슷합니다.
```
NAME              LOCATION     VERSION  ADMIN_CLUSTER      STATE
abm-user-cluster  us-central1  1.29.100-gke.251   abm-admin-cluster  RUNNING
```
PERMISSION_DENIED 오류가 발생하면 입력한 프로젝트 ID를 다시 확인합니다. 프로젝트 ID가 올바르면 gcloud auth login을 실행하여 프로젝트에 액세스 권한이 있는 계정으로 Google Cloud CLI에 로그인합니다.
업그레이드할 수 있는 버전 목록을 가져옵니다.
```
gcloud container bare-metal clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION
```
다음을 바꿉니다.
- USER_CLUSTER_NAME: 업그레이드할 사용자 클러스터 이름입니다.
- PROJECT_ID: 클러스터가 구성원인 Fleet 호스트 프로젝트의 ID입니다.
- REGION: GKE On-Prem API가 클러스터 메타데이터를 실행하고 저장하는 Google Cloud 리전입니다.
이 명령어 출력은 다음과 비슷합니다.
```
versions:
- hasDependencies: true
version: 1.15.2
- hasDependencies: true
version: 1.15.1
- hasDependencies: true
version: 1.15.0
- version: 1.14.6
```
- hasDependencies: true에 나열되지 않은 버전을 선택합니다. 이 예시에서 사용자 클러스터를 업그레이드할 수 있는 유일한 버전은 1.14.6입니다.
사용자 클러스터를 업그레이드합니다.
```
gcloud container bare-metal clusters update USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION
```
VERSION을 업그레이드하려는 Google Distributed Cloud 버전으로 바꿉니다. 이전 명령어의 출력에서 버전을 지정합니다. 최신 패치 버전으로 업그레이드하는 것이 좋습니다.

명령어 출력은 다음과 비슷합니다.
```
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입니다.

작업 상태를 확인하려면 출력에서 OPERATION_ID를 다음 명령어로 복사합니다. 다른 터미널 창을 열고 명령어를 실행합니다.
```
gcloud container bare-metal operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION
```

필드 및 플래그에 대한 자세한 내용은 gcloud container bare-metal clusters 참조를 확인하세요.

Terraform

Terraform을 사용하여 클러스터를 업그레이드하려면 클러스터를 만들 때 사용한 Terraform 구성을 사용합니다.

Terraform 구성 파일이 있는 디렉터리로 변경합니다.
업그레이드할 수 있는 버전 목록을 가져옵니다.
```
gcloud container bare-metal clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION
```
다음을 바꿉니다.
- USER_CLUSTER_NAME: 업그레이드할 사용자 클러스터 이름입니다.
- PROJECT_ID: 사용자 클러스터가 구성원인 Fleet 호스트 프로젝트의 ID입니다.
- REGION: GKE On-Prem API가 메타데이터를 실행하고 저장하는 Google Cloud 리전입니다.
PERMISSION_DENIED 오류가 발생하면 입력한 프로젝트 ID를 다시 확인합니다. 프로젝트 ID가 올바르면 gcloud auth login을 실행하여 프로젝트에 액세스 권한이 있는 계정으로 Google Cloud CLI에 로그인합니다.
Terraform 구성에서 bare_metal_version을 업그레이드하려는 Google Distributed Cloud 버전으로 변경합니다. 이전 명령어의 출력에서 버전을 지정합니다. 최신 패치 버전으로 업그레이드하는 것이 좋습니다.
Terraform 계획을 초기화하고 만듭니다.
```
terraform init
```
Terraform은 Google Cloud 제공업체와 같은 필요한 라이브러리를 설치합니다.
구성을 검토하고 필요한 경우 변경합니다.
```
terraform plan
```
Terraform 계획을 적용하여 사용자 클러스터를 만듭니다.
```
terraform apply
```

google_gkeonprem_bare_metal_cluster 리소스에 대한 자세한 내용은 참고 문서를 확인하세요.