cilium 编码初识

说明

下面所有内容都是中文文档描述，你可以直接复制为多篇文档（例如 01-架构概览.md、02-主CNI-网络.md 等），或者放在一个总文档里。
我会按你要求的两个维度来组织：

• 架构维度：主 CNI / Chaining
• 功能维度：网络 / 安全 / 可观测性

并且都聚焦在「代码学习视角」——告诉你：看哪个目录、哪个模块、用什么顺序读。

---

文档 1：整体视角——按架构与功能的学习地图

1.1 架构维度总览

• 主 CNI 架构

  • Cilium agent：集群中运行在每个节点上的核心守护进程
    • 入口：daemon/main.go
    • 子命令与子模块：daemon/cmd
  • Cilium operator：负责 IPAM、CRD 控制器、垃圾回收等控制面逻辑
    • 入口：operator/main.go
    • 逻辑：operator/cmd、operator/pkg 等
  • CNI 插件（主 CNI 模式）
    • 入口：plugins/cilium-cni/main.go
    • 扩展命令：plugins/cilium-cni/cmd
    • 公共库：plugins/cilium-cni/lib、plugins/cilium-cni/types
  • eBPF 数据面
    • 关键程序：
      • Pod 侧：bpf/bpf_lxc.c
      • 节点侧：bpf/bpf_host.c、bpf/bpf_network.c
      • XDP：bpf/bpf_xdp.c
      • Socket LB：bpf/bpf_sock.c
      • WireGuard：bpf/bpf_wireguard.c
    • BPF 公共库：bpf/lib

• Chaining 架构

  • Cilium 与 AWS CNI、Flannel、Azure CNI 等组合使用，由对方分配 IP，Cilium 主做策略与可观测性。
  • Chaining CNI 插件实现：
    • 总入口仍然是 cilium-cni，但会根据配置选择 Chaining 模式：
      • 公共接口：plugins/cilium-cni/chaining/api
      • AWS CNI：plugins/cilium-cni/chaining/awscni
      • Azure CNI：plugins/cilium-cni/chaining/azure
      • Flannel：plugins/cilium-cni/chaining/flannel
      • 通用 veth：plugins/cilium-cni/chaining/generic-veth

1.2 功能维度总览

• 网络（Networking）
  • 控制面：端点、IPAM、服务/LB、节点、ClusterMesh
  • 数据面：各类 BPF 程序、maps、WireGuard/IPsec
• 安全（Security）
  • 身份：标签、identity、kvstore
  • 策略：CiliumNetworkPolicy 转换、L3/L4/L7 策略
  • L7/认证：Envoy、代理、mTLS、DNS/FQDN
• 可观测性（Observability）
  • Hubble：流日志、Hubble Relay、api/v1/flow
  • 监控与指标：Prometheus metrics、监控事件管线
  • 健康与调试：cilium-health、bugtool、cilium-dbg

---

文档 2：主 CNI 架构下的网络功能

2.1 推荐阅读顺序

1. 从 CNI 调用到 agent：主线调用链
   • CNI 插件：plugins/cilium-cni/main.go
   • agent 入口：daemon/main.go、daemon/cmd
2. 控制面网络模型
   • 端点与端点管理：pkg/endpoint、pkg/endpointmanager
   • IPAM：pkg/ipam、pkg/ipalloc、pkg/ip、pkg/cidr
   • 服务和负载均衡：pkg/loadbalancer + pkg/k8s
   • 节点与集群：pkg/node、pkg/nodediscovery、pkg/clustermesh、clustermesh-apiserver
3. 数据面 eBPF
   • Pod 侧：bpf/bpf_lxc.c
   • Node 侧：bpf/bpf_host.c、bpf/bpf_network.c
   • XDP：bpf/bpf_xdp.c
   • socket LB / WireGuard：bpf/bpf_sock.c、bpf/bpf_wireguard.c
   • 管理 BPF maps 与加载逻辑：pkg/maps、pkg/datapath、pkg/ebpf

2.2 关键包与代码要点

• 端点（Endpoints）

  • pkg/endpoint：单个 Pod/EP 的状态、策略引用、BPF 程序挂载点等。
  • pkg/endpointmanager：全局管理所有 EP 的生命周期。

• IPAM 与路由

  • pkg/ipam：不同 IPAM 模式的抽象（Kubernetes、ENI 等）。
  • pkg/ipalloc：实际 IP 分配池。
  • 工具：pkg/ip、pkg/cidr。

• 服务与负载均衡

  • pkg/loadbalancer：Service、Backend、Frontend 等抽象。
  • pkg/k8s：监听 Kubernetes Service、Endpoints、EndpointSlice，把它们同步到内部 LB 模型和 BPF maps。

• 节点与跨集群

  • pkg/node：本地节点状态、节点间路由信息。
  • pkg/nodediscovery：从 K8s 或其他来源发现节点。
  • pkg/clustermesh + clustermesh-apiserver：实现多集群互联。

• 数据面 BPF

  • bpf/bpf_lxc.c：Pod 入口/出口的主程序（挂在容器 veth 上）。
  • bpf/bpf_host.c：管理节点 ingress/egress 的处理。
  • bpf/bpf_network.c：更细粒度的网络路径逻辑。
  • bpf/bpf_xdp.c：XDP 场景下的 fast path。
  • pkg/maps：Go 端对 BPF map 的抽象（如 CT、LB、Policy map）。
  • pkg/datapath：加载、更新 BPF 程序和 map 的管理逻辑。

---

文档 3：主 CNI 架构下的安全功能

3.1 推荐阅读顺序

1. 身份与标签体系
   • pkg/labels、pkg/identity、pkg/kvstore
2. 策略引擎
   • pkg/policy（策略模型与计算）
   • pkg/k8s 中 CNP / NP 控制器
3. L7 安全与认证
   • pkg/proxy、pkg/envoy、pkg/ciliumenvoyconfig
   • pkg/auth、pkg/fqdn
4. 数据面中的策略执行
   • bpf/lib 中关于策略 map 和权限判断的部分

3.2 身份与策略

• 标签与 identity

  • pkg/labels：定义 key/value 标签及操作（合并、过滤、比较）。
  • pkg/labelsfilter：标签过滤规则。
  • pkg/identity：把一组标签映射到一个整数 security identity。
  • pkg/idpool：分配 identity ID。
  • pkg/kvstore：把 identity、policy 等在集群中分布式存储与同步。

• 策略引擎（Policy）

  • pkg/policy：
    • 策略对象：规则、选择器、Ingress/Egress 规则等。
    • 策略计算：给定 source/destination identity、端口、协议，判断是否允许。
  • pkg/k8s：
    • 监听 CiliumNetworkPolicy、NetworkPolicy 等 CRD/资源。
    • 把 K8s 对象翻译为内部 policy 模型，并触发 BPF map 更新。

3.3 L7、安全代理与认证

• L7 / Envoy 集成

  • pkg/ciliumenvoyconfig：Cilium 定义的 Envoy 配置 CRD。
  • pkg/envoy：与 Envoy 交互的辅助逻辑。
  • pkg/proxy：管理 L7 代理实例（HTTP、Kafka 等）。

• 认证与 DNS/FQDN 策略

  • pkg/auth：
    • 处理集群内流量认证（如 SPIFFE、mTLS）相关逻辑。
  • pkg/fqdn：
    • DNS 解析结果缓存与更新。
    • 支持基于域名的策略（如允许访问 *.example.com）。

• 数据面中的策略执行

  • 在 bpf/lib 中，关注与 policy map、identity 和权限判定相关的文件，例如：
    • bpf/lib/policy.h（名称可能略有差异，以实际为准）：包含策略匹配宏和 map 定义。
  • 结合 pkg/maps 中关于 policy map 的定义一同阅读。

---

文档 4：主 CNI 架构下的可观测性

4.1 Hubble 与流级可观测性

• 核心组件

  • Hubble 主程序：hubble/main.go、hubble/cmd
  • Hubble Relay：hubble-relay/main.go
  • Go 端 Hubble 核心库：pkg/hubble
  • 流数据模型：
    • api/v1/flow（proto/服务定义）
    • api/v1/models（自动生成的模型）

• 生成流日志的大致流程（代码学习视角）

  1. BPF 程序在关键路径上记录事件（如 CT、policy decision、drop/forward）。
  2. 通过 perf ring buffer / maps 把事件传给用户空间。
  3. Cilium agent 中的 monitor / hubble 组件消费这些事件，转换为 Flow 对象。
  4. Hubble server 提供 gRPC 接口，Hubble Relay 聚合多个 agent 的数据。

• 推荐阅读路径

  • 从 pkg/hubble 入手，看 Hubble server 如何订阅事件。
  • 再看 pkg/monitor、pkg/eventqueue 理解事件管线。
  • 最后对照 api/v1/flow 里定义的字段，看流是如何编码/传输的。

4.2 指标（Metrics）与监控

• 指标模块

  • Agent 指标：pkg/metrics
  • Operator 指标：operator/metrics

• 学习要点

  • 看 pkg/metrics 中如何注册 Prometheus 指标、以及指标的命名规范。
  • 查找典型指标更新的调用点，可以反向看网络/策略不同功能与指标的对应关系。

4.3 健康检查与调试工具

• cilium-health

  • 入口：cilium-health/main.go
  • 健康响应器：cilium-health/responder

• 调试工具

  • cilium-dbg：cilium-dbg/main.go、cilium-dbg/cmd
  • bugtool：bugtool/main.go、bugtool/cmd

---

文档 5：Chaining 架构下的网络 / 安全 / 可观测性

5.1 Chaining × 网络

• 核心思想

  • 由其他 CNI（AWS CNI、Flannel 等）负责 IPAM + 路由，Cilium 专注于 BPF 策略 + 可观测性。

• 关键代码位置

  • Chaining 框架：
    • plugins/cilium-cni/chaining/api：定义 chaining 接口。
    • 实现：
      • AWS CNI：plugins/cilium-cni/chaining/awscni
      • Azure：plugins/cilium-cni/chaining/azure
      • Flannel：plugins/cilium-cni/chaining/flannel
      • generic-veth：plugins/cilium-cni/chaining/generic-veth
  • IPAM 相关：
    • 通用 IPAM：pkg/ipam
    • 云厂商：pkg/aws、pkg/azure

• 学习建议

  • 先通读 chaining/api 接口，理解 “一个 chaining 实现需要做什么”。
  • 再对比 awscni/flannel/azure 等实现，体会 Cilium 在不同 CNI 下只做部分网络配置。

5.2 Chaining × 安全

• 安全组件复用

  • 身份与策略：完全复用 pkg/identity、pkg/policy、pkg/kvstore。
  • 数据面策略执行：仍然是 bpf/lib + 主要 BPF 程序。

• 差异点

  • Chaining 模式下，Cilium 对 L3 拓扑、IP 的掌控度变弱，因此策略计算时更多依赖 identity、标签，而非本地分配 IP 的信息。
  • 阅读策略路径时，可以对比主 CNI 与 Chaining 下 IPAM 部分的差异。

5.3 Chaining × 可观测性

• 可观测性组件完全共享

  • Hubble：hubble、hubble-relay、pkg/hubble、api/v1/flow
  • 监控与 metrics：pkg/metrics、operator/metrics
  • 事件管线：pkg/monitor、pkg/recorder、pkg/eventqueue

• 学习要点

  • 从 Hubble 的角度看，数据来源仍然是 BPF 事件，因此在 Chaining 模式下 可观测性能力基本不变。
  • 差异主要在于：链路前半段由其他 CNI 负责，但进入 Cilium hook 之后的行为与主 CNI 类似。

---

文档 6：建议的代码学习路线图（汇总）

6.1 如果你从零开始看 Cilium 代码

• 第 1 阶段：整体架构 + 主 CNI 网络

  • plugins/cilium-cni（如何从 CNI 调用到 agent）
  • daemon/main.go + daemon/cmd（agent 主结构）
  • pkg/endpoint、pkg/ipam、pkg/loadbalancer、pkg/node
  • bpf/bpf_lxc.c、bpf/bpf_host.c

• 第 2 阶段：安全（策略 + 身份 + L7）

  • pkg/labels、pkg/identity、pkg/kvstore
  • pkg/policy + pkg/k8s 中 CNP 控制器
  • pkg/proxy、pkg/envoy、pkg/ciliumenvoyconfig、pkg/auth、pkg/fqdn
  • 对应的 bpf/lib 中策略执行代码

• 第 3 阶段：可观测性

  • Hubble：pkg/hubble、hubble、hubble-relay、api/v1/flow
  • pkg/monitor、pkg/metrics、operator/metrics、pkg/recorder

• 第 4 阶段：Chaining 专项

  • plugins/cilium-cni/chaining/api + awscni/azure/flannel/generic-veth 实现
  • 对比主 CNI 模式下 IPAM 和路由行为的变化。

---

如果你希望，我可以在下一步把上面某一篇文档展开成更详细的章节结构（例如为 pkg/policy 列出重要类型和函数，并说明阅读顺序），也会保持全部中文说明。