使用 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 是 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 角色。

版本要求

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

您可以直接升级到属于同一次要版本或下一个次要版本的版本。例如，您可以从 1.29.100 升级到 1.29.200，或者从 1.28.100 升级到 1.29.200。不允许升级到比已安装版本的多个次要版本。

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

升级管理员集群

控制台

  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 替换为要升级到的 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 参考文档。

升级用户集群

控制台

  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.29.100-gke.251   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 替换为要升级到的 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 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 更改为要升级到的 Google Distributed Cloud 版本。请从上一条命令的输出中指定版本。我们建议您升级到最新的补丁版本。

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

    terraform init

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

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

    terraform plan

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

    terraform apply

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