企业官网建设流程全解析

• 开发者工具
• 代码生成
• CLI
• 云原生
• 后端

2024 年是 Kubebuilder 从"功能加法"转向"精简与合规"的关键一年。本指南以仓库 roadmap/roadmap_2024.md 为核心骨架，系统梳理该年度五大战略目标——脚手架对齐 controller-runtime 最新演进、新增 Helm Chart 打包插件、基础设施从 GCP 迁往 Kubernetes 共享体系、kube-rbac-proxy 退出默认脚手架、以及 4.x 大版本移除废弃插件，并结合作者仓库中的设计文档与真实脚手架产物（testdata）给出可验证的落地细节。读完本文，你将理解 Kubebuilder 2024 年各项决策背后的动机、影响范围与迁移路径，并掌握build-installer分发、NetworkPolicy 保护 metrics 端点等实操手段。

路线图总览：2024 年的五大核心目标

Kubebuilder 的路线图由 roadmap/README.md 统一组织，按年度拆分为 roadmap_2024.md、roadmap_2025.md、roadmap_2026.md，每个目标条目遵循统一的模板（Status / Objective / Context / Motivations / References）。2024 年路线图列出的目标及其最终状态如下：

这些目标并非彼此孤立：例如"去 kube-rbac-proxy 化"同时牵动基础设施迁移与 metrics 端点安全方案的重构，而"移除废弃插件"则是 4.x 大版本整理的一部分。下文逐一展开。

一、脚手架对齐 controller-runtime 的最新变化

背景：稳定的插件系统 vs 快速演进的 controller-runtime

Kubebuilder 的插件系统设计上追求稳定，但它所依赖的 controller-runtime 仍在快速演进（当时版本仍低于 1.0.0）。controller-runtime 中围绕 webhook 的若干变更与弃用（deprecation）直接影响 Kubebuilder 生成的脚手架、示例与文档。为此，2024 年路线图将该目标列为第一优先级：更新 Kubebuilder 的 controller 脚手架、samples 与文档，使其与 controller-runtime 的最新实践保持一致。

落地与验收：release 4.3.0

该目标于 release4.3.0完成，主要工作集中在 webhook 相关接口的适配。仓库中的对应实现可参考 pkg/plugins/golang/v4 下的 webhook 脚手架（webhook.go）以及 testdata/project-v4/internal/webhook 中真实生成的 webhook 代码，后者是验证脚手架输出是否符合新接口的直接样本。用户在升级到 4.3.0 后，重新生成的 webhook 代码将遵循 controller-runtime 最新的 handler 接口约定。

关于 webhook 的基础概念与手工接入方式，可进一步参考 docs/book/src/reference/webhook-overview.md 与 docs/book/src/reference/admission-webhook.md。

二、新增可选插件：Helm Chart 打包（helm/v2alpha）

动机：让解决方案"可分发、可集成"

Kubernetes 生态的快速增长，使得解决方案的分发方式需要更灵活、更易获取。Kubebuilder 社区由此提出为项目提供 Helm Chart 打包能力，简化解决方案在集群中的分发与集成，方便管理员与常见应用结合使用。

现状：初版已合并，社区协作持续推进

该目标状态为"✅ 完成（初版已合并，欢迎进一步改进与贡献）"。实现位于 pkg/plugins/optional/helm/v2alpha，是 Kubebuilder 的可选插件之一——它不进入默认脚手架，而是由用户按需启用。这与 roadmap/README.md 中"聚焦项目范围、最小化第三方依赖"的总方针一致：Kubebuilder 作为库提供插件 API，具体集成交由最了解自身项目的维护者完成。

可选插件家族中与 helm 并列的还有 pkg/plugins/optional/grafana/v1alpha（Grafana 面板）与 pkg/plugins/optional/autoupdate/v1alpha（自动更新），它们共同体现了"按需扩展、默认精简"的设计哲学。

三、基础设施迁移：从 GCP 走向 Kubernetes 共享体系

目标与动机

Kubernetes 项目整体倡导从 GCP 迁移到共享基础设施，并将镜像仓库从k8s.gcr.io迁往registry.k8s.io。Kubebuilder 2024 路线图明确跟进这一倡议，动机包括：确保构建产物的长期可用性、与 kubernetes-sigs 组织下其他项目保持一致、降低对"可能被单方面关停"的 GCP 项目的依赖（可参考 designs/discontinue_usage_of_kube_rbac_proxy.md 中对 GCP 依赖风险的论述）。

迁移范围与状态

值得强调的是，GCP 当时仅用于三类工作：重建并托管 kube-rbac-proxy 镜像（该镜像的构建配置记录在 RELEASE.md 的 "To build the kube-rbac-proxy images" 小节）、构建与发布 EnvTest 二进制（对应 RELEASE.md 的 "To build the kubebuilder-tools artifacts" 小节），以及 PR 标题检查镜像。路线图明确邀请社区参与讨论、提供反馈，以共同塑造更安全高效的脚手架方案。

四、kube-rbac-proxy 退出默认脚手架（3.15.0 起）

这是 2024 年路线图中影响面最大的一项变更，其完整设计记录在 designs/discontinue_usage_of_kube_rbac_proxy.md（状态为 Implementable，作者 @camilamacedo86）。该设计文档既是路线图条目的依据，也是理解迁移细节的第一手资料。

为什么要移除：多重压力叠加

• 基础设施可靠性：kube-rbac-proxy 不属于 Kubernetes 伞形组织，其镜像依赖 Google 基础设施重建与托管；GCR 宣布弃用后，此前由 Kubebuilder 提供的全部 kube-rbac-proxy 镜像在 2025 年 4 月 22 日后将不可用。
• 安全与背书：kube-rbac-proxy 长期处于加入 Kubernetes auth-sig 的流程中，但尚未获得官方背书；auth-sig 审查要求其进行重大更新。
• 社区反馈：部分社区成员认为 kube-rbac-proxy 过于"教条"（issue #3482），倾向默认集成 cert-manager 以配合 Prometheus 与 metrics 的安全诉求（issue #3657）。
• 维护负担：为第三方项目重建镜像、持续打标签，给 Kubebuilder 维护者带来沉重负担。

结论：自 3.15.0 起不再默认生成，并给出两条出路

设计文档明确了分阶段迁移路径：

• Phase 1（即刻执行）：以 Kubernetes NetworkPolicy 取代 kube-rbac-proxy，对应 PR #3853 与发布说明中的迁移指引。
• Phase 2（可选增强）：将 cert-manager 作为可选选项与 metrics 结合，实现 metrics 端点的加密通信（对应 config/default/kustomization.yaml 中[METRICS-WITH-CERTS]一节的cert_metrics_manager_patch.yaml挂载逻辑）。
• Phase 3（待 controller-runtime 增强）：利用 controller-runtime 新增的 metrics 安全服务特性（MetricsFilterProvider/MetricsSecureServing），见 main.go 中对应的配置模式。
• Phase 4（未来）：一旦 kube-rbac-proxy 进入 Kubernetes 伞形组织，则通过 Kubebuilder 外部插件 API 提供集成，用户可显式执行kubebuilder init|edit --plugins="kube-rbac-proxy/v1"按需启用。

对于现有用户，设计文档给出的两条出路是：改用 kube-rbac-proxy 项目自身在 quay.io 托管的镜像，或按照更新后的脚手架指引改用 NetworkPolicy。

当前脚手架中的落地形态：NetworkPolicy 保护 metrics 端点

在仓库的 v4 测试项目中，可以找到 NetworkPolicy 的实际落地产物：

• testdata/project-v4/config/network-policy/allow-metrics-traffic.yaml：仅允许来自带有metrics: enabled标签命名空间中的 Pod，访问 controller-manager 的 8443 端口（TCP）。
• testdata/project-v4/config/network-policy/kustomization.yaml：同时注册allow-webhook-traffic.yaml与allow-metrics-traffic.yaml。
• 在 config/default/kustomization.yaml 中，../network-policy默认以注释形式存在（#- ../network-policy），用户取消注释即可启用——这正体现了设计文档中"允许用户按需开关"的灵活性。

NetworkPolicy 的本质是集群 CNI 层面的"简单防火墙"，它只控制 IP/端口层面的流量，不提供 authn/authz 与加密；设计文档对此坦诚回应：通过叠加 cert-manager 证书与 controller-runtime 的 metrics 安全特性，可以在不引入额外第三方依赖的前提下达到相同或更优的保护水平。需要提醒的是，NetworkPolicy 的执行依赖集群 CNI 的支持——Calico、Cilium、WeaveNet、Canal 以及更新后的 Amazon VPC CNI 均支持，但用户在采用前仍需确认自身 CNI 能力。

metrics 端点的新式安全配置样例

设计文档给出了配合 cert-manager 的 ServiceMonitor 示例。在当前的 v4 脚手架中，metrics 相关配置分布在：

• metrics_service.yaml：metrics Service，暴露 8443 端口。
• manager_metrics_patch.yaml：为 manager 容器追加--metrics-bind-address=:8443参数，启用 HTTPS metrics 端点。
• cert_metrics_manager_patch.yaml：挂载 metrics-server 证书（ca.crt/tls.crt/tls.key）并追加--metrics-cert-path参数。

上述配置的完整讲解可参考 docs/book/src/reference/metrics.md，其中对 HTTPS metrics 端点、ServiceMonitor 与证书注入有更细致的说明。

五、项目分发辅助：build-installerMakefile 目标（v3.14.0 起）

为了让 Kubebuilder 项目更容易部署到集群，2024 路线图将"Kustomize 分发"列为已完成目标，自 releasev3.14.0起，脚手架新增了build-installerMakefile 目标。

实操：一键生成可分发的 install.yaml

在任一 v4 项目中执行：

make build-installer IMG=<registry>/<project>:tag

即可在项目dist/目录下生成一个聚合了 CRD 与 Deployment 的dist/install.yaml。其实现位于 testdata/project-v4/Makefile：

.PHONY: build-installer build-installer: manifests generate kustomize ## Generate a consolidated YAML with CRDs and deployment. mkdir -p dist cd config/manager && "$(KUSTOMIZE)" edit set image controller=${IMG} "$(KUSTOMIZE)" build config/default > dist/install.yaml

注意该目标先依赖manifests generate kustomize，确保 CRD 与生成的代码是最新的，然后用kustomize edit set image注入镜像，最后将config/default的全部资源（含 CRD、RBAC、manager、可选的 webhook/certmanager/network-policy）折叠为单个 YAML。生成后即可直接通过 URL 部署：

kubectl apply -f https://raw.githubusercontent.com/<org>/my-project/<tag or branch>/dist/install.yaml

这一能力极大降低了 Kubebuilder 项目"上集群"的门槛：将dist/install.yaml托管到任意静态站点或 Git 仓库，即可让用户一条命令完成部署。

六、4.x 大版本：移除废弃插件，提升可维护性与用户体验

目标与动机

随着 Kubebuilder 演进到 CLI 4.x，维护"已无法继续支持"的旧插件版本/种类代价高昂。2024 路线图将"移除全部废弃插件"列为大版本目标，动机在于：精简开发流程、消除用户困惑，并以清晰更新的文档提升整体用户体验。

落地：废弃移除 + 模块 bump

该目标已完成并发布：

• 移除弃用：对应 issue #3603 的清理工作，将不再支持的插件版本/种类从代码库中删除。
• 模块 bump：对应 PR #3924，将 Kubebuilder 主模块版本提升至 4.x，使插件版本语义与 CLI 版本体系对齐，避免旧插件与新 CLI 的兼容歧义。

对用户而言，升级到 4.x 意味着不再能使用被移除的旧版插件；需要检查自身项目的 PROJECT 文件 中所声明的插件版本，确保其属于 4.x 支持的集合，必要时使用kubebuilder的迁移/重新生成能力更新脚手架。

如何跟进与参与后续路线图

Kubebuilder 的路线图迭代机制保持开放：社区可以对照 roadmap/README.md 中的条目模板提出新目标，通过 CONTRIBUTING.md 提交 issue 或 PR。2024 年之后的方向可查看 roadmap_2025.md 与 roadmap_2026.md。作者仓库中的设计文档目录 designs 还沉淀了 crd 版本转换、extensible CLI 插件阶段设计、简化脚手架等提案，与年度路线图互为补充，是理解 Kubebuilder 演进脉络的高价值资料。

结语：2024 年路线图的启示

回顾 2024 年 Kubebuilder 的五项目标，可以清晰看到一条主线：在保证脚手架稳定的前提下，持续降低对第三方依赖与外部基础设施的耦合。无论是 webhook 接口对齐 controller-runtime、以 Helm 插件扩展分发能力、将构建发布迁往共享基础设施，还是以 NetworkPolicy + cert-manager 组合取代 kube-rbac-proxy、在大版本中清理废弃插件，最终都指向同一个目标——让 Kubebuilder 生成的 Go 项目更安全、更易维护、更可持续地长期运行在 Kubernetes 生态中。对于正在使用或计划采用 Kubebuilder 的开发者，理解这些变化及其迁移路径，是顺利升级到 3.15+/4.x 并保障项目长期健康的关键前提。

• 开发者工具
• 代码生成
• CLI
• 云原生
• 后端