Kubebuilder 架构与设计思路分析

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

一句话定位

Kubebuilder 是构建 Kubernetes APIs using CRDs 的 SDK，把 API type、marker、controller-runtime manager、webhook、RBAC 和 manifests 生成流程标准化。

核心架构图

┌────────────────────────────────────────────────────────────────────────────┐
│ Operator author workflow                                                   │
│ kubebuilder init and create api define a project, API types, and           │
│ controllers.                                                               │
└────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Scaffolded project                                                         │
│ Project layout, controller-runtime Manager, Reconciler, tests, and config  │
│ tree.                                                                      │
└────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Generation toolchain                                                       │
│ controller-tools markers generate CRDs, RBAC, webhooks, deepcopy, and      │
│ manifests.                                                                 │
└────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Output                                                                     │
│ Controller image and installable Kubernetes manifests for an operator.     │
└────────────────────────────────────────────────────────────────────────────┘

模块分层

关键数据流

kubebuilder init
        │
        ▼
create api 生成 type/reconciler
        │
        ▼
开发 API marker 和 reconcile
        │
        ▼
controller-gen 生成 YAML
        │
        ▼
部署 controller manager

设计决策与哲学

• 补齐 CRD / controller 脚手架 维度：Kubebuilder 让当前 wiki 不只停留在 serving engine 或单个 operator，而能解释 Kubernetes 平台里的相邻控制面。
• 边界判断：kubebuilder 解决项目结构和生成路径；controller-runtime 解决运行时 controller 抽象。
• 选型价值：它应和 kubernetes, model-serving-operator, declarative-agent-management 一起看，而不是孤立评估。