将复制的控制平面迁移到使用云控制器管理器

cloud-controller-manager 是一个 Kubernetes 控制平面组件，它嵌入特定于云的控制逻辑。云控制器管理器允许你将集群链接到云提供商的 API，并将与该云平台交互的组件与仅与集群交互的组件分离。

通过解耦 Kubernetes 和底层云基础设施之间的互操作性逻辑，cloud-controller-manager 组件使云提供商能够以与主 Kubernetes 项目不同的速度发布功能。

背景

作为云提供商提取工作的一部分，所有特定于云的控制器都必须从 kube-controller-manager 中移出。所有在 kube-controller-manager 中运行云控制器的现有集群都必须迁移为改为在特定于云提供商的 cloud-controller-manager 中运行控制器。

领导者迁移提供了一种机制，在该机制中，HA 集群可以在升级复制的控制平面时，通过两个组件之间的共享资源锁，安全地在 kube-controller-manager 和 cloud-controller-manager 之间迁移“特定于云”的控制器。对于单节点控制平面，或者如果在升级期间可以容忍控制器管理器的不可用，则不需要领导者迁移，可以忽略本指南。

可以通过在 kube-controller-manager 或 cloud-controller-manager 上设置 --enable-leader-migration 来启用领导者迁移。领导者迁移仅在升级期间应用，并且在升级完成后可以安全地禁用或保持启用。

本指南将引导你完成从带有内置云提供商的 kube-controller-manager 升级控制平面到同时运行 kube-controller-manager 和 cloud-controller-manager 的手动过程。如果你使用工具来部署和管理集群，请参阅该工具和云提供商的文档，了解有关迁移的具体说明。

开始之前

假设控制平面正在运行 Kubernetes 版本 N，并要升级到版本 N + 1。尽管可以在同一版本中进行迁移，但理想情况下，迁移应作为升级的一部分执行，以便配置的更改可以与每个版本保持一致。N 和 N + 1 的确切版本取决于每个云提供商。例如，如果云提供商构建一个与 Kubernetes 1.24 一起使用的 cloud-controller-manager，则 N 可以是 1.23，N + 1 可以是 1.24。

控制平面节点应运行启用领导者选举的 kube-controller-manager，这是默认设置。从版本 N 开始，必须使用 --cloud-provider 标志设置一个内部云提供商，并且不应部署 cloud-controller-manager。

树外云提供商必须构建一个带有领导者迁移实现的 cloud-controller-manager。如果云提供商导入 v0.21.0 或更高版本的 k8s.io/cloud-provider 和 k8s.io/controller-manager，则领导者迁移将可用。但是，对于 v0.22.0 之前的版本，领导者迁移是 Alpha 版，需要在 cloud-controller-manager 中启用特性门控 ControllerManagerLeaderMigration。

本指南假设每个控制平面节点的 kubelet 将 kube-controller-manager 和 cloud-controller-manager 作为由其清单定义的静态 Pod 启动。如果组件在不同的设置中运行，请相应地调整步骤。

对于授权，本指南假设集群使用 RBAC。如果另一种授权模式授予 kube-controller-manager 和 cloud-controller-manager 组件权限，请以与该模式匹配的方式授予所需的访问权限。

授予对迁移租约的访问权限

控制器管理器的默认权限仅允许访问其主要租约。为了使迁移工作，需要访问另一个租约。

你可以通过修改 system::leader-locking-kube-controller-manager 角色来授予 kube-controller-manager 对租约 API 的完全访问权限。此任务指南假设迁移租约的名称为 cloud-provider-extraction-migration。

kubectl patch -n kube-system role 'system::leader-locking-kube-controller-manager' -p '{"rules": [ {"apiGroups":[ "coordination.k8s.io"], "resources": ["leases"], "resourceNames": ["cloud-provider-extraction-migration"], "verbs": ["create", "list", "get", "update"] } ]}' --type=merge`

对 system::leader-locking-cloud-controller-manager 角色执行相同的操作。

kubectl patch -n kube-system role 'system::leader-locking-cloud-controller-manager' -p '{"rules": [ {"apiGroups":[ "coordination.k8s.io"], "resources": ["leases"], "resourceNames": ["cloud-provider-extraction-migration"], "verbs": ["create", "list", "get", "update"] } ]}' --type=merge`

初始领导者迁移配置

领导者迁移可以选择采用一个配置文件，该文件表示控制器到管理器分配的状态。目前，使用内部云提供商，kube-controller-manager 运行 route、service 和 cloud-node-lifecycle。以下示例配置显示了分配。

可以在没有配置的情况下启用领导者迁移。请参阅默认配置获取详细信息。

kind: LeaderMigrationConfiguration
apiVersion: controllermanager.config.k8s.io/v1
leaderName: cloud-provider-extraction-migration
resourceLock: leases
controllerLeaders:
  - name: route
    component: kube-controller-manager
  - name: service
    component: kube-controller-manager
  - name: cloud-node-lifecycle
    component: kube-controller-manager

或者，由于控制器可以在任一控制器管理器下运行，因此将两边的 component 设置为 * 使配置文件在迁移的双方之间保持一致。

# wildcard version
kind: LeaderMigrationConfiguration
apiVersion: controllermanager.config.k8s.io/v1
leaderName: cloud-provider-extraction-migration
resourceLock: leases
controllerLeaders:
  - name: route
    component: *
  - name: service
    component: *
  - name: cloud-node-lifecycle
    component: *

在每个控制平面节点上，将内容保存到 /etc/leadermigration.conf，并更新 kube-controller-manager 的清单，以便将该文件挂载在容器内的相同位置。此外，更新同一清单以添加以下参数

--enable-leader-migration 在控制器管理器上启用领导者迁移
--leader-migration-config=/etc/leadermigration.conf 设置配置文件

在每个节点上重新启动 kube-controller-manager。目前，kube-controller-manager 已启用领导者迁移，并已准备好进行迁移。

部署云控制器管理器

在版本 N + 1 中，控制器到管理器分配的所需状态可以用一个新的配置文件表示，如下所示。请注意，每个 controllerLeaders 的 component 字段从 kube-controller-manager 更改为 cloud-controller-manager。或者，使用上面提到的通配符版本，它具有相同的效果。

kind: LeaderMigrationConfiguration
apiVersion: controllermanager.config.k8s.io/v1
leaderName: cloud-provider-extraction-migration
resourceLock: leases
controllerLeaders:
  - name: route
    component: cloud-controller-manager
  - name: service
    component: cloud-controller-manager
  - name: cloud-node-lifecycle
    component: cloud-controller-manager

在创建版本 N + 1 的控制平面节点时，应将内容部署到 /etc/leadermigration.conf。应更新 cloud-controller-manager 的清单，以与版本 N 的 kube-controller-manager 相同的方式挂载配置文件。同样，将 --enable-leader-migration 和 --leader-migration-config=/etc/leadermigration.conf 添加到 cloud-controller-manager 的参数中。

使用更新的 cloud-controller-manager 清单创建一个版本 N + 1 的新控制平面节点，并将 kube-controller-manager 的 --cloud-provider 标志设置为 external。版本 N + 1 的 kube-controller-manager 必须不能启用领导者迁移，因为使用外部云提供商时，它不再运行迁移的控制器，因此它不参与迁移。

有关如何部署 cloud-controller-manager 的更多详细信息，请参阅云控制器管理器管理。

升级控制平面

控制平面现在包含版本 N 和 N + 1 的节点。版本 N 的节点仅运行 kube-controller-manager，而版本 N + 1 的节点同时运行 kube-controller-manager 和 cloud-controller-manager。根据哪个控制器管理器持有迁移租约，迁移的控制器（如配置中指定）在版本 N 的 kube-controller-manager 或版本 N + 1 的 cloud-controller-manager 下运行。任何时候都不会有任何控制器在两个控制器管理器下运行。

以滚动方式，创建一个版本 N + 1 的新控制平面节点，并关闭一个版本 N 的节点，直到控制平面仅包含版本 N + 1 的节点。如果需要从版本 N + 1 回滚到 N，请将启用 kube-controller-manager 的领导者迁移的版本 N 的节点添加回控制平面，每次替换一个版本 N + 1 的节点，直到只有版本 N 的节点。

（可选）禁用领导者迁移

现在控制平面已升级为同时运行版本 N + 1 的 kube-controller-manager 和 cloud-controller-manager，领导者迁移已完成其工作，可以安全地禁用以节省一个租约资源。将来可以安全地重新启用领导者迁移以进行回滚。

在滚动管理器中，更新 cloud-controller-manager 的清单以取消设置 --enable-leader-migration 和 --leader-migration-config= 标志，同时删除 /etc/leadermigration.conf 的挂载，最后删除 /etc/leadermigration.conf。要重新启用领导者迁移，请重新创建配置文件，并将其挂载和启用领导者迁移的标志添加回 cloud-controller-manager。

默认配置

从 Kubernetes 1.22 版本开始，领导者迁移 (Leader Migration) 提供了一个适用于默认控制器到管理器分配的默认配置。可以通过设置 --enable-leader-migration 来启用默认配置，而无需设置 --leader-migration-config=。

对于 kube-controller-manager 和 cloud-controller-manager，如果没有启用任何内置云提供商或更改控制器所有权的标志，则可以使用默认配置，避免手动创建配置文件。

特殊情况：迁移 Node IPAM 控制器

如果你的云提供商提供了 Node IPAM 控制器的实现，你应该切换到 cloud-controller-manager 中的实现。通过在 N + 1 版本的 kube-controller-manager 的标志中添加 --controllers=*,-nodeipam 来禁用其中的 Node IPAM 控制器。然后将 nodeipam 添加到迁移的控制器列表中。

# wildcard version, with nodeipam
kind: LeaderMigrationConfiguration
apiVersion: controllermanager.config.k8s.io/v1
leaderName: cloud-provider-extraction-migration
resourceLock: leases
controllerLeaders:
  - name: route
    component: *
  - name: service
    component: *
  - name: cloud-node-lifecycle
    component: *
  - name: nodeipam
-   component: *

下一步

阅读控制器管理器领导者迁移增强提案。

上次修改时间：2024年12月04日，太平洋标准时间上午11:27: 更新 controller-manager-leader-migration.md (f1d5525f85)