本文档介绍了如何在 Google Distributed Cloud for VMware（纯软件）中升级集群和节点池。本文档介绍了升级管理员工作站、用户集群和管理员集群的步骤。对于用户集群，本文档介绍了同时或分别升级控制平面和节点池的步骤。
本页面适用于管理底层技术基础架构生命周期的 IT 管理员和运维人员。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE Enterprise 用户角色和任务。
在继续操作之前，我们建议您先查看以下文档：
检查防火墙规则
在 1.29 版及更高版本中，服务器端预检检查默认处于启用状态。服务器端预检检查需要额外的防火墙规则。在管理员集群的防火墙规则中，搜索“预检检查”，并确保已配置所有必需的防火墙规则。
使用服务器端预检检查时，当您使用 gkectl 升级用户集群时，预检检查会在管理员集群上运行，而不是在管理员工作站上本地运行。当您使用 Google Cloud 控制台、Google Cloud CLI 或 Terraform 升级集群时，服务器端预检查也会在管理员集群上运行。
当您升级管理员集群时，Google Distributed Cloud 会部署一个 Kubernetes in Docker（种类）集群，用于暂时托管升级管理员集群所需的 Kubernetes 控制器。此暂时性集群称为引导集群。在升级管理员集群时，服务器端预检检查会在引导集群上运行。
Google API 和 IAM 要求
如需将集群升级到 1.28 及更高版本，您必须启用 kubernetesmetadata.googleapis.com 并向日志记录监控服务账号授予 kubernetesmetadata.publisher IAM 角色。如需使用 Cloud Monitoring，必须进行这些更改。
启用
kubernetesmetadata.googleapis.com：gcloud services enable --project PROJECT_ID \ kubernetesmetadata.googleapis.com将
PROJECT_ID替换为用户集群所属的舰队宿主项目的 ID。这是您在创建集群时指定的项目。如果您的集群是使用gkectl创建的，则这是集群配置文件的gkeConnect.projectID字段中的项目 ID。如果您的组织设置了许可名单，以允许来自 Google API 和其他地址的流量通过代理服务器，请将
kubernetesmetadata.googleapis.com添加到许可名单：将
kubernetesmetadata.publisher角色授予 logging-monitoring 服务账号：gcloud projects add-iam-policy-binding PROJECT_ID \ --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \ --role "roles/kubernetesmetadata.publisher"
将 SERVICE_ACCOUNT_EMAIL 替换为日志记录和监控服务账号的电子邮件地址。
升级用户集群的 IAM 要求
如果您计划使用 gkectl 进行用户集群升级，请跳过本部分。
如果您不是项目所有者，但想要使用 Google Cloud 控制台、Google Cloud CLI 或 Terraform 升级用户集群，则必须在创建集群的 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 角色。
在升级之前或之后进行配置更改
如果您需要对集群进行配置更改，请在升级之前或之后执行集群更新。升级时，对集群配置的唯一更改应该是版本。其他配置更改可能会被静默忽略或导致升级失败，具体取决于集群版本和类型。如需了解详情，请参阅移除不受支持的更改以解除升级屏蔽。
升级管理员工作站
如果您计划使用 gkectl 升级用户集群，则需要升级管理员工作站。
如果您打算使用控制台、gcloud CLI 或 Terraform 升级用户集群，则可以暂时跳过升级管理员工作站。但是，当您准备好升级管理员集群时，您需要升级管理员工作站，因为只有 gkectl 支持管理员集群升级。
升级管理员工作站的方式取决于您创建该工作站的方式：gkeadm 或由用户管理。
gkeadm
查找所需的文件
创建管理员工作站之前，您填写了由 gkeadm create config 生成的管理员工作站配置文件。此文件的默认名称为 admin-ws-config.yaml。
此外，您的工作站还具有信息文件。此文件的默认名称与管理员工作站的名称相同。
找到您的管理员工作站配置文件和信息文件。您需要它们来完成升级步骤。如果这些文件在当前目录中并且具有默认名称，则运行升级命令时无需指定它们。如果这些文件位于其他目录中，或者您更改了文件名，则可以使用 --config 和 --info-file 标志进行指定。
如果输出信息文件缺失，您可以重新创建。 请参阅如果信息文件缺失则重新创建。
升级
如需升级管理员工作站，请执行以下操作：
下载
gkeadm：gkeadm upgrade gkeadm --target-version TARGET_VERSION
将 TARGET_VERSION 替换为升级操作的目标版本。 您需要以
X.Y.Z-gke.N.的形式指定完整的版本号。如需查看 Google Distributed Cloud 版本的列表，请参阅版本控制。升级管理员工作站：
gkeadm upgrade admin-workstation --config AW_CONFIG_FILE \ --info-file INFO_FILE请替换以下内容：
AW_CONFIG_FILE：管理员工作站配置文件的路径。如果文件位于当前目录中且名称为admin-ws-config.yaml，则可以省略此标志。INFO_FILE：信息文件的路径。如果文件位于当前目录中，则可以省略此标志。此文件的默认名称与管理员工作站的名称相同。
由用户管理
在管理员工作站上，前往您要在其中安装新版 gkectl 的目录。
下载 gkectl：
gcloud storage cp gs://gke-on-prem-release/gkectl/VERSION/gkectl ./ chmod +x gkectl
将 VERSION 替换为升级操作的目标版本。 例如：1.30.100-gke.96。
下载 Google Distributed Cloud 软件包。确保该版本与您用于下载 gkectl 的版本一致：
gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/VERSION/gke-onprem-vsphere-VERSION.tgz ./
查看可用于集群升级的版本
运行以下命令，查看哪些版本可以升级：
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG
输出会显示当前版本和可用于升级的版本。
如果您计划使用控制台、gcloud CLI 或 Terraform 进行升级，则在版本发布后，需要大约 7 到 10 天的时间，才能在所有 Google Cloud 区域的 GKE On-Prem API 中使用该版本。控制台中仅列出了用户集群升级的可用版本。使用 gcloud CLI 或 Terraform 升级用户集群的步骤包括运行 gcloud container vmware clusters query-version-config 以获取可用于升级的版本。
升级用户集群
您可以使用 gkectl、控制台、gcloud CLI 或 Terraform 升级用户集群。如需了解如何确定要使用哪种工具，请参阅选择用于升级用户集群的工具。
gkectl
准备升级用户集群
在管理员工作站上执行以下步骤：
运行
gkectl prepare，将操作系统映像导入 vSphere：gkectl prepare \ --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG
如果您的集群有 Windows 节点池，请运行
gkectl prepare windows并更新节点池的osImage字段。如需查看详细说明，请参阅升级具有 Windows 节点池的用户集群。在用户集群配置文件中，将
gkeOnPremVersion设置为升级操作的目标版本。仅限 Ubuntu 和 COS 节点池：指定要升级的节点池。Ubuntu 和 COS 节点池支持将节点池与控制平面分开升级，但 Windows 节点池不支持。
在用户集群配置文件中，指明要升级的节点池，如下所示：
对于要升级的每个节点池，移除
nodePools.nodePool[i].gkeOnPremVersion字段或将其设置为空字符串。对于您不想升级的每个节点池，请将
nodePools.nodePool[i].gkeOnPremVersion设置为当前版本。
例如，假设您的用户集群为 1.15.5-gke.41 版，并且有两个节点池：
pool-1和pool-2。此外，假设您要将控制平面和pool-1升级到 1.16.3-gke.45，但希望pool-2保持为 1.15.5-gke.41 版。用户集群配置文件的以下部分展示了如何指定此示例：gkeOnPremVersion: 1.16.3-gke.45 nodePools: - name: pool-1 gkeOnPremVersion: "" cpus: 4 memoryMB: 8192 replicas: 3 osImageType: ubuntu_containerd - name: pool-2 gkeOnPremVersion: 1.15.5-gke.41 cpus: 4 memoryMB: 8192 replicas: 5 osImageType: ubuntu_containerd
运行预检检查
升级到 1.29 版及更高版本时，您可以在升级用户集群之前运行预检检查：
gkectl upgrade cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG \ --dry-run
使用 --dry-run 标志时，gkectl upgrade cluster 会运行预检检查，但不会启动升级过程。虽然早期版本的 Google Distributed Cloud 会运行预检检查，但它们无法与升级分开运行。通过添加 --dry-run 标志，您可以在升级之前发现并解决预检检查在您的用户集群中发现的任何问题。
运行 gkectl upgrade cluster
gkectl upgrade cluster 命令有两个变体：
异步：（推荐）
使用异步变体时，该命令会开始升级，然后完成。在升级的整个过程中，您无需观察该命令的输出。您可以通过运行gkectl list clusters和gkectl describe clusters来定期检查升级进度。如需使用异步变体，请在该命令中添加--async标志。同步：
在同步变体中，gkectl upgrade cluster命令会在升级过程中向管理员工作站输出状态消息。
异步升级
如果您要升级到 1.16 之后的版本，请跳过此步骤。
如果您为用户集群使用准备好的凭据和私有注册表，请确保在升级用户集群之前准备好私有注册表凭据。如需了解如何准备私有注册表凭据，请参阅为用户集群配置准备好的凭据。
在管理员工作站上，启动异步升级：
gkectl upgrade cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG \ --async
上述命令完成后，您便可以在升级过程中继续使用您的管理员工作站。
如需查看升级的状态，请运行以下命令：
gkectl list clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG
输出会显示集群
STATE的值。如果集群仍在升级，则STATE的值为UPGRADING。例如：NAMESPACE NAME READY STATE AGE VERSION my-uc-gkeonprem-mgmt my-uc False UPGRADING 9h 1.30.0-gke.1
STATE的可能值包括PROVISIONING、UPGRADING、DELETING、UPDATING、RUNNING、RECONCILING、ERROR和UNKNOWN。如需获取有关升级进度和集群事件的详细信息，请运行以下命令：
gkectl describe clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --cluster USER_CLUSTER_NAME -v 5
输出会显示指定用户集群的 OnPremUserCluster 自定义资源，其中包括集群状态、条件和事件。
我们记录了每个关键升级阶段的开始和结束的事件，包括：
- ControlPlaneUpgrade
- MasterNodeUpgrade
- AddonsUpgrade
- NodePoolsUpgrade
输出示例：
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal NodePoolsUpgradeStarted 22m onprem-user-cluster-controller Creating or updating node pools: pool-2: Creating or updating node pool Normal AddonsUpgradeStarted 22m onprem-user-cluster-controller Creating or updating addon workloads Normal ControlPlaneUpgradeStarted 25m onprem-user-cluster-controller Creating or updating cluster control plane workloads: deploying user-kube-apiserver-base, ...: 14/15 pods are ready Normal ControlPlaneUpgradeFinished 23m onprem-user-cluster-controller Control plane is running
升级完成后，
gkectl list clusters会显示STATUS为RUNNING：NAMESPACE NAME READY STATE AGE VERSION my-uc-gkeonprem-mgmt my-uc True RUNNING 9h 1.30.0-gke.1
此外，升级完成后，
gkectl describe clusters会在Status下显示一个Last GKE On Prem Version字段。例如：Status: Cluster State: RUNNING Last GKE On Prem Version: 1.30.0-gke.1
排查异步升级问题
对于异步升级，超时时长取决于集群中的节点数。如果升级花费的时间超过超时时长，则集群状态会从 UPGRADING 更改为 ERROR，并且事件表示升级操作超时。请注意，此处的 ERROR 状态表示升级花费的时间超过预期，但尚未终止。控制器会继续进行协调，并不断重试操作。
超时通常是由 PodDisruptionBudget (PDB) 引起的死锁的结果。在这种情况下，无法从旧节点中逐出 Pod，并且无法排空旧节点。如果 Pod 逐出花费的时间超过 10 分钟，我们会向 OnPremUserCluster 对象写入一个事件。您可以通过运行 gkectl describe clusters 来捕获该事件。然后，您可以调整 PDB 以允许节点排空。之后，升级便可以继续进行并最终完成。
事件示例
Warning PodEvictionTooLong 96s (x2 over 4m7s) onprem-user-cluster-controller Waiting too long(>10m0.00000003s) for (kube-system/coredns-856d6dbfdf-dl6nz) eviction.
此外，当升级被阻止或失败时，您可以运行 gkectl diagnose 来检查是否存在常见的集群问题。根据检查结果，您可以决定是执行手动修复，还是联系 Anthos 支持团队以获取进一步帮助。
同步升级
gkectl upgrade 命令运行预检检查。如果预检检查失败，则该命令会被屏蔽。您必须修复故障，或使用 --skip-preflight-check-blocking 标志。只有在您确信没有任何严重故障时，才应跳过预检检查。
在管理员工作站上继续执行以下步骤：
如果您要升级到 1.16 之后的版本，请跳过此步骤。
如果您为用户集群使用准备好的凭据和私有注册表，请确保在升级用户集群之前准备好私有注册表凭据。如需了解如何准备私有注册表凭据，请参阅为用户集群配置准备好的凭据。
升级集群：
gkectl upgrade cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG_FILE
如果您要升级到 1.14.0 版或更高版本，系统会为用户集群生成新的 kubeconfig 文件，该文件会覆盖任何现有文件。如需查看此文件中的集群详情，请运行以下命令：
kubectl config view --kubeconfig USER_CLUSTER_KUBECONFIG
升级其他节点池
如果您仅升级了用户集群的控制平面，或者升级了控制平面和部分（但不是全部）节点池，请执行以下步骤来升级节点池：
修改用户集群配置文件。对于要升级的每个节点池，请移除
nodePools.nodePool[i].gkeOnPremVersion字段或将其设置为空字符串，如以下示例所示：gkeOnPremVersion: 1.16.3-gke.45 nodePools: - name: pool-1 gkeOnPremVersion: "" cpus: 4 memoryMB: 8192 replicas: 3 osImageType: ubuntu_containerd - name: pool-2 gkeOnPremVersion: "" cpus: 4 memoryMB: 8192 replicas: 5 osImageType: ubuntu_containerd运行
gkectl update cluster以应用更改：gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG
请替换以下内容：
ADMIN_CLUSTER_KUBECONFIG：管理员集群 kubeconfig 文件的路径USER_CLUSTER_CONFIG：用户集群配置文件的路径
如果在升级节点池后遇到问题，可以回滚到先前版本。如需了解详情，请参阅在升级后回滚节点池。
恢复升级
如果用户集群升级中断，您可以通过运行带 --skip-validation-all 标志的同一升级命令来恢复用户集群升级：
gkectl upgrade cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG_FILE \ --skip-validation-all
控制台
升级用户集群需要对管理员集群进行一些更改。控制台会自动执行以下操作：
在 GKE On-Prem API 中注册管理员集群（如果尚未注册）。
下载并将一组组件部署到管理员集群。组件的版本与您为升级指定的版本相匹配。这些组件可让管理员集群管理该版本的用户集群。
如需升级用户集群，请执行以下操作：
在控制台中，进入 Google Kubernetes Engine 集群概览页面。
选择 Google Cloud 项目，然后选择要升级的集群。
在详细信息面板中，点击更多详细信息。
在集群基本信息部分，点击 升级。
在选择目标版本列表中，选择您要升级到的版本。精选列表仅包含最新的补丁版本。
点击升级。
在集群升级之前，系统会运行预检检查以验证集群状态和节点健康状况。预检检查通过后，用户集群会开始升级。升级大约需要 30 分钟才能完成。
如需查看升级的状态，请点击集群详情标签页上的显示详情。
gcloud CLI
升级用户集群需要对管理员集群进行一些更改。gcloud container vmware clusters upgrade 命令会自动执行以下操作：
在 GKE On-Prem API 中注册管理员集群（如果尚未注册）。
下载并将一组组件部署到管理员集群。组件的版本与您为升级指定的版本相匹配。这些组件可让管理员集群管理该版本的用户集群。
如需升级用户集群，请执行以下操作：
更新 Google Cloud CLI 组件：
gcloud components update仅限 Ubuntu 和 COS 节点池：如果您只想升级用户集群的控制平面，并将所有节点池保留在当前版本，请更改集群的升级政策：
gcloud container vmware clusters update USER_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION \ --upgrade-policy control-plane-only=True
替换以下内容：
USER_CLUSTER_NAME：要升级的用户集群的名称。PROJECT_ID：用户集群所属的舰队宿主项目的 ID。这是您在创建集群时指定的项目。如果您的集群是使用gkectl创建的，则这是集群配置文件的gkeConnect.projectID字段中的项目 ID。REGION：Google Cloud 区域，GKE On-Prem API 在其中运行并存储其元数据。 如果集群是使用 GKE On-Prem API 客户端创建的，则这是您在创建集群时选择的区域。如果集群是使用gkectl创建的，则这是您在将集群注册到 GKE On-Prem API 中时指定的区域。
获取可用的升级目标版本列表：
gcloud container vmware clusters query-version-config \ --cluster=USER_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION
此命令的输出类似如下所示：
versions: - version: 1.16.3-gke.45 - version: 1.16.2-gke.28 - version: 1.16.1-gke.45 - version: 1.16.0-gke.669 - version: 1.15.6-gke.25 - version: 1.15.5-gke.41 An Anthos version must be made available on the admin cluster ahead of the user cluster creation or upgrade. Versions annotated with isInstalled=true are installed on the admin cluster for the purpose of user cluster creation or upgrade whereas other version are released and will be available for upgrade once dependencies are resolved. To install the version in the admin cluster, run: $ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION您可以忽略版本列表后面的消息。您要升级到的版本是否已安装在管理员集群上并不重要。
upgrade命令会下载并部署与您在upgrade命令中指定的版本匹配的组件软件包。升级集群。 如果您运行
update命令将升级策略更改为control-plane-only=True，则只会升级集群的控制平面。否则，集群的控制平面和所有节点池都会升级。gcloud container vmware clusters upgrade 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。您可以通过在另一个终端窗口中运行以下命令来了解操作的状态：gcloud container vmware operations describe OPERATION_ID \ --project=PROJECT_ID \ --location=REGION
升级节点池
如果您选择仅升级用户集群的控制平面，请在升级用户集群的控制平面后，执行以下步骤以升级节点池：
获取用户集群上的节点池列表：
gcloud container vmware node-pools list --cluster=USER_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION
对于您要升级的每个节点池，请运行以下命令：
gcloud container vmware node-pools update NODE_POOL_NAME \ --cluster=USER_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION \ --version=VERSION
Terraform
更新 Google Cloud CLI 组件：
gcloud components update在 GKE On-Prem API 中注册管理员集群（如果尚未注册）。在 GKE On-Prem API 中注册集群后，您无需再次执行此步骤。
获取可用的升级目标版本列表：
gcloud container vmware clusters query-version-config \ --cluster=USER_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION
请替换以下内容：
USER_CLUSTER_NAME：用户集群的名称。PROJECT_ID：用户集群所属的舰队项目的 ID。这是您在创建集群时指定的项目。如果您的集群是使用gkectl创建的，则这是集群配置文件的gkeConnect.projectID字段中的项目 ID。REGION：Google Cloud 区域，GKE On-Prem API 在其中运行并存储其元数据。 在您用于创建用户集群的main.tf文件中，该区域位于集群资源的location字段中。
此命令的输出类似如下所示：
versions: - version: 1.16.3-gke.45 - version: 1.16.2-gke.28 - version: 1.16.1-gke.45 - version: 1.16.0-gke.669 - version: 1.15.6-gke.25 - version: 1.15.5-gke.41 An Anthos version must be made available on the admin cluster ahead of the user cluster creation or upgrade. Versions annotated with isInstalled=true are installed on the admin cluster for the purpose of user cluster creation or upgrade whereas other version are released and will be available for upgrade once dependencies are resolved. To install the version in the admin cluster, run: $ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION下载新版本的组件并将其部署到管理员集群中：
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION \ --required-platform-version=VERSION
此命令会将您在
--required-platform-version中指定版本的组件下载到管理员集群，然后部署组件。 这些组件可让管理员集群管理该版本的用户集群。在用于创建用户集群的
main.tf文件中，将集群资源中的on_prem_version更改为新版本。仅限 Ubuntu 和 COS 节点池：如果您只想升级用户集群的控制平面，并将所有节点池保留在当前版本，请将以下内容添加到集群资源中：
upgrade_policy { control_plane_only = true }初始化并创建 Terraform 方案：
terraform initTerraform 会安装任何所需的库，例如 Google Cloud 提供商。
检查配置，并根据需要进行更改：
terraform plan应用 Terraform 方案以创建用户集群：
terraform apply
升级节点池
如果您选择仅升级用户集群的控制平面，请在升级用户集群的控制平面后，按照以下步骤升级其他节点池：
在要升级的每个节点池的资源的
main.tf中，添加以下内容：on_prem_version = "VERSION"
例如：
resource "google_gkeonprem_vmware_node_pool" "nodepool-basic" { name = "my-nodepool" location = "us-west1" vmware_cluster = google_gkeonprem_vmware_cluster.default-basic.name config { replicas = 3 image_type = "ubuntu_containerd" enable_load_balancer = true } on_prem_version = "1.16.0-gke.0" }初始化并创建 Terraform 方案：
terraform init检查配置，并根据需要进行更改：
terraform plan应用 Terraform 方案以创建用户集群：
terraform apply
升级管理员集群
升级用户集群后，您可以升级管理员集群。
准备工作：
如果您要升级到 1.13 版或更高版本，则必须先填写管理员集群配置文件中的
gkeConnect部分来注册管理员集群。根据配置文件更改运行gkectlupdate cluster 命令。请确保您的
gkectl和集群是适合进行升级的版本，并且您已下载合适的软件包。管理员集群与用户集群之间的版本偏差取决于 Google Distributed Cloud 版本。如需确保您可以升级管理员集群，请参阅管理员集群和用户集群版本偏差。确保管理员集群配置文件中的
bundlepath字段与您要升级到的软件包的路径相匹配。如果您对管理员集群配置文件中的字段进行了其他任何更改，则升级期间会忽略这些更改。如需使这些更改生效，您必须先升级集群，然后根据配置文件更改运行 update cluster 命令，以对集群进行其他更改。
运行 gkectl upgrade admin
请在管理员工作站上执行本部分中的步骤。 gkectl upgrade admin 命令有两个变体：
异步：
使用异步变体时，该命令会开始升级，然后完成。在升级的整个过程中，您无需观察该命令的输出。您可以通过运行gkectl list admin和gkectl describe admin来定期检查升级进度。如需使用异步变体，请在该命令中添加--async标志。异步升级的要求：
- 仅支持版本为 1.29 或更高版本的高可用性管理员集群。
- 所有用户集群都必须启用 Controlplane V2。
同步：
在同步变体中，gkectl upgrade admin命令会在升级过程中向管理员工作站输出状态消息。
异步升级
在管理员工作站上，启动异步升级：
gkectl upgrade admin \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config ADMIN_CLUSTER_CONFIG_FILE \ --async
替换以下内容：
ADMIN_CLUSTER_KUBECONFIG：管理员集群的 kubeconfig 文件的路径。ADMIN_CLUSTER_CONFIG_FILE：管理员集群配置文件的路径。
上述命令完成后，您便可以在升级过程中继续使用您的管理员工作站。
使用
gkectl upgrade admin，运行以下命令：gkectl upgrade admin -h如需查看升级的状态，请运行以下命令：
gkectl list admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
输出会显示集群
STATE的值。如果集群仍在升级，则STATE的值为UPGRADING。例如：NAME STATE AGE VERSION gke-admin-test UPGRADING 9h 1.30.100-gke.96
STATE的可能值包括RUNNING、UPGRADING、RECONCILING、ERROR和UNKNOWN。如需获取有关升级进度和集群事件的详细信息，请运行以下命令：
gkectl describe admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
输出会显示指定管理员集群的 OnPremAdminCluster 自定义资源，其中包括集群状态、条件和事件。
我们记录了每个关键升级阶段的开始和结束的事件。
输出示例：
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal ControlPlaneUpgradeStarted 40m onprem-admin-cluster-controller Creating or updating admin cluster API Controller Normal ControlPlaneMachineUpgradeStarted 40m onprem-admin-cluster-controller Creating or updating control plane machine Normal StatusChanged 40m onprem-admin-cluster-controller OnPremAdminCluster status changed: - New ClusterState condition: UPGRADING - New Ready condition: False, CreateOrUpdateControlPlaneMachine, Creating or updating control plane machine Normal StatusChanged 2m onprem-admin-cluster-controller OnPremAdminCluster status changed: - New ClusterState condition: RUNNING - New Ready condition: True, ClusterRunning, Cluster is running升级完成后，
gkectl list admin会显示STATUS为RUNNING：NAME STATE AGE VERSION gke-admin-test RUNNING 9h 1.30.100-gke.96此外，升级完成后，
gkectl describe admin会在Status下显示一个Last GKE On Prem Version字段。例如：Status: Cluster State: RUNNING Last GKE On Prem Version: 1.30.0-gke.1
排查异步升级问题
对于异步升级，超时时长取决于集群中的节点数。如果升级花费的时间超过超时时长，则集群状态会从 UPGRADING 更改为 ERROR，并且事件表示升级操作超时。请注意，此处的 ERROR 状态表示升级花费的时间超过预期，但尚未终止。控制器会继续进行协调，并不断重试操作。当升级被阻止或失败时，您可以运行 gkectl diagnose 来检查是否存在常见的集群问题。根据检查结果，您可以决定是执行手动修复，还是联系 Google Cloud 支持团队以获取进一步帮助。
同步升级
运行以下命令：
gkectl upgrade admin \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config ADMIN_CLUSTER_CONFIG_FILE \
替换以下内容：
ADMIN_CLUSTER_KUBECONFIG：管理员集群 kubeconfig 文件的路径。ADMIN_CLUSTER_CONFIG_FILE：管理员集群配置文件的路径。
gkectl upgrade命令运行预检检查。如果预检检查失败，则该命令会被屏蔽。您必须修复失败，或在命令中使用--skip-preflight-check-blocking标志来取消屏蔽命令。如果您要升级到 1.14.0 版或更高版本，系统会为管理员集群生成新的 kubeconfig 文件，该文件会覆盖任何现有文件。如需查看此文件中的集群详情，请运行以下命令：
kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG
移除整个软件包
如果您下载了整个软件包，而且已成功运行 gkectl prepare 和 gkectl upgrade admin 命令，您应删除整个软件包以节省管理员工作站上的磁盘空间。运行以下命令以删除整个软件包：
rm /var/lib/gke/bundles/gke-onprem-vsphere-${TARGET_VERSION}-full.tgz
恢复管理员集群升级
管理员集群升级中断或失败时，如果管理员集群检查点包含恢复中断之前状态所需的状态，则可以继续升级。
警告：升级失败后，请勿使用 gkectl repair admin-master 修复管理员主节点。这将导致管理员集群进入错误状态。
请按照以下步骤操作：
在开始初始升级尝试之前，检查管理员控制平面的运行状况是否良好。请参阅诊断集群问题。如该主题中所述，为管理员集群运行
gkectl diagnose cluster命令。如果管理员控制平面在初始升级尝试之前运行状况不佳，请使用
gkectl repair admin-master命令修复管理员控制平面。在升级中断或失败后重新运行升级命令时，请使用与之前的升级尝试相同的软件包和目标版本。
重新运行升级命令时，恢复的升级会从检查点重新创建管理员集群状态，并重新运行整个升级。从 1.12.0 开始，如果管理员控制平面健康状况不佳，升级过程将直接升级到目标版本，而不会在继续升级之前尝试恢复源版本的管理员集群。
从管理员集群故障可用或退出的位置恢复升级。如果该检查点不可用，则升级将回退到依赖于管理员控制平面，因此管理员控制平面必须运行状况良好才能继续升级。成功升级后，系统会重新生成检查点。
如果 gkectl 在管理员集群升级期间意外退出，则系统不会清理种类集群。在重新运行升级命令以恢复升级之前，请删除种类集群：
docker stop gkectl-control-plane && docker rm gkectl-control-plane
删除种类集群后，再次运行升级命令。
升级后回滚管理员工作站
您可以将管理员工作站回滚到升级前使用的版本。
升级期间，gkeadm 会在输出信息文件中记录升级之前的版本。在回滚期间，gkeadm 会使用列出的版本下载较旧的文件。
如需将管理员工作站回滚到之前的版本，请执行以下操作：
gkeadm rollback admin-workstation --config=AW_CONFIG_FILE
如果您的管理员工作站配置文件是默认的 admin-ws-config.yaml，则可以省略 --config=AW_CONFIG_FILE。否则，请将 AW_CONFIG_FILE 替换为管理员工作站配置文件的路径。
回滚命令会执行以下步骤：
- 下载
gkeadm的回滚版本。 - 备份当前管理员工作站的主目录。
- 使用
gkeadm的回滚版本创建新的管理员工作站。 - 删除原始管理员工作站。
安装其他版本的软件包以进行升级
如果您要升级工作站，则系统会安装具有相应版本的软件包以升级集群。如果您要使用其他版本，请按照以下步骤安装 TARGET_VERSION（即您要升级到的版本）的软件包。
如需查看当前的
gkectl和集群版本，请运行以下命令。如需查看详细信息，请使用--details/-d标志。gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
输出会提供集群版本的相关信息。
根据获得的输出结果查找以下问题，并视需要修复问题。
如果当前管理员集群版本比 TARGET_VERSION 低多个次要版本，请将所有集群升级到比 TARGET_VERSION 低一个次要版本。
如果
gkectl版本低于 1.11，并且您想要升级到 1.12.x，则必须执行多次升级。一次升级一个次要版本，直到升级到 1.11.x，然后按照本主题中的说明操作。如果
gkectl版本低于 TARGET_VERSION，请将管理员工作站升级到 TARGET_VERSION。
当您确定
gkectl和集群版本适合升级时，请下载软件包。检查管理员工作站上是否已存在软件包 tar 压缩包。
stat /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz
如果软件包不在管理员工作站上，请下载它。
gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz /var/lib/gke/bundles/
安装软件包。
gkectl prepare --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz --kubeconfig ADMIN_CLUSTER_KUBECONFIG
将 ADMIN_CLUSTER_KUBECONFIG 替换为您的 kubeconfig 文件的路径。 如果文件位于当前目录中且名称为
kubeconfig，则可以省略此标志。列出可用的集群版本，并确保目标版本包含在可用的用户集群版本中。
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
现在，您可以创建目标版本的用户集群，也可以将用户集群升级到目标版本。
升级流程问题排查
如果您在使用推荐的升级流程时遇到问题，请按照以下建议解决问题。这些建议假设您是从 1.11.x 设置开始，并且执行了推荐的升级流程。
另请参阅排查集群创建和升级问题。
排查用户集群升级问题
假设您在升级用户集群时发现升级版本存在问题。您从 Google 支持获知，该问题会在即将发布的补丁程序版本中得到解决。您可以按以下步骤操作：
- 继续在生产环境中使用当前版本。
- 在补丁程序版本发布后，在非生产集群中测试该补丁程序版本。
- 当您确信补丁程序版本可靠后，将所有生产用户集群升级到该补丁程序版本。
- 将管理员集群升级到该补丁程序版本。
排查管理员集群升级问题
如果您在升级管理员集群时遇到问题，则必须与 Google 支持团队联系以解决管理员集群相关问题。
同时，借助新的升级流程，您仍然可以利用新用户集群功能，而不受管理员集群升级的影响。这使您可以根据需要降低管理员集群的升级频率。您的升级流程可以按如下所示进行：
- 将生产用户集群升级到 1.12.x。
- 将管理员集群保持为早期版本，并继续接收安全补丁程序。
- 在测试环境中测试管理员集群从 1.11.x 升级到 1.12.x，如果出现问题则报告问题；
- 如果您的问题在 1.12.x 补丁程序版本中得到解决，则可以选择将生产管理员集群升级到该补丁程序版本（如果需要）。
当前版本的已知问题
如果您从 1.7 版或更高版本升级，以下已知问题可能会影响升级。
另请参阅已知问题。
如果数据磁盘几乎已满，则升级管理员工作站可能会失败
如果您使用 gkectl upgrade admin-workstation 命令升级管理员工作站，则当数据磁盘几乎已满时，升级可能会失败，因为系统会在升级到新的管理员工作站时尝试在本地备份当前的管理员工作站。如果无法清除数据磁盘上的足够空间，请使用带有附加标志 --backup-to-local=false 的 gkectl upgrade admin-workstation 命令来防止对当前管理工作站进行本地备份。
使用 PodDisruptionBudget 的工作负载中断
目前，升级集群可能会导致使用 PodDisruptionBudgets (PDB) 的工作负载中断或停机。
节点无法完成升级过程
如果您配置的 PodDisruptionBudget 对象无法允许任何额外的中断，则节点升级可能会在反复尝试后仍无法升级到控制平面版本。为防止此故障，我们建议您扩容 Deployment 或 HorizontalPodAutoscaler，以允许节点排空，同时仍遵循 PodDisruptionBudget 配置。
如需查看不允许出现任何中断的所有 PodDisruptionBudget 对象，请运行以下命令：
kubectl get poddisruptionbudget --all-namespaces -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.name}/{.metadata.namespace}{"\n"}{end}'
附录
关于在 1.1.0-gke.6 版本中启用的 VMware DRS 规则
从 1.1.0-gke.6 版开始，Google Distributed Cloud 会自动为您的用户集群节点创建 VMware 分布式资源调度器 (DRS) 反亲和性规则，使其分布到数据中心内的至少三个物理主机上。从 1.1.0-gke.6 版开始，此功能会自动为新集群和现有集群启用。
在升级之前，请确保您的 vSphere 环境满足以下条件：
VMware DRS 已启用。VMware DRS 需要 vSphere Enterprise Plus 许可版本。如需了解如何启用 DRS，请参阅在集群中启用 VMware DRS
凭据配置文件中提供的 vSphere 用户名具有
Host.Inventory.EditCluster权限。至少有三个物理主机可用。
如果 vSphere 环境不满足上述条件，您仍然可以升级，但如果要将用户集群从 1.3.x 升级到 1.4.x，则需要停用反亲和性群组。如需了解详情，请参阅 Google Distributed Cloud 版本说明中的此已知问题。
关于升级过程中的停机时间
| 资源 | 说明 |
|---|---|
| 管理员集群 | 当管理员集群关停时，用户集群上的用户集群控制平面和工作负载会继续运行，除非它们受到导致停机的故障的影响。 |
| 用户集群控制平面 | 通常情况下，用户集群控制层面应该不会出现较长的停机时间。但是，与 Kubernetes API 服务器的长时间运行的连接可能会中断，需要重新建立连接。在这些情况下，API 调用方应该重试，直到建立连接。在最糟糕的情况下，升级期间的停机时间可能长达一分钟。 |
| 用户集群节点 | 如果升级需要更改用户集群节点，Google Distributed Cloud 会以滚动方式重新创建节点，并重新安排在这些节点上运行的 Pod。您可以通过配置适当的 PodDisruptionBudgets 和反亲和性规则来防止对工作负载产生影响。 |
如果信息文件缺失则重新创建
如果管理员工作站的输出信息文件缺失，则必须重新创建此文件，以便继续升级。此文件是在您最初创建工作站时创建的；如果您在之后进行了升级，则系统会使用新信息对此文件进行更新。
输出信息文件采用以下格式：
Admin workstation version: GKEADM_VERSION Created using gkeadm version: GKEADM_VERSION VM name: ADMIN_WS_NAME IP: ADMIN_WS_IP SSH key used: FULL_PATH_TO_ADMIN_WS_SSH_KEY To access your admin workstation: ssh -i FULL-PATH-TO-ADMIN-WS-SSH-KEY ubuntu@ADMIN-WS-IP
下面是一个输出信息文件示例：
Admin workstation version: v1.10.3-gke.49 Created using gkeadm version: v1.10.3-gke.49 VM name: admin-ws-janedoe IP: 172.16.91.21 SSH key used: /usr/local/google/home/janedoe/.ssh/gke-admin-workstation Upgraded from (rollback version): v1.10.0-gke.194 To access your admin workstation: ssh -i /usr/local/google/home/janedoe/.ssh/gke-admin-workstation ubuntu@172.16.91.21
在编辑器中创建文件，并替换相应的参数。使用与 gkeadm 运行所在目录中的虚拟机名称相同的文件名保存该文件。例如，如果虚拟机名称为 admin-ws-janedoe，请将文件保存为 admin-ws-janedoe。
后续步骤
gcloud CLI 参考文档
Terraform 参考文档