Cilium 端点清单管理实战深入解析cilium-dbg endpoint list命令【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读cilium-dbg endpoint list是 Cilium 数据面运维中最常用的诊断命令之一用于列出当前 Cilium Agent 上管理的全部本地端点Endpoint并以表格形式呈现每个端点的策略执行状态ingress/egress、安全身份 ID、安全相关标签、IPv4/IPv6 地址与运行状态。本文将基于该命令的官方参考文档Documentation/cmdref/cilium-dbg_endpoint_list.md结合仓库内 CLI 实现与 API 模型源码完整讲解命令用法、全部参数含义、表格字段的取值语义以及如何借助json/yaml/jsonpath输出接入自动化巡检与脚本处理帮助你从会敲命令进阶到看懂输出、会用数据。命令概览与定位cilium-dbg endpoint list属于cilium-dbgCLI 的endpoint命令族其定位是List all endpoints。在 Cilium 的语境中Endpoint是 Cilium 应用策略的最小网络单元——一个受管容器、Pod 或宿主机上的网络命名空间对应一个由 Agent 分配的本地 ID 与安全身份Identity。该命令只负责列出端点若需查看单个端点的详细信息、修改配置或管理标签可分别使用endpoint get、endpoint config、endpoint labels等子命令见 Documentation/cmdref/cilium-dbg_endpoint.md。命令基本用法cilium-dbg endpoint list [flags]从源码 cilium-dbg/cmd/endpoint_list.go 可以看到该子命令还注册了别名ls因此以下两条命令完全等价cilium-dbg endpoint list cilium-dbg endpoint ls执行时CLI 会通过client.EndpointList()调用 Agent 的 REST APIGET /endpoint拉取该节点上所有端点的完整状态对象再格式化输出见 cilium-dbg/cmd/endpoint_list.go。这决定了它的一个重要特性它只反映运行cilium-dbg时所连接的那一个 Cilium Agent 节点上的本地端点而非整个集群的端点集合。在多节点集群中排查时需要按节点分别执行或借助kubectl进入对应节点操作。参数详解list 自身的选项参数类型/默认值说明-h, --helpbool显示list子命令的帮助信息--no-headersbool默认false不打印表格的列头表头行-o, --output stringstring默认空指定输出格式json、yaml或jsonpath{}--no-headers的底层实现是在 cilium-dbg/cmd/endpoint_list.go 中通过BoolVar注册的全局变量noHeaders当其为true时printEndpointList会跳过表头打印见 cilium-dbg/cmd/endpoint_list.go。该参数非常适合将表格输出直接喂给awk/cut等文本处理工具做二次解析。-o/--output选项由公共函数command.AddOutputOption统一注册见 pkg/command/output.go三个取值分别对应json输出完整的端点对象 JSON缩进格式化yaml输出 YAML 格式的端点对象jsonpath{...}按 JSONPath 表达式从端点对象中提取指定字段例如jsonpath{range .items[*]}{.id}{\n}{end}之类的表达式可批量抽取 ID。继承自父命令的全局选项list子命令还继承了cilium-dbg根命令的以下选项在任何子命令下均可用--config string 配置文件默认 $HOME/.cilium.yaml -D, --debug 开启调试消息 -H, --host string 服务端 API 的 URI --log-driver strings 日志输出端点例如 syslog --log-opt map 日志驱动选项例如 formatjson其中-H/--host用于指定要连接的 Agent API 地址是排查远程节点、或通过 socat 等端口转发工具连接非本机 Agent 时的关键参数--config则用于指定自定义配置文件默认读取$HOME/.cilium.yaml。表格输出字段深度解读不带-o选项时cilium-dbg endpoint list通过text/tabwriter输出对齐的文本表格见 cilium-dbg/cmd/endpoint_list.go。默认输出包含如下列头定义于 cilium-dbg/cmd/endpoint_list.goENDPOINT POLICY (ingress) POLICY (egress) IDENTITY LABELS (source:key[value]) IPv6 IPv4 STATUS ENFORCEMENT ENFORCEMENT下面逐列说明其含义与取值来源各列数据均来自 Agent API 返回的models.Endpoint对象其结构定义见 api/v1/models/endpoint.go。ENDPOINT端点的 Agent 本地 IDep.IDint64。它是节点内唯一的整数标识可用于cilium-dbg endpoint get id、cilium-dbg endpoint config id等后续操作。输出前端点会按 ID 升序排序见 cilium-dbg/cmd/endpoint_list.go保证多次执行输出顺序稳定。POLICY (ingress) / POLICY (egress) 与 ENFORCEMENT这两列展示端点当前**实际生效Realized**的 L3/L4 策略执行模式取值映射由endpointPolicyMode()函数完成见 cilium-dbg/cmd/endpoint_list.go。其依据是ep.Status.Policy.Realized.PolicyEnabled字段该字段是枚举类型所有取值定义在 api/v1/models/endpoint_policy_enabled.goPolicyEnabled原始枚举值ingress 列显示egress 列显示noneDisabledDisabledbothEnabledEnabledingressEnabledDisabledegressDisabledEnabledaudit-bothDisabled (Audit)Disabled (Audit)audit-ingressDisabled (Audit)Disabledaudit-egressDisabledDisabled (Audit)其他/无法解析UnknownUnknown对应关系在 cilium-dbg/cmd/endpoint_list.go 中有明确的常量定义PolicyEnabled Enabled、PolicyDisabled Disabled、PolicyAudit Disabled (Audit)、UnknownState Unknown。Enabled表示该方向已启用策略强制enforcement即该方向的流量必须经过 Cilium 策略校验Disabled表示该方向未启用强制流量默认放行Disabled (Audit)表示该方向处于审计Audit模式——流量不会被拦截但会被记录并报告通常用于灰度验证策略是否会被误伤Unknown表示端点状态对象缺失或尚未同步ep.Status、ep.Status.Policy或Realized为 nil 时的兜底值。注意表头中POLICY (ingress)与POLICY (egress)下各有一行ENFORCEMENT这是 Cilium 有意设计的双层表头提醒用户这两列描述的是策略执行/强制状态而不是策略规则本身的内容。IDENTITY端点的安全身份 IDep.Status.Identity.ID来自 api/v1/models/identity.go 中的Identity模型。该 ID 是 Cilium 网络策略NetworkPolicy / CiliumNetworkPolicy中按身份而非按 IP 授权的核心依据——不同端点只要标签组合产生同一身份就共享同一 ID。若端点状态缺失则显示no label id见 cilium-dbg/cmd/endpoint_list.go。LABELS (source:key[value])该列显示端点的安全相关标签Security-Relevant Labels取自ep.Status.Labels.SecurityRelevant按字典序排序输出见 cilium-dbg/cmd/endpoint_list.go。标签采用source:key[value]格式例如k8s:io.kubernetes.pod.namespacedefault其中source标识标签来源如k8s、container、cni等。当端点没有任何安全相关标签时显示no labels。一个端点通常关联多个标签。此时printEndpointList会将第一个标签打印在端点主行上其余标签另起一行继续输出见 cilium-dbg/cmd/endpoint_list.go以便每个标签独占一列宽度、保持可读性。这也意味着在解析文本输出时同一端点可能占据多行。IPv6 / IPv4端点主网络接口的 IPv6 与 IPv4 地址取自ep.Status.Networking.Addressing[0]见 cilium-dbg/cmd/endpoint_list.go地址对类型定义见 api/v1/models/address_pair.go。若Status/Networking缺失显示Unknown若寻址列表为空显示No address。这两个地址也是通过cilium-dbg endpoint get、cilium policy trace等命令定位具体流量的重要线索。STATUS端点的运行状态直接取自ep.Status.State字符串值见 cilium-dbg/cmd/endpoint_list.go例如ready、waiting-to-regenerate、regenerating、restoring、disconnected等。ready表示端点策略与数据面均已就绪若状态未同步则显示Unknown。此列是快速判断哪个 Pod 的网络未就绪的首要依据。结构化输出json / yaml / jsonpath当传入-o选项时listEndpoints()会走command.OutputOption()分支将完整的端点对象切片而非表格行交给输出函数处理见 cilium-dbg/cmd/endpoint_list.go。输出管线实现在 pkg/command/output.go-o jsonjson.MarshalIndent输出带 2 空格缩进的 JSON-o yaml通过 yaml 库序列化输出-o jsonpath{...}使用 k8s 风格的jsonpath解析器AllowMissingKeys(true)对对象执行字段抽取见 pkg/command/output.go。几个实用示例# 输出全部端点对象的完整 JSON含 spec/status 全量字段 cilium-dbg endpoint list -o json # 输出 YAML 格式 cilium-dbg endpoint list -o yaml # 仅提取每个端点的 ID 与 IPv4 地址 cilium-dbg endpoint list -o jsonpath{range .items[*]}{.id} {.status.networking.addressing[0].ipv4}{\\n\}{end}需要注意-o json/yaml输出的是端点对象的原始 API 结构字段命名与表格列并不一一对应例如表格中的IDENTITY对应 JSON 中的status.identity.idPOLICY两列对应status.policy.realized.policy-enabled。因此在脚本中处理结构化输出前建议先执行一次cilium-dbg endpoint list -o json查看完整的 JSON 结构再编写对应的解析逻辑。此外jsonpath表达式的items路径与models.Endpoint切片序列化后的 JSON 键名id、spec、status保持一致可参考 api/v1/models/endpoint.go 中的字段注释确认嵌套层级。典型排障工作流将上述能力组合起来可以形成一套完整的端点排查流程快速总览执行cilium-dbg endpoint list先看STATUS列是否有非ready的端点再看POLICY两列是否为预期状态例如预期强制却显示Disabled。定位可疑端点通过IDENTITY或LABELS列找到目标 Pod 对应的端点 ID例如cilium-dbg endpoint list | grep namespace。深挖单端点用cilium-dbg endpoint get id查看该端点的完整 spec/status源码见 cilium-dbg/cmd/endpoint_get.go也支持-l按标签查询用cilium-dbg endpoint log id查看状态变更历史定位异常发生的时间点。核查策略生效情况cilium-dbg endpoint list的POLICY列只反映是否强制若需查看具体允许/拒绝的流量方向可结合cilium-dbg policy get id或 Hubble 流量观测进一步确认。自动化巡检在监控脚本中组合-o json与--no-headers例如定时抓取非ready端点数量# 统计状态非 ready 的端点数依赖 jq仅作示意 cilium-dbg endpoint list -o json | jq [.[] | select(.status.state ! ready)] | length常见问题与注意事项只能看到本节点端点该命令查询的是-H/--host指向的单个 Agent不是集群维度视图集群级端点信息请通过 Kubernetes APIkubectl get ciliumendpoints或对应 CRD获取。audit模式下的状态审计模式显示为Disabled (Audit)容易被误读为未启用策略。它实际上代表策略已在计算中、但以只记录不拦截的方式运行升级为强制模式前务必确认审计日志符合预期。多标签端点的多行输出用文本工具解析默认表格时同一个端点可能输出多行后续行为纯标签行建议优先使用-o json进行机器解析。命令帮助与生成机制本文涉及的cmdref文档包括 cilium-dbg_endpoint_list.md由cilium-dbg cmdref工具自动生成--help输出即为其来源仓库中Documentation/cmdref/update-cmdref.sh负责在参数变更时重新生成这些文档因此文档与二进制保持同步。延伸阅读端点命令族总览cilium-dbg endpoint含config、disconnect、get、health、labels、list、log共 7 个子命令CLI 根命令与全局参数cilium-dbg输出选项的通用实现json/yaml/jsonpath 打印管线pkg/command/output.go端点 API 模型字段与注释即 JSON 结构说明api/v1/models/endpoint.go、api/v1/models/endpoint_policy.go、api/v1/models/endpoint_policy_enabled.go列表命令的完整实现与列定义cilium-dbg/cmd/endpoint_list.go【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考