2026/9/12 17:46:26
FEATURED · 精选文章 
Cilium 的 cgroup 元数据排查cilium-dbg cgroups list 命令完全指南【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本文聚焦 Cilium 的cilium-dbg cgroups list命令它是运维和开发人员排查 Cilium 与 Kubernetes Pod/容器 cgroup 关联关系时的核心诊断工具。通过本文你将掌握该命令的完整语法、全部输出选项、底层数据模型POD NAME / POD NAMESPACE / CGROUP IDS并理解其从命令行到 Daemon API、再到 cgroup 管理器的事件驱动架构的完整调用链能够在实际集群中快速定位 Pod 与 cgroup ID 的映射关系。命令概览cgroups 子命令家族cilium-dbg是 Cilium 在节点上用于与本地 cilium-agent 交互的诊断 CLI。cgroups是其下的一个子命令族用于展示 Cilium 维护的 cgroup 元数据父命令cilium-dbg cgroups短描述为 Cgroup metadata见 cilium-dbg/cmd/cgroups.go子命令list别名ls短描述为 Display cgroup metadata maintained by Cilium在源码中父命令通过RootCmd.AddCommand(CgroupsCmd)挂载到根命令下而list子命令通过CgroupsCmd.AddCommand(cgroupsListCmd)注册并声明了别名ls因此cilium-dbg cgroups ls与cilium-dbg cgroups list完全等价见 cilium-dbg/cmd/cgroups_list.go。命令语法与输出选项基本语法cilium-dbg cgroups list [flags]该命令不带任何位置参数运行后向本机 cilium-agent 的 Daemon API 发起一次查询将返回的 cgroup 元数据以表格形式打印到标准输出。list 专属选项选项说明-h, --help显示list子命令的帮助信息--no-headers不打印表格头POD NAME / POD NAMESPACE / CGROUP IDS-o, --output string指定输出格式可选json、yaml或jsonpath{}其中--no-headers在源码中通过cgroupsListCmd.Flags().BoolVar(cgroupsListNoHeaders, no-headers, false, Do not print headers)注册默认值为false-o/--output则由command.AddOutputOption(cgroupsListCmd)统一注入见 cilium-dbg/cmd/cgroups_list.go。继承自父命令的全局选项选项说明--config string配置文件路径默认$HOME/.cilium.yaml-D, --debug开启调试消息-H, --host string服务端 API 的 URI 地址--log-driver strings日志输出端点例如syslog--log-opt map日志驱动选项例如formatjson默认表格输出解读在未指定-o/--output时命令通过 Go 标准库的tabwritertabwriter.NewWriter(os.Stdout, 5, 0, 3, , 0)格式化输出三列表格POD NAME POD NAMESPACE CGROUP IDSPOD NAMEPod 名称POD NAMESPACEPod 所在命名空间CGROUP IDS该 Pod 下容器对应的 cgroup ID值得注意的细节一个 Pod 可能包含多个容器如业务容器 Sidecar。源码中的打印逻辑见 cilium-dbg/cmd/cgroups_list.go规定每个 Pod 的第一个容器会同时打印 Pod 名称与命名空间而后续容器只打印 cgroup ID行首位置留空用缩进表示这些 cgroup ID 属于同一 Pod。这种紧凑布局便于一眼看出一个 Pod 下挂了几个 cgroup。JSON / YAML / jsonpath 结构化输出当需要脚本化处理或精确提取字段时使用-o/--output切换输出格式# 输出 JSON cilium-dbg cgroups list -o json # 输出 YAML cilium-dbg cgroups list -o yaml # 使用 jsonpath 提取所有 cgroup ID cilium-dbg cgroups list -o jsonpath{.items[*].cgroup-id}结构化输出对应的是 api/v1/models/cgroup_pod_metadata.go 中定义的CgroupPodMetadata对象列表其字段如下字段JSON 键说明namenamePod 名称namespacenamespacePod 命名空间ipsipsPod 关联的 IP 列表containerscontainers容器元数据列表每个容器对象见 api/v1/models/cgroup_container_metadata.go又包含字段JSON 键说明cgroup-idcgroup-idcgroup IDuint64cgroup-pathcgroup-pathcgroup 路径值得注意的是默认表格输出只展示name、namespace和cgroup-id三列而Pod 的 IP 列表与 cgroup 路径字段在表格模式下不会显示只有切换到json/yaml等结构化输出才能看到完整数据。底层调用链从 CLI 到 Daemon API1. CLI 侧发起 HTTP 请求listCgroups()函数见 cilium-dbg/cmd/cgroups_list.go通过 swagger 生成的客户端调用resp, err : client.Daemon.GetCgroupDumpMetadata(daemon.NewGetCgroupDumpMetadataParams())即向 cilium-agent 的 Daemon API 发起GET /cgroup-dump-metadata请求。请求失败时错误信息会经过pkg.Hint(err)处理附加排障提示后写入 stderr 并以退出码 1 结束。2. API 契约Swagger 定义的响应模型该端点由 api/v1/openapi.yaml 定义成功返回 HTTP 200响应体为CgroupDumpMetadata见 api/v1/models/cgroup_dump_metadata.go其唯一字段是pod-metadatas即[]*CgroupPodMetadata列表失败时返回 HTTP 500见 api/v1/server/restapi/daemon/get_cgroup_dump_metadata_responses.go。对应的服务端路由处理器注册在 api/v1/server/restapi/daemon/get_cgroup_dump_metadata.goswagger 注解为GET /cgroup-dump-metadata daemon getCgroupDumpMetadata。3. Daemon 侧cgroup 管理器的事件驱动实现在 cilium-agent 内部该端点的真正实现位于 cgroups manager 模块。入口注册于 pkg/cgroups/manager/cell.gocell.Provide(newGetCgroupDumpMetadataRestApiHandler),核心逻辑集中在 pkg/cgroups/manager/manager.goDumpPodMetadata()第 150 行向 manager 的单协程事件循环投递podDumpMetadataEvent事件事件循环第 243 行起处理该事件并调用dumpPodMetadata()第 416 行收集全部FullPodMetadata此外 manager 还维护podGetMetadataEvent单容器查询供GetPodMetadataForContainer使用以及通过 watch Kubernetes Pod 对象触发的updatePodMetadata/replacePodMetadata/deletePodMetadata事件第 257-390 行保证元数据随 Pod 生命周期实时更新。也就是说cilium-dbg cgroups list输出的数据并非实时扫描 cgroup 文件系统而是读取 cilium-agent 内由事件驱动维护的 Pod→cgroup 元数据缓存快照。DumpPodMetadata与GetPodMetadataForContainer也是 Cilium 中按 cgroup 归属 Pod 元数据的关键入口是理解 Cilium 如何将 cgroup 事件如 socket 层 hook映射回 Pod 身份的核心。4. cgroup 文件系统前提Cilium 依赖 cgroup v2 提供相关能力。cilium-agent 启动时通过--cgroup-root配置项option.CGroupRoot描述为 Path to Cgroup2 filesystem见 daemon/cmd/daemon_main.go指定 cgroup2 挂载点并在初始化阶段调用cgroups.CheckOrMountCgrpFS(logger, option.Config.CGroupRoot)见 daemon/cmd/daemon_main.go确认或挂载 cgroup2 文件系统。若节点未正确挂载 cgroup2cgroup 元数据的维护与查询将无法正常工作。实战示例诊断 Pod 与 cgroup 的映射场景一查看默认表格输出$ cilium-dbg cgroups list POD NAME POD NAMESPACE CGROUP IDS my-app-6b9f4d5c7f-2xk9z default 123456 123457上例说明default命名空间下的my-app-6b9f4d5c7f-2xk9zPod 包含两个容器分别对应 cgroup ID123456与123457第二个容器行首无 Pod 信息表示与上一行同属一个 Pod。场景二脚本化获取 JSON$ cilium-dbg cgroups list -o json [ { name: my-app-6b9f4d5c7f-2xk9z, namespace: default, ips: [10.0.1.42], containers: [ {cgroup-id: 123456, cgroup-path: /kubepods/burstable/podxxx/abc} ] } ]此时可以同时看到表格模式缺失的ips与cgroup-path字段。场景三隐藏表头便于粘贴$ cilium-dbg cgroups list --no-headers my-app-6b9f4d5c7f-2xk9z default 123456常见问题与排障提示返回空结果cgroup 元数据由 cilium-agent 通过 watch Kubernetes Pod 维护若 agent 尚未同步完成、未启用相关能力或节点无 Pod 运行列表可能为空此时可结合cilium-dbg status检查 agent 与 Kubernetes 的连通性。Unable to retrieve cgroups metadata当 Daemon API 返回的 payload 为 nil 时见 cilium-dbg/cmd/cgroups_list.go命令会输出该提示并以退出码 1 结束通常是 agent 侧 cgroup 模块未初始化或 API 异常。cgroup v2 依赖确保 cilium-agent 的--cgroup-root指向正确的 cgroup2 挂载点相关初始化逻辑见 daemon/cmd/daemon_main.go。远程执行通过-H指定 Daemon API 的 URI 可对远程 agent 执行查询配合--config指定配置文件可覆盖默认的$HOME/.cilium.yaml。延伸阅读父命令参考页cilium-dbg cgroupsCLI 源码实现cilium-dbg/cmd/cgroups_list.gocgroup 管理器实现pkg/cgroups/manager/manager.goAPI 数据模型api/v1/models/cgroup_dump_metadata.go、api/v1/models/cgroup_pod_metadata.go、api/v1/models/cgroup_container_metadata.gocilium-dbg 全部命令参考Documentation/cmdref/cilium-dbg.md【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cilium 的 cgroup 元数据排查：cilium-dbg cgroups list 命令完全指南
Cilium 的 cgroup 元数据排查cilium-dbg cgroups list 命令完全指南【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本文聚焦 Cilium 的cilium-dbg cgroups list命令它是运维和开发人员排查 Cilium 与 Kubernetes Pod/容器 cgroup 关联关系时的核心诊断工具。通过本文你将掌握该命令的完整语法、全部输出选项、底层数据模型POD NAME / POD NAMESPACE / CGROUP IDS并理解其从命令行到 Daemon API、再到 cgroup 管理器的事件驱动架构的完整调用链能够在实际集群中快速定位 Pod 与 cgroup ID 的映射关系。命令概览cgroups 子命令家族cilium-dbg是 Cilium 在节点上用于与本地 cilium-agent 交互的诊断 CLI。cgroups是其下的一个子命令族用于展示 Cilium 维护的 cgroup 元数据父命令cilium-dbg cgroups短描述为 Cgroup metadata见 cilium-dbg/cmd/cgroups.go子命令list别名ls短描述为 Display cgroup metadata maintained by Cilium在源码中父命令通过RootCmd.AddCommand(CgroupsCmd)挂载到根命令下而list子命令通过CgroupsCmd.AddCommand(cgroupsListCmd)注册并声明了别名ls因此cilium-dbg cgroups ls与cilium-dbg cgroups list完全等价见 cilium-dbg/cmd/cgroups_list.go。命令语法与输出选项基本语法cilium-dbg cgroups list [flags]该命令不带任何位置参数运行后向本机 cilium-agent 的 Daemon API 发起一次查询将返回的 cgroup 元数据以表格形式打印到标准输出。list 专属选项选项说明-h, --help显示list子命令的帮助信息--no-headers不打印表格头POD NAME / POD NAMESPACE / CGROUP IDS-o, --output string指定输出格式可选json、yaml或jsonpath{}其中--no-headers在源码中通过cgroupsListCmd.Flags().BoolVar(cgroupsListNoHeaders, no-headers, false, Do not print headers)注册默认值为false-o/--output则由command.AddOutputOption(cgroupsListCmd)统一注入见 cilium-dbg/cmd/cgroups_list.go。继承自父命令的全局选项选项说明--config string配置文件路径默认$HOME/.cilium.yaml-D, --debug开启调试消息-H, --host string服务端 API 的 URI 地址--log-driver strings日志输出端点例如syslog--log-opt map日志驱动选项例如formatjson默认表格输出解读在未指定-o/--output时命令通过 Go 标准库的tabwritertabwriter.NewWriter(os.Stdout, 5, 0, 3, , 0)格式化输出三列表格POD NAME POD NAMESPACE CGROUP IDSPOD NAMEPod 名称POD NAMESPACEPod 所在命名空间CGROUP IDS该 Pod 下容器对应的 cgroup ID值得注意的细节一个 Pod 可能包含多个容器如业务容器 Sidecar。源码中的打印逻辑见 cilium-dbg/cmd/cgroups_list.go规定每个 Pod 的第一个容器会同时打印 Pod 名称与命名空间而后续容器只打印 cgroup ID行首位置留空用缩进表示这些 cgroup ID 属于同一 Pod。这种紧凑布局便于一眼看出一个 Pod 下挂了几个 cgroup。JSON / YAML / jsonpath 结构化输出当需要脚本化处理或精确提取字段时使用-o/--output切换输出格式# 输出 JSON cilium-dbg cgroups list -o json # 输出 YAML cilium-dbg cgroups list -o yaml # 使用 jsonpath 提取所有 cgroup ID cilium-dbg cgroups list -o jsonpath{.items[*].cgroup-id}结构化输出对应的是 api/v1/models/cgroup_pod_metadata.go 中定义的CgroupPodMetadata对象列表其字段如下字段JSON 键说明namenamePod 名称namespacenamespacePod 命名空间ipsipsPod 关联的 IP 列表containerscontainers容器元数据列表每个容器对象见 api/v1/models/cgroup_container_metadata.go又包含字段JSON 键说明cgroup-idcgroup-idcgroup IDuint64cgroup-pathcgroup-pathcgroup 路径值得注意的是默认表格输出只展示name、namespace和cgroup-id三列而Pod 的 IP 列表与 cgroup 路径字段在表格模式下不会显示只有切换到json/yaml等结构化输出才能看到完整数据。底层调用链从 CLI 到 Daemon API1. CLI 侧发起 HTTP 请求listCgroups()函数见 cilium-dbg/cmd/cgroups_list.go通过 swagger 生成的客户端调用resp, err : client.Daemon.GetCgroupDumpMetadata(daemon.NewGetCgroupDumpMetadataParams())即向 cilium-agent 的 Daemon API 发起GET /cgroup-dump-metadata请求。请求失败时错误信息会经过pkg.Hint(err)处理附加排障提示后写入 stderr 并以退出码 1 结束。2. API 契约Swagger 定义的响应模型该端点由 api/v1/openapi.yaml 定义成功返回 HTTP 200响应体为CgroupDumpMetadata见 api/v1/models/cgroup_dump_metadata.go其唯一字段是pod-metadatas即[]*CgroupPodMetadata列表失败时返回 HTTP 500见 api/v1/server/restapi/daemon/get_cgroup_dump_metadata_responses.go。对应的服务端路由处理器注册在 api/v1/server/restapi/daemon/get_cgroup_dump_metadata.goswagger 注解为GET /cgroup-dump-metadata daemon getCgroupDumpMetadata。3. Daemon 侧cgroup 管理器的事件驱动实现在 cilium-agent 内部该端点的真正实现位于 cgroups manager 模块。入口注册于 pkg/cgroups/manager/cell.gocell.Provide(newGetCgroupDumpMetadataRestApiHandler),核心逻辑集中在 pkg/cgroups/manager/manager.goDumpPodMetadata()第 150 行向 manager 的单协程事件循环投递podDumpMetadataEvent事件事件循环第 243 行起处理该事件并调用dumpPodMetadata()第 416 行收集全部FullPodMetadata此外 manager 还维护podGetMetadataEvent单容器查询供GetPodMetadataForContainer使用以及通过 watch Kubernetes Pod 对象触发的updatePodMetadata/replacePodMetadata/deletePodMetadata事件第 257-390 行保证元数据随 Pod 生命周期实时更新。也就是说cilium-dbg cgroups list输出的数据并非实时扫描 cgroup 文件系统而是读取 cilium-agent 内由事件驱动维护的 Pod→cgroup 元数据缓存快照。DumpPodMetadata与GetPodMetadataForContainer也是 Cilium 中按 cgroup 归属 Pod 元数据的关键入口是理解 Cilium 如何将 cgroup 事件如 socket 层 hook映射回 Pod 身份的核心。4. cgroup 文件系统前提Cilium 依赖 cgroup v2 提供相关能力。cilium-agent 启动时通过--cgroup-root配置项option.CGroupRoot描述为 Path to Cgroup2 filesystem见 daemon/cmd/daemon_main.go指定 cgroup2 挂载点并在初始化阶段调用cgroups.CheckOrMountCgrpFS(logger, option.Config.CGroupRoot)见 daemon/cmd/daemon_main.go确认或挂载 cgroup2 文件系统。若节点未正确挂载 cgroup2cgroup 元数据的维护与查询将无法正常工作。实战示例诊断 Pod 与 cgroup 的映射场景一查看默认表格输出$ cilium-dbg cgroups list POD NAME POD NAMESPACE CGROUP IDS my-app-6b9f4d5c7f-2xk9z default 123456 123457上例说明default命名空间下的my-app-6b9f4d5c7f-2xk9zPod 包含两个容器分别对应 cgroup ID123456与123457第二个容器行首无 Pod 信息表示与上一行同属一个 Pod。场景二脚本化获取 JSON$ cilium-dbg cgroups list -o json [ { name: my-app-6b9f4d5c7f-2xk9z, namespace: default, ips: [10.0.1.42], containers: [ {cgroup-id: 123456, cgroup-path: /kubepods/burstable/podxxx/abc} ] } ]此时可以同时看到表格模式缺失的ips与cgroup-path字段。场景三隐藏表头便于粘贴$ cilium-dbg cgroups list --no-headers my-app-6b9f4d5c7f-2xk9z default 123456常见问题与排障提示返回空结果cgroup 元数据由 cilium-agent 通过 watch Kubernetes Pod 维护若 agent 尚未同步完成、未启用相关能力或节点无 Pod 运行列表可能为空此时可结合cilium-dbg status检查 agent 与 Kubernetes 的连通性。Unable to retrieve cgroups metadata当 Daemon API 返回的 payload 为 nil 时见 cilium-dbg/cmd/cgroups_list.go命令会输出该提示并以退出码 1 结束通常是 agent 侧 cgroup 模块未初始化或 API 异常。cgroup v2 依赖确保 cilium-agent 的--cgroup-root指向正确的 cgroup2 挂载点相关初始化逻辑见 daemon/cmd/daemon_main.go。远程执行通过-H指定 Daemon API 的 URI 可对远程 agent 执行查询配合--config指定配置文件可覆盖默认的$HOME/.cilium.yaml。延伸阅读父命令参考页cilium-dbg cgroupsCLI 源码实现cilium-dbg/cmd/cgroups_list.gocgroup 管理器实现pkg/cgroups/manager/manager.goAPI 数据模型api/v1/models/cgroup_dump_metadata.go、api/v1/models/cgroup_pod_metadata.go、api/v1/models/cgroup_container_metadata.gocilium-dbg 全部命令参考Documentation/cmdref/cilium-dbg.md【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
)
