将用户集群迁移到推荐功能

概览

本页面介绍了如何将 1.30 版或更高版本的用户集群迁移到以下推荐功能：

• 以容器网络接口 (CNI) 的形式迁移到 Dataplane V2。
• 将使用 kubeception 的用户集群迁移到 Controlplane V2。

• 将负载均衡器配置：

  • 从集成式 F5 BIG-IP 负载均衡器配置迁移到 ManualLB

    或

  • 从捆绑式 Seesaw 负载均衡器迁移到 MetalLB。

本页面适用于管理底层技术基础设施生命周期的 IT 管理员和运维人员。 如需了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE Enterprise 用户角色和任务。

最佳实践

我们建议您先迁移最不重要的环境（例如测试环境）。验证迁移成功后，请对每个环境重复此过程，最后再迁移生产环境。这样，您就可以在迁移到下一个更关键的环境之前，验证每次迁移是否成功，并确保工作负载正常运行。

我们建议您创建一个新用户集群并启用 Controlplane V2，以了解与 kubeception 集群的架构差异。新集群不会影响您的工作负载。但在最糟糕的情况下，如果迁移失败，您便已经为工作负载备好了一个集群。

如需详细了解迁移规划，请参阅规划将集群迁移到推荐功能。

要求

在此次迁移中：

• 用户集群必须为 1.30 版或更高版本。
• 所有节点池的版本都必须与用户集群的版本相同。
• 如果集群使用的是 Seesaw 负载均衡器，请确保您不依赖 Seesaw 来保留客户端 IP 地址，如下一部分所述。

Seesaw 客户端 IP 地址保留

如需检查 externalTrafficPolicy，请运行以下命令：

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get svc -A -o yaml | grep "externalTrafficPolicy: Local"

如果您遇到此问题，请与 Google 支持团队联系。

估算时间承诺并规划维护窗口

当您更新集群时，所有节点池都会默认并行更新。不过，在每个节点池中，节点会按顺序更新。因此，总更新时间取决于最大的节点池中的节点数。要计算每项更新的粗略估算值，请执行以下操作：

• 如果从 Seesaw 迁移到 MetalLB，则估计更新为 MetalLB 负载均衡器选择节点池需要 15 分钟。对于此更新，仅所选节点池进行了更新。
• 对于迁移过程中的任何其他更新，请将 15 分钟乘以节点池中的节点数。

要估算时间承诺，请计算您需要更新集群的次数。以下概要步骤显示了何时需要运行 gkectl update cluster 来更新集群：

1. 如果用户集群使用始终开启的 Secret 加密，请停用该功能并运行 gkectl update cluster。
2. 如果用户集群的 enableDataplaneV2 未设置或设置为 false，请更改配置，然后运行 gkectl update cluster 以迁移到 Dataplane V2。

3. 为负载均衡器和控制平面迁移做好准备：

   1. 如果管理员集群已启用自动修复，请将其停用。然后运行 gkectl update admin。此更新会很快完成，因为它不会重新创建管理员集群节点。
   2. 如果用户集群使用 Seesaw，请选择一个节点池供 MetalLB 负载均衡器要使用，然后运行 gkectl update cluster。此更新仅会更新所选节点池中的节点。

4. 进行所有必要的配置更改，以更新负载均衡器并迁移到 Controlplane V2。然后运行 gkectl update cluster。

5. 迁移后，如果您停用了始终开启的 Secret 加密功能，请重新启用该功能并运行 gkectl update cluster。

迁移所需的总时间取决于您必须运行 gkectl cluster update 的次数，而这又取决于您的配置。例如，假设您要迁移到 Dataplane V2、ControlPlane V2 和 MetalLB。此外，假设最大的节点池中有 10 个节点，而 MetalLB 将使用的节点池中有 3 个节点。如需估算迁移时间，请将以下值相加：

• 迁移到 Dataplane V2 的时间 150 分钟，因为 15 分钟 * 最大池中 10 个节点 = 150 分钟。
• MetalLB 使用节点池的时间 45 分钟，因为 15 分钟 * 该节点池中 3 个节点 = 45 分钟。
• Controlplane V2 和 MetalLB 更新的时间 150 分钟，因为 15 分钟 * 最大池中 10 个节点 = 150 分钟。

迁移所需的总时间约为 345 分钟，即 5 小时 45 分钟。

如有必要，您可以分阶段进行迁移。在前面的示例中，您可以用一个维护窗口迁移到 Dataplane V2，然后用一个或两个维护窗口完成其余的迁移。

规划迁移期间的停机时间

在规划迁移时，请规划以下类型的停机时间：

• 控制平面停机时间：在迁移期间，对 Kubernetes API 服务器的访问会受到影响。如果您要迁移到 Controlplane V2，则 kubeception 用户集群的控制平面会在迁移 loadBalancer.vips.controlPlaneVIP 时出现停机时间。停机时间通常不到 10 分钟，但具体时长取决于您的基础设施。
• 工作负载停机时间：LoadBalancer 类型的 Service 使用的虚拟 IP (VIP) 地址不可用。这种情况仅在从 Seesaw 迁移到 MetalLB 时发生。MetalLB 迁移过程将针对 LoadBalancer 类型的 Kubernetes Service 停止用户集群中所有 VIP 地址的网络连接两到十分钟。迁移完成后，连接将恢复正常。

下表介绍了迁移的影响：

• 受影响：迁移期间服务中断明显。
• 不受影响：服务中断不会发生，或者几乎不会被察觉。

迁移准备工作

为确保迁移成功，请执行以下部分中的步骤。

分配新的 IP 地址

如果您要迁移到 ControlPlane V2，请在工作器节点（节点池中的节点）所在的 VLAN 中分配新的静态 IP 地址。

• 您需要为 loadBalancer.vips.controlPlaneVIP 提供一个 IP 地址。

• 为每个控制平面节点分配一个 IP 地址。您需要分配的 IP 地址数量取决于用户集群是高可用性 (HA) 集群还是非 HA 集群。

  • 非 HA：一个 IP 地址
  • HA：三个 IP 地址

更新防火墙规则

如果您要迁移到 Controlplane V2，请更新用户集群上的防火墙规则。确保为用户集群上的控制平面节点新分配的 IP 地址可以访问所有必需的 API 和其他目的地，如防火墙规则用户集群节点中所述。

检查集群和节点池版本

验证所有节点池是否使用与用户集群相同的版本，该版本必须为 1.30 或更高版本。如果不是，请先将节点池升级到用户集群配置文件中的 gkeOnPremVersion，然后再继续迁移。如需检查版本，请运行以下命令：

gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details

将 ADMIN_CLUSTER_KUBECONFIG 替换为用户集群 kubeconfig 文件的路径。

检查集群健康状况

检查集群健康状况，并解决 gkectl diagnose cluster 命令报告的任何问题：

gkectl diagnose cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --cluster-name <var>USER_CLUSTER_NAME</var>

替换以下内容：

• ADMIN_CLUSTER_KUBECONFIG：管理员集群 kubeconfig 文件的路径。
• USER_CLUSTER_NAME：用户集群的名称。

在管理员集群中停用自动修复功能

如果您要迁移用户集群以使用 Controlplane V2，并且管理员集群中已启用自动修复功能，请停用自动修复。检查管理员集群配置文件的 autoRepair.enabled 字段。如果该字段未设置或设置为 true，请执行以下步骤：

1. 在管理员集群配置文件中，将 autoRepair.enabled 设置为 false。例如：

   autoRepair:
     enabled: true
   

2. 更新管理员集群：

   gkectl update admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --config ADMIN_CLUSTER_CONFIG
   

替换以下内容：

• ADMIN_CLUSTER_KUBECONFIG：管理员集群的 kubeconfig 文件的路径。
• ADMIN_CLUSTER_CONFIG：管理员集群配置文件的路径。

迁移完成后，请务必在管理集群中重新启用自动修复。

检查始终开启的 Secret 加密是否存在问题

如果您要迁移用户集群以使用 Controlplane V2，请检查始终启用的 Secret 加密是否存在问题。

如果用户集群已启用始终开启的 Secret 加密，则必须先执行停用始终开启的 Secret 加密并解密 Secret 中的步骤，然后才能开始迁移。否则，新的 Controlplane V2 集群将无法解密 Secret。

在开始迁移之前，请运行以下命令，看看是否曾在某个时间点启用过始终开启的 Secret 加密：

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  get onpremusercluster USER_CLUSTER_NAME \
  -n USER_CLUSTER_NAME-gke-onprem-mgmt \
  -o jsonpath={.spec.secretsEncryption}

如果上述命令的输出为空，则表示始终开启的 Secret 加密从未启用。您可以开始迁移。

如果上述命令的输出不为空，则表示始终开启的 Secret 加密之前已启用。在迁移之前，您必须执行下一部分中的步骤，以确保新的 ControlPlane V2 集群可以解密 Secret。

以下示例显示了非空输出：

{"generatedKeyVersions":{"keyVersions":[1]}}

停用始终开启的 Secret 加密，在需要时解密 Secret

如需停用始终开启的 Secret 加密并解密 Secret，请执行以下步骤：

1. 在用户集群配置文件中，如需停用始终开启的 Secret 加密，请将 disabled: true 字段添加到 secretsEncryption 部分：

   secretsEncryption:
       mode: GeneratedKey
       generatedKey:
           keyVersion: KEY_VERSION
           disabled: true
   

2. 更新集群：

   gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --config USER_CLUSTER_CONFIG
   

   替换以下内容：

   • ADMIN_CLUSTER_KUBECONFIG：管理员集群 kubeconfig 文件的路径
   • USER_CLUSTER_CONFIG：用户集群配置文件的路径

3. 对特定 DaemonSet 执行滚动更新，如下所示：

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
     rollout restart statefulsets kube-apiserver \
     -n USER_CLUSTER_NAME

4. 以 YAML 格式获取用户集群中所有 Secret 的清单：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
     get secrets -A -o yaml > SECRETS_MANIFEST.yaml

5. 为了以明文形式将所有 Secret 存储在 etcd 中，请重新应用用户集群中的所有 Secret：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
     apply -f SECRETS_MANIFEST.yaml

   您现在可以开始迁移到 Controlplane V2。迁移完成后，您可以在集群上重新启用始终开启的 Secret 加密。

启用节点池以供 MetalLB 使用

如果您要从捆绑式 Seesaw 负载均衡器迁移到 MetalLB，请执行本部分的步骤。如果用户集群配置文件中包含 loadBalancer.kind: Seesaw，则集群会使用 Seesaw。如果您要迁移集成式 F5 BIG-IP 配置，请跳至下一部分：迁移到 Dataplane V2。

选择一个节点池并将其启用以用于 MetalLB。迁移会在该节点池中的节点上部署 MetalLB。

1. 在用户集群配置文件的 nodePools 部分中，选择一个节点池或添加新节点池，然后将 enableLoadBalancer 设置为 true。例如：

   nodePools:
     - name: pool-1
       replicas: 3
       enableLoadBalancer: true
   

2. 更新集群：

   gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
       --config USER_CLUSTER_CONFIG
   

如需详细了解 MetalLB，请参阅使用 MetalLB 进行捆绑式负载均衡。

迁移到 Dataplane V2

在迁移之前，请运行以下命令，检查集群上是否已启用 DataPlane V2：

kubectl —kubeconfig ADMIN_CLUSTER_KUBECONFIG get onpremusercluster USER_CLUSTER_NAME -n USER_CLUSTER_NAME-gke-onprem-mgmt -o yaml | grep enableDataplaneV2

如果已启用 Dataplane V2，请跳至下一部分：为负载均衡器迁移做好准备。

如需迁移到 Dataplane V2，请执行以下步骤。如果您对暂时移除 NetworkPolicy 规范有疑虑，请与 Google 支持团队联系。

如果您的集群使用的是 NetworkPolicy，请从集群中暂时移除其规范，如下所示：

1. 检查是否有任何非系统 NetworkPolicy 应用于您的集群：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get networkpolicy -A -o wide | grep -v kube-system
   

2. 如果先前步骤的输出不为空，请将每个 NetworkPolicy 规范保存到文件中：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE -o yaml > NETWORK_POLICY_NAME.yaml
   

   替换以下内容：

   • NETWORK_POLICY_NAME：您要保存的 NetworkPolicy 的名称。
   • NETWORK_POLICY_NAMESPACE：NetworkPolicy 的命名空间。

3. 使用以下命令删除 NetworkPolicy：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE
   

请按以下步骤迁移到 Dataplane V2：

1. 在用户集群配置文件中将 enableDataplaneV2 设置为 true。

2. 如需启用 DataPlane V2，请更新您的集群：

   gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
   --config USER_CLUSTER_CONFIG
   

3. 如果您在先前步骤中移除了任何非系统 NetworkPolicy 规范，请在更新完成后使用以下命令重新应用它们：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG apply -f NETWORK_POLICY_NAME.yaml
   

完成这些步骤后，您便已启用 Dataplane V2。接下来，准备将集群迁移到推荐的负载均衡器和 ControlPlane V2。

为负载均衡器迁移做好准备

如果您的用户集群使用的是 Seesaw 负载均衡器或集成式 F5 BIG-IP，请按照本部分中的步骤进行所需的用户集群配置文件更改。否则，请跳至下一部分：为迁移到 ControlPlane V2 做好准备。

loadBalancer:
vips:
  controlPlaneVIP: 192.0.2.5
  ingressVIP: 198.51.100.20
kind: "f5BigIP" "ManualLB"
f5BigIP:
  address: "203.0.113.2"
  credentials:
  fileRef:
    path: "my-config-folder/user-creds.yaml"
    entry: "f5-creds"
  partition: "my-f5-user-partition"

loadBalancer:
  vips:
    controlPlaneVIP: "198.51.100.50"
    ingressVIP: "198.51.100.10"
  kind: "MetalLB" "Seesaw"
  seesaw:
    ipBlockFilePath: "user-cluster-2-ipblock.yaml"
    vrid: 1
    masterIP: ""
    cpus: 4
    memoryMB: 3072
  metalLB:
  addressPools:
    - name: "address-pool-1"
      enableLoadBalancer: true
      addresses:
      - "198.51.100.10/32"
      - "198.51.100.80 - 198.51.100.89"

为迁移到 Controlplane V2 做好准备

如果集群未启用 Controlplane V2，请执行以下操作：

• 更新用户集群配置文件。
• 如果集群使用手动负载均衡 (loadBalancer.kind: "ManualLB")，还需要更新负载均衡器上的配置。

以下部分介绍了这些步骤。

如果集群已启用 Controlplane V2，请跳至迁移用户集群部分。

更新用户集群配置文件

对现有用户集群配置文件进行以下更改：

1. 将 enableControlplaneV2 设置为 true。
2. （可选）使 Controlplane V2 用户集群的控制平面具备高可用性 (HA)。要从非 HA 集群更改为 HA 集群，请将 masterNode.replicas 从 1 更改为 3。
3. 将用户集群控制平面节点的静态 IP 地址添加到 network.controlPlaneIPBlock.ips 部分。控制平面节点的 IP 地址必须与工作器节点位于同一 VLAN 中。
4. 在 network.controlPlaneIPBlock 部分中填写 netmask 和 gateway。
5. 填写 network.hostConfig 部分（如果为空）。
6. 确保 loadBalancer.vips.controlPlaneVIP 字段包含控制平面 VIP 的新 IP 地址。IP 地址必须与控制平面节点 IP 位于同一 VLAN。
7. 如果用户集群使用手动负载均衡，请将 loadBalancer.manualLB.controlPlaneNodePort 和 loadBalancer.manualLB.konnectivityServerNodePort 设置为 0。虽然在启用 Controlplane V2 时不需要它们，但它们的值必须为 0。
8. 如果用户集群使用手动负载均衡，请按照下一部分中所述配置负载均衡器。

如有需要，请调整负载均衡器中的映射

如果您的用户集群已在使用手动负载均衡，您需要在负载均衡器上配置一些映射。如果您要从集成式 F5 BIG-IP 配置迁移到手动负载均衡，则无需对负载均衡器进行任何配置更改，可以跳到下一部分迁移用户集群。

对于您在 network.controlPlaneIPBlock 部分中指定的每个 IP 地址，请在负载均衡器中为控制平面节点配置以下映射：

(ingressVIP:80) -> (NEW_NODE_IP_ADDRESS:ingressHTTPNodePort)
(ingressVIP:443) -> (NEW_NODE_IP_ADDRESS:ingressHTTPSNodePort)

用户集群中的所有节点（控制平面节点和工作器节点）都需要这些映射。由于 NodePort 是在集群上配置的，因此 Kubernetes 会在所有集群节点上打开 NodePort，以便集群中的任何节点都可以处理数据平面流量。

配置映射后，负载均衡器会在标准 HTTP 和 HTTPS 端口上监听您为用户集群的入站流量 VIP 地址配置的 IP 地址上的流量。负载均衡器会将请求路由到集群中的任意节点。将请求路由到某个集群节点后，内部 Kubernetes 网络会将请求路由到目标 Pod。

迁移用户集群

首先，仔细查看您对用户集群配置文件所做的所有更改。除非您要更新集群以进行迁移，否则所有负载均衡器和 Controlplane V2 设置都是不可变的。

如需更新集群，请运行以下命令：

gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG

Controlplane V2 迁移

在 Controlplane V2 迁移期间，更新会执行以下操作：

1. 创建启用了 ControlPlane V2 的新集群的控制平面。
2. 停止 kubeception 集群的 Kubernetes 控制平面。
3. 截取 kubeception 集群的 etcd 快照。
4. 关闭 kubeception 集群的用户集群控制平面节点。在迁移完成之前，这些节点不会被删除，因为这样可以通过回退到该 kubeception 集群来进行故障恢复。
5. 使用先前步骤中创建的 etcd 快照恢复新控制平面中的集群数据。
6. 将 kubeception 集群的节点池节点连接到新的控制平面，该控制平面可通过新的 controlPlaneVIP 访问。
7. 协调已恢复的用户集群，以满足启用了 ControlPlane V2 的集群的最终状态。

请注意以下几点：

• 在迁移期间，用户集群工作负载不会出现停机时间。
• 在迁移期间，用户集群控制平面会有一些停机时间。具体而言，在停止 kubeception 集群的 Kubernetes 控制平面到完成将 kubeception 集群的节点池节点连接到新控制平面的过程中，控制平面不可用。（在测试中，此停机时间不超过 7 分钟，但实际时长取决于您的基础设施。）
• 迁移结束时，kubeception 集群的用户集群控制平面节点会被删除。如果管理员集群的 network.ipMode.type 设置为 "static"，您可以回收一些未使用的静态 IP 地址。您可以使用 kubectl get nodes -o wide 列出管理员集群节点对象，以查看正在使用的 IP 地址。如需回收这些 IP 地址，请从管理员集群配置文件中移除它们，然后运行 gkectl update admin。

迁移后

更新完成后，请执行以下步骤：

1. 验证用户集群是否正在运行：

   kubectl get nodes --kubeconfig var>USER_CLUSTER_KUBECONFIG
   

   输出类似于以下内容：

   cp-vm-1       Ready    control-plane,master   18m
   cp-vm-2       Ready    control-plane,master   18m
   cp-vm-3       Ready    control-plane,master   18m
   worker-vm-1   Ready                           6m7s
   worker-vm-2   Ready                           6m6s
   worker-vm-3   Ready                           6m14s
   

2. 如果您迁移到了 Controlplane V2，请更新管理员集群上的防火墙规则以移除 kubeception 用户集群的控制平面节点。

3. 如果您停用了始终开启的 Secret 加密，请重新启用该功能。

   1. 在用户集群配置文件中，移除 disabled: true 字段。

   2. 更新用户集群：

      gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
          --config USER_CLUSTER_CONFIG
      

4. 如果您在管理员集群中停用了自动修复功能，请重新启用该功能。

   1. 在管理员集群配置文件中，将 autoRepair.enabled 设置为 true。

   2. 更新集群：

      gkectl update admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
          --config ADMIN_CLUSTER_CONFIG
      

负载均衡器迁移

如果您迁移了负载均衡器，请验证负载均衡器组件是否已成功运行。

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get pods \
    --namespace kube-system --selector app=metallb

metallb-controller-744884bf7b-rznr9   1/1     Running
metallb-speaker-6n8ws                 1/1     Running
metallb-speaker-nb52z                 1/1     Running
metallb-speaker-rq4pp                 1/1     Running

kubectl --kubeconfig CLUSTER_KUBECONFIG \
api-resources --verbs=list -o name | xargs -n 1 kubectl --kubeconfig
CLUSTER_KUBECONFIG get --show-kind --ignore-not-found
--selector=onprem.cluster.gke.io/legacy-f5-resource=true -A

Warning: v1 ComponentStatus is deprecated in v1.19+
NAMESPACE     NAME                        TYPE     DATA   AGE
kube-system   secret/bigip-login-sspwrd   Opaque   4      14h
NAMESPACE     NAME                              SECRETS   AGE
kube-system   serviceaccount/bigip-ctlr         0         14h
kube-system   serviceaccount/load-balancer-f5   0         14h
NAMESPACE     NAME                                        READY   UP-TO-DATE   AVAILABLE   AGE
kube-system   deployment.apps/k8s-bigip-ctlr-deployment   1/1     1            1           14h
kube-system   deployment.apps/load-balancer-f5            1/1     1            1           14h
NAME                                                                                ROLE                                       AGE
clusterrolebinding.rbac.authorization.k8s.io/bigip-ctlr-clusterrole-binding         ClusterRole/bigip-ctlr-clusterrole         14h
clusterrolebinding.rbac.authorization.k8s.io/load-balancer-f5-clusterrole-binding   ClusterRole/load-balancer-f5-clusterrole   14h
NAME                                                                 CREATED AT
clusterrole.rbac.authorization.k8s.io/bigip-ctlr-clusterrole         2024-03-25T05:16:40Z
clusterrole.rbac.authorization.k8s.io/load-balancer-f5-clusterrole   2024-03-25T05:16:41Z