升级 GKE On-Prem

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

目标版本

从 GKE On-Prem 1.3.2 版开始,您可以直接升级到同一或下一次要发布版本中的任何版本。例如,您可以从 1.3.2 版升级到 1.4.0 版。当 1.4.1 版发布后,您将可以直接从 1.3.2 版升级到 1.4.1 版。

下表显示了可能的直接升级:

当前版本1.4.01.4.11.4.2
1.3.2
1.4.0
1.4.1

如果当前版本低于 1.3.2,则必须执行依序升级。例如,如果您要从 1.2.0 升级到 1.2.2,则必须先从 1.2.0 升级到 1.2.1,然后再从 1.2.1 升级到 1.2.2。

升级流程概述

  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,请按以下步骤操作:

gsutil cp gs://gke-on-prem-release-public/gkeadm/[VERSION]/linux/gkeadm ./
chmod +x gkeadm

其中,[VERSION] 是升级的目标版本。例如,1.5.0-gke.27。

要升级管理员工作站,请执行以下操作:

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 下,添加一个包含 gatewayhostnameipnetmask 的块。

重要提示:从 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 文件中,请基于 netmaskgateway 将地址添加到相应的块中。

  • 将所需数量的额外静态 IP 地址添加到相应的块中,然后运行 gkectl update cluster

(可选)停用新的 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 [CONFIG_FILE] \
[FLAGS]

其中:

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

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

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

升级用户集群

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

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

gkectl

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

其中:

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

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

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

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

Console

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

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

  1. 访问 Cloud Console 中的 GKE 菜单。

    访问 GKE 菜单

  2. 在用户集群的通知列下,点击现在可升级(如有)。

  3. 复制 gkectl upgrade cluster 命令。

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

恢复升级

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

gkectl upgrade cluster \
--kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
--config [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)。这些字段允许从 Cloud Console 登录集群:

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

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

oidc:
  clientsecret: "secret"

节点无法完成升级过程

如果您在集群上安装了 Anthos Service Mesh 或 OSS Istio,用户节点可能会在多次尝试后仍无法升级到控制层面版本,具体取决于 Istio 组件的 PodDisruptionBudget 设置。为避免此故障,我们建议您在升级之前,将 istio-system 命名空间中组件的 Pod 横向自动扩缩的 minReplicas 设置从 1 增加到 2。这样可以确保您始终具有 ASM 控制层面运行实例。

如果您拥有 Anthos Service Mesh 1.5 及更高版本或 OSS Istio 1.5 及更高版本,请运行以下命令:

kubectl patch hpa -n istio-system istio-ingressgateway -p '{"spec":{"minReplicas": 2}}' --type=merge
kubectl patch hpa -n istio-system istiod -p '{"spec":{"minReplicas": 2}}' --type=merge

如果您拥有 Anthos Service Mesh 1.4.x 或 OSS Istio 1.4.x,请运行以下命令:

kubectl patch hpa -n istio-system istio-galley -p '{"spec":{"minReplicas": 2}}' --type=merge
kubectl patch hpa -n istio-system istio-ingressgateway -p '{"spec":{"minReplicas": 2}}' --type=merge
kubectl patch hpa -n istio-system istio-nodeagent -p '{"spec":{"minReplicas": 2}}' --type=merge
kubectl patch hpa -n istio-system istio-pilot -p '{"spec":{"minReplicas": 2}}' --type=merge
kubectl patch hpa -n istio-system istio-sidecar-injector -p '{"spec":{"minReplicas": 2}}' --type=merge

附录

关于在 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反亲和性规则来防止对工作负载产生影响。

问题排查

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

使用 gkectl 诊断集群问题

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

默认日志记录行为

对于 gkectlgkeadm,使用默认日志记录设置便已足够:

  • 默认情况下,日志条目的保存方式如下:

    • 对于 gkectl,默认日志文件为 /home/ubuntu/.config/gke-on-prem/logs/gkectl-$(date).log,该文件与运行 gkectl 的本地目录中的 logs/gkectl-$(date).log 文件进行符号链接。
    • 对于 gkeadm,默认日志文件是运行 gkeadm 的本地目录中的 logs/gkeadm-$(date).log
  • 所有日志条目都会保存在日志文件中,即使它们不输出到终端(当 --alsologtostderrfalse 时)也是如此。
  • -v5 详细程度(默认)涵盖支持团队所需的所有日志条目。
  • 日志文件还包含已执行的命令和失败消息。

我们建议您需要帮助时,将日志文件发送给支持团队。

为日志文件指定非默认位置

要为 gkectl 日志文件指定非默认位置,请使用 --log_file 标志。您指定的日志文件不会与本地目录进行符号链接。

要为 gkeadm 日志文件指定非默认位置,请使用 --log_file 标志。

在管理员集群中查找 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