2. Controller Runtime 简介：定位、核心模块与控制面通信角色

Controller Runtime 是 Kubernetes 社区官方维护的 Go 库，位于 sigs.k8s.io/controller-runtime 路径下。它封装了 client-go 的底层细节，为开发者提供一套声明式、可组合的抽象层，用于快速构建运行在 Kubernetes 控制面内的控制器和 Operator。在控制面通信体系中，Controller Runtime 充当“中间件”角色——它不直接操作 etcd，而是通过 Informer 机制监听 API Server 的事件流，并将事件调度到用户定义的业务逻辑中。

2.1 定位：从 client-go 到 Controller Runtime 的演进

在 Controller Runtime 出现之前，开发者直接使用 client-go 编写控制器，需要手动管理 Informer、Lister、WorkQueue、Leader Election 等基础设施。Controller Runtime 将这些重复劳动抽象为可插拔模块，使开发者只需关注 Reconciler 函数。下表对比了两者的关注点差异：

2.2 核心功能模块总览

Controller Runtime 由五个核心模块构成，它们协同工作，形成从事件监听到业务逻辑执行的完整闭环。下图展示了模块间的依赖与数据流：

2.3 各模块详解

2.3.1 Manager——控制器的“操作系统”

Manager 是 Controller Runtime 的顶层容器，负责初始化、启动和优雅关闭所有组件。它提供以下核心能力：

• 依赖注入：通过 Manager.Options 配置 Cache、Client、Scheme、Leader Election 等。
• 生命周期管理：调用 mgr.Start(ctx) 启动所有注册的 Controller 和 Webhook。
• 共享资源：所有 Controller 共享同一个 Cache 和 Client，避免重复连接 API Server。
• Leader 选举：内置 leaderelection 集成，支持高可用部署。

2.3.2 Cache——本地状态缓存

Cache 封装了 client-go 的 Informer 和 Indexer，为 Controller 提供本地缓存视图。它通过 List-Watch 机制与 API Server 保持同步：

• List：启动时全量拉取资源列表，构建初始索引。
• Watch：持续监听资源变更事件（Add/Update/Delete），增量更新本地缓存。
• Indexer：支持按字段、标签、命名空间等维度建立索引，加速查询。

Cache 的存在使得 Controller 在 Reconcile 时无需每次都请求 API Server，大幅降低控制面负载。

2.3.3 Client——读写 Kubernetes 资源

Client 是 Controller Runtime 提供的统一资源操作接口，分为两种模式：

Client 实现了 client.Client 接口，支持 Typed 和 Unstructured 两种资源操作方式。

2.3.4 Controller——事件调度引擎

Controller 负责将 Cache 传递过来的事件（Event）转换为 Reconcile 请求，并放入工作队列。其核心工作流程如下：

1. 事件注册：通过 Watches() 或 For() / Owns() 声明要监听哪些资源。
2. 事件处理：EventHandler 将事件对象转换为 reconcile.Request{NamespacedName}。
3. 队列管理：使用 workqueue.RateLimitingQueue 实现限速、去重和重试。
4. Worker 池：默认启动多个 Worker 并发执行 Reconcile，通过 MaxConcurrentReconciles 配置。

2.3.5 Reconciler——业务逻辑入口

Reconciler 是开发者唯一需要实现的接口，定义如下：

type Reconciler interface {
    Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
}

Reconciler 接收一个 NamespacedName（命名空间 + 名称），返回 Result 和 error：

• Result{Requeue: true}：立即重新入队。
• Result{RequeueAfter: 5 * time.Second}：延迟重新入队。
• Result{}：处理成功，无需重试。
• error != nil：框架自动处理重试和指数退避。

2.4 在控制面通信中的角色

Controller Runtime 在 Kubernetes 控制面通信中扮演 事件驱动中间件 的角色。下图展示了它如何嵌入控制面通信链路：

从通信角度看，Controller Runtime 实现了以下关键机制：

• 事件订阅：通过 Informer 的 List-Watch 机制，以长连接方式订阅 API Server 的资源变更事件，避免轮询。
• 本地缓存：减少对 API Server 的直接读请求，降低控制面压力。
• 异步解耦：Controller 将事件放入工作队列，Reconciler 异步处理，实现生产-消费模型。
• 限速与重试：内置指数退避和限速队列，防止异常事件冲击 API Server。

2.5 模块协作流程示例

以一个 Deployment 控制器为例，展示模块间的完整协作流程：

1. Cache 通过 Informer 监听 Deployment 资源，收到一个 ADDED 事件。
2. Controller 的 EventHandler 将事件对象转换为 reconcile.Request{Name: "my-deploy", Namespace: "default"}，放入工作队列。
3. Worker 从队列中取出请求，调用 Reconciler.Reconcile()。
4. Reconciler 通过 Client.Get() 从 Cache 中读取 Deployment 当前状态。
5. Reconciler 计算期望状态与当前状态的差异，通过 Client.Update() 或 Client.Status().Update() 写入 API Server。
6. API Server 将变更持久化到 etcd，并触发下一轮事件通知。