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

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

一句话定位

controller-tools 提供 controller-gen，用 Go marker 生成 CRD、RBAC、webhook、deepcopy 等 Kubernetes API 工程资产。

核心架构图

┌────────────────────────────────────────────────────────────────────────────┐
│ Go API source                                                              │
│ Types, Kubebuilder markers, RBAC comments, webhook comments, and object    │
│ metadata.                                                                  │
└────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ controller-gen                                                             │
│ Parses markers and type information to generate Kubernetes integration     │
│ artifacts.                                                                 │
└────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Generated artifacts                                                        │
│ CRD schemas, deepcopy code, RBAC manifests, webhook configs, and object    │
│ YAML.                                                                      │
└────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Consumers                                                                  │
│ Kubebuilder/operator build pipelines and cluster installation workflows.   │
└────────────────────────────────────────────────────────────────────────────┘

模块分层

关键数据流

开发者在 API types 写 markers
        │
        ▼
controller-gen 解析 package
        │
        ▼
生成 CRD/RBAC/webhook/deepcopy
        │
        ▼
kubebuilder/kustomize 打包部署

设计决策与哲学

• 补齐 API 生成工具 维度：controller-tools 让当前 wiki 不只停留在 serving engine 或单个 operator，而能解释 Kubernetes 平台里的相邻控制面。
• 边界判断：kubebuilder 是脚手架；controller-tools 是实际生成 CRD/RBAC 等产物的工具链。
• 选型价值：它应和 kubernetes, model-serving-operator, declarative-agent-management 一起看，而不是孤立评估。