Cilium FQDN 代理调试指南：cilium-dbg fqdn 命令族完全解析-育师

Cilium FQDN 代理调试指南：cilium-dbg fqdn 命令族完全解析

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

本指南以cilium-dbg fqdn命令族为核心，系统讲解 Cilium 中 FQDN（DNS）代理的调试与运维方法。通过cilium-dbg fqdn cache list、cilium-dbg fqdn cache clean与cilium-dbg fqdn names三个子命令，你可以查看端点 DNS 解析记录、强制清理过期的 DNS 缓存、检查策略中的 DNS 名称/正则表达式内部状态。读完本文，你将掌握 FQDN 代理缓存的数据模型、过滤与输出参数、底层实现原理，以及基于cilium-dbg的完整故障排查路径。

一、命令总览：FQDN 代理与`cilium-dbg fqdn`命令树

Cilium 的 FQDN 代理（FQDN proxy / DNS proxy）是 Cilium 网络策略体系中"基于 DNS 名称的安全策略"的支撑组件。它拦截端点发出的 DNS 查询，将域名到 IP 的映射关系记录到缓存中，从而让策略可以使用toFQDNs等规则匹配 DNS 名称，而不是依赖可能变化的 IP 地址。

cilium-dbg fqdn命令族提供了对这套机制的观测与控制入口，其完整命令树如下：

cilium-dbg fqdn ├── cilium-dbg fqdn cache │ ├── cilium-dbg fqdn cache list # 列出 FQDN 代理缓存内容 │ └── cilium-dbg fqdn cache clean # 清理 FQDN 代理缓存 └── cilium-dbg fqdn names # 显示 Cilium 内部持有的 DNS 名称 / 正则表达式状态

对应的命令说明（来自命令参考文档）：

命令	用途
`cilium-dbg fqdn`	管理 fqdn proxy（父命令，直接运行显示帮助信息）
`cilium-dbg fqdn cache`	管理 fqdn proxy cache（父命令，直接运行显示帮助信息）
`cilium-dbg fqdn cache list`	列出 fqdn proxy cache 内容
`cilium-dbg fqdn cache clean`	清理 fqdn proxy cache
`cilium-dbg fqdn names`	显示 Cilium 内部为 DNS 名称 / 正则表达式保存的状态

在源码层面，这些命令全部定义在 cilium-dbg/cmd/fqdn.go 中。该文件使用 cobra 框架将命令挂载到RootCmd（RootCmd.AddCommand(fqdnCmd)），其中fqdn cache list与fqdn cache clean又通过fqdnCacheCmd.AddCommand(...)挂载为cache的子命令。

二、全局参数：所有`fqdn`子命令共用的连接与日志选项

所有cilium-dbg fqdn子命令都继承自父命令的全局参数（同样适用于整个cilium-dbg工具），用于配置 Agent API 的连接方式与日志行为：

--config string Config file (default is $HOME/.cilium.yaml) -D, --debug Enable debug messages -H, --host string URI to server-side API --log-driver strings Logging endpoints to use (example: syslog) --log-opt map Log driver options (example: format=json)

参数	说明
`--config string`	配置文件路径，默认为`$HOME/.cilium.yaml`
`-D, --debug`	启用调试消息输出
`-H, --host string`	服务端（cilium-agent）API 的 URI 地址；当在容器外调试时通常需要指向 agent 的 UNIX socket 或转发端口
`--log-driver strings`	日志输出端点，例如`syslog`
`--log-opt map`	日志驱动选项，例如`format=json`

这些参数由 cilium-dbg/cmd/root.go 中的根命令统一解析，所有子命令共享同一套连接配置。

三、`cilium-dbg fqdn cache list`：查看 DNS 解析缓存

cilium-dbg fqdn cache list用于列出 FQDN 代理缓存的内容，是排查"域名解析结果是否符合预期""策略为何放行/阻断某 IP"的首选工具。

3.1 完整参数说明

cilium-dbg fqdn cache list [flags]

短选项	长选项	默认值	说明
`-e`	`--endpoint string`	空	仅列出指定 endpoint id 的缓存条目
`-p`	`--matchpattern string`	空	仅列出 FQDN 与 matchpattern 匹配的缓存条目
`-o`	`--output string`	空	输出格式：`json`、`yaml`、`jsonpath='{}'`
`-s`	`--source string`	空	仅列出指定来源的缓存条目（`lookup`、`connection`）
`-h`	`--help`	-	显示帮助

3.2 默认表格输出与字段含义

不带-o参数时，命令以表格形式输出（实现见 cilium-dbg/cmd/fqdn.go）：

Endpoint Source FQDN TTL ExpirationTime IPs

每列对应api/v1/models.DNSLookup模型中的字段（定义见 api/v1/models/dns_lookup.go）：

列	对应模型字段	含义
`Endpoint`	`endpoint-id`	发起该次 DNS 查询的端点 ID；`0`表示 agent 自身发起的全局查询
`Source`	`source`	该 FQDN-IP 关联的产生原因，取值为`lookup`或`connection`（见下）
`FQDN`	`fqdn`	DNS 名称
`TTL`	`ttl`	DNS 响应中的 TTL（秒）
`ExpirationTime`	`expiration-time`	该条数据在缓存中的绝对过期时间
`IPs`	`ips`	该 DNS 名称解析出的 IP 地址列表，多个 IP 用逗号分隔

模型中还包含lookup-time（该条数据收到的时间）字段，同样可通过 JSON 输出查看。

3.3`--source`过滤：lookup 与 connection 的区别

FQDN 代理缓存中每条记录的来源分为两类，其值在 pkg/fqdn/namemanager/api.go 中定义：

lookup：该 FQDN-IP 关联来源于一次真实的 DNS 查询（DNSSourceLookup），数据来自端点的 DNS 解析历史（DNSHistory）；
connection：该关联来源于一次由 DNS 查询产生的、正在持续的活动连接（DNSSourceConnection），数据来自端点侧跟踪的 "DNS zombie"（DNSZombies）——即 DNS 记录本身已过期，但连接仍然存活的 IP 关联，其TTL字段显示为0，ExpirationTime对应下一次连接跟踪（CT）GC 的预计时间（DNSZombieMappings.NextCTGCUpdate()，见 pkg/fqdn/cache.go）。

从 pkg/fqdn/namemanager/api.go 的实现看，当source未指定时默认返回两类记录的并集；指定lookup或connection则只返回对应来源的记录。另有一个内部来源global（DNSSourceGlobal），对应 agent 自身缓存的全局 DNS 数据（endpoint-id为 0）。

3.4`--matchpattern`过滤的匹配规则

--matchpattern（服务端参数为matchpattern）使用 Cilium 的 matchpattern 语法对 FQDN 进行过滤。在服务端，parseFqdnFilters会对模式调用matchpattern.Sanitize并编译为正则表达式（见 pkg/fqdn/namemanager/api.go），因此支持如*.cilium.io之类的通配模式。

3.5`--endpoint`过滤

指定-e <endpoint-id>时，命令调用policy.GetFqdnCacheID接口（服务端对应getFQDNCacheIDHandler），仅返回该端点的 DNS 历史与 DNS zombie 记录；若端点 ID 不存在，服务端返回GetFqdnCacheIDNotFound，CLI 会静默处理该 404 并输出空结果（见 cilium-dbg/cmd/fqdn.go）。

3.6 JSON / YAML 输出

配合-o参数可输出结构化数据，便于脚本处理：

cilium-dbg fqdn cache list -o json cilium-dbg fqdn cache list -o yaml cilium-dbg fqdn cache list -o 'jsonpath={.items[0].fqdn}'

结构化输出直接序列化[]*models.DNSLookup数组。需要注意，cacheEntry的 JSON 字段名与DNSLookup模型刻意保持一致（见 pkg/fqdn/cache.go 的注释），这使得cilium-dbg fqdn cache list -o json导出的文件可直接通过--tofqdns-per-cache等预加载选项重新灌入缓存。

四、`cilium-dbg fqdn cache clean`：强制清理 DNS 缓存

当 DNS 记录因 TTL 过期但策略行为异常、或需要强制刷新域名解析结果时，可使用cilium-dbg fqdn cache clean强制删除缓存条目。

cilium-dbg fqdn cache clean [flags]

短选项	长选项	默认值	说明
`-f`	`--force`	`false`	跳过删除前的确认提示
`-p`	`--matchpattern string`	空	仅删除 FQDN 与 matchpattern 匹配的缓存条目
`-h`	`--help`	-	显示帮助

4.1 确认机制与 force 模式

默认情况下（不带-f），命令会先调用listFQDNCache()打印即将被删除的缓存条目，然后通过confirmCleanup()请求用户输入确认，确认后才真正执行删除（见 cilium-dbg/cmd/fqdn.go）。这在生产环境中可防止误删整份缓存。需要非交互式删除（例如在脚本中）时使用-f。

4.2 底层删除逻辑：ForceExpire 与 DNS zombie GC

clean命令对应的服务端实现是deleteFQDNCacheHandler（pkg/fqdn/namemanager/api.go），它调用manager.deleteDNSLookups(time.Now(), matchPatternStr)：

将matchpattern编译为可选的正则匹配器；
对全局DNSCache、每个端点的DNSHistory调用ForceExpire（pkg/fqdn/cache.go），强制在 TTL 到期前清除条目；
对每个端点的DNSZombies调用ForceExpire并执行 zombie GC（DNSZombieMappings.GC），回收仍存活连接的 zombie 条目为活动连接；
将变更同步回全局缓存，并更新 ipcache 元数据层与端点 header 文件（SyncEndpointHeaderFile）。

简言之，clean不是简单删除，而是触发一次完整的缓存与连接状态收敛流程，确保清理后策略与数据面状态保持一致。

五、`cilium-dbg fqdn names`：查看策略侧的 DNS 名称与正则表达式状态

cilium-dbg fqdn names [flags]

该命令仅有一个-h/--help选项，输出 Cilium 内部针对 DNS 名称/正则表达式保存的策略选择器状态（对应policy.GetFqdnNamesAPI）。

其输出为 JSON 格式（CLI 侧使用command.PrintOutputWithType(result.Payload, "json")强制以 JSON 输出，见 cilium-dbg/cmd/fqdn.go），内容对应models.NameManager模型：

{ "FQDNPolicySelectors": [ { "SelectorString": "example.com", "RegexString": "^example\\.com$" } ] }

服务端实现为getFQDNNamesHandler（pkg/fqdn/namemanager/api.go），遍历 name manager 中注册的全部 FQDN 策略选择器（allSelectors），返回每个选择器的字符串形式与对应的正则表达式。通过它，你可以核对当前加载的toFQDNs策略规则实际被翻译成了哪些正则，是验证"策略是否按预期生成规则"的关键手段。

六、请求链路：从 CLI 到数据面的完整调用关系

结合源码，cilium-dbg fqdn命令族的完整调用链如下：

CLI 层（cilium-dbg/cmd/fqdn.go）：cobra 命令解析参数，构造 policy 客户端请求（policy.NewGetFqdnCacheParams/NewGetFqdnCacheIDParams/NewDeleteFqdnCacheParams/NewGetFqdnNamesParams），通过client.Policy调用对应 REST 接口；
API 客户端层（api/v1/client/policy）：由 go-swagger 生成的客户端代码，负责 HTTP 参数编码与响应解码；
服务端 handler 层（pkg/fqdn/namemanager/api.go）：getFQDNCacheHandler、getFQDNCacheIDHandler、deleteFQDNCacheHandler、getFQDNNamesHandler分别处理四个接口，通过parseFqdnFilters完成 CIDR / matchpattern / source 过滤解析；
数据模型层（api/v1/models/dns_lookup.go）：DNSLookup模型是 CLI 与服务端之间传递的统一结构；
缓存层（pkg/fqdn/cache.go）：DNSCache的cacheEntry（Name/LookupTime/ExpirationTime/TTL/IPs）与DNSZombieMappings构成实际的数据存储，ForceExpire提供 TTL 前强制过期能力。

七、实战场景：DNS 策略排查三步走

以下是一个结合本命令族的典型 FQDN 故障排查流程：

第一步：确认解析结果是否落入缓存。当某个toFQDNs策略未按预期生效时，先查看端点的 DNS 解析记录：

cilium-dbg fqdn cache list -e <endpoint-id> cilium-dbg fqdn cache list -p "*.example.com"

确认目标域名是否出现在缓存中、解析出的 IP 是否与预期一致、ExpirationTime是否已经过期。

第二步：核对策略侧的规则翻译。若解析结果正确但策略行为异常，用names检查内部状态：

cilium-dbg fqdn names

核对FQDNPolicySelectors中的SelectorString与RegexString是否与期望的 DNS 名称匹配。

第三步：必要时强制刷新缓存。当 DNS 记录变更（例如域名迁移到新 IP）而旧映射仍被缓存时，强制清理后观察策略是否恢复：

cilium-dbg fqdn cache clean -p "*.example.com" cilium-dbg fqdn cache clean -f # 脚本化场景跳过确认

清理后可用list再次确认条目已被移除。整个排查过程中，可通过-D（debug）与-H（指定 agent API 地址）组合使用，进一步获得请求级的调试输出。

八、注意事项

所有命令都需要能与 cilium-agent 的 API 通信（-H指定，默认连接本地 agent）；命令输出反映的是当前 agent 实例的数据面状态，多节点集群需在目标节点上分别执行。
--matchpattern遵循 Cilium matchpattern 语法（支持通配），而非简单的子串匹配；非法模式会在服务端返回 400 错误。
clean的默认交互确认在生产环境中是安全网，自动化脚本务必显式传入-f。
上述命令文档由cilium-dbg cmdref自动生成（见 Documentation/cmdref 目录），命令行结构与参数以当前仓库版本为准。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Cilium FQDN 代理调试指南：cilium-dbg fqdn 命令族完全解析