Cilium 命令速查手册从 CLI 基础操作到 eBPF 与 Kubernetes 实战【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/ciliumCilium 的日常运维完全围绕一套统一的命令行接口展开。本文以仓库中的 Documentation/cheatsheet.rst 为骨架结合 cilium-dbg 与 cilium-health 等目录下的真实源码实现系统讲解 Cilium CLI 的全局用法、JSON/JSONPath 输出、shell 补全、monitor 事件监控、endpoint/service 管理、eBPF 连接跟踪操作以及 Kubernetes 场景下的策略与端点查询。读完本文你将掌握一套可直接复制的 Cilium 排障与日常管理命令组合并能理解这些命令背后的数据来源与底层原理。一、Cilium CLI 是什么一个二进制多套入口Cilium 通过一个易用的命令行接口进行控制。这个 CLI 是一个单一应用程序通过子命令subcommand组织所有功能全部子命令的完整说明见命令参考指南 Documentation/cmdref。从 cilium-dbg/cmd/root.go 的源码可以看到根命令定义RootCmd cobra.Command{ Use: cilium-dbg, Short: CLI, Long: CLI for interacting with the local Cilium Agent, }在 shell 中直接执行cilium-dbg在文档编写语境中亦常写作cilium会打印出命令的完整帮助信息$ cilium CLI for interacting with the local Cilium Agent Usage: cilium-dbg [command] Available Commands: bpf Direct access to local eBPF maps cleanup Reset the agent state completion Output shell completion code for bash config Cilium configuration options debuginfo Request available debugging information from agent endpoint Manage endpoints identity Manage security identities kvstore Direct access to the kvstore monitor Monitoring policy Manage security policies prefilter Manage XDP CIDR filters service Manage services loadbalancers status Display status of daemon version Print version information Flags: --config string config file (default is $HOME/.cilium.yaml) -D, --debug Enable debug messages -H, --host string URI to server-side API Use cilium [command] --help for more information about a command.值得注意的是当前仓库实际编译出的二进制名称为cilium-dbg见 cilium-dbg/main.go 的调用链文档速查表中的cilium与源码中的cilium-dbg指向同一套 CLI 入口部分系统上同时提供名为cilium的封装具体以你所安装发行版的命令名为准。所有命令和子命令都支持-h选项用于查看该子命令可用的选项与参数。命令执行出错时CLI 会返回非零退出码non-zero status这一约定便于在脚本中做错误判断。从 cilium-dbg/cmd/root.go 可见根命令执行出错时直接打印错误并调用os.Exit(1)。全局参数背后的源码逻辑上面帮助信息里的三个全局 Flag 在 root.go 中注册--config string指定配置文件路径默认读取$HOME/.cilium.yaml。初始化逻辑见 initConfig()优先使用--config指定的文件否则按$HOME下的.cilium名称查找配置文件并支持CILIUM_前缀的环境变量覆盖vp.SetEnvPrefix(cilium)。-D, --debug开启调试消息输出。-H, --host string指定连接 Cilium Agent 服务端 API 的 URI。CLI 通过 pkg/client 包创建的 API 客户端与本地 Agent 通信。二、命令工具集JSON 输出与 shell 补全2.1 JSON 输出-o json所有 list 类命令默认会返回从 Cilium Daemon 检索到的信息并以整齐的表格形式打印。如果需要更详细的内容可以使用全局选项-o json获取 JSON 输出$ cilium-dbg endpoint list -o json该选项通过command.AddOutputOption(cmd)挂载到各 list 命令上例如 endpoint_list.go 与 service_list.go。当检测到输出选项开启时命令会走command.PrintOutput(...)分支直接输出结构化数据而不是表格。2.2 JSONPath 提取-o jsonpath除了完整 JSONCilium 还支持 JSONPath 表达式用于从返回结构中精确提取所需字段。JSONPath 模板参考 Kubernetes 文档中的kubectlJSONPath 语法。$ cilium-dbg endpoint list -o jsonpath{[*].id} 29898 38939 56326 $ cilium-dbg endpoint list -o jsonpath{range [*]}{.id}{}{.status.policy.spec.policy-enabled}{\n}{end} 29898none 38939none 56326none第一个例子直接列出所有 endpoint 的 id第二个例子利用range/end构造循环把每个 endpoint 的 id 与策略启用状态拼成idpolicy-enabled形式逐行输出。注意 JSONPath 里的.status.policy.spec.policy-enabled对应 endpoint 状态模型中策略配置的启用字段none / ingress / egress / both 等这些枚举值在 api/v1/models 的 endpoint policy 模型中定义。对于排障场景JSONPath 特别适合做只看我关心的字段的快速扫描例如按状态过滤、提取 IP 地址集合等且可以直接喂给jq或 shell 脚本做二次处理。2.3 shell Tab 补全bash / zsh / fish如果使用 bash 或 zshCLI 可以为子命令提供 tab 补全。临时启用$ source (cilium completion)注意当前源码的实现root.go要求显式传入 shell 名cilium-dbg completion bash、cilium-dbg completion zsh或cilium-dbg completion fish不带参数时默认按 bash 处理。因此实际使用中建议写全$ source (cilium-dbg completion bash)若要每次登录 shell 都自动加载补全可将补全代码追加到~/.bashrc$ echo source (cilium completion) ~/.bashrc其他 shell 的安装方式在源码的completionExample注释root.go中有完整示例例如 zsh 写入~/.cilium/completion.zsh.inc后由~/.zshrcsourcefish 写入~/.config/fish/completions/cilium.fish。三、基础命令实战3.1 查看 Agent 状态status检查 Agent 运行状况$ cilium-dbg status KVStore: Ok Etcd: 172.17.0.3:4001 Kubernetes: Disabled Cilium: Ok OK NodeMonitor: Listening for events on 2 CPUs with 64x4096 of shared memory Cilium health daemon: Ok Controller Status: 6/6 healthy Proxy Status: OK, ip 10.15.28.238, port-range 10000-20000 Cluster health: 1/1 reachable (2018-04-11T07:33:09Z)输出逐行解释KVStorekvstore 连通性及后端地址此处为 Etcd。Kubernetes是否与 Kubernetes 集成。CiliumAgent 主进程状态。NodeMonitor节点监控器正在监听的 CPU 数与共享内存配置。Cilium health daemon健康守护进程状态。Controller Status后台控制器健康比例此处 6/6 全部健康。Proxy StatusEnvoy/代理状态、地址与端口范围。Cluster health集群内节点可达性。如需更详细的诊断信息可以使用--all-controllers --all-health --all-redirects展开所有细节$ cilium-dbg status --all-controllers --all-health --all-redirects KVStore: Ok Etcd: 172.17.0.3:4001 Kubernetes: Disabled Cilium: Ok OK NodeMonitor: Listening for events on 2 CPUs with 64x4096 of shared memory Cilium health daemon: Ok Controller Status: 6/6 healthy Name Last success Last error Count Message kvstore-lease-keepalive 2m52s ago never 0 no error ipcache-bpf-garbage-collection 2m50s ago never 0 no error resolve-identity-29898 2m50s ago never 0 no error sync-identity-to-k8s-pod (29898) 50s ago never 0 no error sync-IPv4-identity-mapping (29898) 2m49s ago never 0 no error sync-IPv6-identity-mapping (29898) 2m49s ago never 0 no error Proxy Status: OK, ip 10.15.28.238, port-range 10000-20000 Cluster health: 1/1 reachable (2018-04-11T07:32:09Z) Name IP Reachable Endpoints reachable runtime (localhost) 10.0.2.15 true false展开后能看到每个后台控制器的名称、最近一次成功/失败时间、失败计数与消息这是排查某个同步任务长期失败的首选入口。从源码看status.gostatus子命令还支持以下 Flag--all-addresses展示所有已分配地址而不仅是计数。--all-nodes展示所有节点而不仅是 localhost。--all-clusters展示所有集群。--all-redirects展示所有重定向。--brief仅输出一行摘要。--verbose等价于同时开启上述所有--all-*与--all-health。--timeout健康查询超时时间默认 30s。--require-k8s-connectivity若 Agent 无法访问 Kubernetes 控制面命令返回非零退出码默认 true。status底层通过 client.Daemon.GetHealthz 调用 Agent 的/healthzAPI 获取数据若 Agent 不可达会输出cilium: daemon unreachable并以状态码 1 退出--brief模式还会对不健康状态做退出码区分适合在脚本里做健康探针。3.2 查看 Agent 配置与策略获取当前 Agent 的运行时配置$ cilium-dbg config该命令打印所有布尔配置项的启用/禁用状态实现见 helpers.go 的dumpConfig值可被解析为 bool 时显示Enabled/Disabled否则原样打印可与cilium-dbg config get key、cilium-dbg config set key value配合做运行时调参。列出所有已导入的策略规则$ cilium-dbg policy get四、Monitoring观察数据平面的实时事件monitor命令用于查看数据平面BPF 程序发出的通知与事件。从 monitor.go 的 Long 描述可知它覆盖四类内容丢包通知、捕获的数据包 trace、策略判定policy verdict通知以及调试信息。基本用法$ cilium-dbg monitorVerbose 输出开启调试信息$ cilium-dbg monitor -vExtra verbose 输出额外包含报文解析$ cilium-dbg monitor -v -v只查看与某个 endpoint 相关的事件$ cilium-dbg monitor --related-toid只查看第 7 层L7即 API 层事件$ cilium-dbg monitor -t L7只显示丢包事件$ cilium-dbg monitor --type drop不解析报文内容用十六进制显示负载$ cilium-dbg monitor -v -v --hexmonitor 的实现要点事件类型过滤器-t/--type支持的类型名称定义在 pkg/monitor/api/types.godrop、debug、capture、trace、l7、agent、policy-verdict、trace-sock。例如-t drop只过滤丢包通知-t l7过滤第 7 层访问日志。endpoint 过滤有三组 Flagmonitor.go--from按源 endpoint 过滤、--to按目的 endpoint 过滤、--related-to源或目的任一匹配。执行前会先校验所给 endpoint 是否真实存在validateEndpointsFilters所有过滤器都无效时直接退出。输出形式--hex用十六进制展示负载而不再做协议解析-j/--json输出 JSON会覆盖-v-n/--numeric将所有安全身份以数字形式显示方便对照 identity 表。数据来源monitor 通过 unix socket 连接 Agent 的 node-monitor消息按 monitor API 版本 1.2 使用 gob 编码解码monitor.go连接断开EOF时会自动重连并等待connTimeout。输出事件时printer.FormatEvent(pl)会综合 link cache 与 endpoint 信息把安全身份、endpoint 名称等翻译成可读文本这也是-n参数存在的意义。五、Connectivity集群健康检查cilium-health是独立的健康检查工具入口见 cilium-health/main.go用于检查集群连通性$ cilium-health status它通过向集群内各节点注入探针流量验证节点之间以及节点到 endpoint 的路径是否可达是跨节点网络排障的第一步。status输出通常包括每个远端节点的 IP、是否可达、以及可达的 endpoint 数量等信息。六、Endpoints端点管理获取所有本地 endpoint 列表$ cilium-dbg endpoint list查看某个 endpoint 的详细属性与状态$ cilium-dbg endpoint get id查看该 endpoint 最近的相关日志$ cilium-dbg endpoint log id为该 endpoint 开启调试输出配合 monitor 观察该 endpoint 的调试事件$ cilium-dbg endpoint config id Debugtrueendpoint list 的表头与数据来源printEndpointList 输出的表格列包括ENDPOINTid、POLICY (ingress)/POLICY (egress)ingress/egress 方向策略启用状态、ENFORCEMENT、IDENTITY安全身份、LABELS (source:key[value])、IPv6、IPv4与STATUS。策略模式枚举在 endpoint_list.go 中映射为Enabled、Disabled、Disabled (Audit)与Unknown。endpoint get id的 id 参数支持数字 ID、label 或容器 ID 前缀等多种形式解析逻辑在 helpers.go 的requireEndpointID中并会调用endpointid.Parse做校验。七、Loadbalancing负载均衡查询获取负载均衡服务列表$ cilium-dbg service list也可以直接从 eBPF map 读取负载均衡信息$ cilium-dbg bpf lb list两条命令的差异在于数据来源service list走 API 从 Agent 获取服务模型service_list.go输出ID / Frontend / Service Type / Backend四列后端会带状态active 等clustermesh 远端服务还会标注(Remote)使用--clustermesh-affinity可额外打印 preferred 信息bpf lb list则直接 dump 内核中 LB 相关的 BPF map反映数据平面实际装载的条目两者对照可用于判断配置是否真正下发生效。八、eBPF 排障连接跟踪与 Verifier 日志8.1 查看连接跟踪表列出连接跟踪connection tracking条目$ sudo cilium-dbg bpf ct list清空连接跟踪条目$ sudo cilium-dbg bpf ct flush说明这两条命令操作的是内核 BPF map需要 root 权限因此示例中带sudo。这是文档中少数需要提权执行的命令。从源码看bpf_ct_list.gobpf ct list在 clustermesh 场景下还支持按集群过滤cilium-dbg bpf ct list cluster id并通过common.RequireRootPrivilege强制校验 root。可选参数-d/--time-diff可打印条目的时间差帮助判断连接的新旧与老化情况。8.2 排查 BPF Verifier 问题当 BPF 程序加载被 Verifier 拒绝时从日志中提取相关上下文$ journalctl -u cilium-dbg | grep -B20 -F10 Verifier-B20显示匹配行前 20 行-F10显示匹配行后 10 行从而把 Verifier 报错前后的完整日志带出来。更常见的实际场景是查看 agent 单元通常是cilium或cilium-agent的日志$ journalctl -u cilium | grep -B20 -A10 -i verifier当怀疑 datapath 相关功能异常如策略不生效、连接被异常丢弃时结合cilium-dbg monitor --type drop观察丢包原因码再回查 Verifier/Agent 日志是标准排障链路。九、Kubernetes 场景用 kubectl 查询 Cilium 资源在 Kubernetes 上运行 Cilium 时可以通过自定义资源CRD用单一的kubectl命令列出所有 cilium endpoint 或策略无需逐台进入 Pod 执行 CLI。9.1 Policies两种策略资源Kubernetes 下存在两类策略Kubernetes NetworkPolicy 与 CiliumNetworkPolicyCNP均可用kubectl获取。Kubernetes Network Policy$ kubectl get netpolCilium Network Policy$ kubectl get cnp NAME AGE rule1 3m $ kubectl get cnp rule1 NAME AGE rule1 3m $ kubectl get cnp rule1 -o jsonkubectl get cnp列出全部 Cilium 网络策略kubectl get cnp rule1查看单条策略-o json导出完整定义含 spec 中的 endpointSelector、ingress/egress 规则等。9.2 EndpointsCiliumEndpoint 资源CiliumEndpointCEPCRD 用于检索由 Cilium 管理的全部 endpoint$ kubectl get cep NAME AGE 34e299f0-b25c2fef 41s 34e299f0-dd86986c 42s 4d088f48-83e4f98d 2m 4d088f48-d04ab55f 2m 5c6211b5-9217a4d1 1m 5c6211b5-dccc3d24 1m 700e0976-6cb50b02 3m 700e0976-afd3a30c 3m 78092a35-4874ed16 1m 78092a35-4b08b92b 1m 9b74f61f-14571299 7s 9b74f61f-f9a96f4a 7s查看单个 CEP 的完整 JSON$ kubectl get cep 700e0976-6cb50b02 -o json用 JSONPath 批量提取每个 endpoint 的 id 与策略启用状态$ kubectl get cep -o jsonpath{range .items[*]}{.status.id}{}{.status.status.policy.spec.policy-enabled}{\n}{end} 30391ingress 5766ingress 51796none 40355none注意此处 JSONPath 的写法与本地 CLI 略有差异{range .items[*]}遍历资源列表的 items 字段字段路径不带前缀Kubernetes JSONPath 语法。输出中ingress表示该 endpoint 当前仅启用了 ingress 方向的策略执行none表示未启用策略执行。这种方式的优势一次kubectl调用即可横跨整个集群而非单节点汇总所有 endpoint 或策略并且可以直接复用 kubectl 的-o yaml/json/jsonpath等输出能力适合在 CI 脚本或大规模集群审计中批量使用。十、排障路径速查综合全文将常用排障链路归纳如下便于快速定位问题症状首选命令关键观察点Agent 整体健康cilium-dbg statusKVStore / Controllers / Cluster health控制器任务长期失败cilium-dbg status --all-controllersLast error 与 Count 列流量被丢cilium-dbg monitor --type drop丢包原因码与相关 endpoint某个 Pod 无策略/策略异常cilium-dbg endpoint listPOLICY 列与 IDENTITY服务后端不生效cilium-dbg service list对照cilium-dbg bpf lb list配置态 vs 数据平面态连接建立异常sudo cilium-dbg bpf ct listCT 条目是否存在/是否被刷掉BPF 程序加载失败journalctl -u cilium \| grep -B20 -A10 -i verifierVerifier 拒绝原因跨节点连通问题cilium-health status各节点 Reachable 状态需要说明的是本文所有命令与输出均以当前仓库含 Documentation/cheatsheet.rst、cilium-dbg、cilium-health、pkg/monitor 等源码路径为准部分输出样例为文档历史上的真实运行结果字段含义以你部署版本实际输出为准。全部子命令的最新帮助信息可在仓库中查看 Documentation/cmdref 下对应的命令参考文档或在本地执行cilium-dbg command --help获取。/output_article【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考