controller-runtime 架构与设计思路分析

原文：raw/controller-runtime-architecture-analysis.md · 仓库：https://github.com/kubernetes-sigs/controller-runtime · 优先级 P0

一句话定位

controller-runtime 是现代 Kubernetes controller 的通用库，封装 Manager、cache、client、reconcile、webhook、envtest 等生产控制器骨架。

核心架构图

┌────────────────────────────────────────────────────────────────────────────┐
│ Custom controller binary                                                   │
│ Operator code is built around controller-runtime primitives.               │
└────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Manager                                                                    │
│ Scheme, leader election, metrics, health probes, webhooks, cache, and      │
│ lifecycle.                                                                 │
└────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Controller layer                                                           │
│ Informer cache, typed client, workqueue, reconciler, retry, status, and    │
│ finalizers.                                                                │
└────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Runtime boundary                                                           │
│ Kubernetes API server, admission webhooks, and envtest form the execution  │
│ surface.                                                                   │
└────────────────────────────────────────────────────────────────────────────┘

模块分层

关键数据流

manager 启动 cache/webhook/controllers
        │
        ▼
watch 事件进入 workqueue
        │
        ▼
reconciler 读取 cache/API
        │
        ▼
patch status/finalizer/owned resources
        │
        ▼
错误重试或完成

设计决策与哲学

• 补齐 Operator SDK 维度：controller-runtime 让当前 wiki 不只停留在 serving engine 或单个 operator，而能解释 Kubernetes 平台里的相邻控制面。
• 边界判断：client-go 是底层机制；controller-runtime 是现代 operator 工程默认抽象；kubebuilder 在其上做项目脚手架。
• 选型价值：它应和 kubernetes, model-serving-operator, declarative-agent-management 一起看，而不是孤立评估。