升级 GKE On-Prem

本主题介绍如何升级 GKE On-Prem。

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

准备工作

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

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

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

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

依序升级

GKE On-Prem 支持依序升级。要将集群升级到新版本，该集群必须为前一个最新版本。

您无法将集群直接从早于上一个版本的版本直接升级到最新版本。如果您的集群早于上一个版本，则必须按顺序进行升级。

示例

假设以下版本可用，并且假设您的管理员工作站和集群运行的是最早的版本：

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

在本例中，1.1 是最新版本。要从 1.0.1 升级到 1.1，请按以下步骤操作：

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。

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

当您升级管理员工作站时，Terraform 会删除管理员工作站虚拟机，并将其替换为升级后的管理员工作站。在升级管理员工作站之前，您需要备份 GKE On-Prem 配置文件和集群的 kubeconfig 文件。稍后，您需要将这些文件复制到升级后的管理员工作站。

升级管理员工作站

重要提示：您将使用 Terraform 升级管理员工作站。请务必复制管理员工作站的文件。Terraform 会删除当前的管理员工作站虚拟机，并将其替换为新虚拟机。

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

• gkectl
• 完整软件包

升级管理员工作站后，您需要升级集群。

下载 OVA

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

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

gsutil cp gs://gke-on-prem-release/admin-appliance/1.2.2-gke.2/gke-on-prem-admin-appliance-vsphere-1.2.2-gke.2.{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.2.2-gke.2.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.2.2-gke.2.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

连接到管理员工作站

1. 通过 SSH 连接到管理员工作站：

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

2. 如果您使用代理，则需要为代理配置 Google Cloud CLI，以便运行 gcloud 和 gsutil 命令。如需查看相关说明，请参阅配置 gcloud CLI 以在代理/防火墙后使用。

3. 使用您的帐号凭据登录 Google Cloud：

   gcloud auth login

4. 将 gcloud 注册为 Docker 凭据帮助程序。（详细了解此命令）：

   gcloud auth configure-docker

5. 为已列入许可名单的服务帐号创建私钥。

   复制服务帐号的电子邮件地址：

   gcloud iam service-accounts list

   创建该服务帐号的私钥，其中 [KEY_FILE] 是您为文件选择的名称。以下命令会将文件保存到当前工作目录：

   gcloud iam service-accounts keys create key.json \
   --project [PROJECT_ID] --iam-account [ALLOWLISTED_SERVICE_ACCOUNT_EMAIL]

   其中：

   • [PROJECT_ID] 是项目 ID。
   • [KEY_FILE] 是服务帐号私钥的名称和保存路径，如 /home/ubuntu/key.json。
   • [ALLOWLISTED_SERVICE_ACCOUNT_EMAIL] 是已列入许可名单的服务帐号的电子邮件地址。

6. 激活已列入许可名单的服务帐号：

   gcloud auth activate-service-account --project [PROJECT_ID] \
   --key-file [KEY_FILE]
   

复制备份配置和 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 --config [CONFIG_FILE]

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

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

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

升级管理员集群

运行以下命令：

gkectl upgrade admin \
--kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
--config [CONFIG_FILE]

其中，[ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件，[CONFIG_FILE] 是您用于执行升级的 GKE On-Prem 配置文件。

升级用户集群

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

gkectl

从管理员工作站运行以下命令：

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

其中，[ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件，[CLUSTER_NAME] 是您要升级的用户集群的名称，[CONFIG_FILE] 是您用于执行升级的 GKE On-Prem 配置文件。

控制台

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

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

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

   访问 GKE On-Prem 菜单

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.2-gke.3 升级到版本 1.0.11

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"

附录

关于在 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. 使用该配置文件进行升级。您的集群已升级，但该功能未启用。

其他升级场景

本主题介绍升级 GKE On-Prem 的最简单方法，即升级管理员工作站，然后升级现有集群。下表介绍了另一种升级场景。在这一场景中，您将只升级 gkectl 和您的集群，而不会升级管理员工作站：

场景	步骤
版本没有管理员工作站的安全更新。	下载 gkectl。 下载升级软件包。 按照本页面上的说明操作。

问题排查

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

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

表现

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

可能的原因

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

解决方法

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

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

使用 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 控制器的日志来尝试进行调试：

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