企业官网建设流程全解析

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

Kubebuilder 在 3.15.0 版本起不再在新脚手架的默认配置中引入 kube-rbac-proxy，转而采用 Kubernetes 原生 NetworkPolicy、可选的 cert-manager 以及 controller-runtime 的指标安全特性来保护 /metrics 端点。本文基于仓库中的设计文档 designs/discontinue_usage_of_kube_rbac_proxy.md，梳理该决策的动机、四阶段落地计划、风险与替代方案，并结合仓库内脚手架 testdata（testdata/project-v4）展示升级后的真实清单配置，帮助读者理解如何迁移既有项目、如何按需启用 HTTPS 指标服务。

背景：为什么要弃用 kube-rbac-proxy

kube-rbac-proxy 是业界常用的边车（sidecar）代理，曾长期作为 Kubebuilder 默认脚手架中保护/metrics端点的手段。然而随着 Kubernetes 基础设施生态的演进，Kubebuilder 维护者重新评估了这一默认依赖，核心考量如下：

• 共享基础设施迁移：Kubernetes SIG 项目要求所有镜像发布到registry.k8s.io，而该发布流程只对 Kubernetes umbrella 内的项目生效；
• Google Container Registry（GCR）停服：Google Cloud Platform 官方宣布弃用 Container Registry，意味着 Kubebuilder 此前发布在gcr.io/kubebuilder/kube-rbac-proxy的镜像在2025 年 4 月 22 日起将不可再被获取；
• 未纳入 Kubernetes umbrella：kube-rbac-proxy 尚未正式进入 Kubernetes Auth SIG 的官方支持范围，Kubernetes Auth SIG 的评审显示其仍需大量改动才能获得官方背书；
• 维护权不在自身：Kubebuilder 维护者无法持续、可靠地为第三方项目构建和推送镜像，这违背了项目"可被维护者持续支撑"的目标。

其中最关键的一点是：依赖一个可能随时被停用的 Google 基础设施，且这种停用"不在我们控制范围内"，这对项目可靠性和镜像可用性构成了直接风险。社区对此也有明确诉求，见 issue #3482（社区成员希望将其从默认脚手架移除）与 #3230（镜像可用性风险）。

目标与非目标：界定改造边界

目标

• 最大化指标端点保护，不新增第三方依赖：在不需要构建、推送第三方镜像的前提下，提供尽可能高的保护等级；
• 避免破坏性变更：用旧版本生成项目的用户仍可使用新版本脚手架，并可按自己的节奏迁移；
• 可持续维护：所有由 Kubebuilder 脚手架生成的项目都应由其维护者可持续地支撑；
• 摆脱 Google Cloud Platform 依赖：考虑到 GCP 可能单方面关停服务，主动迁移；
• 符合 Kubernetes umbrella 规范：不再推广或背书尚未被 Kubernetes umbrella 组织认可、且随工作负载一起交付的方案；
• 推广外部插件 API：遵循 Kubebuilder 通过外部插件（external plugins）支持第三方集成的指导方针，让第三方项目维护者自己维护与脚手架集成的实现；
• 网络策略使用可灵活开关：允许用户选择不使用 NetworkPolicy（例如打算使用不支持的 CNI 或供应商方案时）。

非目标

需要明确的是：本提案不以复刻 kube-rbac-proxy 的功能或同等保护级别为目标。NetworkPolicy 与 kube-rbac-proxy 的工作方式不同——前者是基于 IP 地址/端口层级的简单防火墙，不直接提供 authn/authz 与加密能力。因此，仅靠 NetworkPolicy 无法达到与 kube-rbac-proxy 完全一致的保护水平。

不过，通过组合 NetworkPolicy、cert-manager 以及 controller-runtime 引入的新特性（PR #2407），可以从整体上回应 kube-rbac-proxy 所处理的主要安全关切。

四阶段落地计划

提案将整个迁移拆解为四个阶段，每阶段都必须伴随对应的文档更新（文档更新要求），确保最终用户理解如何启用、配置和使用这些选项。

阶段一：过渡到 NetworkPolicy（默认行为）

这是本提案的立即行动：用 Kubernetes 原生 NetworkPolicy 替换 kube-rbac-proxy。从release 3.15.0开始，Kubebuilder 不再为新项目脚手架 kube-rbac-proxy，默认启用 NetworkPolicy 保护。

仓库 testdata 中已经固化了这一脚手架形态，见 testdata/project-v4/config/network-policy：

• allow-metrics-traffic.yaml：仅允许来自带有metrics: enabled标签的命名空间中的 Pod 访问 8443 端口（即指标端口），把抓取指标的行为显式限定在已打标签的命名空间内：

apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: labels: app.kubernetes.io/name: project-v4 app.kubernetes.io/managed-by: kustomize name: allow-metrics-traffic namespace: system spec: podSelector: matchLabels: control-plane: controller-manager app.kubernetes.io/name: project-v4 policyTypes: - Ingress ingress: # Allow pods in namespaces labeled 'metrics: enabled' to scrape metrics. - from: - namespaceSelector: matchLabels: metrics: enabled # Only from namespaces with this label ports: - port: 8443 protocol: TCP

• allow-webhook-traffic.yaml：允许所有来源访问 Webhook 的 9443 Pod 端口（Kubernetes API server 需要通过 Service 访问准入与 CRD 转换 Webhook）：

apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: labels: app.kubernetes.io/name: project-v4 app.kubernetes.io/managed-by: kustomize name: allow-webhook-traffic namespace: system spec: podSelector: matchLabels: control-plane: controller-manager app.kubernetes.io/name: project-v4 policyTypes: - Ingress ingress: - ports: - port: 9443 protocol: TCP

• kustomization.yaml：将以上两个资源聚合为一个可被 kustomize 引用的组件。

在项目根配置 testdata/project-v4/config/default/kustomization.yaml 中，network-policy 默认处于注释状态，用户按需取消注释即可启用（# [NETWORK POLICY] Control ingress to metrics and webhook ports.下的#- ../network-policy）；由于它是默认脚手架的一部分，新项目可通过取消注释直接开启。这一设计同时满足了"默认启用（体现在脚手架上）"与"用户可自由 opt-out（通过注释）"两个要求——例如当用户使用不支持 NetworkPolicy 的 CNI 时，可以整体跳过该组件。

开放问题 1 的回应：NetworkPolicy 虽然属于 Kubernetes 核心 API，但其强制执行依赖集群安装的 CNI 插件。主流 CNI（Calico、Cilium、WeaveNet、Canal）均支持 NetworkPolicy；AWS 此前不支持，但 Amazon VPC CNI 已宣布支持 Kubernetes Network Policies。此外，在该提案下用户仍可按需启用/禁用该选项。

阶段二：将 cert-manager 作为指标的可选选项

在第一阶段落地（对应开源 PR #3853）之后，提案设想引入 cert-manager 做 TLS 证书管理，并与 controller-runtime 的新特性（PR #2407）形成协同，为指标端点带来加密通信乃至基于 mTLS 的认证能力，显著提升脚手架项目的安全模型。

• cert-manager：自动化 TLS 证书的签发与管理，配置 mTLS 时还能增加一层认证。目前 Kubebuilder 在脚手架 Webhook 时已使用 cert-manager，提案的思路是让用户能像 Webhook 一样为指标启用 cert-manager；
• 必须保持可选：Kubebuilder 的目标之一是降低新用户门槛，因此默认脚手架与快速开始流程不应强制用户安装 cert-manager；只有在启用 Webhook、启用指标 HTTPS 等特定功能时才建议使用。

实现方式是在config/default/kustomization.yaml中引入一个可配置的 Kustomize patch，用于同时 patchconfig/prometheus/monitor.yaml中的 ServiceMonitor 与证书，类似现有 Webhook 的做法（现有 Webhook 场景下config/default/kustomization.yaml已通过 replacements 注入 cert-manager CA 注入注解，覆盖 ValidatingWebhookConfiguration、MutatingWebhookConfiguration 与 CRD）。提案设计了一个名为metrics_https_patch.yaml的 patch 文件，启用方式为：

# [METRICS WITH HTTPS] To enable the ServiceMonitor using HTTPS, uncomment the following line # Note that for this to work, you also need to ensure that cert-manager is enabled in your project - path: metrics_https_patch.yaml

启用 cert-manager 后的 ServiceMonitor 示例如下（这是提案给出的目标形态，强调生产环境不应跳过 TLS 校验）：

# Prometheus Monitor Service (Metrics) with cert-manager apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: labels: control-plane: controller-manager app.kubernetes.io/name: project-v4 app.kubernetes.io/managed-by: kustomize name: controller-manager-metrics-monitor namespace: system annotations: cert-manager.io/inject-ca-from: $(NAMESPACE)/controller-manager-certificate spec: endpoints: - path: /metrics port: https scheme: https bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token tlsConfig: # We should recommend ensure that TLS verification is not skipped in production insecureSkipVerify: false caFile: /etc/prometheus/secrets/ca.crt # CA certificate injected by cert-manager certFile: /etc/prometheus/secrets/tls.crt # TLS certificate injected by cert-manager keyFile: /etc/prometheus/secrets/tls.key # TLS private key injected by cert-manager selector: matchLabels: control-plane: controller-manager

仓库中已固化的可对照实现

虽然metrics_https_patch.yaml本身是提案中的规划产物，但仓库 testdata 已经实现了与之同构的"cert-manager 保护指标"配置，可作为落地参考：

• cert_metrics_manager_patch.yaml：通过 Kustomize 为 manager Deployment 添加volumeMounts、--metrics-cert-path=/tmp/k8s-metrics-server/metrics-certs参数，并挂载来自metrics-server-certSecret 的ca.crt、tls.crt、tls.key；
• certificate-metrics.yaml：定义一个由selfsigned-issuer签发的metrics-certsCertificate，dnsNames由config/default/kustomization.yaml中的 replacements 注入SERVICE_NAME.SERVICE_NAMESPACE.svc(.cluster.local)；
• monitor_tls_patch.yaml：将 ServiceMonitor 的tlsConfig替换为从metrics-server-certSecret 读取ca、cert与keySecret，并把insecureSkipVerify置为false；
• 未使用 cert-manager 时，脚手架默认的 monitor.yaml 使用insecureSkipVerify: true，并注释明确提示生产环境不推荐该配置、建议启用 cert-manager。

启用上述 HTTPS 指标链路的入口同样是 config/default/kustomization.yaml 中注释掉的cert_metrics_manager_patch.yaml与[METRICS-WITH-CERTS]段，以及默认启用的manager_metrics_patch.yaml（通过--metrics-bind-address=:8443让 manager 以 HTTPS 暴露指标）。指标 Service 定义见 metrics_service.yaml，其https端口为 8443。

开放问题 2 与 6 的回应：NetworkPolicy 确实不提供 authn/authz 与加密，但结合 cert-manager 与 controller-runtime 新特性可以达到同等甚至更高的保护水平且无第三方依赖；同时 cert-manager 不能被默认强制启用——Kubebuilder 的目标是让新用户快速上手，但可以对 Webhook、指标 HTTPS 等特定高级功能做强制要求。

阶段三：利用增强后的 controller-runtime 特性

controller-runtime 的 issue #2781 跟踪了指标端点安全配置对齐最佳实践的诉求。在该问题得到解决后，提案计划直接用 controller-runtime 的能力保护指标端点，同时处理authn（认证）与 authz（授权）。实现示例参考了 cluster-api 项目的util/flags/diagnostics.go。

将来启用该能力时，main.go中 manager 的构造将形如：

ctrlOptions := ctrl.Options{ MetricsFilterProvider: filters.WithAuthenticationAndAuthorization, MetricsSecureServing: true, }

开放问题 5 的回应：是的，可以在修复若干问题后使用 controller-runtime 的 HTTPS 安全指标服务特性——但该配置需要与最佳实践对齐，这正是 issue #2781 的跟踪目标。

开放问题 3 与 4 的回应：Kubebuilder 曾尝试借助共享基础设施继续构建并推送镜像（test-infra 中有对应 recipe），但 kube-rbac-proxy 不在 Kubernetes umbrella 下而无法生效；也实验过用 GitHub 仓库作为替代（PR #3854），但似乎不被允许。而 EnvTest 使用的二进制同样面临此问题，controller-runtime 维护者已计划在自己项目内构建这些二进制，该变更对社区用户大概率是透明的——这进一步印证了"Kubebuilder 不应负责维护和推广第三方制品"的立场。

阶段四：kube-rbac-proxy 进入 umbrella 后以外部插件回归

一旦 kube-rbac-proxy 被纳入 Kubernetes umbrella（可跟踪 brancz/kube-rbac-proxy#238 与 创建插件）将其集成，用户即可按需选择：

kubebuilder init|edit --plugins="kube-rbac-proxy/v1"

该插件可复用 pkg/plugin/util 提供的代码操作工具——例如 util.go 中的UncommentCode（搜索目标内容并移除注释前缀）用于打开config/default/kustomization中被注释的 patch、启用 NetworkPolicy 的默认禁用，以及 util.go 中的ReplaceInFile（替换文件中全部匹配内容）用于把main.go中的指标安全配置替换为 controller-runtime 原生特性。

这一方案让 kube-rbac-proxy 以"用户自行 opt-in"的方式融入脚手架，符合 Kubebuilder 通过插件 API 支持第三方集成的方针——第三方项目维护者最熟悉自己的方案，由其维护集成实现最有利于用户体验。

开放问题与官方回应

风险与缓解

已推广镜像的丢失风险

迁移到 Kubernetes SIG 共享基础设施后，Kubebuilder 无法再像以前一样自动构建和推广镜像——该流程仅对 umbrella 内项目生效。缓解措施包括：

• k8s-infra 维护者可作为"应急方案"手动将镜像迁移到新的registry.k8s.io；
• 仍想使用 kube-rbac-proxy 的用户，最佳路径是切换到由项目自身维护在quay.io（quay.io/repository/brancz/kube-rbac-proxy）的镜像；
• 继续使用 kube-rbac-proxy 需要用户更新项目、发布新版本，并确保config/default/manager_auth_proxy_patch.yaml中的镜像引用指向新位置。

必须明确：保证这些镜像在任何基础设施下持续被推广，对 Kubebuilder 维护者而言"绝对超出我们的控制范围"，并不可靠。

Google Cloud Platform 项目的影响

截至目前 Kubebuilder 尚未收到其 GCP 项目被关停的官方通知，但由于 GCR 弃用，用户从2025 年初起将无法从原位置消费这些镜像。项目将通过与社区开放沟通、通过邮件列表等渠道广泛通知，推动尽早脱离对相关镜像的依赖。

备选方案评估

方案 A：仅把镜像从gcr.io换成registry.k8s.io

由 k8s-infra 维护者手动将镜像加入gcr.io/k8s-staging-kubebuilder/kube-rbac-proxy并推广到registry.k8s.io/kubebuilder/kube-rbac-proxy，同时：

• a) 引导用户把镜像仓库从gcr.io/k8s-staging-kubebuilder/kube-rbac-proxy改为registry.k8s.io/kubebuilder/kube-rbac-proxy；
• b) 在文档、脚手架与所有渠道（含邮件）中明确声明：kube-rbac-proxy 正在成为 Kubernetes/auth-sig 的一部分但尚未完成，因此是"不受支持/不安全"的方案。

缺点：Kubebuilder 仍不符合自身目标（脚手架第三方集成而非推广外部插件 API）；仍在推广 auth-sig 评审认为不够安全/可靠的方案；仍需手动请求 k8s-infra 维护者构建与推广镜像；用户需要改动所有已支持的项目并保证旧版本不被继续使用；且将来 kube-rbac-proxy 被 umbrella 接受后路径还会再次变更，Kubebuilder 无法确保镜像长期可用。

方案 B：保留 kube-rbac-proxy 为 opt-in，并下沉为 alpha 插件

该方案将 kube-rbac-proxy 移出默认脚手架，作为可选插件供用户集成，同时清晰沟通其使用影响。

缺点：基本继承方案 A 的全部缺点（区别在于明确声明 Kubebuilder 无法管理这些镜像，并把当前实现移入 alpha 插件，可能让后续从 Kubebuilder 仓库迁往 kube-rbac-proxy 仓库的过程更顺畅）。但这对用户和 Kubebuilder 维护者而言都是"双倍的工作量"——需要为达成最终目标处理两轮破坏性变更。因此更合理的做法是一次到位：直接鼓励使用外部插件 API，让 kube-rbac-proxy 在自己仓库中集成一次，而不要设置这些中间步骤。

总结与迁移建议

决策结论：从 Kubebuilder3.15.0起，默认脚手架不再包含 kube-rbac-proxy。具体建议如下：

• 已有用户：切换至项目托管于 quay.io 的镜像，或按照更新的脚手架指南改用 NetworkPolicy；
• 项目更新：可人工审查脚手架变更，或使用项目提供的升级辅助工具（rescaffold 相关说明见 docs/book/src/reference）；
• 版本发布：相关沟通与使用指南将随 release 一同发布。

对正在维护 Kubebuilder 项目的开发者，本设计文档给出了清晰的迁移路径：默认接受 NetworkPolicy 方案（在config/default/kustomization.yaml取消#- ../network-policy注释）；需要 HTTPS 指标时按 阶段二 启用 cert-manager 与对应 patch；期望更高安全级别时跟踪 controller-runtime 的指标安全特性演进；而 kube-rbac-proxy 的回归将以外部插件形态出现，等待其进入 Kubernetes umbrella。

该提案的价值在于：既回应了社区对"减少第三方依赖、增强可维护性"的长期诉求，又通过分阶段设计保证了向后兼容与用户自由度——这正是 设计文档 中"开放问题 + 四阶段 + 备选方案"结构所呈现的完整决策逻辑。

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