掌握 cilium-dbg fqdn cache：Cilium FQDN 代理缓存的查看与清理实战指南
【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium
cilium-dbg fqdn cache是 Cilium 数据路径排障中高频使用的命令组，用于管理 FQDN（完全限定域名）代理缓存——即 Cilium 在 DNS 层观测到的"域名 ↔ IP"映射数据。本文以仓库中 cilium-dbg fqdn cache 命令参考 为主体，结合 fqdn.go 命令实现、DNSLookup API 模型 与 pkg/fqdn 缓存核心实现，系统讲解该命令的完整参数、输出含义、底层原理与真实排障用法。读完本文，你将能够熟练地按端点、域名模式、数据来源过滤查看 FQDN 缓存，安全地强制清理过期条目，并理解缓存条目从产生到过期的完整生命周期。
为什么需要管理 FQDN 代理缓存
Cilium 的toFQDNs策略允许基于 DNS 域名而非 IP 编写网络策略。为了让策略引擎拿到"某个域名当前解析到哪些 IP"，Cilium 内置了 DNS 代理（FQDN proxy）：当端点的 DNS 查询经过代理时，代理会记录查询结果并写入一个带 TTL 与过期时间的缓存，供策略选择器（selector）使用，最终为这些 IP 分配基于 FQDN 的安全身份（identity）。
这个缓存就是cilium-dbg fqdn cache命令管理的对象。它回答了排障中最常见的问题：某个域名解析到的 IP 是否已被 Cilium 观测并纳入策略计算？与之配套的还有 cilium-dbg fqdn names（查看策略内部持有的 DNS 名称/正则状态）和 cilium-dbg fqdn（命令组入口）。
命令层级总览
cilium-dbg fqdn Manage fqdn proxy # 命令组入口 ├── cilium-dbg fqdn cache │ ├── cilium-dbg fqdn cache list # 列出缓存内容 │ └── cilium-dbg fqdn cache clean # 清理缓存 └── cilium-dbg fqdn names # 查看 DNS 名称 / 正则内部状态命令树定义见 cilium-dbg/cmd/fqdn.go：fqdnCmd挂载cache与names子命令，cache又挂载list与clean。顶层fqdn cache不带子命令时仅打印帮助信息。
查看 FQDN 代理缓存：cilium-dbg fqdn cache list
基本用法：
cilium-dbg fqdn cache list [flags]不带任何参数时，命令通过 REST API 拉取全量FQDN 缓存，并输出如下格式的表格：
Endpoint Source FQDN TTL ExpirationTime IPs参数详解
| 参数 | 简写 | 类型 | 说明 |
|---|---|---|---|
--endpoint | -e | string | 只列出指定 endpoint ID 的缓存条目 |
--matchpattern | -p | string | 只列出 FQDN 与匹配模式（matchpattern）相符的条目 |
--source | -s | string | 只列出特定来源的条目，取值lookup或connection |
--output | -o | string | 输出格式：json、yaml或jsonpath='{}' |
--help | -h | — | 显示帮助 |
从 init() 中的标志注册 可以看到这些标志与 CLI 变量的绑定关系。其中--output由command.AddOutputOption统一注册，因此输出格式能力与其他 cilium-dbg 命令保持一致。
输出列与 DNSLookup 模型一一对应
表格的每一行对应一个DNSLookup对象，其字段定义在 api/v1/models/dns_lookup.go（swagger 生成模型）：
| 表头 | 模型字段 | 含义 |
|---|---|---|
Endpoint | endpoint-id | 发起这次 DNS 查询的端点 ID；为 0 表示由 agent 自身发起 |
Source | source | 该 FQDN↔IP 关联产生的原因：DNS 查询（lookup）或由 DNS 查询建立、仍在持续的连接（connection） |
FQDN | fqdn | DNS 名称 |
TTL | ttl | DNS 响应中的 TTL 值 |
ExpirationTime | expiration-time | 该条数据在缓存中绝对过期时间（RFC3339 时间） |
IPs | ips | 本次查询返回的 IP 地址列表，多个 IP 以逗号分隔 |
| （表格未展示） | lookup-time | 数据被接收的绝对时间 |
Source字段的两种取值在模型注释中有明确定义："Either a DNS lookup or an ongoing connection to an IP that was created by a DNS lookup"，即lookup（DNS 查询产生）与connection（由查询结果建立的存活连接产生），这也正是-s/--source参数的取值集合。
过滤与格式化实例
按端点过滤（需要指定-e，此时走GetFqdnCacheID接口）：
cilium-dbg fqdn cache list --endpoint 725 cilium-dbg fqdn cache list -e 725 -s lookup按域名模式过滤：
cilium-dbg fqdn cache list --matchpattern '*.github.com'按来源过滤：
cilium-dbg fqdn cache list --source lookup cilium-dbg fqdn cache list --source connection输出 JSON / YAML 供脚本或 jq 消费：
cilium-dbg fqdn cache list -o json cilium-dbg fqdn cache list -o jsonpath='{.items[0].fqdn}'在 fqdn.go 的 listFQDNCache 实现 中，当指定--output时走command.PrintOutput(lookups)直接序列化[]*models.DNSLookup；否则用tabwriter打印对齐表格。注意一个细节：-e与-s、-p可以组合使用，且-e缺失时请求的是全量接口GetFqdnCache，命中 404（NotFound）时被静默处理，不会中断命令。
排障真实输出示例
策略排障文档 给出了 DNS 请求之后的典型输出：
# cilium-dbg fqdn cache list Endpoint Source FQDN TTL ExpirationTime IPs 725 lookup api.github.com. 3600 2023-02-10T18:16:05.842Z 140.82.121.6 725 lookup support.github.com. 3600 2023-02-10T18:16:09.371Z 185.199.111.133,185.199.109.133,185.199.110.133,185.199.108.133随后可通过cilium-dbg ip list | grep <IP>验证这些 IP 是否已获得对应的 FQDN 身份标签：
# cilium-dbg ip list | grep -A 1 140.82.121.6 140.82.121.6/32 fqdn:api.github.com reserved:world这条"缓存 → 身份"的验证链路，是定位toFQDNs策略"流量没被放行"类问题的最常用手段。
清理 FQDN 代理缓存：cilium-dbg fqdn cache clean
基本用法：
cilium-dbg fqdn cache clean [flags]参数详解
| 参数 | 简写 | 类型 | 说明 |
|---|---|---|---|
--force | -f | bool | 跳过删除确认 |
--matchpattern | -p | string | 只删除 FQDN 与匹配模式相符的缓存条目 |
默认的安全交互流程
不加-f时，命令先预览即将删除的条目，再要求确认，避免误删：
# cilium-dbg fqdn cache clean Following cache entries are going to be deleted: Endpoint Source FQDN TTL ExpirationTime IPs 725 lookup api.github.com. 3600 2023-02-10T18:16:05.842Z 140.82.121.6 # (confirm) FQDN proxy cache cleared从 cleanFQDNCache 实现 可以看到：未指定--force时先调用listFQDNCache()打印预览，再调用confirmCleanup()等待用户确认；确认通过后构造DeleteFqdnCache请求，带-p时通过SetMatchpattern设置匹配模式，成功后输出FQDN proxy cache cleared。
跳过确认并定向清理：
cilium-dbg fqdn cache clean --force cilium-dbg fqdn cache clean -f -p '*.expired.example.com'底层语义：强制过期而非删除
从缓存实现看，清理并不是简单地从字典里抹掉条目。pkg/fqdn/cache.go 中ForceExpire(expireLookupsBefore time.Time, nameMatch *regexp.Regexp)将匹配的条目按"过期时间早于给定时刻"强制置为过期并返回受影响域名集合；同时配套的DNSZombieMappings.ForceExpire（cache.go）会清理对应的 zombie（僵尸）映射。这意味着被清理的域名如果再次被查询或仍有存活连接，会依据新的 DNS 响应重新入缓存，符合 DNS 语义。匹配模式在缓存层以正则表达式形式参与过滤。
源码级原理剖析
CLI 层：REST 调用路径
cilium-dbg/cmd/fqdn.go 是纯客户端实现，三个核心动作对应三个 API：
| 动作 | CLI 函数 | REST API |
|---|---|---|
| 列出全部/按源/按模式 | listFQDNCache() | GET /policy/fqdn-cache（GetFqdnCache） |
| 列出指定端点 | listFQDNCache() | GET /policy/fqdn-cache/{id}（GetFqdnCacheID） |
| 清理缓存 | cleanFQDNCache() | DELETE /policy/fqdn-cache（DeleteFqdnCache） |
API 客户端由api/v1/client/policy包提供，与 文档自动生成机制 保持一致：cmdref文档由命令本身生成，因此文档中的参数与真实 CLI 永远同步。
缓存核心：DNSCache 的生命周期
pkg/fqdn/cache.go 中的DNSCache是 FQDN 代理缓存的真正载体，关键方法包括：
Update(lookupTime, name, ips, ttl, ...)：写入一次 DNS 查询结果，内部按 IP→条目（ipEntries）与名称→条目（nameEntries）双向索引维护（cache.go）；isExpiredBy(pointInTime)：依据expiration = lookupTime + TTL判断过期（cache.go）；GC(now, zombies)：周期性垃圾回收，处理 TTL 过期条目与 zombie 映射（cache.go）；ForceExpire(...)：上文所述的强制过期入口（cache.go）；Dump()/DumpNames()：输出快照，正是fqdn cache list表格与服务端响应序列化的数据来源（cache.go）。
其中DNSZombieMappings是 Cilium 的一个精巧设计：DNS TTL 过期但 TCP 连接仍存活时，IP→名称映射不能立刻删除（否则已建立连接会被策略拒绝），因此先转为 zombie 并在连接结束或 CT GC 后彻底回收。这也解释了Source=connection条目的存在意义。
相关命令：cilium-dbg fqdn names
与缓存管理配套的 cilium-dbg fqdn names 用于展示 Cilium 内部为 DNS 名称/正则表达式持有的状态（GetFqdnNames接口，见 fqdn.go），输出为 JSON，适合对比"策略注册的选择器"与"缓存中实际出现的名称"是否一致。
实战排障场景建议
- 域名解析了但流量不放行：先
cilium-dbg fqdn cache list -e <endpoint>确认代理是否真的观测到该域名的映射，再cilium-dbg ip list | grep <IP>确认 IP 是否拿到fqdn:身份标签（链路示例见 troubleshooting.rst）。 - 怀疑缓存脏数据：用
cilium-dbg fqdn cache clean -f强制清理全部缓存，或-p定向清理特定域名，触发重新解析。 - 关注身份数量：
toFQDNs的每个 IP 都会按标签组合分配安全身份。监控identity_label_sources{type="fqdn"}指标可检测 FQDN 身份是否接近耗尽；fqdn_selectors指标反映注册的toFQDNs选择器数量（详见 troubleshooting.rst）。 - 注意
-p与-e的组合：list中-e决定走单端点接口，其余过滤条件（-s、-p）在两种接口下均可用。
使用注意事项
- 所有子命令都继承父命令的通用标志：
--config（配置文件，默认$HOME/.cilium.yaml）、-D/--debug、-H/--host（服务端 API URI）、--log-driver、--log-opt，远程排障时通过-H指向目标节点 API 即可。 Endpoint=0表示 agent 自身的查询，过滤端点时注意区分。- 缓存清理作用于整个 agent 的 FQDN 缓存（而非单个策略），
clean是运维操作，生产环境建议先用list预览或配合-p收敛范围。 - 本文所述命令基于当前仓库源码（
cilium-dbg二进制）；不同 Cilium 版本的行为以对应版本的cilium-dbg fqdn cache --help输出为准。
【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
