跳转至

SOP — prometheus_deploy/values.yaml 回写现场基线（消除文件与现场漂移）

主题工程：prometheus-baseline-align-20261003｜变更日期：2026-10-03｜类型：纯文件对齐（不改动运行系统） 关联：HANDOFF §3.3「values.yaml 与现场漂移」、log-metrics-crosslink-20261002/SOP.md §11.2

1. 背景

2026-10-02 日志↔指标互跳第四阶段发现：prometheus_deploy/values.yaml 已不是现场基线 —— 现场 values（helm get values）比文件多出若干项。当时为规避风险，相关升级一律改走 --reuse-values -f <overlay>，未回写文件，该项以【待决策】挂在 HANDOFF §3.3。

2026-10-03 实测：漂移已由 10 项涨到 13 项 —— 第四阶段的 K8s 节点 relabel 与 组三 #12 的 grafana 内存上调都只走了 overlay、没回写。漂移会随每次 overlay 式升级继续扩大， 且新人若照 RUNBOOK.md §5.2 用 -f values.yaml 单文件升级，会静默丢掉这 13 项 （邮件路由失效、Grafana 调度漂移、内存回退、大盘标签缺失）。用户决策：执行回写。

2. 目标

  1. prometheus_deploy/values.yaml 成为现场完整基线（唯一例外见下）；
  2. 判据：helm template -f values.yaml（单文件）渲染结果与 -f <现场 values> 渲染结果 逐字节一致；
  3. 例外：SMTP 授权码不回写（凭据不入库），继续由 dell-r620-monitor 工程从 ~/.secrets 运行时注入。

3. 前置条件

  • kubectl / helm 可用且指向本集群；release kube-prometheus-stack 处于 deployed（本次为 revision 12）；
  • chart 包在本工程内：prometheus_deploy/charts/kube-prometheus-stack-91.4.1.tgz；
  • 读取 ~/.secrets/ 内凭据时只 source 不打印（本 SOP 不涉及读取授权码明文）。

4. 影响范围

项 说明
变更对象 仅文件 prometheus_deploy/values.yaml（+ 本主题文档与项目档案）
运行系统 不改动——不执行 helm upgrade，无 Pod 重启、无服务中断
业务影响 无。本次是"让文件追上现场"，现场本就是这 13 项生效态
窗口期 无（纯文件操作）

5. 分步操作

步骤 1：备份文件基线（高危动作前必做）

覆盖现有 values.yaml 前先备份，落在本主题 backup/prometheus_deploy/ 并登记台账。

cd /home/rain/Documents/k8s_ins
mkdir -p prometheus-baseline-align-20261003/backup/prometheus_deploy
cp -p prometheus_deploy/values.yaml \
  prometheus-baseline-align-20261003/backup/prometheus_deploy/values.yaml.bak.$(date +%Y%m%d-%H%M%S)

预期：backup/prometheus_deploy/ 出现一个 .bak.<时间戳>；失败判断：目录不可写 → 先修权限再继续（未备份不得往下走）。

步骤 2：落盘现场基线

helm get values 默认只返回用户提供的 values（不含 chart 默认值），正是"现场基线"的本体。

cd /home/rain/Documents/k8s_ins
helm -n monitoring get values kube-prometheus-stack -o yaml > prometheus-baseline-align-20261003/live-values.yaml
helm -n monitoring get manifest kube-prometheus-stack   > prometheus-baseline-align-20261003/live-manifest.yaml
wc -l prometheus-baseline-align-20261003/live-values.yaml   # 本次实测 220 行

坑：live-values.yaml 含 SMTP 授权码明文（来自 ~/.secrets 注入）—— 后续任何打印/比对必须打码，禁止整体 Read/cat。

步骤 3：逐键比对，定位差异

用一次性脚本按键路径递归比对（对 dict 递归、对 list 整体比较——helm 对 list 是整体替换）， 输出三类差异；含 password/secret/token 的键一律打码。

cd /home/rain/Documents/k8s_ins
python3 prometheus-baseline-align-20261003/compare_values.py

预期：列出现场有而文件缺的项、文件有而现场无的项、两侧值不同的项。本次实测 13 项（明细见附录 A）。

步骤 4：回写 values.yaml（12 项）

按差异逐处 SearchReplace 回写，并更新过时注释：

回写位置 内容
alertmanager.config.global smarthost / from / username / require_tls 四项（授权码不回写，改注释写明注入方式）
alertmanager.config.inhibit_rules 新增（主机 exporter 掉线时抑制同主机 host 告警）
alertmanager.config.route.group_by + route.routes group_by 加 alertname/cluster；新增 6 条分级路由
alertmanager.config.receivers 新增 env-monitor-email-p1/p2/p3 三个邮件接收器
grafana.nodeSelector 新增，固定 k8s-node-03
grafana.resources requests.memory 256Mi→384Mi、limits.memory 512Mi→1Gi（组三 #12）
prometheus-node-exporter.prometheus.monitor.relabelings 新增两条（hostname / cluster，第四阶段）

段首注释同步更正：Alertmanager 由"不接告警渠道"改为"已接 SMTP 邮件告警（P1/P2 分级 + P3 心跳）"。

坑（凭据红线）：授权码是唯一有意不回写的项。values.yaml 中只保留两行注释说明注入方式， 文件内不得出现授权码明文。

步骤 5：验证（见第 6 章）

6. 验证

判据一：单文件渲染 == 现场渲染（逐字节）

两侧用同一个占位授权码渲染，消除唯一差异项后应完全一致——这是"文件已等价于现场"的直接证据。

cd /home/rain/Documents/k8s_ins/prometheus_deploy && D=/home/rain/Documents/k8s_ins/prometheus-baseline-align-20261003
helm template kube-prometheus-stack charts/kube-prometheus-stack-91.4.1.tgz -n monitoring \
  -f values.yaml --set alertmanager.config.global.smtp_auth_password='DUMMY-PW' > "$D/render-new.yaml"
helm template kube-prometheus-stack charts/kube-prometheus-stack-91.4.1.tgz -n monitoring \
  -f "$D/live-values.yaml" --set alertmanager.config.global.smtp_auth_password='DUMMY-PW' > "$D/render-live.yaml"
diff "$D/render-live.yaml" "$D/render-new.yaml" && echo RENDER-IDENTICAL

预期：无 diff 输出 + RENDER-IDENTICAL。本次实测：两份各 6377 行、逐字节一致。

判据二：差异收敛到 1 项（唯一例外）

cd /home/rain/Documents/k8s_ins && python3 prometheus-baseline-align-20261003/compare_values.py

预期：MISSING_IN_FILE 仅 alertmanager.config.global.smtp_auth_password（打码显示）1 项， EXTRA_IN_FILE 与 DIFF 均为 0。本次实测一致（13 → 1）。

判据三：幂等复跑

cd /home/rain/Documents/k8s_ins/prometheus_deploy
helm template kube-prometheus-stack charts/kube-prometheus-stack-91.4.1.tgz -n monitoring \
  -f values.yaml --set alertmanager.config.global.smtp_auth_password='DUMMY-PW' > /tmp/render-rerun.yaml
diff -q /tmp/render-rerun.yaml ../prometheus-baseline-align-20261003/render-new.yaml && echo 幂等

预期：输出 幂等。本次实测通过。

判据四：凭据未落库

grep -n 'smtp_auth_password' prometheus_deploy/values.yaml   # 只应命中注释行

预期：仅命中 2 行注释（注入方式说明），无 smtp_auth_password: <值> 形式。

7. 回滚

项 内容
备份位置 prometheus-baseline-align-20261003/backup/prometheus_deploy/values.yaml.bak.20261003-010044
台账 prometheus-baseline-align-20261003/backup/README.md
回滚动作 cp <备份> prometheus_deploy/values.yaml 覆盖即可
回滚后验证 重跑第 6 章判据二 → 差异应回到 13 项
运行系统 无需回滚（本次未改动任何运行对象）

回滚触发判据（任一成立即回滚）：① 判据一出现 diff（回写与现场不等价）； ② 判据二新增了计划外差异；③ values.yaml 中出现授权码明文。

8. 风险说明

风险 缓解
回写笔误导致未来单文件升级丢配置 以"双渲染逐字节一致"为判据，不以肉眼核对为准
授权码被顺带写入文件 明确列入 v1 例外；判据四专门校验
回写后与各工程 overlay 双份定义 overlay 不再回写、保留原样；--reuse-values -f overlay 仍幂等。注意：今后修改这些项应改 values.yaml 为单一源，避免两处漂移（见附录 B 待办）
误以为需要 helm upgrade 才能生效 现场已是这 13 项生效态，本次不执行 upgrade；若日后确需 upgrade，见 prometheus_deploy/RUNBOOK.md §5.2

附录 A：本次 13 项差异明细

# 键路径 性质
1–4 alertmanager.config.global.{smtp_smarthost,smtp_from,smtp_auth_username,smtp_require_tls} 现场有、文件缺
5 alertmanager.config.global.smtp_auth_password 现场有、文件缺（不回写，v1 例外）
6 alertmanager.config.inhibit_rules 现场有、文件缺
7 alertmanager.config.route.routes 现场有、文件缺
8 grafana.nodeSelector 现场有、文件缺
9 prometheus-node-exporter.prometheus.monitor.relabelings 现场有、文件缺（第四阶段）
10 alertmanager.config.receivers 值不同（现场多 3 个邮件接收器）
11 alertmanager.config.route.group_by 值不同（现场多 alertname/cluster）
12 grafana.resources.limits.memory 512Mi → 1Gi（组三 #12）
13 grafana.resources.requests.memory 256Mi → 384Mi（组三 #12）

附录 B：遗留

  1. 双份定义：13 项中的 Alertmanager 组与 grafana 内存，在 dell-r620-monitor-20260929、env-monitor-deploy、group3-tails-20261003、 log-metrics-crosslink-20261002 各自的 overlay 中仍有一份。本次不回退 overlay（避免扩大影响面）， 但应在下次触及这些工程时明确"values.yaml 为单一源"，或在其 SOP 加一行指针。
  2. 授权码入 Secret：改用 Alertmanager 原生 smtp_auth_password_file + K8s Secret 挂载， 可让 values.yaml 成为 100% 基线。属改实现，单独立项。

附录 C：交付物清单

文件 说明
prometheus_deploy/values.yaml 变更对象（回写 12 项 + 注释更正）
prometheus-baseline-align-20261003/compare_values.py 一次性比对脚本（可复用于日后 drift 复核）
prometheus-baseline-align-20261003/live-values.yaml 现场 values 快照（含授权码明文，勿外传）
prometheus-baseline-align-20261003/live-manifest.yaml 现场 manifest 快照
prometheus-baseline-align-20261003/render-{new,live}.yaml 两侧渲染产物（判据一的证据）
prometheus-baseline-align-20261003/backup/ 备份与台账

来源：/home/rain/Documents/k8s_ins/prometheus-baseline-align-20261003/docs/SOP.md ｜ 最后更新：2026-10-03 01:02（由 build/sync.py 同步，请勿在站点侧修改）