Cilium Agent HTTP API 参考指南访问方式、Go 客户端与兼容性保证【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/ciliumCilium 以 eBPF 技术提供网络、安全与可观测能力其核心数据面组件cilium-agent对外暴露一套基于 JSON 的 HTTP API定义于 api/v1/openapi.yaml用于对单个 agent 实例进行可见性与控制。本文以 Documentation/api.rst 为骨架结合仓库源码系统讲解该 API 的访问方式CLI 客户端与 Go 客户端、典型用法、资源模型以及兼容性承诺帮助读者快速上手并在此基础上做二次开发。API 定位与作用域Cilium API 由cilium-agent提供是 agent 与其所在节点上各类管理工具之间的标准接口。它的设计有两条核心原则以单个 agent 实例为边界绝大多数 API 调用只作用于当前这个cilium-agent所管理的资源本节点的 endpoint、策略、服务等不会跨越节点。少数调用提供集群级视图例如安全身份security identity解析类接口可以给出整个集群范围的可见性这类调用会在文档与 API 描述中单独标注。从实现上看API 服务是在 agent 进程内通过 Hive 依赖注入装配起来的在 daemon/cmd/cells.go 中configureAPIServer将server.Server由 api/v1/server 生成的服务端代码与swaggerSpec即 api/v1/openapi.yaml 解析出的规格对象注入 HTTP 服务从而把 OpenAPI 描述的操作映射为真实的处理函数。也就是说openapi.yaml不只是文档它同时是服务端路由注册与客户端代码生成的事实来源。如何访问 API通过 CLI 客户端访问推荐最简单的访问方式是使用ciliumCLI 客户端。该客户端会自动定位同节点上 agent 暴露的 API 并访问$ cilium-dbg [...]cilium-dbg默认连接本机 agent 的 API但也可以使用-H/--host标志指向任意 API 地址。例如显式指定 agent 暴露的 UNIX domain socket$ cilium-dbg -H unix:///var/run/cilium/cilium.socksocket 路径解析逻辑cilium-dbg究竟连接到哪里由 pkg/client/client.go 中的DefaultSockPath()决定优先读取环境变量CILIUM_SOCK指定的 socket 路径若未设置回退到默认路径RuntimePath /cilium.sock即/var/run/cilium/cilium.sock见 pkg/defaults/defaults.go。这也是文档示例中unix:///var/run/cilium/cilium.sock的来源。除管理 API 外agent 还会在同一目录暴露shell.sock调试 shell与monitor1_2.sock事件监控流它们是相互独立的通道。通过 Go 客户端访问仓库提供两组 Go 包作为官方客户端入口包作用pkg/client主客户端抽象封装对 agent API 的全部高层调用api/v1/modelsAPI 资源的数据类型模型endpoint、policy、service 等pkg/client中的Client结构体嵌入embed了由 OpenAPI 规格生成的 api/v1/client 客户端因此既能使用高层便捷方法如EndpointList()也能直接调用底层的CiliumAPI接口方法如Daemon.GetConfig。Go 客户端最小示例文档给出的完整示例可在仓库cilium/client-example中找到核心代码逻辑如下import ( fmt github.com/cilium/cilium/pkg/client ) func main() { c, err : client.NewDefaultClient() if err ! nil { // 处理错误通常是 agent 未运行或 socket 不可达 ... } endpoints, err : c.EndpointList() if err ! nil { ... } for _, ep : range endpoints { fmt.Printf(%8d %14s %16s %32s\n, ep.ID, ep.ContainerName, ep.Addressing.IPV4, ep.Addressing.IPV6) } }连接参数与高可用等待pkg/client提供多种构造方式满足不同场景NewDefaultClient()连接CILIUM_SOCK或默认 socket 路径NewClient(host string)连接任意地址TCP 或 unixhost 为空时与默认客户端等价pkg/client/client.goNewDefaultClientWithTimeout(timeout)在指定超时时间内轮询等待 agent 就绪。其实现会先尝试创建客户端再调用Daemon.GetConfig探测 agent 是否已启动每 500ms 重试一次直到超时pkg/client/client.go。传输层细节位于 pkg/client/client.go 的configureTransport当协议为unix时禁用 HTTP 压缩并用net.Dial直连 socket当为 TCP 时则走标准代理与拨号逻辑。传输协议与 API 版本整个 API 采用JSON over HTTP具体约定定义在 api/v1/openapi.yaml 的头部swagger: 2.0遵循 OpenAPI 2.0Swagger规范描述info.title: Cilium APIinfo.version: v1beta1x-schemes: [unix]默认传输 scheme 为本地 UNIX domain socket同时兼容 TCP 部署basePath: /v1所有路径以/v1为前缀produces/consumes均为application/json请求与响应均使用 JSON 编码。agent 的 API 服务在进程启动时即绑定并开始服务openapi.yaml既是客户端代码api/v1/client生成的输入也是服务端 handler 注册的规格来源。核心资源与典型操作根据openapi.yaml中声明的路径API 主要覆盖以下资源域资源域路径前缀说明节点信息/cluster/nodes获取 agent 中存储的节点信息支持client-id头实现增量 diff健康状态/healthzagent 及各组件datastore、Kubernetes、Hubble健康检查支持brief与require-k8s-connectivity参数配置/config读取 agent 运行配置Endpoint/endpoint、/endpoint/{id}、/endpoint/{id}/config、/endpoint/{id}/labels、/endpoint/{id}/log、/endpoint/{id}/healthz端点容器网络实体的增删查改、配置、标签、日志与健康安全身份/identity、/identity/{id}、/identity/endpoints身份分配与解析其中身份解析提供集群级可见性IPAM/ipam、/ipam/{ip}IP 地址分配管理策略/policy、/policy/selectors、/policy/subject-selectors安全策略 CRUD 与选择器信息负载均衡/service、/lrpService 与本地重定向策略Local Redirect Policy预过滤/prefilterBPF 预过滤规则管理调试信息/debuginfo、/cgroup-dump-metadata系统级诊断数据BPF Map/map、/map/{name}、/map/{name}/events查看 BPF map 内容与订阅事件流FQDN/fqdn/cache、/fqdn/cache/{id}、/fqdn/namesDNS 名称缓存查询与清理IP 缓存/ipIP 缓存查询节点 ID/node/ids节点 ID 分配查询BGP/bgp/peers、/bgp/routes、/bgp/route-policiesBGP 对等体、路由与路由策略查询这些路径均由tags归组例如/cluster/nodes、/healthz、/config属于daemon组对应的 Go 客户端方法集中在 api/v1/client/daemon。两个代表性调用剖析健康检查/healthz返回 agent 与 datastore、Kubernetes 集成、Hubble 等组件的健康与状态信息。其可选参数很有实际价值——require-k8s-connectivity默认true设为 true 时若 agent 无法连接 Kubernetes 控制面健康状态也会相应失败便于在 CI/故障演练中准确反映数据面与控制面的依赖关系。Endpoint 列表EndpointList()是文档示例中的核心调用。它在 pkg/client/endpoint.go 中实现内部通过生成的 daemon 客户端请求GET /endpoint返回[]*models.Endpoint每个元素包含ID、ContainerName、Addressing.IPV4、Addressing.IPV6等字段Addressing定义于 api/v1/models与文档示例中的格式化输出一一对应。对应地EndpointGet(id)pkg/client/endpoint.go可按 ID 查询单个端点详情。兼容性保证文档明确承诺Cilium API 自 1.0 版本起保持稳定在 Cilium 1.x 的整个生命周期内将维持向后兼容backward compatibility。这意味着依赖 API 的第三方工具与客户端包括cilium-dbg、官方 Go 客户端以及社区集成不会因小版本升级而失效新增能力以向后兼容的方式扩展新路径、新可选字段不会破坏既有调用但 API 版本标识为v1beta1见openapi.yaml的info.version实际语义以 1.x 生命周期内的稳定性承诺为准。对开发者而言编写集成代码时应遵循 JSON over HTTP /v1basePath 的既有约定优先复用 pkg/client 的高层封装若需绕过封装也可直接面向openapi.yaml生成的客户端与模型。在仓库中继续深入完整 OpenAPI 规格所有路径、参数、响应与definitionsapi/v1/openapi.yaml生成的 Go 客户端按资源分组如daemon、endpoint、policyapi/v1/client资源数据模型models.Endpoint、models.ClusterNodeStatus等api/v1/models高层客户端抽象与 socket 发现逻辑pkg/client/client.go、pkg/client/endpoint.goagent 端 API 服务装配与启动daemon/cmd/cells.go默认 socket 路径与环境变量定义pkg/defaults/defaults.go客户端测试验证默认 socket 与 host 解析行为pkg/client/client_test.go【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考