Cilium 实战用cilium-dbg fqdn cache list检视 FQDN 代理 DNS 缓存【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本文围绕 Cilium 的 FQDN 代理FQDN proxy与cilium-dbg fqdn cache list命令展开讲解如何查看 Cilium 代理缓存的 域名 → IP 映射并结合--endpoint、--source、--matchpattern、--output等参数按端点、来源和域名模式精准过滤缓存条目。读完本文你将掌握该命令的完整用法、输出字段的语义TTL、过期时间、lookup/connection 两种来源并理解其背后的 API 调用链与 DNS 缓存实现原理从而在日常排障中快速判断某个域名是否已被 Cilium 解析、由哪个端点触发、何时过期。命令总览FQDN 代理缓存管理在 Cilium 中FQDN 代理fqdn proxy负责拦截端点发出的 DNS 查询将解析结果写入缓存供基于 FQDN 的网络策略toFQDNs使用。CLI 侧提供了三个子命令来管理这一缓存cilium-dbg fqdn cache list列出缓存内容本文主题cilium-dbg fqdn cache clean清理缓存条目删除不再有活跃流量的记录cilium-dbg fqdn顶层命令还有一个兄弟命令cilium-dbg fqdn names用于展示 Cilium 内部对 DNS 名/正则表达式的状态即已启用的 FQDN 策略选择器。命令结构定义在 cilium-dbg/cmd/fqdn.go其中fqdnCacheCmdManage fqdn proxy cache挂载了list与clean两个子命令并注册在cilium-dbg fqdn之下fqdnNames子命令则对应 Show internal state Cilium has for DNS names / regexes。本命令的标准用法cilium-dbg fqdn cache list [flags]命令参数详解cilium-dbg fqdn cache list的全部专属参数如下与 cilium-dbg_fqdn_cache_list.md 保持一致参数简写类型默认值说明--endpoint-estring空仅列出指定 endpoint id 的缓存条目--help-h--显示 list 子命令帮助--matchpattern-pstring空仅列出 FQDN 匹配 matchpattern 的缓存条目--output-ostring空输出格式json、yaml或jsonpath{}--source-sstring空仅列出指定来源的条目lookup、connection这些 flag 在 fqdn.go 的 init() 中通过 cobra 注册fqdnListCacheCmd.Flags().StringVarP(fqdnCacheMatchPattern, matchpattern, p, , List cache entries with FQDN that match matchpattern) fqdnListCacheCmd.Flags().StringVarP(fqdnEndpointID, endpoint, e, , List cache entries for a specific endpoint id) fqdnListCacheCmd.Flags().StringVarP(fqdnSource, source, s, , List cache entries from a specific source (lookup, connection)) command.AddOutputOption(fqdnListCacheCmd)-o/--output由 pkg/command/output.go 的AddOutputOption统一提供支持json、yaml以及jsonpath{...}三种格式便于脚本化处理与自动化排障。继承自父命令的全局参数与 cilium-dbg 其它子命令一致该命令还继承以下父命令参数参数说明--config string配置文件路径默认$HOME/.cilium.yaml-D, --debug启用调试信息-H, --host stringCilium 服务端 API 的 URI--log-driver strings日志输出端点例如syslog--log-opt map日志驱动选项例如formatjson其中-H/--host常用于在运行有 Cilium agent 的节点上通过远程 API 查看另一台节点的缓存或在使用非默认 socket 的场景下指定 API 地址。典型使用场景与示例1. 列出全部缓存条目不带任何过滤参数输出所有端点缓存的所有 DNS 解析记录cilium-dbg fqdn cache list输出使用tabwriter渲染成对齐的表格表头在 listFQDNCache() 中定义Endpoint Source FQDN TTL ExpirationTime IPs 0 lookup api.github.com. 600 2026-09-12T03:00:00Z 140.82.112.6,140.82.113.6 1015 connection api.github.com. 0 2026-09-12T02:20:00Z 140.82.113.6各列含义如下Endpoint发起该 DNS 查询的端点 ID值为0表示记录由 agent 自身产生Source条目来源取值为lookup来自实际 DNS 查询响应或connection来自已建立的活动连接FQDN完整限定域名DNS 响应中的名字TTLDNS 响应中的 TTL秒connection来源的条目 TTL 为 0ExpirationTime该条目在缓存中的绝对过期时间IPs本次查询返回的 IP 地址列表多个地址以逗号分隔。2. 按端点过滤只查看某个具体端点如 endpoint 1015的缓存cilium-dbg fqdn cache list --endpoint 1015该参数会切换到按端点 ID 查询的 API 路径见下文底层实现适合在定位某个 Pod 为什么解析到了错误的 IP时使用。3. 按来源过滤区分来自 DNS 查询与来自活动连接两种条目cilium-dbg fqdn cache list --source lookup # 只看 DNS lookup 来源 cilium-dbg fqdn cache list --source connection # 只看活动连接来源两者的差异正是FQDN → IP 关联存在的原因lookup表示该 IP 来自一次真实的 DNS 解析connection表示该 IP 正被一条由 DNS 解析创建的连接所使用属于 DNS 僵尸条目zombie体系的一部分见下文源码分析。4. 按域名模式过滤使用通配符模式筛选特定域名的记录cilium-dbg fqdn cache list --matchpattern *.github.com. cilium-dbg fqdn cache list --matchpattern api.*.com.--matchpattern与cilium-dbg fqdn cache clean -p使用相同的模式语法由 pkg/fqdn/matchpattern/matchpattern.go 提供解析与校验ValidateWithoutCache/Sanitize支持类似策略规则的 FQDN 通配符。多个过滤条件可以组合使用例如同时按端点与来源过滤cilium-dbg fqdn cache list --endpoint 1015 --source lookup --matchpattern *.github.com.5. 结构化输出与脚本化在自动化场景中使用-o输出 JSON 或 YAMLcilium-dbg fqdn cache list -o json cilium-dbg fqdn cache list -o yaml cilium-dbg fqdn cache list -o jsonpath{.items[*].fqdn}JSON 输出对应 DNSLookup 模型 的字段endpoint-id、fqdn、ips、lookup-time、expiration-time、source、ttl方便用jq等工具继续加工cilium-dbg fqdn cache list -o json | jq -r .[] | select(.sourcelookup) | .fqdn底层实现从 CLI 到缓存的调用链客户端侧的分支逻辑在 listFQDNCache() 中CLI 根据是否指定--endpoint选择不同的 API指定了--endpoint调用client.Policy.GetFqdnCacheID(params)并把端点 ID 通过params.SetID(fqdnEndpointID)传给服务端若目标端点不存在服务端返回 404GetFqdnCacheIDNotFoundCLI 会静默地视为空结果未指定--endpoint调用client.Policy.GetFqdnCache(params)一次拉取所有端点的 DNS 历史。无论走哪条路径--source与--matchpattern都会分别通过params.SetSource与params.SetMatchpattern透传到服务端。对应 API 定义位于 api/v1/server/restapi/policy如get_fqdn_cache.go、get_fqdn_cache_id.goswagger route 为GET /fqdn/cache与GET /fqdn/cache/{id}。服务端的过滤与组装服务端处理器位于 pkg/fqdn/namemanager/api.gogetFQDNCacheHandler.Handle与getFQDNCacheIDHandler.Handle首先调用parseFqdnFiltersapi.go#L279-L304把--matchpattern编译为正则表达式经matchpattern.SanitizeValidateWithoutCache、把source原样透传随后调用dnsHistoryModelapi.go#L62-L159对每个端点遍历两份数据端点自身的DNSHistory缓存来自 DNS 查询响应Source lookupDNSZombies中的存活僵尸条目DumpAliveSource connection。source的取值常量定义在 pkg/fqdn/namemanager/api.go#L24-L28DNSSourceLookup lookup DNSSourceConnection connection DNSSourceGlobal globaldnsHistoryModel的组装逻辑api.go#L97-L156展示了两类条目的差异lookup 条目来自ep.DNSHistory.Dump()完整携带 DNS 响应中的TTL、ExpirationTime和全部 IPconnection 条目来自ep.DNSZombies.DumpAlive(prefixMatcher)每条僵尸记录对应一个 IP 及其关联的多个域名TTL固定为 0ExpirationTime取下一次连接跟踪CTGC 的时间。根据source参数函数分别返回 lookup、connection 或两者的并集。当查询结果为空时服务端返回 404NewGetFqdnCacheNotFoundCLI 捕获后输出空表格而不报错。缓存的数据结构缓存本体由 pkg/fqdn/cache.go 的DNSCache实现该文件开头注释说明其结构用于将数据导出为api/v1/models.DNSLookupJSON。DNS 僵尸映射DNSZombieMappings同文件 cache.go#L905 附近负责跟踪已解析但仍有活跃连接的 IP防止因 DNS TTL 过期而错误地删除仍在使用的映射——这正是connection来源条目存在的意义。需要进一步深挖时可阅读同目录的 cache_test.go 了解各查询与过期行为的测试用例。与 clean 命令的配合排障工作流cilium-dbg fqdn cache list最常见的实战搭档是 cilium-dbg fqdn cache clean源码 cleanFQDNCache()。典型排障流程如下用 list 观察当前缓存确认目标域名是否已解析、来源与剩余 TTLcilium-dbg fqdn cache list --matchpattern *.example.com.若发现过期或错误条目影响了策略判定先预览将被删除的内容不带-f时 clean 会先调用listFQDNCache()打印待删除条目并要求确认cilium-dbg fqdn cache clean --matchpattern *.example.com.确认无误后强制执行cilium-dbg fqdn cache clean --force --matchpattern *.example.com.再次 list 验证清理结果并观察后续 DNS 查询是否重新填充缓存。clean 在服务端调用deleteDNSLookupsnamemanager/api.go#L163-L205它会强制过期所有当前没有活跃流量的匹配条目同时刷新全局缓存与 ipcache 元数据——这也是为什么 clean 会谨慎地要求确认的原因。输出字段与 DNSLookup 模型-o json/yaml输出的每个条目对应 api/v1/models/dns_lookup.go 中的DNSLookup结构An IP - DNS mapping, with metadata字段映射如下JSON 字段表格列类型语义endpoint-idEndpointint64发起查询的端点 ID0 表示 agent 自身fqdnFQDNstringDNS 名称ipsIPs[]string本次查询返回的 IP 列表lookup-time-date-time数据被接收的绝对时间expiration-timeExpirationTimedate-time数据在缓存中过期的绝对时间sourceSourcestring关联存在的原因lookupDNS 查询或connection由查询创建的连接ttlTTLint64DNS 响应中的 TTL这一模型同样被 FQDN 缓存的导出、调试工具以及cilium-dbg fqdn cache list -o jsonpath{...}的字段筛选所复用掌握其字段语义后可以轻松编写基于 JSON 输出的监控与告警脚本。注意事项--matchpattern中的域名采用 FQDN 格式末尾带点如api.github.com.模式匹配基于通配符与正则转换建议先小范围过滤验证再用于批量操作connection来源的条目TTL恒为 0其生命周期由连接跟踪驱动而非 DNS TTL因此单看 TTL 列不足以判断其是否失效需结合ExpirationTime未指定--endpoint时返回所有端点的缓存在拥有大量端点的集群中建议配合-e、-p缩小范围或使用-o json做服务端聚合后再本地过滤本命令查询的是 agent 内存中的 FQDN 缓存属于运行时诊断手段不涉及持久化数据修改如需修改缓存请使用cilium-dbg fqdn cache clean并注意其确认机制。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考