使用者痛点：并用可视化的时序图和代码片段帮助定位关键点，让你不再“摸不着头脑”。

Controller 注册后的完整调用时序

整个流程分为五个阶段：注册 → 构造 → 启动 Informer → 并发启动 Controller → 阻塞运行。

完整时序图

kube-controller-manager 进程启动
├─ 阶段 : 注册
│ NewControllerDescriptors
│
│ └─ 返回 map*ControllerDescriptor ← 仅元数据，不实例化
│
├─ 阶段 : Leader Election
│
│ └─ leaderElectAndRun → 竞争 Lease 锁
│ ├─ 未获取到锁 → 阻塞在 acquire。每 2s 重试
│ └─ 获取到锁 → OnStartedLeading 回调
│ ▼
┌───────────────────────────────────────────────────────────────┐
│ 阶段 : 构造所有 Controller │
│ │
│ │
│ run := func { │
│ ① CreateControllerContext ← 创建共享上下文 │
│ ② BuildControllers ← 逐个构造 │
│ ③ InformerFactory.Start ← 启动 Informer │
│ ④ RunControllers ← 并发启动 │
│ } │
└───────────────────────────────────────────────────────────────┘
▼
① CreateControllerContext
├─ 创建 SharedInformerFactory
├─ 创建 metadata Informer Factory
├─ 等待 API Server 就绪
└─ 创建 RESTMapper
② BuildControllers
├─ 第 1 个: SA Token Controller
│ └─ constructor → NewServiceAccountTokenController
└─ 第 ~N 个: 按注册顺序构造
for _,desc := range controllerDescriptors {
if desc.RequiresSpecialHandling → skip
if!IsControllerEnabled → skip
if FeatureGate 未启用 → skip
desc.BuildController → constructor
}
③ InformerFactory.Start
└─ 启动所有 Informer 的 Watch 连接
④ close
└─ 广播信号："Informer 已就绪，Controller 可以开始消费数据了"
⑤ RunControllers
└─ 并发启动所有 Controller
└─ 阶段 : 阻塞运行，直到 ctx 被取消

RunControllers 的并发启动细节

RunControllers 位于 controllermanager.go#L710-L795

func RunControllers(ctx context.Context,controllerCtx *controllerContext,controllers controller.Interface。jitter time.Duration,shutdownTimeout time.Duration) bool {
// ① 每个 Controller 一个 goroutine，全部并发启动
for _,controller := range controllers {
go func {
// ② Jitter: 随机延迟后启动，防止所有 Controller 同时发起 List 请求
time.Sleep(wait.Jitter(
controllerCtx.ComponentConfig.Generic.ControllerStartInterval.Duration,controllerStartJitterMaxFactor,))
// ③ 调用 Controller.Run，阻塞直到 ctx 被取消
ctrl.Run
}
}
// ④ 等待 ctx 被取消
<-ctx.Done
    // ⑤ 等待所有 Controller 在 shutdownTimeout 内优雅退出
}

关键设计：

• Jitter 防惊群：所有 Controller 不会同时启动，而是随机错开。默认 ControllerStartInterval 为 0sjitter factor 为 0.5；生产环境可通过配置让每个控制器产生约 <=5s 的随机延迟，从而避免 API Server 瞬间压力峰值。
• Run 方法是阻塞的：以 ReplicaSet Controller 为例，它内部会开启 worker goroutine 来消费工作队列，但外层的 .Run 会一直阻塞在 `<-ctx.Done` 上，直至进程退出或失去 Leader 权限。

controllerLoop 包装器

每个具体业务控制器的构造函数最终返回的是 *controllerLoop

type controllerLoop struct {
name string
run runFunc // func
}
func Name string { return loop.name }
func Run {
loop.run
}

以 Deployment Controller 为例（apps.go#L145-L147)：

return newControllerLoop {
dc.Run)
},controllerName)。nil
// dc.Run 内部会启动 N 个 worker goroutine，接下来阻塞在 <-ctx.Done
// 因此 controllerLoop.Run 同样是阻塞式入口。

完整时间线

t=0 程序入口 -> NewControllerDescriptors
注册 N 个 Descriptor
t≈0+ Leader Election 开始，阻塞等待 Lease 锁
t=N 获得 Leader 锁后触发 OnStartedLeading 回调：
├─ CreateControllerContext ~100ms
├─ BuildControllers ~500ms
│ • SA Token Controller 最先实例化
│ • 后续控制器按注册顺序实例化并检查 FeatureGate/EnableFlag 等过滤条件
├─ InformerFactory.Start 即时
├─ close 即时
└─ RunControllers 即时
t=N+Δ 所有控制器并发运行：
• 每个控制器内部再启动若干 worker goroutine 消费事件队列
t=M 收到 SIGTERM 或 Leader Election 丢失：
• ctx 被取消 -> 所有 controllerLoop.Run 返回 -> 等待 shutdownTimeout ->
主进程退出。

整体 & 常见误区表格

阶段	触发时机 / 条件	主要操作	是否并发?
注册	程序入口执行一次 NewControllerDescriptors	创建 map*ControllerDescriptor仅保存名称和构造函数，不实例化实际对象。	否

Leader Election 在 leaderElectAndRun 中阻塞 直到成功抢到租约。
竞争 kube-system/kube-controller-manager Lease；抢到后回调 OnStartedLeading。否

构造 Controllers Leader 成功后立即执行。怎么说呢，

• `CreateControllerContext` – 初始化共享 Informer、RESTMapper、metadata 工厂等。
• `BuildControllers` – 按注册顺序遍历 Descriptor，过滤未启用/特性关闭项后调用对应 constructor。怎么说呢，
• `InformerFactory.Start` – 启动底层 Watch。
• `close` – 发出 “Informer 已就绪” 信号。

否

并发运行 Controllers Informer 就绪后立即触发。

• `for each ctrl { go ctrl.Run }` – 每个控制器独立 goroutine。
• `wait.Jitter` – 随机延迟防止 “惊群”。
• `ctrl.Run` 本身是阻塞式入口，会在内部再派生 worker。
• `<-ctx.Done` – 主循环等待上下文取消。
• `shutdownTimeout` – 优雅关闭超时时间。
*

是 阻塞运行 & 优雅退出 收到 SIGTERM 或失去 Leader 权限。ctx 被 cancel → 所有 `Run` 返回 → 按 `shutdownTimeout` 等待结束。是

快速定位技巧：

• If you see “controller not started” in logs → check wher **InformerFactory.Start** has been called before **RunControllers** phase.
• If a specific controller never runs its business logic → verify that its descriptor passed **FeatureGate** and **IsEnabled** checks during **BuildControllers**.
• If you experience high API‑Server load at startup → tune .ComponentConfig.Generic.ControllerStartInterval/.controllerStartJitterMaxFactor.

This re‑organized view should make it crystal clear **when** registration happens。**when** each controller is actually instantiated,and **when** it finally starts processing events.

。

---