ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

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

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 中 FQDNDNS代理的调试与运维方法。通过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 cachecilium-dbg fqdn names显示 Cilium 内部为 DNS 名称 / 正则表达式保存的状态在源码层面这些命令全部定义在 cilium-dbg/cmd/fqdn.go 中。该文件使用 cobra 框架将命令挂载到RootCmdRootCmd.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: formatjson)参数说明--config string配置文件路径默认为$HOME/.cilium.yaml-D, --debug启用调试消息输出-H, --host string服务端cilium-agentAPI 的 URI 地址当在容器外调试时通常需要指向 agent 的 UNIX socket 或转发端口--log-driver strings日志输出端点例如syslog--log-opt map日志驱动选项例如formatjson这些参数由 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.goEndpoint Source FQDN TTL ExpirationTime IPs每列对应api/v1/models.DNSLookup模型中的字段定义见 api/v1/models/dns_lookup.go列对应模型字段含义Endpointendpoint-id发起该次 DNS 查询的端点 ID0表示 agent 自身发起的全局查询Sourcesource该 FQDN-IP 关联的产生原因取值为lookup或connection见下FQDNfqdnDNS 名称TTLttlDNS 响应中的 TTL秒ExpirationTimeexpiration-time该条数据在缓存中的绝对过期时间IPsips该 DNS 名称解析出的 IP 地址列表多个 IP 用逗号分隔模型中还包含lookup-time该条数据收到的时间字段同样可通过 JSON 输出查看。3.3--source过滤lookup 与 connection 的区别FQDN 代理缓存中每条记录的来源分为两类其值在 pkg/fqdn/namemanager/api.go 中定义lookup该 FQDN-IP 关联来源于一次真实的 DNS 查询DNSSourceLookup数据来自端点的 DNS 解析历史DNSHistoryconnection该关联来源于一次由 DNS 查询产生的、正在持续的活动连接DNSSourceConnection数据来自端点侧跟踪的 DNS zombieDNSZombies——即 DNS 记录本身已过期但连接仍然存活的 IP 关联其TTL字段显示为0ExpirationTime对应下一次连接跟踪CTGC 的预计时间DNSZombieMappings.NextCTGCUpdate()见 pkg/fqdn/cache.go。从 pkg/fqdn/namemanager/api.go 的实现看当source未指定时默认返回两类记录的并集指定lookup或connection则只返回对应来源的记录。另有一个内部来源globalDNSSourceGlobal对应 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 不存在服务端返回GetFqdnCacheIDNotFoundCLI 会静默处理该 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--forcefalse跳过删除前的确认提示-p--matchpattern string空仅删除 FQDN 与 matchpattern 匹配的缓存条目-h--help-显示帮助4.1 确认机制与 force 模式默认情况下不带-f命令会先调用listFQDNCache()打印即将被删除的缓存条目然后通过confirmCleanup()请求用户输入确认确认后才真正执行删除见 cilium-dbg/cmd/fqdn.go。这在生产环境中可防止误删整份缓存。需要非交互式删除例如在脚本中时使用-f。4.2 底层删除逻辑ForceExpire 与 DNS zombie GCclean命令对应的服务端实现是deleteFQDNCacheHandlerpkg/fqdn/namemanager/api.go它调用manager.deleteDNSLookups(time.Now(), matchPatternStr)将matchpattern编译为可选的正则匹配器对全局DNSCache、每个端点的DNSHistory调用ForceExpirepkg/fqdn/cache.go强制在 TTL 到期前清除条目对每个端点的DNSZombies调用ForceExpire并执行 zombie GCDNSZombieMappings.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$ } ] }服务端实现为getFQDNNamesHandlerpkg/fqdn/namemanager/api.go遍历 name manager 中注册的全部 FQDN 策略选择器allSelectors返回每个选择器的字符串形式与对应的正则表达式。通过它你可以核对当前加载的toFQDNs策略规则实际被翻译成了哪些正则是验证策略是否按预期生成规则的关键手段。六、请求链路从 CLI 到数据面的完整调用关系结合源码cilium-dbg fqdn命令族的完整调用链如下CLI 层cilium-dbg/cmd/fqdn.gocobra 命令解析参数构造 policy 客户端请求policy.NewGetFqdnCacheParams/NewGetFqdnCacheIDParams/NewDeleteFqdnCacheParams/NewGetFqdnNamesParams通过client.Policy调用对应 REST 接口API 客户端层api/v1/client/policy由 go-swagger 生成的客户端代码负责 HTTP 参数编码与响应解码服务端 handler 层pkg/fqdn/namemanager/api.gogetFQDNCacheHandler、getFQDNCacheIDHandler、deleteFQDNCacheHandler、getFQDNNamesHandler分别处理四个接口通过parseFqdnFilters完成 CIDR / matchpattern / source 过滤解析数据模型层api/v1/models/dns_lookup.goDNSLookup模型是 CLI 与服务端之间传递的统一结构缓存层pkg/fqdn/cache.goDNSCache的cacheEntryName/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再次确认条目已被移除。整个排查过程中可通过-Ddebug与-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),仅供参考
返回列表