Cilium cgroup 元数据管理cilium-dbg cgroups 命令参考与实现解析【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读cilium-dbg cgroups是 Cilium 命令行调试工具cilium-dbg中用于查看cgroup 元数据Cgroup metadata的命令组。在启用了 socket 负载均衡SocketLB追踪的场景下Cilium Agent 会在后台维护一份「Pod 与其容器 cgroup」的映射关系而本文要介绍的cilium-dbg cgroups list正是将该映射以表格、JSON 或 YAML 形式导出的官方调试入口。阅读本文后你将掌握cilium-dbg cgroups的完整用法与全部参数并理解这条命令背后从 CLI 到 Agent 守护进程、再到 cgroup 管理器的完整数据链路。一、命令概览cilium-dbg cgroupscilium-dbg cgroups是cilium-dbg命令树下的一个命令组父命令其功能定位只有一句话Cgroup metadata即负责展示 Cilium 所维护的 cgroup 元数据。它本身不执行任何查询动作真正的查询逻辑在它的子命令list中。1.1 命令结构cilium-dbg cgroups └── cilium-dbg cgroups list # 显示 Cilium 维护的 cgroup 元数据别名ls在源码中该命令组由 cilium-dbg/cmd/cgroups.go 定义// CgroupsCmd represents the cgroups command var CgroupsCmd cobra.Command{ Use: cgroups, Short: Cgroup metadata, } func init() { RootCmd.AddCommand(CgroupsCmd) }它基于spf13/cobra构建通过init()挂载到RootCmd根命令之下。命令元数据Use与Short正是本参考文档标题与描述的直接来源。1.2 自身参数-h, --help help for cgroups与大多数 Cobra 命令一致cgroups父命令仅提供-h/--help用于查看该命令组的帮助信息包括可用子命令列表。二、全局继承参数Options inherited from parent commands无论运行cilium-dbg cgroups还是其子命令list所有来自cilium-dbg根命令的全局参数都会生效。这些参数定义了客户端如何连接 Cilium Agent 的服务端 API参数说明--config string配置文件路径默认读取$HOME/.cilium.yaml-D, --debug启用调试消息输出-H, --host string服务端 API 的 URI即连接 Cilium Agent 的地址--log-driver strings日志输出端点例如syslog--log-opt map日志驱动选项例如formatjson其中-H/--host是最常用的参数当你在非 Agent 所在节点运行cilium-dbg时需要显式指定 Agent 的 API 地址例如cilium-dbg -H unix:///var/run/cilium/cilium.sock cgroups list。cilium-dbg默认通过本地 socket 与服务端通信。三、核心子命令cilium-dbg cgroups listcilium-dbg cgroups list是这一命令组的核心其用途为Display cgroup metadata maintained by Cilium显示 Cilium 维护的 cgroup 元数据。命令定义位于 cilium-dbg/cmd/cgroups_list.govar cgroupsListCmd cobra.Command{ Use: list, Aliases: []string{ls}, Short: Display cgroup metadata maintained by Cilium, Run: func(cmd *cobra.Command, args []string) { listCgroups() }, }值得注意的是它注册了别名ls因此cilium-dbg cgroups ls与cilium-dbg cgroups list完全等价方便习惯短命令的用户。3.1 用法cilium-dbg cgroups list [flags]3.2 子命令专属参数参数说明-h, --help显示list子命令的帮助信息--no-headers输出表格时不打印表头-o, --output string输出格式取值json、yaml、jsonpath{}在源码中这两个业务参数通过如下代码注册cilium-dbg/cmd/cgroups_list.gofunc init() { CgroupsCmd.AddCommand(cgroupsListCmd) cgroupsListCmd.Flags().BoolVar(cgroupsListNoHeaders, no-headers, false, Do not print headers) command.AddOutputOption(cgroupsListCmd) }--no-headers是一个布尔开关默认false由cgroupsListNoHeaders变量承载-o/--output通过公共工具函数command.AddOutputOption注入支持 Cilium CLI 统一的输出格式约定json/yaml/jsonpath便于脚本化解析与自动化集成。3.3 默认输出三列表格当不指定-o时命令以text/tabwriter渲染的对齐表格输出固定三列表头见 cilium-dbg/cmd/cgroups_list.goPOD NAME POD NAMESPACE CGROUP IDSPOD NAMEPod 名称POD NAMESPACEPod 所在命名空间CGROUP IDS该 Pod 下各容器的 cgroup ID数字当一个 Pod 包含多个容器时第一个容器与 Pod 名称/命名空间同行打印其余容器仅缩进打印 cgroup ID\t\t%d见 cilium-dbg/cmd/cgroups_list.gofor _, pm : range podMetas { for i, container : range pm.Containers { if i 0 { fmt.Fprintf(w, %s\t%s\t%d\t\n, pm.Name, pm.Namespace, container.CgroupID) } else { fmt.Fprintf(w, \t\t%d\t\n, container.CgroupID) } } } w.Flush()--no-headers的作用即跳过表头行if !cgroupsListNoHeaders { ... }适合将输出直接喂给其他文本处理工具。3.4 结构化输出示例指定-o json后输出将变为结构化数据对应下述数据模型{ pod-metadatas: [ { name: my-app-6b4d9f5d5c-abcde, namespace: default, containers: [ { cgroup-id: 123456789, cgroup-path: /kubepods/burstable/... } ], ips: [10.0.1.5] } ] }指定-o yaml或-o jsonpath{...}时遵循同样的字段名约定可用于监控告警脚本、日志采集等场景。四、数据模型cgroup 元数据的字段结构list子命令展示的数据由 Cilium 的 REST API 数据模型定义位于 api/v1/models 目录由 go-swagger 生成共三层结构4.1 CgroupDumpMetadata顶层定义于 api/v1/models/cgroup_dump_metadata.go// CgroupDumpMetadata cgroup full metadata type CgroupDumpMetadata struct { // pod metadatas PodMetadatas []*CgroupPodMetadata json:pod-metadatas }4.2 CgroupPodMetadataPod 维度定义于 api/v1/models/cgroup_pod_metadata.gotype CgroupPodMetadata struct { Containers []*CgroupContainerMetadata json:containers Ips []string json:ips Name string json:name,omitempty Namespace string json:namespace,omitempty }注意该结构不仅包含容器 cgroup 信息还额外携带了 Pod 的IP 列表ips字段这为调试「Pod IP ↔ cgroup ↔ 容器」的映射关系提供了完整证据。4.3 CgroupContainerMetadata容器维度定义于 api/v1/models/cgroup_container_metadata.gotype CgroupContainerMetadata struct { // cgroup id CgroupID uint64 json:cgroup-id,omitempty // cgroup path CgroupPath string json:cgroup-path,omitempty }默认表格输出只展示cgroup-idcgroup-path字段仅在结构化输出json/yaml中可见它记录了容器 cgroup 的完整路径如/kubepods/burstable/pod-xxx/yyy对排查容器归属问题尤为有用。五、底层原理从 CLI 到 Agent 的完整数据链路cilium-dbg cgroups list不是本地读取文件而是通过 Cilium 的 REST API 从 Agent 侧拉取数据。整个链路如下5.1 第一步CLI 调用服务端 API在 cilium-dbg/cmd/cgroups_list.go 中listCgroups()直接调用 Agent 的 APIfunc listCgroups() { resp, err : client.Daemon.GetCgroupDumpMetadata(daemon.NewGetCgroupDumpMetadataParams()) if err ! nil { fmt.Fprintf(os.Stderr, %s\n, pkg.Hint(err)) os.Exit(1) } w : tabwriter.NewWriter(os.Stdout, 5, 0, 3, , 0) printMetadata(w, resp.Payload) }这里client即连接 Agent 的 API 客户端GetCgroupDumpMetadata是api/v1/client/daemon包中对应 REST 端点GetCgroupDumpMetadata的封装。若返回为空metadata nil命令会输出Unable to retrieve cgroups metadata并以退出码 1 结束。5.2 第二步Agent 侧 REST 处理Agent 端的 HTTP 处理器位于 pkg/cgroups/manager/rest_api.go。处理器调用 cgroup 管理器的DumpPodMetadata()获取内部元数据再转换为上述 API 模型返回func (h *getCgroupDumpMetadataRestApiHandler) Handle(params daemonrestapi.GetCgroupDumpMetadataParams) middleware.Responder { resp : models.CgroupDumpMetadata{} metadata : h.cgroupManager.DumpPodMetadata() for _, pm : range metadata { // ... 将内部 CgroupPodMetadata 映射为 API 模型 // 填充 CgroupID、CgroupPath、Name、Namespace、Ips } return daemonrestapi.NewGetCgroupDumpMetadataOK().WithPayload(resp) }5.3 第三步cgroup 管理器何时启用关键的一点是cgroup 元数据管理并不是默认无条件启用的。根据 pkg/cgroups/manager/cell.gocgroup 管理器CGroupManager的初始化条件是func newCGroupManager(params cgroupManagerParams) CGroupManager { if !params.KPRConfig.EnableSocketLB || !params.AgentConfig.UnsafeDaemonConfigOption.EnableSocketLBTracing { return noopCGroupManager{} } // ... 否则创建真实管理器并启动 pod 事件处理 Job }即需要同时满足EnableSocketLB启用 socket 负载均衡即 kube-proxy-free 模式下的核心能力EnableSocketLBTracing启用 socket 负载均衡的追踪能力用于 Hubble 观测。任一条件不满足时管理器退化为noopCGroupManager{}空实现此时cilium-dbg cgroups list虽然可以正常调用但返回的pod-metadatas列表为空。因此该命令在启用 SocketLB SocketLB Tracing 的 Cilium 集群中才具有实际数据。在真实管理器启用后Agent 会通过JobGroup.Add(job.OneShot(process-pod-events, cm.processPodEvents))启动一个后台 Jobpkg/cgroups/manager/cell.go持续监听并维护「Pod → 容器 cgroup」映射这正是DumpPodMetadata()的数据来源。5.4 调用链小结cilium-dbg cgroups list │ (REST GET /cgroup-dump-metadata) ▼ Agent REST handler (pkg/cgroups/manager/rest_api.go) │ ▼ CGroupManager.DumpPodMetadata() (pkg/cgroups/manager 包) │ ← 数据由后台 Job processPodEvents 持续维护 ▼ 返回 CgroupDumpMetadata 模型api/v1/models六、典型使用场景与注意事项6.1 快速查看集群中 Pod 与 cgroup 的映射# 在 Agent 节点上默认本地连接 cilium-dbg cgroups list # 使用别名 ls等价写法 cilium-dbg cgroups ls # 指定远端 Agent 地址 cilium-dbg -H unix:///var/run/cilium/cilium.sock cgroups list # 去掉表头便于管道处理 cilium-dbg cgroups list --no-headers典型输出POD NAME POD NAMESPACE CGROUP IDS my-app-6b4d9f5d5c-ab default 123456789 987654321多行 cgroup ID 表示同一 Pod 下存在多个容器。6.2 脚本化获取结构化数据# 获取 JSON 格式 cilium-dbg cgroups list -o json # 获取 YAML 格式 cilium-dbg cgroups list -o yaml # 仅提取首个 Pod 名称jsonpath 语法 cilium-dbg cgroups list -o jsonpath{.pod-metadatas[0].name}6.3 注意事项适用前提如 第五节 所述该命令输出的完整数据依赖 Agent 启用EnableSocketLB与EnableSocketLBTracing。未启用时返回空列表属于预期行为而非命令故障。权限要求cilium-dbg需要具备访问 Agent REST API 的能力默认本地 unix socket建议在 Agent 所在节点或具备相应权限的容器内执行。参考文档一致性本文对应命令参考文档为 Documentation/cmdref/cilium-dbg_cgroups.md 与 Documentation/cmdref/cilium-dbg_cgroups_list.md二者由cilium-dbg cmdref自动生成字段与源码保持一致。七、延伸阅读若希望深入了解该命令背后的系统可继续阅读当前仓库中的以下资源CLI 实现cilium-dbg/cmd/cgroups.go、cilium-dbg/cmd/cgroups_list.goAPI 数据模型api/v1/models/cgroup_dump_metadata.go、api/v1/models/cgroup_pod_metadata.go、api/v1/models/cgroup_container_metadata.goAgent 侧实现pkg/cgroups/manager/cell.go管理器生命周期与启用条件、pkg/cgroups/manager/rest_api.goREST 处理器相关命令参考cilium-dbg 命令总览【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考