升级 GKE On-Prem

本页面介绍了如何升级 GKE On-Prem。

目标版本

从 GKE On-Prem 1.3.2 版开始，您可以直接升级到同一或下一次要发布版本中的任何版本。例如，您可以从 1.3.2 升级到 1.3.5，或从 1.5.2 升级到 1.6.1。

如果当前版本低于 1.3.2，则必须先依序升级到 1.3.2 版。例如，如需从 1.3.0 升级到 1.3.2，您必须先从 1.3.0 升级到 1.3.1，然后再从 1.3.1 升级到 1.3.2。

如果您要从 1.3.2 版或更高版本升级到非下一个次要版本，则必须在当前版本和所需版本之间升级每个次要版本的一个版本。例如，如果您要从 1.3.2 版升级到 1.6.1 版，则无法直接升级。您必须先从 1.3.2 版升级到 1.4.x 版，其中 x 表示该次要版本下的任何补丁程序版本。然后，您可以升级到 1.5.x 版，最后升级到 1.6.1 版。

升级流程概述

  1. 下载 gkeadm 工具。gkeadm 的版本必须与升级的目标版本相同。

  2. 使用 gkeadm 升级管理员工作站。

  3. 在管理员工作站上，升级管理员集群。

  4. 在管理员工作站上，升级用户集群。

升级政策

升级管理员集群后，请执行以下操作：

  • 您创建的任何新用户集群的版本必须与管理员集群的版本相同。

  • 如果要升级现有用户集群，您必须升级到与管理员集群相同的版本。

  • 在再次升级管理员集群之前，必须将所有用户集群升级到与当前管理员集群相同的版本。

找到您的配置文件和信息文件

创建当前管理员工作站时，请填写由 gkeadm create config 生成的管理员工作站配置文件。此文件的默认名称为 admin-ws-config.yaml。

创建当前管理员工作站时，gkeadm 会为您创建一个信息文件。此文件的默认名称与您当前管理员工作站的名称相同。

找到您的管理员工作站配置文件和信息文件。您需要它们来完成本指南中的步骤。如果这些文件在当前目录中并且具有默认名称，则运行 gkeadm upgrade admin-workstation 时无需指定它们。如果这些文件位于其他目录中，或者您更改了文件名，则可以使用 --config 和 --info-file 标志进行指定。

升级管理员工作站

如需升级管理员工作站，请先下载新版 gkeadm 工具，然后使用该工具升级管理员工作站的配置。gkeadm 的版本必须与升级的目标版本相匹配。

下载 gkeadm

如需下载当前版本的 gkeadm，请按照 GKE On-Prem 页面上的 gkeadm 下载说明执行操作。

升级管理员工作站配置

gkeadm upgrade admin-workstation --config [AW_CONFIG_FILE] --info-file [INFO_FILE]

其中：

  • [AW_CONFIG_FILE] 是管理员工作站配置文件的路径。如果文件位于当前目录中且名称为 admin-ws-config.yaml，则可以省略此标志。

  • [INFO_FILE] 是信息文件的路径。如果文件位于当前目录中，则可以省略此标志。此文件的默认名称与管理员工作站的名称相同。

上述命令会执行以下任务：

  • 备份当前管理员工作站的主目录中的所有文件。其中包括：

    • 您的 GKE On-Prem 配置文件。此文件的默认名称为 config.yaml。

    • 管理员集群和用户集群的 kubeconfig 文件。

    • vCenter 服务器的根证书。请注意，此文件必须具有所有者读写权限。

    • 已列入许可名单的服务帐号的 JSON 密钥文件。请注意，此文件必须具有所有者读写权限。

    • 用于连接和注册、连接和代理以及日志记录监控服务帐号的 JSON 密钥文件。

  • 创建新的管理员工作站，并将所有备份文件复制到新的管理员工作站。

  • 删除旧的管理员工作站。

从 known_hosts 中移除旧的管理员工作站

如果管理员工作站具有静态 IP 地址，则需要在升级管理员工作站后从 known_hosts 文件中移除旧的管理员工作站。

如需从 known_hosts 中移除旧管理员工作站，请执行以下操作：

ssh-keygen -R [ADMIN_WS_IP]

其中，[ADMIN_WS_IP] 是您的管理员工作站的 IP 地址。

在 GKE On-Prem 配置文件中设置软件包路径

在新的管理员工作站上，打开 GKE On-Prem 配置文件。将 bundlepath 的值设置为新管理员工作站上软件包文件的路径：

bundlepath: "/var/lib/gke/bundles/gke-onprem-vsphere-[VERSION]-full.tgz"

其中，[VERSION] 是升级的目标版本。

更新节点操作系统映像和 Docker 映像

在新的管理员工作站上，运行以下命令：

gkectl prepare --config [CONFIG_FILE] [FLAGS]

其中：

  • [CONFIG_FILE] 是新管理员工作站上的 GKE On-Prem 配置文件。

  • [FLAGS] 是一组可选的标志。例如，您可以添加 --skip-validation-infra 标志以跳过检查 vSphere 基础架构这一步。

上述命令会执行以下任务：

  • 如有必要，请将新的节点操作系统映像复制到 vSphere 环境，并将操作系统映像标记为模板。

  • 如果您已配置了私有 Docker 注册表，请将更新后的 Docker 映像推送到私有 Docker 注册表。

验证是否有足够的可用 IP 地址

请在新的管理员工作站上执行本部分中的步骤。

在升级之前，请确保您有足够的 IP 地址可供集群使用。

DHCP

在升级期间，GKE On-Prem 会在管理员集群中创建一个临时节点，并在每个关联的用户集群中创建一个临时节点。请确保您的 DHCP 服务器可以为这些临时节点提供足够的 IP 地址。如需了解详情，请参阅管理员集群和用户集群所需的 IP 地址。

静态 IP 地址

在升级期间，GKE On-Prem 会在管理员集群中创建一个临时节点，并在每个关联的用户集群中创建一个临时节点。请验证您是否已为管理员集群和每个用户集群预留足够的 IP 地址。对于每个集群，您预留的 IP 地址数量应至少比集群节点数量多一个。如需了解详情，请参阅配置静态 IP 地址。

确定管理员集群中的节点数量：

kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] get nodes

其中，[ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件的路径。

接下来，查看为管理员集群预留的地址：

kubectl get cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -o yaml

在输出中，您可以在 reservedAddresses 字段中查看为管理员集群节点预留的 IP 地址数。例如，以下输出显示为管理员集群节点预留了五个 IP 地址：

...
reservedAddresses:
- gateway: 21.0.135.254
  hostname: admin-node-1
  ip: 21.0.133.41
  netmask: 21
- gateway: 21.0.135.254
  hostname: admin-node-2
  ip: 21.0.133.50
  netmask: 21
- gateway: 21.0.135.254
  hostname: admin-node-3
  ip: 21.0.133.56
  netmask: 21
- gateway: 21.0.135.254
  hostname: admin-node-4
  ip: 21.0.133.47
  netmask: 21
- gateway: 21.0.135.254
  hostname: admin-node-5
  ip: 21.0.133.44
  netmask: 21

预留 IP 地址的数量应至少比管理员集群中的节点数量多一个。否则，您可以通过修改集群对象来预留一个额外的地址。

打开集群对象进行修改：

kubectl edit cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG]

在 reservedAddresses 下，添加一个包含 gateway、hostname、ip 和 netmask 的块。

对每个用户集群执行相同的操作。

要确定用户集群中的节点数量，请运行以下命令：

kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] get nodes

其中，[USER_CLUSTER_KUBECONFIG] 是用户集群的 kubeconfig 文件的路径。

要查看为用户集群预留的地址，请运行以下命令：

kubectl get cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
-n [USER_CLUSTER_NAME] [USER_CLUSTER_NAME] -o yaml

其中：

  • [ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件的路径。

  • [USER_CLUSTER_NAME] 是用户集群的名称。

要修改用户集群的集群对象，请运行以下命令：

kubectl edit cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
-n [USER_CLUSTER_NAME] [USER_CLUSTER_NAME]

（可选）停用新的 vSphere 功能

新的 GKE On-Prem 版本可能包含新的功能或对特定 VMware vSphere 功能的支持。有时，升级至某个 GKE On-Prem 版本会自动启用此类功能。如需了解新功能，请参阅 GKE On-Prem 的版本说明。新功能有时会通过 GKE On-Prem 配置文件提供。

如需停用在新的 GKE On-Prem 版本中自动启用和由配置文件驱动的新功能，请在升级集群之前执行以下步骤：

  1. 从升级后的管理员工作站中创建一个新的配置文件，并使用与当前配置文件不同的名称：

    gkectl create-config --config [CONFIG_NAME]

  2. 打开新配置文件并记下该功能的字段。关闭文件。

  3. 打开当前配置文件并添加新功能的字段。将字段的值设置为 false 或等效值。

  4. 保存配置文件。

升级集群之前，请查看版本说明。升级后，您将无法以声明方式更改现有集群的配置。

升级管理员集群

请在新的管理员工作站上执行本部分中的步骤。

回想一下，升级的目标版本必须与 gkeadm 版本相同。

运行以下命令：

gkectl upgrade admin \
--kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
--config [ADMIN_CLUSTER_CONFIG_FILE] \
[FLAGS]

其中：

  • [ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件。

  • [ADMIN_CLUSTER_CONFIG_FILE] 是新管理员工作站上的 GKE On-Prem 管理员集群配置文件。

  • [FLAGS] 是一组可选的标志。例如，您可以添加 --skip-validation-infra 标志以跳过检查 vSphere 基础架构这一步。

升级用户集群

请在新的管理员工作站上执行本部分中的步骤。

回想一下，升级的目标版本必须与 gkeadm 版本相同。

gkectl

gkectl upgrade cluster \
--kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
--config [USER_CLUSTER_CONFIG_FILE] \
--cluster-name [CLUSTER_NAME] \
[FLAGS]

其中：

  • [ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件。

  • [CLUSTER_NAME] 是您要升级的用户集群的名称。

  • [USER_CLUSTER_CONFIG_FILE] 是新管理员工作站上的 GKE On-Prem 用户集群配置文件。

  • [FLAGS] 是一组可选的标志。例如，您可以添加 --skip-validation-infra 标志以跳过检查 vSphere 基础架构这一步。

控制台

您可以选择在用户集群安装期间或创建后向 Google Cloud 控制台注册用户集群。您可以从 Google Cloud 控制台的 GKE 菜单查看并登录到已注册的 GKE On-Prem 集群和 Google Kubernetes Engine 集群。

当 GKE On-Prem 用户集群有可用的升级时，Google Cloud 控制台中会显示一条通知。点击此通知会显示可用版本的列表以及可用于升级集群的 gkectl 命令：

  1. 访问 Google Cloud 控制台中的 GKE 菜单。

    访问 GKE 菜单

  2. 在用户集群的通知列下，点击现在可升级（如有）。

  3. 复制 gkectl upgrade cluster 命令。

  4. 从管理员工作站运行 gkectl upgrade cluster 命令，其中 [ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件，[CLUSTER_NAME] 是要升级的用户集群的名称和 [USER_CLUSTER_CONFIG_FILE] 是新管理员工作站上的 GKE On-Prem 用户集群配置文件。

恢复升级

管理员集群升级成功后，如果用户集群升级中断，您可以通过运行带有 --skip-validation-all 标志的同一升级命令来恢复用户集群升级：

gkectl upgrade cluster \
--kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
--config [USER_CLUSTER_CONFIG_FILE] \
--cluster-name [CLUSTER_NAME] \
--skip-validation-all

恢复管理员集群升级

您不应中断管理员集群升级。目前，管理员集群升级并非总是可以恢复的。如果管理员集群升级因任何原因中断，您应该联系支持团队寻求帮助。

升级后创建新的用户集群

升级管理员工作站和管理员集群后，您创建的任何新用户集群的版本必须与升级目标版本相同。

已知问题

以下已知问题会影响集群升级。

1.1.0-gke.6、1.2.0-gke.6 版本：stackdriver.proxyconfigsecretname 字段被移除

1.1.0-gke.6 版本中移除了 stackdriver.proxyconfigsecretname 字段。如果配置文件中有该字段，则 GKE On-Prem 的预检检查将返回错误。

要解决此问题，请在升级到 1.2.0-gke.6 之前，从配置文件中删除 proxyconfigsecretname 字段。

Stackdriver 引用旧版本

对于 1.2.0-gke.6 之前的版本，一个已知问题阻止了 Stackdriver 在集群升级后更新其配置。Stackdriver 仍引用旧版本，这会阻止 Stackdriver 接收其遥测流水线的最新功能。此问题可能会导致 Google 支持人员难以排查集群问题。

将集群升级到 1.2.0-gke.6 后，请对管理员集群和用户集群运行以下命令：

kubectl --kubeconfig=[KUBECONFIG] \
-n kube-system --type=json patch stackdrivers stackdriver \
-p '[{"op":"remove","path":"/spec/version"}]'

其中，[KUBECONFIG] 是集群的 kubeconfig 文件的路径。

使用 PodDisruptionBudgets 的工作负载中断

目前，升级集群可能会导致使用 PodDisruptionBudget (PDB) 的工作负载中断或停机。

1.2.0-gke.6 版本：升级后 Prometheus 和 Grafana 被停用

在用户集群中，升级时会自动停用 Prometheus 和 Grafana。不过，配置和指标数据不会丢失。在管理员集群中，Prometheus 和 Grafana 保持启用状态。

如需了解相关说明，请参阅 GKE On-Prem 版本说明。

1.1.2-gke.0 版本：已删除的用户集群节点未从 vSAN 数据存储区中移除

如需了解相关说明，请参阅 GKE On-Prem 版本说明。

1.1.1-gke.2 版本：vSAN 数据存储区文件夹中的数据磁盘可以被删除

如果您使用的是 vSAN 数据存储区，则需要创建一个文件夹来保存 VMDK。已知问题要求您向 vcenter.datadisk 提供文件夹的通用唯一标识符 (UUID) 路径，而不是文件路径。这种不匹配可能会导致升级失败。

如需了解相关说明，请参阅 GKE On-Prem 版本说明。

从 1.0.2-gke.3 版本升级到 1.1.0-gke.6 版本：OIDC 问题

配置了 OpenID Connect (OIDC) 的 1.0.11、1.0.1-gke.5、1.0.2-gke.3 版本集群无法升级到版本 1.1.0-gke.6。此问题在 1.1.1-gke.2 版本中已得到解决。

如果您在安装过程中配置了使用 OIDC 的 1.0.11、1.0.1-gke.5 或 1.0.2-gke.3 版本集群，则无法对其进行升级。您应改为创建新集群。

从 1.0.11 版本升级到 1.0.2-gke.3 版本

1.0.2-gke.3 版本引入了以下 OIDC 字段 (usercluster.oidc)。这些字段允许从 Google Cloud 控制台登录集群：

  • usercluster.oidc.kubectlredirecturl
  • usercluster.oidc.clientsecret
  • usercluster.oidc.usehttpproxy

如果要使用 OIDC，即使您不想从 Google Cloud 控制台登录集群，也必须填写 clientsecret 字段。为了使用 OIDC，您可能需要为 clientsecret 提供一个占位值：

oidc:
  clientsecret: "secret"

节点无法完成升级过程

如果您配置的 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 版开始，GKE On-Prem 会自动为您的用户集群节点创建 VMware 分布式资源调度器 (DRS) 反亲和性规则，使其分布到数据中心内的至少三个物理主机上。从 1.1.0-gke.6 版开始，此功能会自动为新集群和现有集群启用。

在升级之前，请确保您的 vSphere 环境满足以下条件：

如果 vSphere 环境不满足上述条件，您仍然可以升级，但如果要将用户集群从 1.3.x 升级到 1.4.x，则需要停用反亲和性群组。如需了解详情，请参阅 GKE On-Prem 版本说明中的已知问题。

停机时间

关于升级过程中的停机时间

资源 说明
管理员集群

当管理员集群关闭时，用户集群上的用户集群控制层面和工作负载会继续运行，除非它们受到导致停机的故障的影响
用户集群控制层面

通常情况下，用户集群控制层面应该不会出现较长的停机时间。但是，与 Kubernetes API 服务器的长时间运行的连接可能会中断，需要重新建立连接。在这些情况下，API 调用方应该重试，直到建立连接。在最糟糕的情况下，升级期间的停机时间可能长达一分钟。
用户集群节点

如果升级需要更改用户集群节点，GKE On-Prem 会以滚动方式重新创建节点，并重新安排在这些节点上运行的 pod。您可以通过配置适当的 PodDisruptionBudget 和反亲和性规则来防止对工作负载产生影响。

问题排查

如需了解详情，请参阅问题排查。

已创建新节点，但运行状况不佳

表现

在使用手动负载平衡模式时，新节点不会自行向用户集群控制层面注册。

可能的原因

可能启用了节点内 Ingress 验证，导致节点的启动流程被阻止。

解决方法

如需停用验证，请运行以下命令：

kubectl patch machinedeployment [MACHINE_DEPLOYMENT_NAME] -p '{"spec":{"template":{"spec":{"providerSpec":{"value":{"machineVariables":{"net_validation_ports": null}}}}}}}' --type=merge

使用 gkectl 诊断集群问题

使用 gkectl diagnose 命令识别集群问题并与 Google 共享集群信息。请参阅诊断集群问题。

以 verbose 模式运行 gkectl 命令

-v5

将 gkectl 错误记录到 stderr

--alsologtostderr

在管理员工作站中查找 gkectl 日志

即使未传入其调试标志，您也可以在以下管理员工作站目录中查看 gkectl 日志：

/home/ubuntu/.config/gke-on-prem/logs

在管理员集群中查找 Cluster API 日志

如果虚拟机在管理员控制层面启动后无法启动，您可以通过在管理员集群中检查 Cluster API 控制器的日志来尝试进行调试：

  1. 在 kube-system 命名空间中找到 Cluster API 控制器 pod 的名称，其中 [ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件的路径：

    kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system get pods | grep clusterapi-controllers

  2. 打开 pod 的日志，其中 [POD_NAME] 是 pod 的名称。您可以选择使用 grep 或类似工具来搜索错误：

    kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system logs [POD_NAME] vsphere-controller-manager