Kubernetes 监控 Helm Chart 贡献指南：以 charts 仓库 prometheus-operator 为例的完整提交流程

本指南以 charts 仓库中stable/prometheus-operator目录下的 CONTRIBUTING.md 为骨架，完整展开向该 Chart 提交代码变更的规范流程：从 Fork 开发、版本号递增、PR 标题前缀、上游 Rules/Dashboards 同步，到 minikube 本地验证、RBAC 与 CRD 变更检查，以及最终通过helm lint。读完本文，你将掌握向这类集成型监控 Chart 提交高质量 PR 的完整方法论，并理解其背后的同步机制与校验工具链。

前置认知：prometheus-operator Chart 的定位与当前状态

在动手贡献之前，需要先清楚这个 Chart 是什么、由哪些部分构成，以及它当前的维护状态。这些信息记录在 Chart.yaml 与 README.md 中。

该 Chart 并不是只安装一个 operator 那么简单，它是一个"全家桶"式的监控栈：安装 prometheus-operator 来创建/配置/管理 Kubernetes 上的 Prometheus 集群，同时默认附带 Prometheus、Alertmanager、node-exporter、kube-state-metrics、Grafana，以及一组用于抓取集群内部组件的 ServiceMonitor（kube-apiserver、kube-scheduler、kube-controller-manager、etcd、kube-dns/coredns、kube-proxy），并内置配套的告警规则与 Grafana Dashboard。

从 requirements.yaml 可以看到它依赖三个子 Chart：

需要注意的关键事实（以当前仓库实际内容为准）：

• 该 Chart 已被标记为deprecated（deprecated: true），README 顶部有显著声明，其后续演进已迁移到其他项目（chart 更名为 kube-prometheus-stack）。向本仓库贡献时应基于当前快照的内容与规范，并清楚它已不再继续演进。
• 当前版本为version: 9.3.2，appVersion: 0.38.1，tillerVersion: ">=2.12.0"，属于 Helm v2 时代（Tiller 组件）的 Chart，因此贡献时相关的命令语境（helm install --name、helm init等）也是 Helm v2 时代的写法。

贡献流程总览：一条 8 步检查清单

CONTRIBUTING.md 将贡献流程凝练为 8 条硬性要求，任何提交都应按此顺序逐条自查：

下面逐条展开讲解，并结合仓库源码、配置与脚本说明每一项背后的具体做法。

Fork 开发与版本号递增：贡献的地基

第一条与第二条是任何 Helm Chart 贡献的通用起点。

Fork 与开发：从仓库 Fork 出自己的副本，在分支上修改stable/prometheus-operator/目录内的 Chart 文件（templates、values.yaml、crds 等），并在本地完成可验证的测试。测试的手段包括下文要讲的 minikube 环境，以及helm lint/helm template等静态校验。

版本号递增：每次变更（无论是修 bug、加参数还是改模板）都必须修改 Chart.yaml 中的version字段。当前为9.3.2，贡献时应按语义化版本规则递增。这一点至关重要：Helm 通过version区分 Chart 的不同发布，若两个不同内容的提交使用同一版本号，会导致helm install/helm upgrade的缓存与索引混乱，无法准确回溯"哪个版本对应哪次变更"。README 中的升级章节（如 8.x.x → 9.x.x、7.x.x → 8.x.x）也印证了"大版本号变化代表破坏性变更，需要人工操作"这一约定，例如从 8.x 升到 9.x 时additionalScrapeConfigsExternal被additionalScrapeConfigsSecret取代。

PR 标题前缀：让变更按目录可检索

第三条要求 PR 标题以[stable/prometheus-operator]开头。charts 仓库包含stable/与incubator/两大目录、数百个 Chart，每个 Chart 由独立维护者关注。通过目录名作为 PR 标题前缀，维护者可以快速过滤出与自己负责的 Chart 相关的 PR，自动化工具也可以按前缀路由通知。类似地，仓库根目录还有面向全仓库的 CONTRIBUTING.md 与 PROCESSES.md 规范（含 Chart 弃用/取消弃用流程），提交流程需要同时满足这两级规范。

改动 Rules 与 Dashboards：必须走上游同步链路

第四条是 prometheus-operator 这个 Chart 最有特色的贡献约束。它的 Grafana Dashboard 与 Prometheus Rules并非在本仓库直接维护，而是"从上游复制、经脚本同步（可能带修改）"而来。README 的 "Developing Prometheus Rules and Grafana Dashboards" 一节明确指出：要改动这些内容，需要先在上游仓库完成变更，再通过脚本同步到本仓库。

同步脚本的工作方式

仓库的 hack 目录 包含两个核心脚本：

• sync_prometheus_rules.py：从上游导入格式合法的 Prometheus 规则 YAML，按 group 名称拆分到 templates/prometheus/rules/ 下的多个独立规则文件（如alertmanager.rules.yaml、kube-apiserver.rules.yaml、node-time.yaml等）。
• sync_grafana_dashboards.py：从上游导入 Grafana Dashboard 的 JSON，拆分到 templates/grafana/dashboards/ 与dashboards-1.14/下的独立 YAML 文件。

上游导入链路

目前导入的规则与面板来源包括：

• kube-prometheus 规则集与 Dashboard：修改路径为 kubernetes-mixin（rules/dashboards）→ 上游 kube-prometheus（执行jb update与make generate-in-docker生成）→ 在本仓库 Fork 中运行同步脚本 → 提交 PR。
• etcd 规则集与 Dashboard：修改路径为 etcd 项目（etcd3_alert.rules.yml 与 grafana.json）→ 在本仓库 Fork 中运行同步脚本 → 提交 PR。

唯一例外是 dashboards-1.14/k8s-coredns.yaml，它是唯一在本仓库直接维护、无需走导入流程的 Dashboard。

这意味着贡献者在改动任何规则或面板前必须回答一个问题：这个改动应该发生在哪里？如果答案是上游，就先走完上游 PR 流程再回来同步；如果答案是 CoreDNS 面板，才可以直接改本仓库文件。这套机制保证了监控内容的上游单一来源，避免同一套规则在多个仓库中出现语义分叉。

用 hack/minikube 做本地端到端验证

第五条要求使用 hack/minikube 目录下的脚本搭建本地 minikube 环境，验证改动后"所有组件都能被真实抓取"。其 README 说明：该目录的配置用于在 minikube 上本地测试整套安装，通过cmd.sh搭建组件并 hack 出一份可用的 etcd 抓取配置。

cmd.sh 提供了按序执行的 5 个命令：

为什么需要 init-etcd-secret 与 values.yaml 配合

minikube 的 etcd 默认启用 TLS 证书认证，Prometheus 抓取 etcd 需要证书。init-etcd-secret从kube-apiserver-minikube容器内读取/var/lib/minikube/certs/etcd/下的ca.crt、apiserver-etcd-client.crt、apiserver-etcd-client.key，写入 monitoring 命名空间的etcd-certsSecret。

配套的 values.yaml 则完成两件事：

prometheus: prometheusSpec: secrets: [etcd-certs] kubeEtcd: serviceMonitor: scheme: https caFile: /etc/prometheus/secrets/etcd-certs/ca.crt certFile: /etc/prometheus/secrets/etcd-certs/client.crt keyFile: /etc/prometheus/secrets/etcd-certs/client.key

这里体现了 Chart 的一个关键设计：prometheus.prometheusSpec.secrets把 Secret 挂载进 Prometheus Pod 的/etc/prometheus/secrets/<secret-name>路径，而kubeEtcd.serviceMonitor的caFile/certFile/keyFile正是引用这一挂载路径。README 的 Exporters 参数表中对kubeEtcd.serviceMonitor.caFile等参数的说明（"Seeprometheus.prometheusSpec.secrets"）与此完全对应——这是理解"Secret 挂载 + ServiceMonitor 引用"这条链路的直接源码证据。

因此，贡献涉及抓取配置（尤其 etcd 这类 TLS 组件）时，应当用这套脚本实际拉起环境，确认抓取目标出现在 Prometheus 的 targets 中，而不是只做静态检查。

RBAC 变更检查：审视权限边界

第六条要求检查 RBAC 规则的变更。这个 Chart 的权限面很宽，RBAC 资源集中在模板目录中：

• Prometheus Operator 的权限：templates/prometheus-operator/clusterrole.yaml、clusterrolebinding.yaml，以及 Pod Security Policy 相关的psp-clusterrole.yaml、psp-clusterrolebinding.yaml、psp.yaml；
• Alertmanager 的 PSP 资源：templates/alertmanager/psp.yaml、psp-role.yaml、psp-rolebinding.yaml；
• 准入 Webhook 修补 Job 的权限：templates/prometheus-operator/admission-webhooks/job-patch/下的clusterrole.yaml、role.yaml、rolebinding.yaml等。

贡献时若改动这些文件，需要自问：权限是否仍然遵循最小化原则？是否引入了不必要的集群级权限？是否与global.rbac.create、global.rbac.pspEnabled等开关的行为一致？例如默认值表中global.rbac.create=true、global.rbac.pspEnabled=true，意味着关闭 RBAC 时相关资源不应再生成，模板中的条件渲染逻辑（if .Values.rbac.create）需要同步调整。

CRD 变更检查：与 operator 版本的匹配

第七条要求检查 CRD spec 的变更。该 Chart 自带的 CRD 清单位于 crds 目录：

• crd-alertmanager.yaml（Alertmanager）
• crd-podmonitor.yaml（PodMonitor）
• crd-prometheus.yaml（Prometheus）
• crd-prometheusrules.yaml（PrometheusRule）
• crd-servicemonitor.yaml（ServiceMonitor）
• crd-thanosrulers.yaml（ThanosRuler）

这与 README 卸载章节列出的 6 个 CRD（kubectl delete crd prometheuses.monitoring.coreos.com等）一一对应。贡献时若升级 operator 镜像（prometheusOperator.image.tag，当前默认v0.38.1）或改动任何 CRD 文件，必须确保二者版本匹配：CRD 新增字段、apiVersion 变更或行为变化都应同步反映，否则会出现"operator 期待新字段、集群里却是旧 CRD"的运行期问题。

与 CRD 相关的还有两个容易混淆的开关（来自 README 配置表）：

• prometheusOperator.createCustomResource（默认true）：Chart 是否创建 CRD。若在 Helm v2 且版本较旧的环境，需要先手动kubectl apply -f创建 CRD 再以--set prometheusOperator.createCustomResource=false安装（README 的 "Helm fails to create CRDs" 工作区一节给出了完整 6 个 CRD 的 apply 命令）；
• prometheusOperator.cleanupCustomResource（默认false）：卸载时是否尝试删除 CRD。README 明确不建议开启，因为删除 CRD 会连带删除其管理的资源，且 CRD 默认不会随helm delete被移除，需手工清理。

仓库 ci 目录 的两个测试 values 也从侧面印证了 CRD 的测试路径：01-provision-crds-values.yaml 关闭了除 operator 之外的全部组件（alertmanager.enabled: false、prometheus.enabled: false、defaultRules.create: false等），并设置createCustomResource: false、关闭 admissionWebhooks 与 tlsProxy，专门用于验证"仅 operator + 由它在启动时幂等创建 CRD"这一最小场景；02 号文件则对应"不带 CRD 的安装"场景。贡献涉及 CRD 时，应确保这两类 CI 场景仍然通过。

通过 helm lint：最后一道静态关卡

第八条要求 PR 必须通过helm lint。helm lint是 Helm 内置的 Chart 校验器，会检查 Chart 结构是否完整（Chart.yaml、values.yaml、templates 等）、YAML 语法是否合法、模板能否正常渲染等。对于本 Chart，由于它模板数量庞大（templates 下包含 prometheus-operator、prometheus、alertmanager、exporters、grafana 等多个子目录），任何模板改动都应在本地执行：

$ helm lint stable/prometheus-operator

只有 lint 通过，PR 才具备被合入的基本资格。作为补充，仓库 test 目录 还提供了 e2e 测试脚本（test/e2e.sh、helm-test-e2e.sh）与 Chart 测试工具配置 ct.yaml，贡献者可以参考这些测试基础设施了解全量校验是如何在 CI 中执行的。需要说明的是，本仓库的 Helm 命令语境基于 Helm v2（Tiller），实际执行时请匹配自己环境中的 Helm 版本与--name等参数用法。

提交前自检清单（速查）

综合 CONTRIBUTING.md 与上文分析，提交 PR 前请按此清单逐项确认：

1. 改动是否在 Fork 的分支中开发完成，并在本地（含 minikube 环境）验证过组件可被正常抓取；
2. Chart.yaml 的version是否已递增；
3. PR 标题是否以[stable/prometheus-operator]开头；
4. 若涉及规则或面板：是否先改上游（kubernetes-mixin / kube-prometheus / etcd），再通过 hack 目录 的sync_prometheus_rules.py/sync_grafana_dashboards.py同步（CoreDNS 面板除外）；
5. 是否用 hack/minikube/cmd.sh 按序执行reset-minikube→init-helm→init-etcd-secret→prometheus-operator完成了端到端验证；
6. 是否检查了 templates/prometheus-operator/ 等目录下 RBAC 文件的权限变更，确保最小权限；
7. 是否检查了 crds 目录 的 CRD spec 与 operator 镜像版本匹配，并覆盖 ci 目录 的两种 CRD 测试场景；
8. 是否已通过helm lint。

这套流程的价值在于：它把"改代码"变成"改代码 + 同步上游 + 端到端验证 + 静态校验"的完整闭环，保证了监控栈这类强耦合组件的每次变更都可追溯、可复现、可回滚。即使该 Chart 当前已标记为 deprecated，其贡献方法论——尤其是"面板与规则必须上游同步""CRD/RBAC 变更需专项检查""本地全组件验证"这三条原则——对任何复杂 Helm Chart 的维护者都有直接的借鉴意义。