本页面介绍了如何升级 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 版。
升级流程概述
下载
gkeadm工具。gkeadm的版本必须与升级的目标版本相同。使用
gkeadm升级管理员工作站。在管理员工作站上，升级管理员集群。
在管理员工作站上，升级用户集群。
升级政策
升级管理员集群后，请执行以下操作：
您创建的任何新用户集群的版本必须与管理员集群的版本相同。
如果要升级现有用户集群，您必须升级到与管理员集群相同的版本。
在再次升级管理员集群之前，必须将所有用户集群升级到与当前管理员集群相同的版本。
找到您的配置文件和信息文件
创建当前管理员工作站时，请填写由 gkeadm create config 生成的管理员工作站配置文件。此文件的默认名称为 admin-ws-config.yaml。
创建当前管理员工作站时，gkeadm 会为您创建一个信息文件。此文件的默认名称与您当前管理员工作站的名称相同。
找到您的管理员工作站配置文件和信息文件。您需要它们来完成本指南中的步骤。如果这些文件在当前目录中并且具有默认名称，则运行 gkeadm upgrade admin-workstation 时无需指定它们。如果这些文件位于其他目录中，或者您更改了文件名，则可以使用 --config 和 --info-file 标志进行指定。
升级管理员工作站
如需升级管理员工作站，请先下载新版 gkeadm 工具，然后使用该工具升级管理员工作站的配置。gkeadm 的版本必须与升级的目标版本相匹配。
下载 gkeadm
如需下载当前版本的 gkeadm，请按照下载页面上的 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 地址可供集群使用。 您可以根据需要预留更多 IP，如 DHCP 和静态 IP 部分中所述。
DHCP
升级管理员集群时，GKE On-Prem 会在管理员集群中创建一个临时节点。升级用户集群时，GKE On-Prem 会在该用户集群中创建一个临时节点。临时节点的目的是确保不间断的可用性。在升级集群之前，请确保您的 DHCP 服务器可以为临时节点提供足够的 IP 地址。如需了解详情，请参阅管理员集群和用户集群所需的 IP 地址。
静态 IP
升级管理员集群时，GKE On-Prem 会在管理员集群中创建一个临时节点。升级用户集群时，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 的块。
重要提示：从 1.5.0 开始，此步骤不适用于用户集群，并且您必须为每个集群使用 gkectl update cluster。
要确定用户集群中的节点数量，请运行以下命令：
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] 是用户集群的名称。
预留的 IP 地址的数量应大于用户集群中的节点数。如果不是这种情况，您可以打开用户集群的 hostconfig 文件进行修改：
如果为用户集群预留的任何地址包含在 hostconfig 文件中，请基于
netmask和gateway将地址添加到相应的块中。将所需数量的额外静态 IP 地址添加到相应的块中，然后运行 gkectl update cluster。
（可选）停用新的 vSphere 功能
新的 GKE On-Prem 版本可能包含新的功能或对特定 VMware vSphere 功能的支持。有时，升级至某个 GKE On-Prem 版本会自动启用此类功能。如需了解新功能，请参阅 GKE On-Prem 的版本说明。新功能有时会通过 GKE On-Prem 配置文件提供。
如需停用在新的 GKE On-Prem 版本中自动启用和由配置文件驱动的新功能，请在升级集群之前执行以下步骤：
从升级后的管理员工作站中创建一个新的配置文件，并使用与当前配置文件不同的名称：
gkectl create-config --config [CONFIG_NAME]
打开新配置文件并记下该功能的字段。关闭文件。
打开当前配置文件并添加新功能的字段。将字段的值设置为
false或等效值。保存配置文件。
升级集群之前，请查看版本说明。升级后，您将无法以声明方式更改现有集群的配置。
升级管理员集群
请在新的管理员工作站上执行本部分中的步骤。
回想一下，升级的目标版本必须与 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 命令：
访问 Google Cloud 控制台中的 GKE 菜单。
在用户集群的通知列下，点击现在可升级（如有）。
复制
gkectl upgrade cluster命令。从管理员工作站运行
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.kubectlredirecturlusercluster.oidc.clientsecretusercluster.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 环境满足以下条件：
- VMware DRS 已启用。VMware DRS 需要 vSphere Enterprise Plus 许可版本。如需了解如何启用 DRS，请参阅在集群中启用 VMware DRS
- 在
vcenter字段中提供的 vSphere 用户帐号拥有Host.Inventory.EditCluster权限。 - 至少有三个物理主机可用。
如果 vSphere 环境不满足上述条件，您仍然可以升级，但如果要将用户集群从 1.3.x 升级到 1.4.x，则需要停用反亲和性群组。如需了解详情，请参阅 GKE On-Prem 版本说明中的已知问题。
停机时间
关于升级过程中的停机时间
| 资源 | 说明 |
|---|---|
| 管理员集群 | 当管理员集群关闭时，用户集群上的用户集群控制层面和工作负载会继续运行，除非它们受到导致停机的故障的影响 |
| 用户集群控制层面 | 通常情况下，用户集群控制层面应该不会出现较长的停机时间。但是，与 Kubernetes API 服务器的长时间运行的连接可能会中断，需要重新建立连接。在这些情况下，API 调用方应该重试，直到建立连接。在最糟糕的情况下，升级期间的停机时间可能长达一分钟。 |
| 用户集群节点 | 如果升级需要更改用户集群节点，GKE On-Prem 会以滚动方式重新创建节点，并重新安排在这些节点上运行的 pod。您可以通过配置适当的 PodDisruptionBudget 和反亲和性规则来防止对工作负载产生影响。 |
问题排查
如需了解详情，请参阅问题排查。
使用 gkectl 诊断集群问题
使用 gkectl diagnose 命令识别集群问题并与 Google 共享集群信息。请参阅诊断集群问题。
默认日志记录行为
对于 gkectl 和 gkeadm，使用默认日志记录设置便已足够：
-
默认情况下，日志条目的保存方式如下：
- 对于
gkectl，默认日志文件为/home/ubuntu/.config/gke-on-prem/logs/gkectl-$(date).log，该文件与运行gkectl的本地目录中的logs/gkectl-$(date).log文件进行符号链接。 - 对于
gkeadm，默认日志文件是运行gkeadm的本地目录中的logs/gkeadm-$(date).log。
- 对于
- 所有日志条目都会保存在日志文件中，即使它们不输出到终端（当
--alsologtostderr为false时）也是如此。 -v5详细程度（默认）涵盖支持团队所需的所有日志条目。- 日志文件还包含已执行的命令和失败消息。
我们建议您在需要帮助时将日志文件发送给支持团队。
为日志文件指定非默认位置
要为 gkectl 日志文件指定非默认位置，请使用 --log_file 标志。您指定的日志文件不会与本地目录进行符号链接。
要为 gkeadm 日志文件指定非默认位置，请使用 --log_file 标志。
在管理员集群中查找 Cluster API 日志
如果虚拟机在管理员控制层面启动后无法启动，您可以通过在管理员集群中检查 Cluster API 控制器的日志来尝试进行调试：
在
kube-system命名空间中找到 Cluster API 控制器 pod 的名称，其中 [ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件的路径：kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system get pods | grep clusterapi-controllers
打开 pod 的日志，其中 [POD_NAME] 是 pod 的名称。您可以选择使用
grep或类似工具来搜索错误：kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system logs [POD_NAME] vsphere-controller-manager