📚 课程目录第4章控制面核心组件详解

4. 控制面核心组件详解

Cilium Agent 是运行在每个 Kubernetes 节点上的核心控制面进程（通常以 DaemonSet 方式部署）。它负责与 Kubernetes API Server、KVStore（etcd）以及节点内核中的 eBPF 程序进行交互。在生产环境中，Agent 的稳定性直接决定了网络策略与负载均衡的正确性。本章深入剖析 Agent 内部三个关键模块：Policy Repository、Endpoint Manager 和 Node Discovery，并给出对应的故障排查切入点。

4.1 Policy Repository：策略的权威存储与实时分发

Policy Repository 是 Cilium Agent 内部用于存储和管理网络策略（CNP、CCNP）的模块。它从 Kubernetes API Server 或 KVStore 监听策略事件，将其转换为内部表示（SelectorCache 与 PolicyCache），并最终生成可下发的 eBPF Map 条目。

  故障排查要点： 当策略未生效时，首先检查 Policy Repository 是否成功解析了策略中的标签选择器。使用 cilium policy get 命令可以查看当前节点上已加载的策略列表及其状态。

4.1.1 核心数据结构与流程

组件	作用	故障排查关注点
SelectorCache	缓存标签选择器与身份（Security Identity）的映射关系	身份解析失败、选择器匹配不到端点
PolicyCache	存储最终的策略规则，按方向（Ingress/Egress）和端点分组	策略冲突、规则未命中、规则顺序错误
L4/L7 Filter	端口、协议、HTTP 方法等具体匹配条件	端口范围错误、协议不匹配、L7 规则语法错误

4.1.2 常见故障模式

策略未加载：Agent 与 API Server 连接中断，或 CRD 版本不匹配。检查 cilium status 中的 "Kubernetes" 健康状态。
选择器未命中：Pod 标签与策略中的 matchLabels 或 matchExpressions 不匹配。使用 cilium policy trace --src-k8s-pod 进行端到端模拟。
身份（Identity）不一致：不同节点上的 Agent 对同一组标签解析出不同的 Security Identity。检查 KVStore 中的 cilium/state/identities 目录。

4.2 Endpoint Manager：端点生命周期的精细管理

Endpoint Manager 负责管理节点上所有由 Cilium 管理的网络端点（Pod 或主机网络端点）。它维护每个端点的状态机，包括创建、健康检查、策略重算、销毁等阶段。每个端点都对应一个独立的 eBPF 程序实例。

最佳实践： 在排查 Pod 网络不通时，优先使用 cilium endpoint list 查看端点状态。如果状态为 "disconnected" 或 "regenerating"，说明端点正在重建或策略正在重新计算，此时网络可能短暂中断。

4.2.1 端点状态机

状态	含义	排查方向
ready	端点正常运行，策略已应用	正常状态
waiting-for-identity	等待 Security Identity 分配	检查 KVStore 连接、身份分配速率
regenerating	正在重新生成 eBPF 程序（策略变更或端点更新）	检查策略变更频率、eBPF 编译错误日志
disconnected	端点与 Agent 通信中断	检查 Pod 网络命名空间、veth pair 状态

4.2.2 故障排查命令

# 查看所有端点状态
cilium endpoint list

# 查看特定端点的详细信息（包括策略、身份、标签）
cilium endpoint get <endpoint-id>

# 触发端点重新生成（用于调试）
cilium endpoint regenerate <endpoint-id>

4.3 Node Discovery：集群拓扑的自动感知

Node Discovery 模块负责发现集群中的其他节点，并维护节点间的隧道或路由信息。它通过 KVStore（etcd）或 Kubernetes Node 资源来交换节点地址、Cilium 内部 IP（CiliumInternalIP）、健康状态等元数据。该模块是跨节点通信（Overlay 或 Direct Routing）的基础。

注意： 如果 Node Discovery 模块故障，会导致新加入的节点无法被其他节点感知，从而造成跨节点 Pod 通信失败。检查 cilium node list 的输出是否包含所有预期节点。

4.3.1 节点信息同步机制

同步方式	数据源	适用场景	故障特征
KVStore	etcd	大规模集群、多集群	etcd 连接超时、watch 中断
Kubernetes Node	K8s API Server	小规模集群、默认模式	API Server 限流、Node 对象未更新

4.3.2 关键数据结构

每个节点在 KVStore 中存储以下信息：

Node IP：节点的外部可达 IP 地址。
CiliumInternalIP：用于 Cilium 内部通信的 IP 地址（通常来自 cilium_host 网卡）。
Health Endpoint：节点健康检查端点的 IP 和端口。
Encryption Key：如果启用了 WireGuard 或 IPsec，会包含公钥信息。

4.3.3 故障排查步骤

验证节点列表：执行 cilium node list，确认所有节点都已出现。如果缺少节点，检查 KVStore 连接或 Kubernetes Node 对象的注解。
检查健康端点：使用 cilium status --verbose 查看节点健康检查是否通过。健康检查失败会导致跨节点流量被标记为不可达。
确认隧道/路由模式：使用 cilium config get 查看 tunnel 或 routing-mode 配置。如果模式不匹配，节点间可能无法正确封装或路由数据包。

  实战案例： 某生产集群新增节点后，新节点上的 Pod 无法访问其他节点上的 Service。排查发现 cilium node list 中缺少新节点信息。进一步检查发现新节点的 Agent 日志报错 "connection to etcd timed out"。修复 etcd 网络连通性后，Node Discovery 自动同步，跨节点通信恢复。