升级 GKE On-Prem

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

如需升级 GKE On-Prem，请升级管理员工作站。然后升级集群。

准备工作

• 请务必按照说明，从您的本地工作站或笔记本电脑执行操作。不要从现有的管理员工作站中执行这些操作。
• 检查集群的当前版本。
• 查看影响升级的版本说明和已知问题。
• 查看版本。

另外，请仔细阅读以下注意事项：

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

资源	说明
管理员集群	当管理员集群关闭时，用户集群上的用户集群控制层面和工作负载会继续运行，除非它们受到导致停机的故障的影响
用户集群控制层面	通常情况下，用户集群控制层面应该不会出现较长的停机时间。但是，与 Kubernetes API 服务器的长时间运行的连接可能会中断，需要重新建立连接。在这些情况下，API 调用方应该重试，直到建立连接。在最糟糕的情况下，升级期间的停机时间可能长达一分钟。 注意：如果用户集群节点在升级过程中无法访问用户控制层面，则系统不会为集群安排新的工作负载。现有工作负载不受影响。
用户集群节点	如果升级需要更改用户集群节点，GKE On-Prem 会以滚动方式重新创建节点，并重新安排在这些节点上运行的 pod。您可以通过配置适当的 PodDisruptionBudget 和反亲和性规则来防止对工作负载产生影响。

依序升级

GKE On-Prem 支持依序升级，这意味着您要升级的集群必须是最接近的上一个补丁程序版本。

您无法将集群直接从早于上一个补丁程序版本的版本直接升级到最新版本。如果您的集群早于上一个补丁程序版本，则必须通过按顺序逐个升级到每个补丁程序版本来完成升级。

示例

如果您要升级到 1.1.0 版本，并且您的管理员工作站和用户集群运行的是较旧的 1.0.1 版本：

• 1.0.1（最早的版本）
• 1.0.2
• 1.1.0（最新版本）

则您必须执行以下步骤，依次升级到 1.0.2 版本和 1.1.0 版本：

1. 将管理员工作站从 1.0.1 升级到 1.0.2。
2. 将集群从 1.0.1 升级到 1.0.2。
3. 将管理员工作站从 1.0.2 升级到 1.1。
4. 将集群从 1.0.2 升级到 1.1.0。

备份 GKE On-Prem 配置文件和 kubeconfig 文件

当您升级管理员工作站时，Terraform 会删除管理员工作站虚拟机，然后将其替换为升级后的管理员工作站。

在执行管理员工作站升级之前，您必须先备份 GKE On-Prem 配置文件和集群的 kubeconfig 文件。gkectl create cluster 命令创建管理员集群和用户集群的 kubeconfig 文件，分别为 [ADMIN_CLUSTER_KUBECONFIG] 和 [USER_CLUSTER_KUBECONFIG]。请参阅基本安装中的示例。 管理员工作站升级完成后，将这些文件复制到升级后的管理员工作站。

升级管理员工作站

您可以使用 Terraform 来升级管理员工作站。

重要提示：您必须先备份管理员工作站的文件，因为 Terraform 会删除当前的管理员工作站虚拟机，并将其替换为新虚拟机。

升级后的管理员工作站包含以下实体，其版本与管理员工作站的开放虚拟化设备 (OVA) 文件相同：

• gkectl
• 完整软件包

下载 OVA

从下载中，下载您要升级到的目标版本的管理员工作站 OVA 文件。

要下载最新的 OVA，请运行以下命令：

gsutil cp gs://gke-on-prem-release/admin-appliance/1.3.2-gke.1/gke-on-prem-admin-appliance-vsphere-1.3.2-gke.1.{ova,ova.1.sig} ~/

注意：要验证此文件，请参阅使用 openssl 验证 OVA。

将 OVA 导入 vSphere 并将其标记为虚拟机模板

在以下部分中，您将：

1. 创建一些变量，以声明您的 vCenter Server 和 vSphere 环境的元素。
2. 将管理员工作站 OVA 导入 vSphere 并将其标记为虚拟机模板。

为 govc 创建变量

在将管理员工作站 OVA 导入 vSphere 之前，您需要提供一些 govc 变量，用于声明您的 vCenter Server 和 vSphere 环境的元素：

注意：您可以通过登录 vCenter Server 找到其中许多值。

export GOVC_URL=https://[VCENTER_SERVER_ADDRESS]/sdk
export GOVC_USERNAME=[VCENTER_SERVER_USERNAME]
export GOVC_PASSWORD=[VCENTER_SERVER_PASSWORD]
export GOVC_DATASTORE=[VSPHERE_DATASTORE]
export GOVC_DATACENTER=[VSPHERE_DATACENTER]
export GOVC_INSECURE=true

您可以选择使用 vSphere 的默认资源池，也可以创建您自己的资源池：

# If you want to use a resource pool you've configured yourself, export this variable:
export GOVC_RESOURCE_POOL=[VSPHERE_CLUSTER]/Resources/[VSPHERE_RESOURCE_POOL]

# If you want to use vSphere's default resource pool, export this variable instead:
export GOVC_RESOURCE_POOL=[VSPHERE_CLUSTER]/Resources

其中：

• [VCENTER_SERVER_ADDRESS] 是您的 vCenter Server 的 IP 地址或主机名。
• [VCENTER_SERVER_USERNAME] 是在 vCenter Server 上拥有管理员角色或同等权限的帐号的用户名。
• [VCENTER_SERVER_PASSWORD] 是 vCenter Server 帐号的密码。
• [VSPHERE_DATASTORE] 是您在 vSphere 环境中配置的数据存储区的名称。
• [VSPHERE_DATACENTER] 是您在 vSphere 环境中配置的数据中心的名称。
• [VSPHERE_CLUSTER] 是您在 vSphere 环境中配置的集群的名称。
如果使用非默认资源池，则
• [VSPHERE_RESOURCE_POOL] 是您为 vSphere 环境配置的资源池的名称。

将 OVA 导入 vSphere：标准交换器

如果您使用的是 vSphere 标准交换器，请使用此命令将 OVA 导入 vSphere：

govc import.ova -options - ~/gke-on-prem-admin-appliance-vsphere-1.3.2-gke.1.ova <<EOF
{
  "DiskProvisioning": "thin",
  "MarkAsTemplate": true
}
EOF

将 OVA 导入 vSphere：分布式交换器

如果您使用的是 vSphere 分布式交换器，请使用以下命令将 OVA 导入到 vSphere，其中 [YOUR_DISTRIBUTED_PORT_GROUP_NAME] 是您的分布式端口组的名称：

govc import.ova -options - ~/gke-on-prem-admin-appliance-vsphere-1.3.2-gke.1.ova <<EOF
{
  "DiskProvisioning": "thin",
  "MarkAsTemplate": true,
  "NetworkMapping": [
      {
          "Name": "VM Network",
          "Network": "[YOUR_DISTRIBUTED_PORT_GROUP_NAME]"
      }
  ]
}
EOF

为新的管理员工作站虚拟机设置 Terraform 模板变量

在管理员工作站的 TFVARS 文件中，将 vm_template 设置为您要升级到的目标版本。vm_template 的值如下所示，其中 [VERSION] 是 OVA 的版本：

gke-on-prem-admin-appliance-vsphere-[VERSION]

使用 Terraform 升级管理员工作站

要升级管理员工作站，请运行以下命令。此命令会删除当前的管理员工作站虚拟机，并将其替换为已升级的虚拟机：

注意：请确保在运行此命令之前将 OVA 导入 vSphere。

terraform init && terraform apply -auto-approve -input=false

连接到管理员工作站

运行以下命令，以通过 SSH 连接到管理员工作站：

ssh -i ~/.ssh/vsphere_workstation ubuntu@[IP_ADDRESS]

复制备份配置和 kubeconfig 文件

之前您已备份 GKE On-Prem 配置文件和集群的 kubeconfig 文件。现在，您应该将这些文件复制回升级后的管理员工作站。

升级集群

升级管理员工作站并连接到该工作站后，请执行以下步骤：

验证是否有足够的可用 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] is the path of your user cluster's kubeconfig file. 是用户集群的 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]

修改配置文件

在管理员工作站虚拟机上，修改您用于创建管理员集群和用户集群的配置文件。设置 bundlepath 的值，其中 [VERSION] 是您的集群要升级到的 GKE On-Prem 版本：

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

关于自动启用的功能

新的 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. 打开当前的配置文件，并在相应的规范中添加新功能的字段。

4. 为该字段提供 false 或同等效果的值。

5. 保存配置文件。继续升级集群。

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

运行 gkectl prepare

gkectl prepare 命令可执行以下任务：

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

• 将新软件包中指定的已更新 Docker 映像推送到您的私有 Docker 注册表（如果您已配置）。

要执行上述任务，请运行以下命令：

gkectl prepare --config [CONFIG_FILE] [FLAGS]

其中：

• [CONFIG_FILE] 是用于执行升级的 GKE On-Prem 配置文件。

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

升级管理员集群

运行以下命令：

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 基础架构这一步。

升级用户集群

要升级用户集群，管理员集群必须先升级到所需版本或更高版本，然后才能升级用户集群。

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 基础架构这一步。

控制台

您可以选择在用户集群安装期间或创建后向 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] 是要升级的用户集群的名称，[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)。这些字段允许从 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 环境满足以下条件：

• VMware DRS 已启用。VMware DRS 需要 vSphere Enterprise Plus 许可版本。如需了解如何启用 DRS，请参阅在集群中启用 VMware DRS
• 在 vcenter 字段中提供的 vSphere 用户帐号拥有 Host.Inventory.EditCluster 权限。
• 至少有三个物理主机可用。

在升级到 1.1.0-gke.6 之前停用 VMware DRS

如果您不想为现有用户集群启用此功能（例如，如果您没有足够的主机来容纳该功能），请在升级用户集群之前执行以下步骤：

1. 打开现有的 GKE On-Prem 配置文件。
2. 在 usercluster 规范下，添加 antiaffinitygroups 字段：

   usercluster:
         ...
         antiaffinitygroups:
           enabled: false
   

3. 保存文件。
4. 使用该配置文件进行升级。您的集群已升级，但该功能未启用。

其他升级场景

如果您的管理员工作站版本没有常见漏洞和披露 (CVE) 等安全补丁程序，您可以使用备用方法升级 GKE On-Prem。此备用方法仅升级 gkectl 和用户集群，不会升级管理员工作站。因此，您必须先对现有管理员工作站应用所有安全更新，然后才能使用此备用方法。

重要提示：使用下载的软件包将用户集群从版本 1.2.2 升级到版本 1.3.0 时，此备用升级方法存在一个已知问题。升级过程中可能会发生超时，从而导致用户集群升级失败。为避免此问题，您必须执行完整的升级流程，包括使用 OVA 文件升级管理员工作站。

1. 更新您的 Google Cloud CLI 组件：gcloud components update。
2. 下载并安装最新的 gkectl 工具。
3. 下载软件包。
4. 升级用户集群。

问题排查

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

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

表现

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

可能的原因

可能启用了节点内 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