本主题介绍如何升级 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.0.1 升级到 1.0.2。
- 将集群从 1.0.1 升级到 1.0.2。
- 将管理员工作站从 1.0.2 升级到 1.1。
- 将集群从 1.0.2 升级到 1.1。
备份 GKE On-Prem 配置文件和 kubeconfig 文件
当您升级管理员工作站时，Terraform 会删除管理员工作站虚拟机，并将其替换为升级后的管理员工作站。在升级管理员工作站之前，您需要备份 GKE On-Prem 配置文件和集群的 kubeconfig 文件。稍后，您需要将这些文件复制到升级后的管理员工作站。
升级管理员工作站
升级管理员工作站时，管理员工作站包含以下实体，其版本与管理员工作站的开放虚拟化设备 (OVA) 文件相同：
gkectl- 完整软件包
升级管理员工作站后，您需要升级集群。
下载 OVA
从下载中，下载您要升级到的目标版本的管理员工作站 OVA 文件。
要下载最新的 OVA，请运行以下命令：
gsutil cp gs://gke-on-prem-release/admin-appliance/1.1.2-gke.0/gke-on-prem-admin-appliance-vsphere-1.1.2-gke.0.{ova,ova.sig} ~/将 OVA 导入 vSphere 并将其标记为虚拟机模板
在以下部分中，您将：
- 创建一些变量，以声明您的 vCenter Server 和 vSphere 环境的元素。
- 将管理员工作站 OVA 导入 vSphere 并将其标记为虚拟机模板。
为 govc 创建变量
在将管理员工作站 OVA 导入 vSphere 之前，您需要提供一些 govc 变量，用于声明您的 vCenter Server 和 vSphere 环境的元素：
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.1.2-gke.0.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.1.2-gke.0.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 升级管理员工作站
要升级管理员工作站，请运行以下命令。此命令会删除当前的管理员工作站虚拟机，并将其替换为已升级的虚拟机：
terraform init && terraform apply -auto-approve -input=false
连接到管理员工作站
通过 SSH 连接到管理员工作站：
ssh -i ~/.ssh/vsphere_workstation ubuntu@[IP_ADDRESS]
如果您使用代理，则需要为代理配置 Google Cloud CLI，以便运行
gcloud和gsutil命令。如需查看相关说明，请参阅配置 gcloud CLI 以在代理/防火墙后使用。使用您的帐号凭据登录 Google Cloud：
gcloud auth login
将
gcloud注册为 Docker 凭据帮助程序。（详细了解此命令）：gcloud auth configure-docker
为已列入许可名单的服务帐号创建私钥。
复制服务帐号的电子邮件地址：
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] 是已列入许可名单的服务帐号的电子邮件地址。
激活已列入许可名单的服务帐号：
gcloud auth activate-service-account --project [PROJECT_ID] \ --key-file [KEY_FILE]
复制备份配置和 kubeconfig 文件
之前您已备份 GKE On-Prem 配置文件和集群的 kubeconfig 文件。现在，您应该将这些文件复制回升级后的管理员工作站。
升级集群
升级管理员工作站并连接到该工作站后，请执行以下步骤：
验证是否有足够的可用 IP 地址
在升级之前，请确保您有足够的 IP 地址可供集群使用。
DHCP
如果集群具有由 DHCP 服务器分配的 IP 地址，请检查创建节点的网络中的 DHCP 服务器是否具有足够的 IP 地址。IP 地址应该多于用户集群中运行的节点。
静态 IP 地址
如果集群具有静态 IP 地址，请检查您是否在集群中分配了足够的 IP 地址：
kubectl get cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \ -n [USER_CLUSTER_NAME] [USER_CLUSTER_NAME] -o yaml
其中：
- [ADMIN_CLUSTER_KUBECONFIG] 告知 kubectl 使用管理员集群的 kubeconfig，后者用于查看和/或更改用户集群配置。
-n [USER_CLUSTER_NAME]告知 kubectl 查找以用户集群命名的命名空间。[USER_CLUSTER_NAME] -o yaml告知 kubectl 您要对哪个用户集群运行命令。-o yaml显示用户集群的配置。
在命令的输出中，查找 reservedAddresses 字段。字段中的 IP 地址应该多于用户集群中运行的节点。
如果您需要向 reservedAddresses 字段添加更多地址，请执行以下步骤：
打开用户集群的配置文件以进行修改：
kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] edit cluster [USER_CLUSTER_NAME] \ -n [USER_CLUSTER_NAME] --validate=false
集群配置会在 shell 的默认编辑器中打开。
根据需要添加任意数量的静态 IP 地址块。IP 地址块由
gateway、hostname、ip、netmask字段组成。
以下是一个示例 reservedAddresses 字段，其中突出显示了四个静态 IP 地址块：
...
networkSpec:
dns:
- 172.x.x.x
ntp: 129.x.x.x
reservedAddresses:
- gateway: 100.x.x.x
hostname: host-1
ip: 100.x.x.x
netmask: x
- gateway: 100.x.x.x
hostname: host-2
ip: 100.x.x.x
netmask: x
- gateway: 100.x.x.x
hostname: host-3
ip: 100.x.x.x
netmask: x
- gateway: 100.x.x.x
hostname: host-4
ip: 100.x.x.x
netmask: x
...
修改配置文件
在管理员工作站虚拟机上，修改您的配置文件。设置 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 版本中自动启用和由配置文件驱动的新功能，请在升级集群之前执行以下步骤：
从升级后的管理员工作站中创建一个新的配置文件，并使用与当前配置文件不同的名称：
gkectl create-config --config [CONFIG_NAME]
打开新的配置文件和该功能的字段。关闭文件。
打开当前的配置文件，并在相应的规范中添加新功能的字段。
为该字段提供
false或同等效果的值。保存配置文件。继续升级集群。
升级集群之前，请务必先阅读版本说明。升级后，您将无法以声明方式更改现有集群的配置。
运行 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 命令：
访问 Google Cloud 控制台中的 GKE 菜单。
在用户集群的通知列下，点击现在可升级（如有）。
复制
gkectl upgrade cluster命令。从管理员工作站运行
gkectl upgrade cluster命令，其中 [ADMIN_CLUSTER_KUBECONFIG] 是管理员集群的 kubeconfig 文件，[CLUSTER_NAME] 是要升级的用户集群的名称，[CONFIG_FILE] 是您用于执行升级的 GKE On-Prem 配置文件。
恢复升级
如果用户集群升级中断，但管理员集群升级成功，您可以通过使用相同的 GKE On-Prem 配置文件和管理员集群 Kubeconfig 再次运行 gkectl upgrade cluster 来恢复升级。
关于继续管理员集群升级
您不应中断管理员集群升级。目前，管理员集群升级并非总是可恢复的。如果管理员集群升级因任何原因中断，您应该联系支持团队寻求帮助。
已知问题
以下已知问题会影响集群升级。
使用 PodDisruptionBudget 的工作负载中断
目前，升级集群可能会导致使用 PodDisruptionBudget (PDB) 的工作负载中断或停机。
版本 1.1.1-gke.2：vSAN 数据存储区文件夹中的数据磁盘可以被删除
如果您使用的是 vSAN 数据存储区，则需要创建一个文件夹来保存 VMDK。目前，已知问题要求您向 vcenter.datadisk 提供文件夹的通用唯一标识符 (UUID) 路径，而不是文件路径。这种不匹配可能会导致升级失败。
针对版本 1.1.2 进行了修复。在升级之前，请对管理员控制层面节点执行以下步骤作为解决方法：
- 从 vCenter 界面中，获取 vSAN 数据存储区中文件夹的 UUID。
列出集群中的机器资源。这些机器对应于集群中的节点：
kubectl get machines -n all
对于管理员控制层面的机器 (
gke-admin-master)，请打开其配置以进行修改：kubectl edit machine [MACHINE_NAME]
更改
spec.providerSpec.value.machineVariables.data_disk_path字段。使用 UUID 替换 VMDK 文件的路径。例如：spec: providerSpec: value: apiVersion: vsphereproviderconfig.k8s.io/v1alpha1 kind: VsphereMachineProviderConfig machineVariables: data_disk_path: 14159b5d-4265-a2ba-386b-246e9690c588/my-disk.vmdk datacenter: datacenter datastore: datastore保存文件。
打开 GKE On-Prem 配置文件。
在
vcenter.datadisk中，将文件路径中的文件夹替换为文件夹的 UUID。例如：vcenter: ... datadisk: "14159b5d-4265-a2ba-386b-246e9690c588/my-disk.vmdk"
继续升级集群。
从版本 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"
附录
关于在 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
如果您不想为现有用户集群启用此功能（例如，如果您没有足够的主机来容纳该功能），请在升级用户集群之前执行以下步骤：
- 打开现有的 GKE On-Prem 配置文件。
- 在
usercluster规范下，按照antiaffinitygroups文档中所述添加antiaffinitygroups字段：usercluster: ... antiaffinitygroups: enabled: false - 保存文件。
- 使用该配置文件进行升级。您的集群已升级，但该功能未启用。
其他升级场景
本主题介绍了升级 GKE On-Prem 的最简单方法。下表介绍了另一种升级场景。在这一场景中，您将只升级 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 控制器的日志来尝试进行调试：
在
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