记录基础监控上线与 Prometheus CRD 优先约定

2026-09-25 17:55:12 +00:00
parent 9bd67a36ba
commit d5ad5ee568
6 changed files with 124 additions and 7 deletions
@@ -6,6 +6,7 @@

 | 约束 | 原因与边界 | 来源 |
 |---|---|---|
+| 新增监控配置优先使用 ServiceMonitor、PodMonitor、PrometheusRule | VictoriaMetrics Operator 负责转换，避免同一目标/规则维护两套声明；历史 VM 配置按需另行迁移 | 维护者 2026-09-25 明确要求；[基础监控运维](../guides/monitoring-foundation.md) |
 | Ayatori 复用 Kubernetes API machinery，不复用其容器编排产品边界 | kube-apiserver/etcd 提供 API、watch、RBAC 与状态协调；领域调度、生命周期、恢复和 GC 属于 Ayatori controllers；Kubernetes workload 只是可替换 backend | [Ayatori 控制面边界](ayatori-control-plane.md) |
 | Kubernetes 内置资源不绑定上游实现组件 | 可由 Ayatori Agent/controller 实现和消费 Node、Lease 等 API；使用 Node 不推导必须部署 kubelet、Pod 或 kube-scheduler | [Ayatori 控制面边界](ayatori-control-plane.md) |
 | Ayatori 只为已验证的管理缺口新增北向资源 | 当前优先 Database、LoadBalancer、Bucket/Object Storage；VM 价值已确认但南向较重；Run 是内部切片，KaaS 按需，FaaS/PaaS 默认不做 | [Ayatori 控制面边界](ayatori-control-plane.md) |
@@ -9,6 +9,16 @@ last_reviewed: 2026-09-25
 “有 exporter”“有 PodMonitor”“数据库里曾出现过指标名”都不能代替当前采集成功和有效规则。
 本页用于接续覆盖建设，服务使用入口仍见 [Grafana](../services/grafana.md)。

+## 第一批补齐进展
+
+2026-09-25 已上线 kube-state-metrics，并恢复 NATS PodMonitor 转换与采集。
+新增集群状态 11 条、主机/ZFS 5 条、采集与通知 5 条规则，共 21 条；正式规则总数为 68。
+新增资源按维护者要求优先使用 ServiceMonitor/PodMonitor/PrometheusRule。
+具体阈值、降噪边界、声明转换关系与验收方法见 [基础监控与告警运维](monitoring-foundation.md)。
+
+下面的规模、矩阵和盲点保留初轮盘点基线，不能再当作第一批实施后的现状。
+第二批数据库/OpenBao/存储/备份、外部探测和集群外心跳尚未实施。
+
 ## 证据和范围

 2026-09-25 17:26–17:31 UTC，只读检查当前集群工作负载、采集 CR、vmagent 实际 targets、
@@ -24,7 +34,7 @@ vmalert 已加载规则、VictoriaMetrics 即时查询、CNPG 监控/备份声
 共享 etcd 采集/规则另以本次现场 CR 为准（来源工作区尚有未提交配置）。
 审阅时主工作区落后于远端且有其他改动，不能拿本地旧 :8080 配置覆盖已合并修复。

-## 当前规模
+## 初轮盘点规模（实施前）

 - 69 个 Deployment/StatefulSet/DaemonSet 对象（44/13/12），不等同于服务数或全部实例数；CNPG 管理的数据库 Pod 不在此统计内。
 - vmagent 有 17 个目标、15 个 job；其中 node-exporter 与 docker-hosts 重复采集同一个 :9100 地址，实际唯一 URL 为 16 个。
@@ -34,7 +44,7 @@ vmalert 已加载规则、VictoriaMetrics 即时查询、CNPG 监控/备份声
 - 严重性为 critical 16、warning 30、info 1；本次规则 API 未报告执行错误。41 条属于监控栈，6 条属于共享 etcd。
 - Telegram 已接 warning/critical 和恢复通知；info 不推送。通知接入验收见服务页。

-## 覆盖矩阵
+## 初轮覆盖矩阵（实施前）

 “无专用告警”指没有该服务的业务/运行告警；共享进程或错误日志规则可能部分命中，不能视为完整覆盖。

@@ -68,7 +78,7 @@ vmalert 已加载规则、VictoriaMetrics 即时查询、CNPG 监控/备份声
 | Marker / OpenViking / LiteLLM 等源码服务 | 未见中央 target；运行范围需由各项目确认 | 无中央专用规则 | 先明确现役范围，再接业务指标；不为归档或未部署服务添加空目标 |
 | e5renew / research-auto | 有集群 workload，但未见专用目标 | 无中央专用规则 | 属外部消费者，业务规则由项目维护；平台提供通用 workload 健康覆盖 |

-## 已确认的盲点
+## 初轮发现的盲点（实施前）

 ### Kubernetes 对象状态

@@ -121,5 +131,5 @@ Samba AD 文档有备份操作示例，SeaweedFS/zot 文档也明确独立异机
 | 3：验证用户可用性 | LAN DNS、入口 HTTPS、Gitea/认证/S3/镜像等关键路径探测；集群外 Watchdog 接收 | 从独立位置发现站点/监控中断，探测不用暴露管理员凭据或制造业务写入 |
 | 4：扩展到其余基础设施和应用 | PVE/OCI/域控主机、Docker/Incus/libvirt/网络；按使用频率接入应用 | 按服务维护覆盖表，退役目标同步移除，采集开销和标签基数受控 |

-先落实第一批；第二批中的备份方案确认可并行推进。开始具体实施前对齐各服务进行中的工作，
+第一批基础补齐已实施，验收边界见上方链接；下一步对齐第二批关键依赖与备份方案。开始具体实施前对齐各服务进行中的工作，
 尤其是共享 etcd、数据库迁移与身份平台；本次盘点不授权自动修改这些项目。
@@ -0,0 +1,97 @@
+---
+title: 基础监控与告警运维
+last_reviewed: 2026-09-25
+---
+
+# 基础监控与告警运维
+
+第一批补齐 Kubernetes 状态、主机/ZFS 和通知链路；业务数据库、备份、外部探测等
+后续范围见 [覆盖计划](monitoring-coverage.md)。本页的规则检查不等于所有服务健康。
+
+## 声明与归属
+
+维护者于 2026-09-25 明确：新增监控配置优先使用 Prometheus Operator 的
+`ServiceMonitor`、`PodMonitor`、`PrometheusRule`。VictoriaMetrics Operator 负责转换为
+VMServiceScrape、VMPodScrape、VMRule，vmagent/vmalert 继续负责采集与规则执行。
+不要再为同一个新目标/规则手工维护一份 VM 对象；已有历史 VM 配置按需求单独迁移。
+
+- kube-state-metrics：Flux HelmRelease，chart `8.5.0` / app `2.20.0`，适配本集群 Kubernetes 1.36。
+- KSM 的 ServiceMonitor 使用 `honorLabels: true`，保留被观测对象的 namespace/pod 等标签。
+  :8080 提供对象指标，:8081 提供 exporter 自身指标；job 均为 `kube-state-metrics`。
+- collector/RBAC 限于本批需要的 nodes、pods、deployments、statefulsets、daemonsets、
+  PVC/PV、jobs/cronjobs、namespaces，只读 list/watch，没有启用 secrets collector。
+- NATS 沿用其 Helm 管理的 PodMonitor，转换后的 `nats/nats` VMPodScrape 抓取 :7777，job 为 `nats/nats`。
+- Operator HelmRelease 依赖 `prometheus-operator-crds`；KSM 同时依赖两者。
+  先确保 CRD Ready，再启动依赖 CRD 的转换器和消费者。
+- 源码：[基础补齐 PR #149](https://git.ddupan.top/panxiao81/homelab-infra/pulls/149)。
+  三份新增规则位于 `platform/observability/metrics/rules/{kubernetes-health,host-health,monitoring-delivery}.yaml`。
+  PrometheusRule 声明切换见 [PR #151](https://git.ddupan.top/panxiao81/homelab-infra/pulls/151)，
+  Flux 已应用 `e8e7bd4b203def4123658a4d02a1d92a854005fc`。
+
+## 21 条规则的范围
+
+| 组 | 规则与持续时间 | 严重性 |
+|---|---|---|
+| Kubernetes（11） | NodeNotReady 5m；Memory/Disk/PID Pressure 5m | 节点未就绪 critical，压力 warning |
+| Kubernetes（续） | CrashLoop 10m；15 分钟内重启 >3 次持续 5m；近期 OOM 重启 1m；Pod Pending 15m | warning |
+| Kubernetes（续） | Deployment/StatefulSet/DaemonSet 可用副本不足 10m；PVC Pending 15m；Job Failed condition 5m | warning |
+| 主机（5） | 可用内存 <10% 持续 10m；磁盘可用空间/inode <10% 持续 15m | warning |
+| 主机（续） | 文件系统只读 5m；ZFS 池非 online 的状态值为 1 持续 5m | critical |
+| 采集（3） | KSM、node-exporter、NATS target down 或整个 job 消失持续 5m | 前两项 critical，NATS warning |
+| 通知（2） | Telegram 失败计数最近 5 分钟增加并持续 1m；Alertmanager 配置加载失败 5m | critical |
+
+主机规则只用 `job="node-exporter"`，避免旧 docker-hosts 重复样本。
+磁盘规则排除 tmpfs/devtmpfs/overlay/squashfs/nsfs/fuse 和临时挂载路径；inode 总数为零不报警。
+OOM 同时要求近期 restart counter 增加，避免历史终止原因持续报警。
+Deployment 以声明副本为准，缩容到零不触发。
+
+本批没有增加主机 CPU/Swap/IO 告警、NATS JetStream 业务规则、数据库/备份或外部探测。
+job 完全消失使用 absent(up) 检查，但未建立每个预期主机/成员的独立清单，不能保证发现
+同一个 job 中少了一个成员；此类预期拓扑检测后续再补。
+
+## 通知、静默与抑制
+
+warning/critical 及恢复消息沿用 [Telegram 路由](../services/grafana.md#telegram-告警接入)。
+新规则 annotations 中包含本 runbook 链接。
+同一 namespace/pod/container 的 `KubePodCrashLooping` 只抑制 `KubePodFrequentRestarts`，
+不抑制 OOM，也不静默整个 namespace。工作负载副本不足仍独立可见。
+
+维护时在 Alertmanager 为明确标签创建有截止时间和原因的 silence；不要把维护中的
+etcd、SPIRE 或 Backstage 直接写成永久排除规则。结束维护后核对 silence 到期和目标健康。
+
+Telegram 完全不可达时，发送失败告警也无法依靠同一渠道送达。该规则有助于留存和
+恢复后通知，不能替代集群外心跳或第二渠道。发送失败时直接检查 Alertmanager/Grafana。
+
+## 接入或升级后如何验收
+
+1. 确认 Flux HelmRelease Ready，原生 ServiceMonitor/PodMonitor/PrometheusRule 存在。
+2. 确认转换出的 VM 对象存在、内容同步；不要仅凭原生 CR 已创建判定成功。
+3. 在 vmagent `/api/v1/targets` 确认 up、最近采集时间和样本数；VictoriaMetrics 即时查询
+   验证 `up{job="kube-state-metrics"}`、`up{job="nats/nats"}` 和所需指标当前有值。
+4. 在 vmalert `/api/v1/rules` 核对规则数量、lastError 和依赖样本。
+   没有失败 Job 或 OOM 时条件指标可能不存在，不能把这种空结果直接当作采集失败。
+5. 变更规则时从源码运行 `bash platform/observability/metrics/tests/check-rules.sh`；
+   依赖 Python 3、PyYAML、promtool（本次验证版本 3.5.0）。该脚本直接读取三份规则的 spec.groups，
+   生成临时文件校验，不维护第二份规则。8 组测试覆盖阈值持续时间、缺失目标和常见噪声边界。
+6. 经维护者授权发送临时 canary，验证触发与恢复后删除测试规则，恢复正式规则总数。
+   不通过制造真实 OOM、磁盘满或破坏 Telegram token 来做验收。
+
+## NATS 转换故障经验
+
+NATS 已有 exporter 和 PodMonitor，但 Operator 自 7 月启动，PodMonitor CRD 到 9 月才安装。
+本次滚动重启 Operator 后，日志记录启动 PodMonitor controller 并创建 `VMPodScrape=nats/nats`，
+之后 target up 且 nats_* 指标入库。NATS 本身没有重启。
+
+遇到同类问题先检查原生 CR、转换对象、转换器日志、watch/RBAC 和 CRD 安装时间；
+不能直接另建同目标 VM scrape 来掩盖转换链路问题。必要重启只针对 Operator，
+先确认当前无升级/恢复操作，重启后验证对象生成和采集。
+
+## 本次验证边界
+
+2026-09-25，KSM 两个端点及 NATS 均 up，KSM 约 5,300 条对象样本和 75 条自身样本，
+可读到 27 个 workload namespace 的容器重启指标。NATS 有约 187 条采集样本。
+正式规则从 47 增为 68，当前规则评估无错误；8 组离线测试、Helm/Kustomize 渲染和服务端 dry-run 通过。
+canary 触发已由维护者确认收到；规则恢复后 Telegram 发送计数从 11 增至 12，
+失败计数仍为 0，Alertmanager 无残留 canary，测试 VMRule 已删除。恢复消息未单独取得收件端确认。
+三份 PrometheusRule 的转换内容一致（仅 VMRule 补默认空 record 字段），vmalert 最终仅有 68 条正式规则，未重复评估。
+这些数量是验收快照，不是容量承诺或持续健康结论。正在调整的 etcd 不在本批修复范围。
@@ -19,7 +19,7 @@ last_reviewed: 2026-09-25
 | 使用 S3 对象存储 | [SeaweedFS](../services/seaweedfs.md) | [OpenBao](../services/openbao.md) |
 | 给应用分配数据库 | [共享 PostgreSQL](../services/shared-postgresql.md) | [计划中的 DBaaS](../services/postgresql-tenant-operator.md) |
 | 给应用提供秘密或存储 | [External Secrets](../services/external-secrets.md)、[OpenEBS](../services/openebs.md) | [OpenBao](../services/openbao.md) |
-| 盘点或补齐监控与告警 | [监控覆盖与补齐计划](monitoring-coverage.md) | [Grafana](../services/grafana.md)、对应服务 runbook |
+| 盘点或补齐监控与告警 | [监控覆盖与补齐计划](monitoring-coverage.md) | [基础监控运维](monitoring-foundation.md)、[Grafana](../services/grafana.md) |
 | 排查内存、日志或追踪 | [Grafana](../services/grafana.md) | 对应服务源码 runbook |
 | 排查域名解析 | [LAN DNS](../services/lan-dns.md)或[Pod DNS](../services/k3s-dns.md) | [Tailscale](../services/tailscale.md)，如果请求来自远程客户端 |
 | 排查登录或域权限 | [Authelia](../services/authelia.md)、[Samba AD](../services/samba-ad.md) | 具体应用的权限说明 |
@@ -16,6 +16,7 @@ last_verified: null
 2026-09-25 的通知链路与采集故障验证范围见下文。

 整体接入范围、已确认盲点和补齐顺序见 [监控覆盖与补齐计划](../guides/monitoring-coverage.md)。
+第一批已接入的规则、阈值、静默和排障方法见 [基础监控与告警运维](../guides/monitoring-foundation.md)。

 ## 先看主机内存与 Swap

@@ -95,7 +96,8 @@ VictoriaLogs 使用 LogsQL。上述 limit 限制返回数量，不保证返回
 - critical 首次分组等待 10 秒，未恢复每小时提醒；warning 等待 1 分钟，
  未恢复每 4 小时提醒。分组键为 `alertname, cluster, job, severity`，
  组内变更通知间隔 5 分钟；两类均发送恢复通知。info、缺失或其他 severity 暂不推送。
- 采用 Alertmanager 默认 Telegram 消息模板；本次没有新增抑制规则。
+- 采用 Alertmanager 默认 Telegram 消息模板；同容器 CrashLoop 抑制重复重启通知，
+  具体匹配范围见基础监控运维指南。

 配置变更通过既有 Flux 流程发布，先确认 ExternalSecret Ready 和目标 Secret
 投射成功，再确认 Alertmanager 加载配置及到 Telegram API 的出站网络。
@@ -2,7 +2,7 @@
 title: NATS
 lifecycle: active
 evidence: documented
-last_reviewed: 2026-09-16
+last_reviewed: 2026-09-25
 last_verified: null
 sources:
  - 维护者于 2026-09-16 提供的部署与消费者说明
@@ -40,3 +40,10 @@ Dynamic Runner 的 stream、subject、durable 名称、worker 配置和具体启

 知识库只保留[Dynamic Runner 的用途与职责边界](gitea-dynamic-runner.md)。
 涉及 runner 的实际配置和实现进度时，先按项目文档接续工作；需要扩大查询范围时再向维护者确认。
+
+## 指标与告警
+
+2026-09-25 已现场确认既有 :7777 prom-exporter 经 PodMonitor → VMPodScrape 接入中央采集，
+job 为 `nats/nats`，target up 且 nats_* 指标有当前样本。已有采集不可用/整个 job 消失告警；
+JetStream 容量、consumer 积压等业务规则仍待第二批。
+转换器故障处理与验证依据见 [基础监控运维](../guides/monitoring-foundation.md#nats-转换故障经验)。