【Cilium / eBPF】可观测与运维口径：cilium status、metrics 语义与 bpftool 边界

「节点健康」与「东西向某条流被拒」的观测入口不同。前者可能卡在 agent 未就绪、kvstore 断连、或 policymap 压力告警；后者可能是 identity 未同步、Service 后端为空、或加密握手失败。若先盯 Grafana 里一条 cilium_endpoint_state 的绿点，往往会错过 Hubble flow 里已经写明的 DROPPED (Policy denied)。

本文是系列第 12 篇，目标是：先选观测层，再读字段语义与失败模式；不虚构 Prometheus scrape 样本，不把文档示例输出当本机实测。flow 字段细则见第 8 篇；把症状落到排障轴见第 13 篇。

本文是「Cilium / eBPF 数据面内核」系列第 12 篇（共 16 篇）。→ 系列目录

篇目	核心内容
第 11 篇 · ClusterMesh	多集群身份与发现边界
第 12 篇 · 可观测	status / metrics / bpftool 口径
第 13 篇 · 排障坐标系	丢包、deny、identity 漂移、Service 黑洞

版本锚定：Cilium v1.20.0（docs.cilium.io/en/v1.20/；源码 tag v1.20.0）。指标名以官方 Observability / Metrics 文档为准；Tentacle 式第三方升版须显式标注。无真实 Cilium 集群则不粘贴伪造 cilium status / Hubble flow 输出。

一、先选观测层，再动命令

Cilium 比「装了 CNI」多三层可观测面：agent 控制面状态、BPF 数据面状态、以及 Hubble 流事件。读信号时固定这个栈：

Cluster 层：   cilium status（CLI）/ Operator 条件 / ClusterMesh 连接摘要
Agent 层：     cilium-dbg status --verbose；controllers；IPAM；Proxy
Datapath 层：  BPF map 压力、CT GC、policy implementation delay
Flow 层：      Hubble observe / Relay；verdict 与 drop reason
Metrics 层：   cilium_*（agent/operator）；hubble_*；可选 envoy_cilium_*
内核旁路：     bpftool（通用）vs cilium-dbg bpf *（Cilium 语义封装）

纪律：同一事故窗口里，先用 status 定「控制面是否病了」，再用 Hubble 定「这条流在哪一跳被判」，最后用 metrics/map 定「是否系统性压力」。两层同时绿、业务仍挂，才下钻加密与 Service 黑洞（第 9、6、13 篇）。

flowchart TD
  symptom["Symptom: timeout / deny / blackhole"]
  symptom --> pick["Pick observation layer"]
  pick --> st["cilium status / cilium-dbg"]
  pick --> hb["Hubble observe / Relay"]
  pick --> prom["cilium_* / hubble_* metrics"]
  pick --> bpf["cilium-dbg bpf / bpftool"]

二、cilium status：摘要，不是根因库

Cilium CLI 的 cilium status（以及节点内 cilium-dbg status）回答的是：agent、Hubble、kvstore/CRD、kube-proxy 替代、加密等子系统是否自报健康。官方排障文档把它当作入口摘要；深挖时要求 --verbose，以展开 IPAM、controller 列表与 Proxy 状态。

常用入口（命令语义；输出须在真实集群执行）：

cilium status
cilium status --wait
kubectl -n kube-system exec -it ds/cilium -- cilium-dbg status --verbose
kubectl -n kube-system exec -it ds/cilium -- hubble status

工程判断：把 cilium status 当「能否进下一层」的闸门，不当「业务连通性证明」。业务超时而 status 全绿，是第 13 篇坐标系的常态入口，不是矛盾。

Hubble 环与 Metrics 开关

官方文档注明：Hubble 默认随 agent（--enable-hubble）；cilium-dbg status 里可看到 Current/Max Flows 与 Metrics: Disabled/Enabled。flow 环写满时旧事件被覆盖——观测丢失，不等于数据面丢包。Hubble Prometheus 指标需单独打开（Helm：hubble.metrics.enabled 等）；agent 指标另走 prometheus.enabled。两套 scrape 目标、两套端口，混成一个「Cilium 绿」会掩盖「Hubble metrics 根本没开」。

三、Agent / Operator metrics：读语义，不读虚构样本

Cilium 与 Hubble 均可导出 Prometheus 指标。官方 Observability → Metrics（对齐 v1.20 叙述）规定：

• Agent / Envoy：prometheus.enabled=true；命名空间 cilium_，Cilium 相关 Envoy 指标常在 envoy_cilium_。
• Operator：默认开；可用 operator.prometheus.enabled=false 关闭。
• Hubble metrics：由 agent 内 Hubble 实例服务；--hubble-metrics 选择指标族。

下列家族按排障语义分组。表中不出现伪造数值；生产以本集群 /metrics 实际暴露名为准。

3.1 控制面与策略落地

3.2 数据面压力与 CT

3.3 Hubble 聚合指标

Hubble metrics 把 flow 事件收成计数器（HTTP、DNS、drop、flow 等可选族）。它们回答「比率与趋势」，不回答「这一次 SYN 的五元组」。与第 8 篇分工：

告警建议（语义级，非抄录阈值）：

• cilium_bpf_map_pressure 对 policy map 持续高位 → 进第 13 篇「策略/identity」轴，先查宽 CIDR/大 selector，不要先重启节点。
• Hubble drop 比率升高但 agent endpoint 全 ready → 先 hubble observe --verdict DROPPED，不要先扩节点。
• policy_implementation_delay 右移 → 对照变更窗口，解释「配置已改、数据面未齐」的短暂窗。

四、bpftool 与 cilium-dbg bpf：边界必须划清

eBPF 通用工具链（bpftool prog / bpftool map）能看见内核里挂了什么程序、map 有多少元素。Cilium 封装的 cilium-dbg bpf *（以及部分 cilium bpf 兼容入口）在同一批 map 上提供带 Cilium 语义的列表与解码。

纪律：

1. 先问语义，再 dump 字节。排查「ClusterIP 是否有后端」用 Cilium 的 service/lb 子命令；只有怀疑「程序没挂上」才下到 bpftool prog show / tc filter。
2. 不要在生产用 bpftool map update「手工修」Cilium map。控制面下一轮 reconcile 会覆盖或把状态打穿；这是排障禁区，不是高级技巧。
3. 版本钉：map 名称与布局随 Cilium 发行变化（例如 policy map 代际）。结论必须写清 v1.20.0；对照旧博客的 map 名时先核对当前 cilium-dbg map list。

# 语义层（在 cilium Pod 内；输出不在此伪造）
cilium-dbg bpf lb list
cilium-dbg bpf ct list global
cilium-dbg bpf metrics list
cilium-dbg map list

# 内核旁证（节点上；确认挂载而非解读策略）
bpftool prog show
bpftool map show

站内 eBPF 系列 讲 verifier/JIT/Map 内核实现；本篇只钉：运维默认停在 Cilium 语义层，bpftool 是旁证。

五、把业务症状接到观测层

Events 与应用日志常只写 connection timed out。真正的 Policy denied、Service backend not found、加密失败码在 Hubble / monitor / agent 日志里——应用超时是索引，不是根因库。

六、观测口径的常见误判

1. cilium status OK ≠ 策略按意图放行：摘要不展开每条 CNP。
   
2. Hubble flow 环 100% ≠ 数据面丢包：是观测缓冲饱和。
   
3. agent metrics 绿 ≠ Hubble metrics 在刮：两套开关、两套端口。
   
4. bpftool 能看见 map ≠ 读懂 policy value：用 cilium-dbg 解码。
   
5. drop 计数升高 ≠ 一定是 NetworkPolicy：还需 reason；可能是 CT 满、非法 SMAC、未启用转发路径等。
   
6. L7 Envoy 指标绿 ≠ L3/L4 identity 策略绿：可选 L7 路径与 BPF 策略是不同跳（第 10 篇）。
   
7. ClusterMesh 摘要 Connected ≠ 远端 identity 已在本地 policy 可用：应用第 11 篇同步检查。
   
8. 把文档示例里的 FORWARDED 行粘进事故报告：只能说明字段长什么样，不能代替本环境证据。

七、接到排障轴

第 13 篇五轴的入口可压缩成：

无真实 Cilium 集群时，只保留上述语义；不要把官方教程截图冒充本环境。排障结论必须能回指到本集群的 status、Hubble 或 metrics；引用官方输出只能说明字段形状。

值班最小仪表盘（语义清单）

1. 控制面：cilium status 失败节点数、controller 错误——回答「谁在管网络时病了」。
   
2. 数据面压力：policy map pressure、CT 条目与 GC——回答「是否系统性撑不住」。
   
3. 流判定：Hubble drop 比率（按 reason）——回答「疼在策略、服务还是别的」。

缺第 1 类会把数据面抖动当成唯一故事；缺第 2 类会在「偶发拒绝」时只盯单条 CNP；缺第 3 类会在 map 压力告警时对不上用户工单。三类齐备仍可能漏掉「指标全绿的加密路径错配」——那一轴必须以路径表与 encrypt status 开场。

时间对齐

Hubble 事件时间戳、Prometheus scrape、kubelet Event 的 lastTimestamp 常差数秒。先定事故窗口（例如变更前后五分钟），再在窗口内对齐，而不是拿「此刻」的 status 否证「十分钟前」的 DROPPED。

八、谱系、争论与开放问题

谱系

Cilium 可观测面叠合三条线：（1）经典 BPF 从过滤语言走到内核可编程包处理（McCanne & Jacobson, USENIX 1993；XDP：Höiland-Jørgensen et al., CoNEXT 2018）；（2）Kubernetes 把策略与身份提升为一等对象后，失败首先表现为 identity/verdict 而非仅 IP 五元组；（3）Prometheus 拉取模型把 agent 自检与流聚合收成时间序列。本篇不发明新指标，只钉哪条线回答哪类问题。

争论：SLO 钉在 agent 还是钉在 flow

A 侧：平台以 cilium status / endpoint ready / map pressure 做 SLO——贴近基础设施生命体征。
B 侧：应用团队以 Hubble drop 比率与合成探测成功率做 SLO——贴近租户体验。
双方都对，但违约 runbook 不同：A 先查 agent/kvstore/map；B 先查 CNP/Service/加密路径。把 A 的绿写成 B 的达标，是多租户平台最常见的假关闭。

开放问题

1. Hubble 采样/环满与「真实丢包」归因对齐：在 ring 高占用时，DROPPED 事件是否系统性欠采样？可检验：固定生成可数的 policy deny，对比 observe 计数与 datapath drop 计数。
   
2. map pressure 告警到「哪条 selector」的自动归因：官方已给手工 policy selectors 路径；能否稳定自动指向顶凶 selector 而不误报？入口：第 13 篇与上游 troubleshooting 专节。

参考资料

官方文档（A 级）

• Cilium v1.20 — Operations / Troubleshooting（status、Hubble、policymap pressure）
• Cilium v1.20 — Observability / Metrics（cilium_* / hubble_* / 开关）
• Cilium v1.20 — Command reference：cilium status、cilium-dbg bpf metrics list、cilium-dbg status
• 源码 tag v1.20.0：bpf/、pkg/maps/、pkg/metrics/（机制核对）

站内对照

• 第 8 篇 · Hubble 信号
• 第 13 篇 · 排障坐标系
• eBPF 内核实现
• k8s-network/13 Cilium 产品篇

论文谱系

• McCanne, S. & Jacobson, V. (1993). The BSD Packet Filter. USENIX Winter ’93
• Höiland-Jørgensen, T. et al. (2018). The eXpress Data Path. CoNEXT ’18

实验台账

• 本篇无集群实测输出；命令与指标均为语义说明。有可调度 Cilium v1.20.0 集群后再补删减后的真实片段。

→ 上一篇：ClusterMesh · 系列目录 · 下一篇：排障坐标系