企业官网建设流程全解析

Cilium 安全策略查看命令详解：cilium-dbg policy get 用法、输出格式与底层实现

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium

cilium-dbg policy get是 Cilium 数据面代理（cilium-dbg）中用于查看节点级安全策略（Policy）的命令，通过 Cilium Agent 暴露的 REST API 拉取策略仓库（Policy Repository）中的全部规则与当前策略修订号。本文基于当前仓库中的命令参考文档 cilium-dbg_policy_get.md 及其底层实现，完整讲解该命令的语法、全部参数、输出格式、端到端调用链、数据模型，以及它被标记为 deprecated 的原因和可用的替代命令，适合需要排查安全策略下发状态、验证策略生效情况的开发者与运维人员阅读。

一、命令定位与弃用背景

cilium-dbg policy get的子命令get定义于 cilium-dbg/cmd/policy_get.go，其命令级描述为：

Display policy node information (deprecated)

它隶属于cilium-dbg policy命令组（见 cilium-dbg/cmd/policy.go，组描述为 "Manage security policies"，即"管理安全策略"）。

需要注意的关键事实：该命令在客户端与服务端两侧均已被显式标记为deprecated（已弃用）：

• 客户端方法注释：// Deprecated, to be removed in v1.19（见 pkg/client/policy.go）；
• 服务端 API 数据模型注释：// Deprecated, will be removed in v1.19（见 api/v1/models/policy.go）。

这意味着在 v1.19 及以后版本中该命令（及对应 API）将被移除。当前版本仍可正常使用，但新脚本与自动化工具应优先考虑后文介绍的替代方案。

二、命令语法与全部选项

命令的完整语法为：

cilium-dbg policy get [flags]

该命令不接受位置参数，全部配置通过 flags 完成。命令自身定义的选项如下：

其中-o/--output选项由command.AddOutputOption(policyGetCmd)动态挂载到命令上（见 cilium-dbg/cmd/policy_get.go），其实现位于 pkg/command/output.go。

继承自父命令的全局选项

policy get同时继承cilium-dbg根命令的全部全局选项：

例如，当需要连接非默认位置的 Agent 时：

cilium-dbg -H unix:///var/run/cilium/cilium.sock policy get

三、典型用法与输出格式

3.1 默认输出（文本模式）

在不指定-o时，命令将策略内容与修订号以纯文本形式打印：

cilium-dbg policy get

对应的实现逻辑见 cilium-dbg/cmd/policy_get.go：

fmt.Printf("%s\nRevision: %d\n", resp.Policy, resp.Revision)

输出由两部分构成：

1. 策略 JSON 内容：即策略仓库中全部规则的 JSON 表示（带两空格缩进）；
2. Revision 修订号：策略仓库当前版本号，每次策略变更都会递增，用于判断策略是否已同步到最新。

3.2 结构化输出（json / yaml / jsonpath）

使用-o/--output可将整个models.Policy对象（包含policy与revision两个字段）以指定格式导出：

# JSON 输出 cilium-dbg policy get -o json # YAML 输出 cilium-dbg policy get -o yaml # JSONPath 提取，例如只取修订号 cilium-dbg policy get -o 'jsonpath={.revision}'

当指定了输出选项时，命令分支走command.PrintOutput(resp)（见 cilium-dbg/cmd/policy_get.go），由 pkg/command/output.go 中的PrintOutputWithType按outputType完成格式化。JSONPath 语法与 Kuberneteskubectl -o jsonpath的表达式约定保持一致，{}内为取值路径，适合在脚本中提取单一字段。

3.3 命令组内的相关子命令

policy get是cilium-dbg policy命令组的成员之一，同组还包括（见 cilium-dbg_policy.md）：

• cilium-dbg policy selectors：显示 SelectorCache 中缓存的 selector 信息；
• cilium-dbg policy subject-selectors：显示主体（subject）SelectorCache 缓存信息；
• cilium-dbg policy wait：等待所有 endpoint 更新到指定策略修订号。

四、端到端调用链与底层实现

从 CLI 输入到最终返回策略内容，policy get经历了一条清晰的调用链，理解它可以帮你准确判断问题出在客户端还是服务端。

第 1 步：CLI 命令入口

policyGetCmd的Run函数在 cilium-dbg/cmd/policy_get.go 中，调用client.PolicyGet()，若出错则Fatalf("Cannot get policy: %s\n", err)直接终止。

第 2 步：客户端 API 封装

client.PolicyGet()定义于 pkg/client/policy.go：

func (c *Client) PolicyGet() (*models.Policy, error) { params := policy.NewGetPolicyParams().WithTimeout(api.ClientTimeout) resp, err := c.Policy.GetPolicy(params) if err != nil { return nil, Hint(err) } return resp.Payload, nil }

它通过api.ClientTimeout设置请求超时，向 Agent 的/policyREST 端点发起 GET 请求（对应 swagger 生成的GetPolicy客户端方法，定义于 api/v1/client/policy 目录）。

第 3 步：Agent 端 HTTP Handler

Agent 端处理函数getPolicyHandler.Handle位于 daemon/restapi/policy.go：

func (h *getPolicyHandler) Handle(params policyrest.GetPolicyParams) middleware.Responder { ruleList, rev := h.Repo.Search() policy := &models.Policy{ Revision: int64(rev), Policy: policy.JSONMarshalRules(ruleList), } h.Log.Debug("Policy Get Request", logfields.PolicyRevision, policy.Revision) return policyrest.NewGetPolicyOK().WithPayload(policy) }

核心动作是调用策略仓库（h.Repo，即pkg/policy.Repository）的Search()方法，一次性取回全部规则与当前修订号。

第 4 步：策略仓库读取

Search()实现在 pkg/policy/repository.go：

func (p *Repository) Search() (types.PolicyEntries, uint64) { p.mutex.RLock() defer p.mutex.RUnlock() return p.searchRLocked(), p.GetRevision() }

• 读取时加读锁（RLock），保证并发安全且不阻塞策略写入；
• searchRLocked()遍历p.rules返回全部PolicyEntry（见同文件第 176-184 行）；
• GetRevision()通过原子操作返回修订号（见 pkg/policy/repository.go）。

第 5 步：序列化输出

规则列表通过JSONMarshalRules序列化为带缩进的 JSON 字符串（pkg/policy/repository.go）：

func JSONMarshalRules(rules types.PolicyEntries) string { b, err := json.MarshalIndent(rules, "", " ") if err != nil { return err.Error() } return string(b) }

因此默认文本输出中看到的"策略内容"就是这条 JSON 字符串；这也解释了为什么-o json的输出中policy字段是一个嵌套的字符串而非对象——它本身就是经过序列化的 JSON。

五、响应数据模型解析

policy get返回的响应体对应 swagger 模型Policy，定义于 api/v1/models/policy.go：

type Policy struct { // Policy definition as JSON. Policy string `json:"policy,omitempty"` // Revision number of the policy. Incremented each time the policy is // changed in the agent's repository Revision int64 `json:"revision,omitempty"` }

revision是排查策略下发问题时的关键指标：如果cilium-dbg policy get返回的修订号与cilium-dbg policy wait所等待的目标修订号不一致，说明策略尚未在 Agent 侧完全生效或存在下发延迟。

六、弃用原因与替代命令

该命令被弃用的原因，从源码注释可以直接看出：它返回的是节点级、全量规则列表的简单转储（h.Repo.Search()直接返回全部PolicyEntry），粒度粗糙、内容冗长，不利于脚本化解析与大规模集群中的定向查询。

仓库中已有的替代方案包括：

1. cilium-dbg policy selectors与cilium-dbg policy subject-selectors：查询 SelectorCache 中缓存的 selector 信息，对应 Agent 端getPolicySelectorsHandler与getPolicySubjectSelectorsHandler（见 daemon/restapi/policy.go），以及客户端封装PolicyCacheGet()、SubjectPolicySelectorsGet()（见 pkg/client/policy.go），可查看策略选择器在 Agent 内的缓存状态，诊断粒度更细。

2. cilium-dbg bpf policy get：直接查询数据面 BPF 策略映射（见 cilium-dbg/cmd/bpf_policy_get.go），用于验证策略是否真正下发到了 eBPF 数据路径，是确认数据面生效情况的权威手段。

3. Kubernetes 侧：在 K8s 环境中，策略的声明式管理应直接使用kubectl get ciliumnetworkpolicy / ciliumclusterwidenetworkpolicy查看 CRD 资源本身。

七、实践建议与注意事项

• 优先使用结构化输出：在自动化脚本或 CI 中，推荐-o json或-o 'jsonpath={.revision}'，避免解析人读格式；
• 注意弃用时限：规划 v1.19 升级时，需将依赖cilium-dbg policy get或/policyREST API 的工具迁移到上述替代方案；
• 区分数据面与控制面：policy get反映的是 Agent 策略仓库（控制面）状态，若要确认 eBPF 数据面实际生效的策略，应结合cilium-dbg bpf policy list/bpf policy get使用；
• 超时控制：客户端请求带api.ClientTimeout超时（见 pkg/client/policy.go），在大规模策略仓库场景下若响应超时，可检查 Agent 端日志中的Policy Get Request调试记录（含PolicyRevision字段，见 daemon/restapi/policy.go）。

八、小结

cilium-dbg policy get以一条命令覆盖了"读取节点全量策略 + 获取修订号"的完整链路：CLI（cilium-dbg/cmd/policy_get.go）→ 客户端封装（pkg/client/policy.go）→ Agent REST Handler（daemon/restapi/policy.go）→ 策略仓库读锁查询与序列化（pkg/policy/repository.go）。尽管它已进入弃用倒计时（v1.19 移除），其"修订号 + 规则转储"的交互模型、-o json/yaml/jsonpath的输出约定，以及 selector 缓存与 BPF 映射等替代排查路径，依然是理解 Cilium 安全策略体系的重要入口。

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium