企业官网建设流程全解析

Cilium 手动删除 IPCache 映射：cilium-dbg bpf ipcache delete 从排查到执行的完整 SOP

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium

一个典型的排障现场

先说结论：要手工清掉一条过期的映射，用cilium-dbg bpf ipcache delete <PREFIX>，但删除前必须先确认条目的真实形态。

场景很常见：某个 Pod 的 IP 已被释放，但节点上的 Cilium IPCache 里还留着它旧的“IP → 身份”映射；后续流量落到这个 IP 时，按过期身份做策略判定，表现就是转发异常、流量莫名被丢。正常情况下 IPCache 由 Agent 自动维护，手动删除只用于排障、测试或纠正异常条目。

这个命令直接操作 Agent 节点内核里的 BPF map，属于低级运维操作。所以本文按排障视角组织：先确认，再删除，再验证，每一步都给出可复制的命令。

背景：IPCache 是数据平面的“地址簿”

一句话理解 IPCache：它记录“IP/CIDR 前缀 → 安全身份（Identity）及远端隧道端点”的映射。数据平面上每个包都要查这张表，才能完成身份识别、策略判定和隧道封装决策。

你可以把它类比成数据平面随身携带的地址簿——查不到，就不知道该把包交给谁、按什么身份放行。它对应的内核 map 名为cilium_ipcache_v2，类型是 LPM Trie（最长前缀匹配），容量上限 512000 条，定义与键值结构见 pkg/maps/ipcache/ipcache.go。

ipcache delete 语法与参数

命令形如：

cilium-dbg bpf ipcache delete <PREFIX> [--clusterid N]

参数就三类，先记住它们再谈执行：

• 位置参数（PREFIX）：待删除的 IP/CIDR 前缀，必须有且仅有一个。必须带前缀长度，如10.244.3.110/32、fd00::a0/128。传裸 IP（如10.244.3.110）会直接报错Invalid prefix address.。
• --clusterid（uint16，默认0）：条目所属的集群 ID，0表示本集群。它参与 BPF map 键的构造，删除时必须与写入时使用的值一致，否则键对不上，删除会失败。
• 继承的全局选项：-H/--host指定 Agent API 地址，--config指定配置文件，-D/--debug开调试日志，--log-driver/--log-opt配置日志后端。排障时最常用的其实是-D。

另外，命令会先做 root 权限校验（实现见 cilium-dbg/cmd/bpf_ipcache_delete.go），非 root 直接拒绝执行——它必须在运行 Cilium Agent 的节点上以 root 身份跑。

排障 SOP：先查后删的完整命令序列

🔎第一步：确认条目存在且格式正确

# 列出全部 IPCache 条目（本地 + 远端 IP 与身份） cilium-dbg bpf ipcache list # 按前缀精确匹配（键的字符串必须完全相等） cilium-dbg bpf ipcache match 10.244.3.110/32 # 按 IP 做最长前缀匹配查询 cilium-dbg bpf ipcache get 10.244.3.110

三者分工不同：list（别名ls）全量展示；match要求前缀键精确相等，命中输出key ... has value ...，未命中输出does not match to any ipcache entry并以非零码退出；get按 IP 走 LPM 语义，命中输出10.244.3.110 maps to identity 6，查不到则输出does not map to any identity。排障时先用list看清真实键长什么样，再决定删谁。

✅第二步：执行删除

# 删除本集群条目（clusterid 缺省为 0，可省略） cilium-dbg bpf ipcache delete 10.244.3.110/32 # ClusterMesh 远端条目：必须带上写入时的 clusterid cilium-dbg bpf ipcache delete 10.244.3.110/32 --clusterid 1

成功时输出：

Deleted entry 10.244.3.110/32@0

末尾的@0就是 clusterid。失败时向 stderr 打印Error deleting entry ...并以退出码 1 结束。

第三步：再次验证

cilium-dbg bpf ipcache match 10.244.3.110/32 # 期望输出：10.244.3.110/32 does not match to any ipcache entry

如果还需要重建映射，可以配合update子命令插入新条目，它支持--identity、--tunnelendpoint、--encryptkey、--skiptunnel、--clusterid参数：

cilium-dbg bpf ipcache update 10.244.3.110/32 \ --tunnelendpoint 172.21.0.2 --identity 6 --clusterid 0

原理速览：LPM Trie 键结构与删除语义

delete 的执行链路很短：解析 CIDR → 用前缀和 clusterid 构造键 → 对cilium_ipcache_v2这张 LPM Trie 执行精确删键。

键由四个字段拼成（pkg/maps/ipcache/ipcache.go 中的Key结构，需与bpf/lib/eps.h中的struct ipcache_key保持同步）：

• Prefixlen：前缀长度，内部叠加了staticPrefixBits偏移；
• ClusterID：即--clusterid；
• Family：地址族，按前缀自动识别 IPv4/IPv6，无需手工指定；
• IP：固定 16 字节，IPv4 存放在低 4 字节。

因此“前缀 + clusterid + 地址族”三者共同决定一个键。这也解释了删除语义：LPM Trie 的删除是精确删键——只移除与所给键完全一致的条目，不级联影响其他前缀。删掉一条 /32 不会动到同网段的 /24 条目，反之亦然；两个前缀在 map 里是相互独立的键。

delete、update、get、match这些子命令都挂在同一个父命令ipcache（“Manage the IPCache mappings for IP/CIDR <-> Identity”）之下，定义见 cilium-dbg/cmd/bpf_ipcache.go。

⚠️ 避坑清单

按“现象 → 原因 → 处理”梳理最常见的四类坑：

1. 提示权限不足→ 命令内置 root 校验。原因：非 root 执行。处理：登录 Agent 节点，用sudo重跑。
2. Error deleting entry ...: no such file or directory（ENOENT）→ 构造出的键在 map 里不存在。常见原因有三个：前缀拼错、clusterid 与写入时不一致、地址族不对。处理：先cilium-dbg bpf ipcache list核对真实键，ClusterMesh 场景尤其检查 clusterid。
3. Invalid prefix address.→ 参数不是合法 CIDR。原因：裸 IP 没带前缀长度。处理：补上/32（IPv4）或/128（IPv6）。
4. No prefix provided.→ 漏传了位置参数。处理：把前缀加到命令后面。

还有一个必须想清楚的坑：删除条目会直接改变数据路径行为——该前缀随即失去身份（策略按无身份/未知处理）与隧道端点（封装决策随之变化）。而且手动删除只是“治标”，Agent 后续可能按控制面状态把条目重新同步回来；根因应在控制面（如 IPAM、身份同步）修复，手工清键只用于排障或临时纠正。

一句话总结与子命令速查

记住六个字：先查后删，键要对上。list看清全貌，match精确核对，delete精确删键，最后再match一次验证收尾。

ipcache 命令族的分工可以这样记：update负责插入/覆盖（带--identity、--tunnelendpoint、--encryptkey、--skiptunnel、--clusterid）；list（别名ls）全量展示；get按 IP 做最长前缀匹配查身份；match按前缀精确匹配；delete精确删键。排障时它们通常成组使用，单独执行delete反而少见——这也是“先查后删”成为习惯的原因。

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium