SOP —— 日志域标签（platform / cluster）¶

变更日期：2026-10-02　｜　工程：monitoring-p2-20261001　｜　类型：C 类（配置变更）备份与回滚台账：backup/platform-labels-20261002/README.md

一、背景¶

日志侧原有的"域"只有一个 cluster 字段，且只覆盖集群外 14 台主机——K8s 容器日志的 input 没有任何 fields，导致实测 24 小时内 74.6 万条（占全部日志最大一块）落入"无域"，视图无法按域筛选 K8s 日志。

同时域模型只有一层（cluster = 机器组），无法表达"这些机器属于哪个平台"。用户明确要求改为两级：粗粒度 platform（4 档：hpc / k8s / infra / network）+ 细粒度 cluster。

二、目标¶

目标	可验证状态
两侧日志均带 `platform` 与 `cluster`	ES 中最近新日志 `platform` 取值 ∈ {hpc, k8s}；`cluster` 出现 `k8s`
集群外 14 台	`cluster` 不变（slurm/lsf/lustre/license/hpc），`platform` 均为 `hpc`
K8s 侧	容器日志与节点日志均为 `cluster: k8s`、`platform: k8s`
幂等	重复执行 `deploy`，14 台输出 `-> OK` 且无 `write-config`

三、前置条件¶

14 台主机 ssh 可达（凭据由工程 paramiko 连接池处理，无需接触 secrets 文件）
kubectl 可用、monitoring 命名空间可达
工程 .venv 就绪；PYTHONPATH="$HOME/py_public_modules"
备份已就位（见台账第一节）
执行窗口：无在跑生产作业时（Filebeat 会重启）

四、影响范围¶

对象	影响	是否停服
集群外 14 台 Filebeat	重写 `/etc/filebeat/filebeat.yml` 并重启服务；文件式 tail 有 registry 不丢日志；journald input 为 `seek: tail`，只采新条目	否（采集中断秒级）
K8s Filebeat DaemonSet（4 节点）	ConfigMap 更新 + 滚动重启	否（逐个重建，采集短暂缺口）

五、分步操作¶

步骤 1：config 增加 platform 映射¶

在 config/default.yaml 的 nodes 段之后新增（不要改动 nodes 结构，多处代码按 {cluster: [节点]} 读取）：

platforms:
  k8s: k8s
  slurm: hpc
  lsf: hpc
  lustre: hpc
  license: hpc
  hpc: hpc

预期：python -c "import yaml;print(yaml.safe_load(open('config/default.yaml'))['platforms'])" 输出上述映射。失败判断：YAML 解析报错 → precheck/deploy 会直接失败，先修正缩进（两空格一级）。

步骤 2：组装节点时补 platform¶

deployer.py::_all_nodes() 改为复制后补字段（直接改原 dict 会污染 config 对象）：

platforms = self.config.get("platforms") or {}
for cluster, items in (self.config.get("nodes") or {}).items():
    for n in items:
        node = dict(n)
        node["platform"] = platforms.get(cluster, cluster)
        out.append((node, cluster))

步骤 3：模板与渲染¶

artifacts/filebeat-host.yml.tpl 的 6 个 input（journald / audit / domain / lsf-logdir / flexlm / vnc）各加一行：

      platform: __PLATFORM__

modules/host_filebeat.py::render_config() 增加一个替换：

.replace("__PLATFORM__", node.get("platform", cluster))

预期：本地渲染一份样本，platform: hpc 出现在 4 处（其余 2 个 input 被 ROLE_GATED_BLOCKS 按角色剔除属正常），且无残留占位符。失败判断：出现 __PLATFORM__ 残留 → 替换行未生效，检查缩进与函数内顺序。

步骤 4：K8s 清单补域标签¶

manifests/12-filebeat-k8s.yaml 两处 input：

容器 input（id: k8s-container-logs）：新增 fields: {cluster: k8s, platform: k8s}，并把 fields_under_root 由 false 改为 true；
节点 input（tags: ["node-syslog"]）：在既有 fields 中补 cluster / platform，并补 fields_under_root: true（与容器侧、主机侧统一到根级）。

步骤 5：下发¶

cd /home/rain/Documents/k8s_ins/monitoring-p2-20261001
PYTHONPATH="$HOME/py_public_modules" .venv/bin/python main.py deploy --dry-run   # 预演：应零改动
PYTHONPATH="$HOME/py_public_modules" .venv/bin/python main.py deploy             # 真实下发

预期：14 台输出 OK write-config,start-service，主机 Filebeat：14 台处理，失败 0 台。失败判断：任一主机 FAILED → 该台回滚见台账第二节（failure_threshold: 1，即一台失败即停）。

坑（本次实测踩到并已修）：ConfigMap 内容变更不会让 DaemonSet 重建 Pod，Filebeat 也不会自动重载配置——表现为"配置改了、行为没变"且日志不报错。工程用 apply_with_configmap_restart() 以 resourceVersion 指纹判断并显式 rollout restart；但该函数原先在 dry-run 时仍会真 apply，导致指纹被预演改掉、真实下发时判定"无变化"而跳过重启。本次已修（self.dry_run 时改用 --dry-run=server 预演并直接返回）。若发现 K8s 侧标签未生效，先查 DaemonSet 的 restartedAt 注解是否为本次时间，若不是则手动 kubectl -n monitoring rollout restart ds/filebeat。

六、验证¶

标签生效（等 30~60 秒让新日志入库）：

kubectl --kubeconfig /home/rain/.kube/config -n monitoring exec elasticsearch-0 -- \
  bash -lc 'curl -s -u "elastic:$ELASTIC_PASSWORD" -H "Content-Type: application/json" \
  "http://localhost:9200/filebeat-*/_search" -d "{\"size\":0,\"query\":{\"range\":{\"@timestamp\":{\"gte\":\"now-90s\"}}},\"aggs\":{\"plat\":{\"terms\":{\"field\":\"platform\",\"size\":10,\"missing\":\"(无)\"}},\"clu\":{\"terms\":{\"field\":\"cluster\",\"size\":10,\"missing\":\"(无)\"}}}}"'

预期（本次实测）：platform = {k8s: 1538, hpc: 600}，cluster = {k8s: 1538, slurm/lsf/lustre/hpc/license: 各百量级}，(无) 仅为重启瞬间的残留。失败判断：k8s 未出现在 cluster 中 → K8s 侧配置未生效，见步骤 5 的坑。

幂等：再跑一次 main.py deploy，14 台应输出 -> OK（无 write-config）。
黑盒无回归：deploy 末行 黑盒探测：10 个目标，失败 0（本次复跑曾出现 ldapadmin-web 瞬时失败，用 Prometheus probe_success 复核为全 1，属网络抖动）。

七、回滚¶

见 backup/platform-labels-20261002/README.md 第二节（恢复 5 个文件 → 重下发 → 手动重启 DaemonSet）。历史文档不会被改写，回滚只影响此后新采集的数据。

八、风险说明¶

风险	缓解
ConfigMap 变更不触发 Pod 重建，配置"改了没生效"	工程内置指纹判断 + `rollout restart`；本次修复了 dry-run 干扰指纹的缺陷；排查手法见步骤 5
Filebeat 重启造成采集缺口	文件式 tail 有 registry 不丢；journald 为 `seek: tail` 不重放历史（这是设计而非缺陷）
`fields_under_root` 由 false 改 true 导致字段位置变化	仅影响 K8s 容器 input（原先无 fields，无既有依赖）；节点 input 的 `log_source` 由 `fields.log_source` 提到根级，与主机侧口径统一
域映射写在 config 却仍需代码读取	`deployer._all_nodes()` 是唯一注入点；新增主机只需在 `nodes` + `platforms` 各登记一处

附录 A：纳管扩面（1b）—— 步骤 1：Harbor¶

背景：Harbor（192.168.31.31，Rocky 9.8）是 K8s 的镜像来源，此前未纳入日志采集。

做法（只改 config，不动代码——它与既有 14 台同系，直接复用 RPM 流程）：

nodes 增加分组：harbor: [{host: 192.168.31.31, name: harbor-01, role: registry}] —— role=registry 不匹配任何 ROLE_GATED_BLOCKS，故不会采 lsf-logdir / vnc（避免与 NFS 单点采集重复）。
platforms 增加 harbor: k8s。
下发：PYTHONPATH="$HOME/py_public_modules" .venv/bin/python main.py deploy。

实测（2026-10-02）：

首次：harbor-01 -> OK install-rpm,write-config,start-service,selfmon-updated，15 台处理，失败 0
幂等复跑：harbor-01 -> OK（无 write-config）
ES 实测（3 分钟窗口）：cluster: harbor 19382 条（platform: k8s），服务分布 auditd 19331 / systemd 36 / sshd 2 / kernel 1

注意：

⚠ Harbor 的 auditd 日志量异常大（3 分钟 1.9 万条）——建议复核其 audit 规则，否则 ILM 14 天窗口内该项会占用可观容量。
⚠ 本工程的自监控以 node_exporter textfile 为出口；Harbor 若未被 env-monitor-deploy 覆盖 node_exporter，则自监控指标无出口（日志采集本身不受影响）。装机后应核对。

待续（同属 1b）：

步骤 2：dell-R620（Ubuntu 24.04，本机）——须先做 deb 系支持（包为 .deb、probe/install 分支、预检 expected_os_major 放宽）；另该机 node_exporter 未运行，自监控无出口，需一并决定是否安装。
步骤 3：OpenWrt .2（OpenWrt 24.10）——不装 Filebeat，改为 logd 转发（uci set system.@system[0].log_ip=<dell-R620>）→ 本机 rsyslog 启用 imudp（当前被注释）→ 落 /var/log/remote/ → 主机侧模板增加对应 input。

来源：/home/rain/Documents/k8s_ins/monitoring-p2-20261001/docs/SOP-platform-labels.md ｜最后更新：2026-10-02 01:52（由 build/sync.py 同步，请勿在站点侧修改）