Cilium 数据面 NAT 表清理实战cilium-dbg bpf nat flush命令深度解析【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读cilium-dbg bpf nat flush是 Cilium 提供的用于清空本地节点全部 NAT网络地址转换映射条目的调试命令。在排查 SNAT 端口耗尽、连接追踪表异常或需要让节点上的地址转换状态“归零”重来时这个命令是数据面eBPF datapath排障工具箱中的关键一环。读完本文你将掌握该命令的完整用法、权限前提、底层执行流程从 CLI 到 eBPF map 的调用链并了解它与bpf nat list、bpf nat retries等姊妹命令的协作方式。一、命令概览与适用场景该命令位于cilium-dbg调试客户端之下其完整命令层级为cilium-dbg bpf nat flush [flags]命令的功能描述为Flush all NAT mapping entries即清空所有 NAT 映射条目。它操作的对象是 Cilium 数据面中负责SNAT源地址转换的全局 NAT 表——当 Pod 流量经过节点转发到外部网络时eBPF 程序会依据这些表将 Pod 的源 IP/端口改写为节点地址。典型适用场景包括SNAT 端口分配异常当节点上全局 NAT 表积累了大量陈旧条目例如长连接中断后遗留的映射导致端口分配紧张时可以清空后让数据面重新建立映射连接追踪conntrack与 NAT 表状态不一致手动清理 NAT 表配合cilium-dbg bpf ct flush等操作恢复数据面一致性测试与验证验证 NAT 表重建能力、评估流量恢复路径。⚠️操作风险提示该命令会删除节点上所有 NAT 映射条目正在进行的连接可能因此中断后续流量需要重新建立映射。请在维护窗口或充分评估影响后执行。二、完整命令参考2.1 命令语法与专属选项cilium-dbg bpf nat flush [flags]该命令本身不接收位置参数仅有一个专属选项选项说明-h, --help显示 flush 子命令的帮助信息2.2 继承自父命令的全局选项作为cilium-dbg命令树的子命令flush会继承来自父命令cilium-dbg bpf nat→cilium-dbg bpf→cilium-dbg的全局选项选项说明--config string指定配置文件默认$HOME/.cilium.yaml-D, --debug开启调试消息输出-H, --host string指定服务端 API 的 URI用于连接 cilium-agent 的 API 端点--log-driver strings日志输出端点示例syslog--log-opt map日志驱动选项示例formatjson2.3 实际执行示例# 直接清空当前节点全部 NAT 映射条目 cilium-dbg bpf nat flush # 查看帮助 cilium-dbg bpf nat flush --help # 以调试模式执行输出更多诊断信息 cilium-dbg bpf nat flush --debug执行成功时命令会逐张表打印被清除的条目数量例如Flushed 42 entries from /sys/fs/bpf/tc/globals/cilium_snat_v4_external三、权限前提必须以 root 运行NAT 表属于内核 BPF 全局状态修改权限受严格限制。命令在入口处调用了common.RequireRootPrivilege进行校验相关实现见 pkg/common/utils.go// RequireRootPrivilege checks if the user running cmd is root. If not, it exits the program func RequireRootPrivilege(cmd string) { if os.Getuid() ! 0 { fmt.Fprintf(os.Stderr, Please run %q command(s) with root privileges.\n, cmd) os.Exit(1) } }即若当前用户不是 rootUID 不为 0程序会直接报错退出。因此请使用sudo或 root 用户执行sudo cilium-dbg bpf nat flush四、底层实现从 CLI 到 eBPF map 的完整调用链flush子命令的核心实现位于 cilium-dbg/cmd/bpf_nat_flush.go其执行流程可分为四步4.1 命令注册命令通过 Cobra 框架注册为bpf nat的子命令父命令定义见 cilium-dbg/cmd/bpf_nat.govar bpfNatFlushCmd cobra.Command{ Use: flush, Short: Flush all NAT mapping entries, Run: func(cmd *cobra.Command, args []string) { common.RequireRootPrivilege(cilium bpf nat flush) flushNat() }, } func init() { BPFNatCmd.AddCommand(bpfNatFlushCmd) }4.2 探测节点启用的 IP 协议族flushNat()首先调用getIpEnableStatuses()获取节点上 IPv4/IPv6 的启用状态实现见 cilium-dbg/cmd/helpers.go优先调用 cilium-agent 的healthz API带 5 秒超时确认 agent 存活若 agent 存活再通过ConfigGet API读取Status.Addressing.IPv4.Enabled/IPv6.Enabled字段若 agent 不可达则回退读取运行时系统配置。只有启用的协议族对应的 NAT 表才会被清空避免对未启用协议做无意义操作。4.3 定位全局 NAT map根据协议族状态调用nat.GlobalMaps见 pkg/maps/nat/nat.go获取全局 NAT mapfunc GlobalMaps(registry *metrics.Registry, ipv4, ipv6 bool) (ipv4Map, ipv6Map *Map) { if ipv4 { ipv4Map NewMap(registry, MapNameSnat4Global, IPv4, maxEntries()) } if ipv6 { ipv6Map NewMap(registry, MapNameSnat6Global, IPv6, maxEntries()) } return }对应两张 BPF 全局表常量定义同上文件 pkg/maps/nat/nat.go常量BPF map 名称含义MapNameSnat4Globalcilium_snat_v4_external全局 IPv4 SNAT 表MapNameSnat6Globalcilium_snat_v6_external全局 IPv6 SNAT 表map 容量由maxEntries()决定优先取配置项NATMapEntriesGlobal未配置时回退到LimitTableMax见 pkg/maps/nat/nat.go。4.4 打开 map 并逐条删除随后代码遍历这两张表存在且非 nil 才处理依次完成打开 → 清空 → 关闭for _, m : range []*nat.Map{ipv4Map, ipv6Map} { if m nil { continue } path, err : m.Path() if err nil { err m.Open() } if err ! nil { if os.IsNotExist(err) { fmt.Fprintf(os.Stderr, Unable to open %s: %s. Skipping.\n, path, err) continue } Fatalf(Unable to open %s: %s, path, err) } defer m.Close() entries : m.Flush() fmt.Printf(Flushed %d entries from %s\n, entries, path) }值得注意的容错设计若某张 map不存在如节点只启用了 IPv4IPv6 表未被创建会打印Unable to open ... Skipping.并跳过不会中断整个命令其他打开错误如权限不足则直接终止并报错。清空动作最终落到(*Map).Flush()见 pkg/maps/nat/nat.go它按协议族分派到doFlush4/doFlush6func (m *Map) Flush() int { if m.family IPv4 { return int(doFlush4(m).deleted) } return int(doFlush6(m).deleted) }而doFlush4/doFlush6的实现方式是可靠遍历DumpReliablyWithCallback整个 map对每个 key 调用DeleteLocked逐一删除见 pkg/maps/nat/nat.go并统计成功删除的条目数返回给上层打印。从实现可以看出flush是遍历 逐条删除而非一次性ClearAll式的整表重置删除过程中若个别条目删除失败会记录错误日志但不会让整个操作失败。五、与其他 NAT 调试命令的配合bpf nat是 cilium-dbg 下管理 NAT 映射表的命令组参见 cilium-dbg_bpf_nat.md 命令参考完整子命令包括子命令功能cilium-dbg bpf nat list列出所有 NAT 映射条目支持-o json\|yaml\|jsonpath输出格式参考 cilium-dbg_bpf_nat_list.mdcilium-dbg bpf nat flush清空所有 NAT 映射条目本文主题cilium-dbg bpf nat retries查看 NAT 端口分配重试的直方图统计推荐的排障顺序通常是先看cilium-dbg bpf nat list观察当前 NAT 表规模和条目内容确认是否存在异常堆积再查cilium-dbg bpf nat retries查看端口分配重试直方图判断是否出现 SNAT 端口分配冲突源码中SnatCollisionRetries 32表示端口分配最多重试 32 次见 pkg/maps/nat/nat.go最后清确认需要重置后执行cilium-dbg bpf nat flush并观察打印出的清除条目数评估数据面恢复情况。六、命令参考文档说明本命令的权威参考文档由cilium-dbg cmdref工具自动生成存放于 Documentation/cmdref/cilium-dbg_bpf_nat_flush.md。当命令实现cilium-dbg/cmd/bpf_nat_flush.go或 Cobra 定义变更时需通过update-cmdref.sh重新生成以保证 CLI 实际行为与文档严格一致。因此本文展示的命令用法、选项与继承的全局参数均与当前仓库中命令实现保持同步。总结cilium-dbg bpf nat flush用于清空节点上cilium_snat_v4_external与cilium_snat_v6_external两张全局 SNAT map必须以 root 权限执行否则命令直接退出底层通过 agent API 探测 IPv4/IPv6 启用状态再对启用协议对应的 map 执行遍历 逐条删除并汇报清除条目数对不存在的 map 具备跳过容错属于低风险、可反复执行的清理类调试操作配合bpf nat list、bpf nat retries使用可以构成完整的 NAT 数据面问题定位闭环。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cilium 数据面 NAT 表清理实战：`cilium-dbg bpf nat flush` 命令深度解析
Cilium 数据面 NAT 表清理实战cilium-dbg bpf nat flush命令深度解析【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读cilium-dbg bpf nat flush是 Cilium 提供的用于清空本地节点全部 NAT网络地址转换映射条目的调试命令。在排查 SNAT 端口耗尽、连接追踪表异常或需要让节点上的地址转换状态“归零”重来时这个命令是数据面eBPF datapath排障工具箱中的关键一环。读完本文你将掌握该命令的完整用法、权限前提、底层执行流程从 CLI 到 eBPF map 的调用链并了解它与bpf nat list、bpf nat retries等姊妹命令的协作方式。一、命令概览与适用场景该命令位于cilium-dbg调试客户端之下其完整命令层级为cilium-dbg bpf nat flush [flags]命令的功能描述为Flush all NAT mapping entries即清空所有 NAT 映射条目。它操作的对象是 Cilium 数据面中负责SNAT源地址转换的全局 NAT 表——当 Pod 流量经过节点转发到外部网络时eBPF 程序会依据这些表将 Pod 的源 IP/端口改写为节点地址。典型适用场景包括SNAT 端口分配异常当节点上全局 NAT 表积累了大量陈旧条目例如长连接中断后遗留的映射导致端口分配紧张时可以清空后让数据面重新建立映射连接追踪conntrack与 NAT 表状态不一致手动清理 NAT 表配合cilium-dbg bpf ct flush等操作恢复数据面一致性测试与验证验证 NAT 表重建能力、评估流量恢复路径。⚠️操作风险提示该命令会删除节点上所有 NAT 映射条目正在进行的连接可能因此中断后续流量需要重新建立映射。请在维护窗口或充分评估影响后执行。二、完整命令参考2.1 命令语法与专属选项cilium-dbg bpf nat flush [flags]该命令本身不接收位置参数仅有一个专属选项选项说明-h, --help显示 flush 子命令的帮助信息2.2 继承自父命令的全局选项作为cilium-dbg命令树的子命令flush会继承来自父命令cilium-dbg bpf nat→cilium-dbg bpf→cilium-dbg的全局选项选项说明--config string指定配置文件默认$HOME/.cilium.yaml-D, --debug开启调试消息输出-H, --host string指定服务端 API 的 URI用于连接 cilium-agent 的 API 端点--log-driver strings日志输出端点示例syslog--log-opt map日志驱动选项示例formatjson2.3 实际执行示例# 直接清空当前节点全部 NAT 映射条目 cilium-dbg bpf nat flush # 查看帮助 cilium-dbg bpf nat flush --help # 以调试模式执行输出更多诊断信息 cilium-dbg bpf nat flush --debug执行成功时命令会逐张表打印被清除的条目数量例如Flushed 42 entries from /sys/fs/bpf/tc/globals/cilium_snat_v4_external三、权限前提必须以 root 运行NAT 表属于内核 BPF 全局状态修改权限受严格限制。命令在入口处调用了common.RequireRootPrivilege进行校验相关实现见 pkg/common/utils.go// RequireRootPrivilege checks if the user running cmd is root. If not, it exits the program func RequireRootPrivilege(cmd string) { if os.Getuid() ! 0 { fmt.Fprintf(os.Stderr, Please run %q command(s) with root privileges.\n, cmd) os.Exit(1) } }即若当前用户不是 rootUID 不为 0程序会直接报错退出。因此请使用sudo或 root 用户执行sudo cilium-dbg bpf nat flush四、底层实现从 CLI 到 eBPF map 的完整调用链flush子命令的核心实现位于 cilium-dbg/cmd/bpf_nat_flush.go其执行流程可分为四步4.1 命令注册命令通过 Cobra 框架注册为bpf nat的子命令父命令定义见 cilium-dbg/cmd/bpf_nat.govar bpfNatFlushCmd cobra.Command{ Use: flush, Short: Flush all NAT mapping entries, Run: func(cmd *cobra.Command, args []string) { common.RequireRootPrivilege(cilium bpf nat flush) flushNat() }, } func init() { BPFNatCmd.AddCommand(bpfNatFlushCmd) }4.2 探测节点启用的 IP 协议族flushNat()首先调用getIpEnableStatuses()获取节点上 IPv4/IPv6 的启用状态实现见 cilium-dbg/cmd/helpers.go优先调用 cilium-agent 的healthz API带 5 秒超时确认 agent 存活若 agent 存活再通过ConfigGet API读取Status.Addressing.IPv4.Enabled/IPv6.Enabled字段若 agent 不可达则回退读取运行时系统配置。只有启用的协议族对应的 NAT 表才会被清空避免对未启用协议做无意义操作。4.3 定位全局 NAT map根据协议族状态调用nat.GlobalMaps见 pkg/maps/nat/nat.go获取全局 NAT mapfunc GlobalMaps(registry *metrics.Registry, ipv4, ipv6 bool) (ipv4Map, ipv6Map *Map) { if ipv4 { ipv4Map NewMap(registry, MapNameSnat4Global, IPv4, maxEntries()) } if ipv6 { ipv6Map NewMap(registry, MapNameSnat6Global, IPv6, maxEntries()) } return }对应两张 BPF 全局表常量定义同上文件 pkg/maps/nat/nat.go常量BPF map 名称含义MapNameSnat4Globalcilium_snat_v4_external全局 IPv4 SNAT 表MapNameSnat6Globalcilium_snat_v6_external全局 IPv6 SNAT 表map 容量由maxEntries()决定优先取配置项NATMapEntriesGlobal未配置时回退到LimitTableMax见 pkg/maps/nat/nat.go。4.4 打开 map 并逐条删除随后代码遍历这两张表存在且非 nil 才处理依次完成打开 → 清空 → 关闭for _, m : range []*nat.Map{ipv4Map, ipv6Map} { if m nil { continue } path, err : m.Path() if err nil { err m.Open() } if err ! nil { if os.IsNotExist(err) { fmt.Fprintf(os.Stderr, Unable to open %s: %s. Skipping.\n, path, err) continue } Fatalf(Unable to open %s: %s, path, err) } defer m.Close() entries : m.Flush() fmt.Printf(Flushed %d entries from %s\n, entries, path) }值得注意的容错设计若某张 map不存在如节点只启用了 IPv4IPv6 表未被创建会打印Unable to open ... Skipping.并跳过不会中断整个命令其他打开错误如权限不足则直接终止并报错。清空动作最终落到(*Map).Flush()见 pkg/maps/nat/nat.go它按协议族分派到doFlush4/doFlush6func (m *Map) Flush() int { if m.family IPv4 { return int(doFlush4(m).deleted) } return int(doFlush6(m).deleted) }而doFlush4/doFlush6的实现方式是可靠遍历DumpReliablyWithCallback整个 map对每个 key 调用DeleteLocked逐一删除见 pkg/maps/nat/nat.go并统计成功删除的条目数返回给上层打印。从实现可以看出flush是遍历 逐条删除而非一次性ClearAll式的整表重置删除过程中若个别条目删除失败会记录错误日志但不会让整个操作失败。五、与其他 NAT 调试命令的配合bpf nat是 cilium-dbg 下管理 NAT 映射表的命令组参见 cilium-dbg_bpf_nat.md 命令参考完整子命令包括子命令功能cilium-dbg bpf nat list列出所有 NAT 映射条目支持-o json\|yaml\|jsonpath输出格式参考 cilium-dbg_bpf_nat_list.mdcilium-dbg bpf nat flush清空所有 NAT 映射条目本文主题cilium-dbg bpf nat retries查看 NAT 端口分配重试的直方图统计推荐的排障顺序通常是先看cilium-dbg bpf nat list观察当前 NAT 表规模和条目内容确认是否存在异常堆积再查cilium-dbg bpf nat retries查看端口分配重试直方图判断是否出现 SNAT 端口分配冲突源码中SnatCollisionRetries 32表示端口分配最多重试 32 次见 pkg/maps/nat/nat.go最后清确认需要重置后执行cilium-dbg bpf nat flush并观察打印出的清除条目数评估数据面恢复情况。六、命令参考文档说明本命令的权威参考文档由cilium-dbg cmdref工具自动生成存放于 Documentation/cmdref/cilium-dbg_bpf_nat_flush.md。当命令实现cilium-dbg/cmd/bpf_nat_flush.go或 Cobra 定义变更时需通过update-cmdref.sh重新生成以保证 CLI 实际行为与文档严格一致。因此本文展示的命令用法、选项与继承的全局参数均与当前仓库中命令实现保持同步。总结cilium-dbg bpf nat flush用于清空节点上cilium_snat_v4_external与cilium_snat_v6_external两张全局 SNAT map必须以 root 权限执行否则命令直接退出底层通过 agent API 探测 IPv4/IPv6 启用状态再对启用协议对应的 map 执行遍历 逐条删除并汇报清除条目数对不存在的 map 具备跳过容错属于低风险、可反复执行的清理类调试操作配合bpf nat list、bpf nat retries使用可以构成完整的 NAT 数据面问题定位闭环。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考