Cilium 带宽管理排查指南cilium-dbg bpf bandwidth list 命令详解与 BPF 实现原理【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/ciliumcilium-dbg bpf bandwidth list是 Cilium 提供的一个诊断命令用于直接读取内核中的cilium_throttleeBPF map查看每个端点Endpoint当前的带宽限速Bandwidth Limit、优先级Prio与方向Direction配置。它是运维人员在排查 Pod 带宽限速不生效、验证带宽注解是否写入数据面、以及检查带宽管理器状态时的第一手工具。读完本文你将掌握该命令的完整语法、输出格式的精确含义并理解其背后的 EDTEarliest Departure Time最早离开时间带宽整形原理与底层 map 结构。一、命令背景Cilium 带宽管理器与cilium_throttlemapCilium 的带宽管理基于 eBPF 实现采用内核的EDTEarliest Departure Time算法配合 FQFair Queueingqdisc 对每个 Pod 进行流量整形。该功能由--enable-bandwidth-manager标志控制定义于 pkg/datapath/linux/bandwidth/types/config.go默认关闭。当带宽管理器启用后Cilium 会在内核中创建一个名为cilium_throttle的 BPF map用于保存每个端点的带宽整形参数。该 map 的 Go 侧定义位于 pkg/maps/bwmap/bwmap.goconst ( MapName cilium_throttle // Flow aggregate is per Pod, so same size as Endpoint map. MapSize lxcmap.MaxEntries // DefaultDropHorizon represents maximum allowed departure // time delta in future. DefaultDropHorizon 2 * time.Second )map 的 key 为EdtId包含端点 IDid与方向directionvalue 为EdtInfo包含带宽Bps、上次调度时间t_last、丢弃/令牌时间$union0以及优先级prio。从结构体定义可以看出限速参数以「每秒字节数」Bytes/s为单位存储而命令输出时则会换算成「每秒比特数」bits/s。在较新版本的 Cilium 中带宽管理逻辑由 Hive cell 管理见 pkg/maps/bwmap/cell.go用户态的statedb表bandwidth-edtsRWTable[Edt]作为数据源通过 reconciler 将条目同步到cilium_throttleBPF map。因此cilium-dbg bpf bandwidth list读取到的内容正是这份已同步到内核的最终生效配置。二、命令语法与全局选项命令完整用法如下cilium-dbg bpf bandwidth list [flags]该命令属于cilium-dbg bpf bandwidth子命令组父命令组摘要为 “BPF datapath bandwidth settings”BPF 数据面带宽设置父命令定义见 cilium-dbg/cmd/bpf_bandwidth.go。完整命令层级为cilium-dbg bpf bandwidth list其中cilium-dbg bpf提供对本地 BPF map 的直接访问Direct access to local BPF maps。全局/继承选项该命令从父命令链中继承以下选项选项说明--config string配置文件路径默认$HOME/.cilium.yaml-D, --debug启用调试信息输出-H, --host string连接 server 端 API 的 URI--log-driver strings日志输出端点例如syslog--log-opt map日志驱动选项例如formatjson三、本命令选项输出格式控制list子命令自身支持两个选项-h, --help help for list -o, --output string json| yaml| jsonpath{}其中-o, --output用于切换输出格式支持三种取值json以 JSON 对象输出整个 map 内容外层 key 为 map 的复合 key 字符串yaml以 YAML 格式输出jsonpath{}按给定的 JSONPath 表达式提取字段输出。不指定-o时默认以人类可读的表格形式打印见下文第四节。该选项由command.AddOutputOption(bpfBandwidthListCmd)注入见 cilium-dbg/cmd/bpf_bandwidth_list.go。四、默认输出格式与列含义不带-o参数运行时命令输出一张四列表格表头由源码中的常量定义const ( labelsIDTitle IDENTITY labelsBandwidth BANDWIDTH (BitsPerSec) labelsPrio PRIO labelsDirection DIRECTION )示例输出表格经过 tabwriter 对齐IDENTITY DIRECTION PRIO BANDWIDTH (BitsPerSec) 10 Egress 7 1M 10 Ingress 0 5M各列含义如下列含义取值说明IDENTITY端点 IDEndpoint IDmap key 的第一部分即EdtId.IdDIRECTION流量方向Egress出向默认或Ingress入向PRIO优先级出向条目显示prio值入向条目恒为 0入向不做优先级分类BANDWIDTH (BitsPerSec)带宽限速以resource.Quantity格式化的人类可读速率如1M、500k实际单位是 bit/s输出按四列依次字典序排序见 cilium-dbg/cmd/bpf_bandwidth_list.go保证多次执行结果稳定便于 diff 对比。方向DIRECTION的判定逻辑map key 的第二个字段direction以整数存储0表示 Egress、1表示 Ingress。这与数据面 pkg/datapath/linux/bandwidth/bandwidth.go 中的常量保持一致const ( DirectionEgress uint8 0 DirectionIngress uint8 1 )命令实现中默认按 Egress 处理仅在direction 1时显示为 Ingress。带宽数值的换算map 中存储的Bps是每秒字节数Bytes/s而命令输出前会执行bps * 8换算为bits/s再通过resource.NewQuantity格式化为可读量如1M 1,000,000 bit/s。这一点与带宽注解的配置口径一致——Kubernetes Pod 的带宽注解kubernetes.io/egress-bandwidth/kubernetes.io/ingress-bandwidth本身就是以 bit/s 为单位声明的。优先级PRIO与 QoS 映射出向条目的PRIO来自 Cilium 的 QoS 优先级映射。源码中为不同 Kubernetes QoS 等级定义了默认优先级见 pkg/datapath/linux/bandwidth/bandwidth.go// GuaranteedQoSDefaultPriority prio value to classify packets to high prio band GuaranteedQoSDefaultPriority 6 1 // BurstableQoSDefaultPriority prio value to classify packets to medium prio band BurstableQoSDefaultPriority 8 1 // BestEffortQoSDefaultPriority prio value to classify packets to medium prio band BestEffortQoSDefaultPriority 5 1这些值映射到 FQ qdisc 的高/中/低优先级 band从而实现基于 QoS 等级的出向流量分级调度。五、输出格式json / yaml下的数据结构使用-o json时输出的是 Go map 的序列化结果外层 key 为endpointID,direction形式的复合字符串例如10,0value 为长度 2 的字符串数组[bps, prio, ...]其构成来自EdtInfo.String()10,0: [1000000, 7]其含义为端点 10、Egress 方向限速约 1,000,000 Bytes/s、优先级 7。yaml 输出结构与之等价。注意json/yaml 输出中的带宽值是 map 原始字节数Bytes/s与默认表格输出的 bit/s 口径不同做脚本解析时需区分。六、底层实现命令如何读取 BPF maplist子命令的完整执行流程见 cilium-dbg/cmd/bpf_bandwidth_list.go可分为四步权限检查调用common.RequireRootPrivilege(cilium bpf bandwidth list)访问 BPF map 需要 root 权限打开 map调用bwmap.ThrottleMap(slog.Default())其内部通过bpf.OpenMap(bpf.MapPath(logger, MapName), EdtId{}, EdtInfo{})打开已初始化pin 在 BPF 文件系统中的cilium_throttlemap见 pkg/maps/bwmap/bwmap.goDump 内容throttleMap.Dump(bpfBandwidthList)将 map 中所有 key/value 读取到内存格式化输出根据是否指定--output走command.PrintOutputjson/yaml/jsonpath或listBandwidth表格。带宽管理器未启用时的行为如果内核中不存在cilium_throttlemap即带宽管理器未启用打开 map 时会返回fs.ErrNotExist命令输出错误并退出bandwidth manager not enabled这与 pkg/maps/bwmap/cell.go 中的生命周期逻辑一致当cfg.EnableBandwidthManager为 false 时Hive cell 会主动bpf.Remove掉 map 的 pin 文件。因此看到该报错即表明--enable-bandwidth-manager未开启属于预期行为而非命令故障。若 map 存在但为空没有任何端点的限速配置则输出No entries found.。七、实战排查场景场景一确认带宽注解是否写入数据面当为 Pod 添加了kubernetes.io/egress-bandwidth: 1M注解后可通过该命令确认配置是否真正同步到内核 BPF mapcilium-dbg bpf bandwidth list # IDENTITY DIRECTION PRIO BANDWIDTH (BitsPerSec) # 1234 Egress 7 1M若在注解生效后列表中仍无对应端点的条目需要进一步检查代理agent是否以--enable-bandwidth-managertrue启动节点内核与网卡是否支持 EDT/FQ不满足时带宽管理器会静默降级参见 pkg/datapath/linux/bandwidth/ops.go 中的 probe 逻辑端点是否为 host 端点host 端点会以 Guaranteed QoS 优先级做一次性设置见 pkg/datapath/linux/bandwidth/bandwidth.go 中ensureHostEndpointQoS的惰性初始化。场景二核对入向限速入向限速kubernetes.io/ingress-bandwidth的条目以DIRECTIONIngress出现且PRIO恒为 0——入向路径不做 QoS 优先级分类见 pkg/maps/bwmap/table.go 中BinaryValue对 Ingress 方向只写TimeHorizonDropOrTokens 0的处理。场景三脚本化采集批量采集所有端点的限速配置时可使用 JSON 输出配合 jq 处理cilium-dbg bpf bandwidth list -o json注意解析时带宽字段为 Bytes/s如需与注解的 bit/s 口径对齐需乘以 8。八、进阶从 user-space 侧查看同一份数据除直接读取 BPF map 外还可以通过 Cilium 的 StateDB 交互式 shell 查看带宽管理器的用户态数据源即 reconciler 的输入表cilium-dbg shell -- db/show bandwidth-edts该表定义于 pkg/maps/bwmap/table.go条目Edt包含EndpointID、Direction、BytesPerSecond、Prio、TimeHorizonDrop以及 reconciler 的同步Status字段。相比 BPF map这张表额外提供了同步状态Status可用于判断某条限速配置是否已成功下发到内核。表内带宽同样以 bit/sBitsPerSecond口径展示与注解配置一致见TableRow中的BytesPerSecond*8换算。这也是官方建议的两条排查路径bpf bandwidth list看内核最终状态db/show bandwidth-edts看用户态声明与同步状态二者结合即可完整定位带宽配置的整个下发链路。九、相关命令与文档cilium-dbg bpf bandwidthbandwidth 子命令组包含list子命令cilium-dbg bpfbpf命令组提供对所有本地 BPF map 的直接访问如ct、lb、nat、policy等带宽管理的 Hive 模块与 map 生命周期pkg/maps/bwmap/cell.gomap key/value 结构定义pkg/maps/bwmap/bwmap.go带宽注解与 QoS 优先级映射pkg/datapath/linux/bandwidth/bandwidth.goStateDB 用户态表定义pkg/maps/bwmap/table.go。总结cilium-dbg bpf bandwidth list是一个轻量但信息量极高的诊断命令它直接暴露cilium_throttleBPF map 中每个端点的 EDT 整形参数方向、优先级、带宽限速配合-o json/yaml可无缝接入自动化巡检脚本。理解它的输出列、单位换算规则以及“带宽管理器未启用”报错的成因能帮助你快速区分「注解未生效」「带宽管理器未开启」「配置未同步到内核」三类常见问题是 Cilium 带宽管理排障链路中不可或缺的一环。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cilium 带宽管理排查指南：cilium-dbg bpf bandwidth list 命令详解与 BPF 实现原理
Cilium 带宽管理排查指南cilium-dbg bpf bandwidth list 命令详解与 BPF 实现原理【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/ciliumcilium-dbg bpf bandwidth list是 Cilium 提供的一个诊断命令用于直接读取内核中的cilium_throttleeBPF map查看每个端点Endpoint当前的带宽限速Bandwidth Limit、优先级Prio与方向Direction配置。它是运维人员在排查 Pod 带宽限速不生效、验证带宽注解是否写入数据面、以及检查带宽管理器状态时的第一手工具。读完本文你将掌握该命令的完整语法、输出格式的精确含义并理解其背后的 EDTEarliest Departure Time最早离开时间带宽整形原理与底层 map 结构。一、命令背景Cilium 带宽管理器与cilium_throttlemapCilium 的带宽管理基于 eBPF 实现采用内核的EDTEarliest Departure Time算法配合 FQFair Queueingqdisc 对每个 Pod 进行流量整形。该功能由--enable-bandwidth-manager标志控制定义于 pkg/datapath/linux/bandwidth/types/config.go默认关闭。当带宽管理器启用后Cilium 会在内核中创建一个名为cilium_throttle的 BPF map用于保存每个端点的带宽整形参数。该 map 的 Go 侧定义位于 pkg/maps/bwmap/bwmap.goconst ( MapName cilium_throttle // Flow aggregate is per Pod, so same size as Endpoint map. MapSize lxcmap.MaxEntries // DefaultDropHorizon represents maximum allowed departure // time delta in future. DefaultDropHorizon 2 * time.Second )map 的 key 为EdtId包含端点 IDid与方向directionvalue 为EdtInfo包含带宽Bps、上次调度时间t_last、丢弃/令牌时间$union0以及优先级prio。从结构体定义可以看出限速参数以「每秒字节数」Bytes/s为单位存储而命令输出时则会换算成「每秒比特数」bits/s。在较新版本的 Cilium 中带宽管理逻辑由 Hive cell 管理见 pkg/maps/bwmap/cell.go用户态的statedb表bandwidth-edtsRWTable[Edt]作为数据源通过 reconciler 将条目同步到cilium_throttleBPF map。因此cilium-dbg bpf bandwidth list读取到的内容正是这份已同步到内核的最终生效配置。二、命令语法与全局选项命令完整用法如下cilium-dbg bpf bandwidth list [flags]该命令属于cilium-dbg bpf bandwidth子命令组父命令组摘要为 “BPF datapath bandwidth settings”BPF 数据面带宽设置父命令定义见 cilium-dbg/cmd/bpf_bandwidth.go。完整命令层级为cilium-dbg bpf bandwidth list其中cilium-dbg bpf提供对本地 BPF map 的直接访问Direct access to local BPF maps。全局/继承选项该命令从父命令链中继承以下选项选项说明--config string配置文件路径默认$HOME/.cilium.yaml-D, --debug启用调试信息输出-H, --host string连接 server 端 API 的 URI--log-driver strings日志输出端点例如syslog--log-opt map日志驱动选项例如formatjson三、本命令选项输出格式控制list子命令自身支持两个选项-h, --help help for list -o, --output string json| yaml| jsonpath{}其中-o, --output用于切换输出格式支持三种取值json以 JSON 对象输出整个 map 内容外层 key 为 map 的复合 key 字符串yaml以 YAML 格式输出jsonpath{}按给定的 JSONPath 表达式提取字段输出。不指定-o时默认以人类可读的表格形式打印见下文第四节。该选项由command.AddOutputOption(bpfBandwidthListCmd)注入见 cilium-dbg/cmd/bpf_bandwidth_list.go。四、默认输出格式与列含义不带-o参数运行时命令输出一张四列表格表头由源码中的常量定义const ( labelsIDTitle IDENTITY labelsBandwidth BANDWIDTH (BitsPerSec) labelsPrio PRIO labelsDirection DIRECTION )示例输出表格经过 tabwriter 对齐IDENTITY DIRECTION PRIO BANDWIDTH (BitsPerSec) 10 Egress 7 1M 10 Ingress 0 5M各列含义如下列含义取值说明IDENTITY端点 IDEndpoint IDmap key 的第一部分即EdtId.IdDIRECTION流量方向Egress出向默认或Ingress入向PRIO优先级出向条目显示prio值入向条目恒为 0入向不做优先级分类BANDWIDTH (BitsPerSec)带宽限速以resource.Quantity格式化的人类可读速率如1M、500k实际单位是 bit/s输出按四列依次字典序排序见 cilium-dbg/cmd/bpf_bandwidth_list.go保证多次执行结果稳定便于 diff 对比。方向DIRECTION的判定逻辑map key 的第二个字段direction以整数存储0表示 Egress、1表示 Ingress。这与数据面 pkg/datapath/linux/bandwidth/bandwidth.go 中的常量保持一致const ( DirectionEgress uint8 0 DirectionIngress uint8 1 )命令实现中默认按 Egress 处理仅在direction 1时显示为 Ingress。带宽数值的换算map 中存储的Bps是每秒字节数Bytes/s而命令输出前会执行bps * 8换算为bits/s再通过resource.NewQuantity格式化为可读量如1M 1,000,000 bit/s。这一点与带宽注解的配置口径一致——Kubernetes Pod 的带宽注解kubernetes.io/egress-bandwidth/kubernetes.io/ingress-bandwidth本身就是以 bit/s 为单位声明的。优先级PRIO与 QoS 映射出向条目的PRIO来自 Cilium 的 QoS 优先级映射。源码中为不同 Kubernetes QoS 等级定义了默认优先级见 pkg/datapath/linux/bandwidth/bandwidth.go// GuaranteedQoSDefaultPriority prio value to classify packets to high prio band GuaranteedQoSDefaultPriority 6 1 // BurstableQoSDefaultPriority prio value to classify packets to medium prio band BurstableQoSDefaultPriority 8 1 // BestEffortQoSDefaultPriority prio value to classify packets to medium prio band BestEffortQoSDefaultPriority 5 1这些值映射到 FQ qdisc 的高/中/低优先级 band从而实现基于 QoS 等级的出向流量分级调度。五、输出格式json / yaml下的数据结构使用-o json时输出的是 Go map 的序列化结果外层 key 为endpointID,direction形式的复合字符串例如10,0value 为长度 2 的字符串数组[bps, prio, ...]其构成来自EdtInfo.String()10,0: [1000000, 7]其含义为端点 10、Egress 方向限速约 1,000,000 Bytes/s、优先级 7。yaml 输出结构与之等价。注意json/yaml 输出中的带宽值是 map 原始字节数Bytes/s与默认表格输出的 bit/s 口径不同做脚本解析时需区分。六、底层实现命令如何读取 BPF maplist子命令的完整执行流程见 cilium-dbg/cmd/bpf_bandwidth_list.go可分为四步权限检查调用common.RequireRootPrivilege(cilium bpf bandwidth list)访问 BPF map 需要 root 权限打开 map调用bwmap.ThrottleMap(slog.Default())其内部通过bpf.OpenMap(bpf.MapPath(logger, MapName), EdtId{}, EdtInfo{})打开已初始化pin 在 BPF 文件系统中的cilium_throttlemap见 pkg/maps/bwmap/bwmap.goDump 内容throttleMap.Dump(bpfBandwidthList)将 map 中所有 key/value 读取到内存格式化输出根据是否指定--output走command.PrintOutputjson/yaml/jsonpath或listBandwidth表格。带宽管理器未启用时的行为如果内核中不存在cilium_throttlemap即带宽管理器未启用打开 map 时会返回fs.ErrNotExist命令输出错误并退出bandwidth manager not enabled这与 pkg/maps/bwmap/cell.go 中的生命周期逻辑一致当cfg.EnableBandwidthManager为 false 时Hive cell 会主动bpf.Remove掉 map 的 pin 文件。因此看到该报错即表明--enable-bandwidth-manager未开启属于预期行为而非命令故障。若 map 存在但为空没有任何端点的限速配置则输出No entries found.。七、实战排查场景场景一确认带宽注解是否写入数据面当为 Pod 添加了kubernetes.io/egress-bandwidth: 1M注解后可通过该命令确认配置是否真正同步到内核 BPF mapcilium-dbg bpf bandwidth list # IDENTITY DIRECTION PRIO BANDWIDTH (BitsPerSec) # 1234 Egress 7 1M若在注解生效后列表中仍无对应端点的条目需要进一步检查代理agent是否以--enable-bandwidth-managertrue启动节点内核与网卡是否支持 EDT/FQ不满足时带宽管理器会静默降级参见 pkg/datapath/linux/bandwidth/ops.go 中的 probe 逻辑端点是否为 host 端点host 端点会以 Guaranteed QoS 优先级做一次性设置见 pkg/datapath/linux/bandwidth/bandwidth.go 中ensureHostEndpointQoS的惰性初始化。场景二核对入向限速入向限速kubernetes.io/ingress-bandwidth的条目以DIRECTIONIngress出现且PRIO恒为 0——入向路径不做 QoS 优先级分类见 pkg/maps/bwmap/table.go 中BinaryValue对 Ingress 方向只写TimeHorizonDropOrTokens 0的处理。场景三脚本化采集批量采集所有端点的限速配置时可使用 JSON 输出配合 jq 处理cilium-dbg bpf bandwidth list -o json注意解析时带宽字段为 Bytes/s如需与注解的 bit/s 口径对齐需乘以 8。八、进阶从 user-space 侧查看同一份数据除直接读取 BPF map 外还可以通过 Cilium 的 StateDB 交互式 shell 查看带宽管理器的用户态数据源即 reconciler 的输入表cilium-dbg shell -- db/show bandwidth-edts该表定义于 pkg/maps/bwmap/table.go条目Edt包含EndpointID、Direction、BytesPerSecond、Prio、TimeHorizonDrop以及 reconciler 的同步Status字段。相比 BPF map这张表额外提供了同步状态Status可用于判断某条限速配置是否已成功下发到内核。表内带宽同样以 bit/sBitsPerSecond口径展示与注解配置一致见TableRow中的BytesPerSecond*8换算。这也是官方建议的两条排查路径bpf bandwidth list看内核最终状态db/show bandwidth-edts看用户态声明与同步状态二者结合即可完整定位带宽配置的整个下发链路。九、相关命令与文档cilium-dbg bpf bandwidthbandwidth 子命令组包含list子命令cilium-dbg bpfbpf命令组提供对所有本地 BPF map 的直接访问如ct、lb、nat、policy等带宽管理的 Hive 模块与 map 生命周期pkg/maps/bwmap/cell.gomap key/value 结构定义pkg/maps/bwmap/bwmap.go带宽注解与 QoS 优先级映射pkg/datapath/linux/bandwidth/bandwidth.goStateDB 用户态表定义pkg/maps/bwmap/table.go。总结cilium-dbg bpf bandwidth list是一个轻量但信息量极高的诊断命令它直接暴露cilium_throttleBPF map 中每个端点的 EDT 整形参数方向、优先级、带宽限速配合-o json/yaml可无缝接入自动化巡检脚本。理解它的输出列、单位换算规则以及“带宽管理器未启用”报错的成因能帮助你快速区分「注解未生效」「带宽管理器未开启」「配置未同步到内核」三类常见问题是 Cilium 带宽管理排障链路中不可或缺的一环。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考