使用 GKE On-Prem API 客户端升级管理员集群或用户集群

本页面介绍如何使用 Google Cloud 控制台或 Google Cloud CLI 升级在 GKE On-Prem API 中注册的 GKE on Bare Metal 管理员或用户集群。如果您使用 Terraform 创建了用户集群，则可以使用 Terraform 升级用户集群。如需了解升级要求、最佳实践和有关升级过程的其他信息，请在继续操作之前查看升级最佳实践以及集群升级的生命周期和阶段。

什么是 GKE On-Prem API？

GKE On-Prem API 是一种由 Google Cloud 托管的 API，可让您使用 Terraform 和标准 Google Cloud 工具来管理本地集群的生命周期。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 升级集群：

  1. 确保您拥有最新版本的 gcloud CLI。根据需要更新 gcloud CLI 组件：

    gcloud components update

IAM 要求

如果您不是 Project Owner，则必须在创建集群的 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 Hub 角色。

版本要求

在 GKE on Bare Metal 版本发布后，大约需要 7 到 10 天才能在 GKE On-Prem API 中使用该版本。

您可以直接升级到同一或下一次要发布版本中的某个版本。例如，您可以从 1.16.1 升级到 1.16.2，或从 1.15.1 升级到 1.16.2。不允许升级到比安装的版本晚一个以上的次要版本。

管理员集群可以管理相同或先前次要版本的用户集群。受管用户集群最多只能比管理员集群低一个次要版本，因此在将管理员集群升级到新的次要版本之前，请确保所有受管用户集群都与管理员集群处于同一次要版本中。

升级管理员集群

控制台

  1. 在控制台中，前往 Google Kubernetes Engine 集群概览页面。

    转到 GKE 集群

  2. 选择 Google Cloud 项目，然后选择要升级的集群。

  3. 在详细信息面板中，点击更多详细信息。

  4. 在集群基本信息部分，点击 升级。

  5. 在选择目标版本列表中，选择您要升级到的版本。我们建议您升级到最新的补丁版本。

  6. 点击升级。

在集群升级之前，系统会运行预检检查以验证集群状态和节点健康状况。预检检查通过后，管理员集群会开始升级。根据集群的大小，升级需要 30 分钟或更长时间才能完成。

如需查看升级的状态，请点击集群详情标签页上的显示详情。

gcloud CLI

  1. （可选）列出项目中所有已注册的管理员集群以确认集群名称和区域：

    gcloud container bare-metal admin-clusters list \
  --project=PROJECT_ID \
  --location=-

    • 将 PROJECT_ID 替换为集群所属的舰队宿主项目的 ID。如果您的集群是使用 bmctl 创建的，则这是集群配置文件的 gkeConnect.projectID 字段中的项目 ID。

    • 设置 --location=- 时，意味着列出所有区域中的所有集群。如果您需要缩小列表范围，请将 --location 设置为特定区域。

    如果您收到 PERMISSION_DENIED 错误，请仔细检查您输入的项目 ID。如果项目 ID 正确无误，请运行 gcloud auth login 以使用有权访问项目的账号登录 Google Cloud CLI。

  2. 获取可用的升级目标版本列表：

    gcloud container bare-metal admin-clusters query-version-config \
  --admin-cluster=ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

    请替换以下内容：

    • ADMIN_CLUSTER_NAME：管理员集群的名称。

    • PROJECT_ID：集群所属的舰队宿主项目的 ID。

    • REGION：GKE On-Prem API 运行并存储集群元数据的 Google Cloud 区域。

  3. 升级管理员集群：

    gcloud container bare-metal admin-clusters update ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION

    将 VERSION 替换为要升级到的 GKE on Bare Metal 版本。请从上一条命令的输出中指定版本。我们建议您升级到最新的补丁版本。

    此命令的输出类似如下所示：

    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.16.8      abm-admin-cluster  RUNNING

如需详细了解相关字段和标志，请参阅 gcloud container Bare-metal admin-clusters 参考文档。

升级用户集群

控制台

  1. 在控制台中，前往 Google Kubernetes Engine 集群概览页面。

    转到 GKE 集群

  2. 选择 Google Cloud 项目，然后选择要升级的集群。

  3. 在详细信息面板中，点击更多详细信息。

  4. 在集群基本信息部分，点击 升级。

  5. 在选择目标版本列表中，选择要升级到的版本。

  6. 点击升级。

在集群升级之前，系统会运行预检检查以验证集群状态和节点健康状况。预检检查通过后，用户集群会开始升级。根据集群的大小，升级需要 30 分钟或更长时间才能完成。

如需查看升级的状态，请点击集群详情标签页上的显示详情。

gcloud CLI

  1. （可选）列出项目中所有已注册的用户集群以确认集群名称和区域：

    gcloud container bare-metal clusters list \
  --project=PROJECT_ID \
  --location=-

    • 将 PROJECT_ID 替换为集群所属的舰队宿主项目的 ID。如果您的集群是使用 bmctl 创建的，则这是集群配置文件的 gkeConnect.projectID 字段中的项目 ID。

    • 设置 --location=- 时，意味着列出所有区域中的所有集群。如果您需要缩小列表范围，请将 --location 设置为特定区域。

    此命令的输出类似如下所示：

    NAME              LOCATION     VERSION  ADMIN_CLUSTER      STATE
abm-user-cluster  us-central1  1.16.8   abm-admin-cluster  RUNNING

    如果您收到 PERMISSION_DENIED 错误，请仔细检查您输入的项目 ID。如果项目 ID 正确无误，请运行 gcloud auth login 以使用有权访问项目的账号登录 Google Cloud CLI。

  2. 获取可用的升级目标版本列表：

    gcloud container bare-metal clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

    请替换以下内容：

    • USER_CLUSTER_NAME：要升级的用户集群的名称。

    • PROJECT_ID：集群所属的舰队宿主项目的 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。

  3. 升级用户集群：

    gcloud container bare-metal clusters update USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION

    将 VERSION 替换为要升级到的 GKE on Bare Metal 版本。请从上一条命令的输出中指定版本。我们建议您升级到最新的补丁版本。

    此命令的输出类似如下所示：

    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 container Bare-metal clusters 参考文档。

Terraform

如需使用 Terraform 升级集群，请使用与创建集群相同的 Terraform 配置。

  1. 切换到 Terraform 配置文件所在的目录。

  2. 获取可用的升级目标版本列表：

    gcloud container bare-metal clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

    请替换以下内容：

    • USER_CLUSTER_NAME：要升级的用户集群的名称。

    • PROJECT_ID：该用户集群所属的舰队宿主项目的 ID。

    • REGION：GKE On-Prem API 运行并存储其元数据的 Google Cloud 区域。

    如果您收到 PERMISSION_DENIED 错误，请仔细检查您输入的项目 ID。如果项目 ID 正确无误，请运行 gcloud auth login 以使用有权访问项目的账号登录 Google Cloud CLI。

  3. 在 Terraform 配置中，将 bare_metal_version 更改为您要升级到的 GKE on Bare Metal 版本。请从上一条命令的输出中指定版本。我们建议您升级到最新的补丁版本。

  4. 初始化并创建 Terraform 方案：

    terraform init

    Terraform 会安装任何所需的库，例如 Google Cloud 提供商。

  5. 检查配置，并根据需要进行更改：

    terraform plan

  6. 应用 Terraform 方案以创建用户集群：

    terraform apply

如需了解 google_gkeonprem_bare_metal_cluster 资源，请参阅参考文档。