升级 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 文件。稍后,您需要将这些文件复制到升级后的管理员工作站。

升级管理员工作站

升级管理员工作站时,管理员工作站包含以下实体,其版本与管理员工作站的开放虚拟化设备 (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 并将其标记为虚拟机模板

在以下部分中,您将:

  1. 创建一些变量,以声明您的 vCenter Server 和 vSphere 环境的元素。
  2. 将管理员工作站 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

连接到管理员工作站

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

    ssh -i ~/.ssh/vsphere_workstation ubuntu@[IP_ADDRESS]
    
  2. 如果您使用代理,则需要为代理配置 Google Cloud CLI,以便运行 gcloudgsutil 命令。如需查看相关说明,请参阅配置 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

如果集群具有由 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 字段添加更多地址,请执行以下步骤:

  1. 打开用户集群的配置文件以进行修改:

    kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] edit cluster [USER_CLUSTER_NAME] \
    -n [USER_CLUSTER_NAME] --validate=false

    集群配置会在 shell 的默认编辑器中打开。

  2. 根据需要添加任意数量的静态 IP 地址块。IP 地址块由 gatewayhostnameipnetmask 字段组成。

以下是一个示例 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 版本中自动启用和由配置文件驱动的新功能,请在升级集群之前执行以下步骤

  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 配置文件。

恢复升级

如果用户集群升级中断,但管理员集群升级成功,您可以通过使用相同的 GKE On-Prem 配置文件和管理员集群 Kubeconfig 再次运行 gkectl upgrade cluster 来恢复升级。

关于继续管理员集群升级

您不应中断管理员集群升级。目前,管理员集群升级并非总是可恢复的。如果管理员集群升级因任何原因中断,您应该联系支持团队寻求帮助。

已知问题

以下已知问题会影响集群升级。

使用 PodDisruptionBudget 的工作负载中断

目前,升级集群可能会导致使用 PodDisruptionBudget (PDB) 的工作负载中断或停机。

版本 1.1.1-gke.2:vSAN 数据存储区文件夹中的数据磁盘可以被删除

如果您使用的是 vSAN 数据存储区,则需要创建一个文件夹来保存 VMDK。目前,已知问题要求您向 vcenter.datadisk 提供文件夹的通用唯一标识符 (UUID) 路径,而不是文件路径。这种不匹配可能会导致升级失败。

针对版本 1.1.2 进行了修复。在升级之前,请对管理员控制层面节点执行以下步骤作为解决方法:

  1. 从 vCenter 界面中,获取 vSAN 数据存储区中文件夹的 UUID。
  2. 列出集群中的机器资源。这些机器对应于集群中的节点:

    kubectl get machines -n all
  3. 对于管理员控制层面的机器 (gke-admin-master),请打开其配置以进行修改:

    kubectl edit machine [MACHINE_NAME]
    
  4. 更改 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
  5. 保存文件。

  6. 打开 GKE On-Prem 配置文件。

  7. vcenter.datadisk 中,将文件路径中的文件夹替换为文件夹的 UUID。例如:

    vcenter:
     ...
     datadisk: "14159b5d-4265-a2ba-386b-246e9690c588/my-disk.vmdk"
    
  8. 继续升级集群。

从版本 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"

附录

关于在 1.1.0-gke.6 版本中启用的 VMware DRS 规则

从 1.1.0-gke.6 版开始,GKE On-Prem 会自动为您的用户集群节点创建 VMware 分布式资源调度器 (DRS) 反亲和性规则,使其分布到数据中心内的至少三个物理主机上。从 1.1.0-gke.6 版开始,此功能会自动为新集群和现有集群启用。

在升级之前,请确保您的 vSphere 环境满足以下条件:

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

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

  1. 打开现有的 GKE On-Prem 配置文件。
  2. usercluster 规范下,按照 antiaffinitygroups 文档中所述添加 antiaffinitygroups 字段:
    usercluster:
          ...
          antiaffinitygroups:
            enabled: false
    
  3. 保存文件。
  4. 使用该配置文件进行升级。您的集群已升级,但该功能未启用。

其他升级场景

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

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

问题排查

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

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

表现

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

可能的原因

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

解决方法

如需停用验证,请运行以下命令:

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

使用 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