4、CiliumEndpoint 与 Identity：Endpoint CRD、安全标识（Security Identity）、标签到 Identity 的映射

Cilium 的网络策略与流量管控核心建立在两个关键抽象之上：CiliumEndpoint（CEP） 和 Security Identity（安全标识）。CEP 是 Kubernetes 原生 Endpoint 的增强版，而 Identity 则是 Cilium 实现“身份即网络边界”的基石。理解这两个对象及其映射关系，是掌握 Cilium 可视化排障与安全策略的前提。

4.1 CiliumEndpoint（CEP）CRD

CiliumEndpoint 是一个自定义资源（CRD），为每个 Pod（或节点）提供细粒度的网络与安全状态视图。它比 Kubernetes 原生的 Endpoint 包含更多信息，是 Cilium Agent 与集群状态同步的核心数据结构。

字段 说明 排障用途
Identity ID 分配给该 Endpoint 的安全标识 ID 确认 Pod 所属的安全组，快速定位策略匹配问题
Labels 从 Pod 继承的标签集合 验证标签是否被正确继承，排查策略未生效的根因
Networking Pod IP、Node IP、接口索引等 确认网络连通性基础信息，排查 IP 冲突或路由错误
Encryption 是否启用 WireGuard/IPsec 加密 验证加密状态，排查加密隧道未建立的问题
State Endpoint 状态（ready、waiting-for-identity 等） 快速判断 Pod 是否已就绪，定位启动卡住的原因

排障提示： 当 Pod 网络策略不生效时，首先检查对应 CEP 的 state 是否为 ready，以及 identity-id 是否与预期一致。使用 kubectl get cep -n <namespace> 可快速列出所有 CEP。

4.2 Security Identity（安全标识）

Security Identity 是 Cilium 为每个逻辑安全组分配的全局唯一整数 ID。它不是绑定到单个 Pod，而是绑定到一组具有相同标签集合的 Pod。这种设计使得策略规则可以基于“身份”而非“IP”编写，大幅提升动态环境的策略稳定性。

  • ID 范围： 1–65535，其中 1–255 为保留 ID（如 host、remote-node、cluster 等），256–65535 为动态分配。
  • 生命周期： Identity 在标签集合首次出现时创建，在最后一个引用它的 Endpoint 删除后，经过 GC 回收。
  • 全局性： 同一集群内，相同标签集合的 Pod 共享同一个 Identity ID，无论它们分布在哪个节点。

核心概念： 在 Cilium 中，网络策略的源/目的不再是 IP 地址，而是 Security Identity。这意味着 Pod 迁移或滚动更新时，只要标签不变，策略自动生效，无需修改任何规则。

4.3 标签到 Identity 的映射机制

Cilium 通过 Label Source 和 Label Selector 实现从 Kubernetes 标签到 Security Identity 的映射。映射过程由 Cilium Operator 和 Cilium Agent 协同完成。

  1. 标签收集： Cilium Agent 监听 Pod 事件，提取 Pod 的 Labels（包括 Kubernetes 原生标签和 Cilium 自定义标签）。
  2. 标签规范化： 将标签转换为 key=value 格式，并附加来源前缀（如 k8s:、container:）。
  3. Identity 分配： Agent 将规范化后的标签集合发送给 Cilium Operator，Operator 查询本地缓存：
    • 若已存在匹配的 Identity，则复用该 ID。
    • 若不存在，则分配一个新的全局唯一 ID，并写入 KV 存储（etcd/CRD）。
  4. CEP 更新： Agent 将获取到的 Identity ID 写入对应 CEP 的 identity-id 字段，完成映射。

避坑指南： 标签变更不会自动触发 Identity 重新分配。只有当 Pod 重启或 Endpoint 重建时，才会重新计算 Identity。若需要立即生效，可手动删除 CEP 对象，Cilium 会自动重建并分配新 Identity。

4.4 映射关系可视化

下图展示了从 Pod 标签到 Security Identity 的完整映射流程，以及 CEP 在其中扮演的桥梁角色。

标签到 Identity 映射流程 标签 → Security Identity 映射流程 Pod app=web,env=prod Cilium Agent 标签规范化 Cilium Operator 分配/复用 ID KV Store Identity 持久化 CiliumEndpoint identity-id: 1024 标签事件 标签集合 写入 ID 返回 ID 分配 ID 更新 CEP 关键说明： • 相同标签集合的 Pod 共享同一个 Security Identity ID • CEP 的 identity-id 字段是排障时验证映射是否正确的第一入口 • 标签变更后需重建 Endpoint 才能触发 Identity 重新分配

4.5 排障实战：验证 Identity 映射

当网络策略未按预期生效时，可通过以下步骤快速验证 Identity 映射是否正确：

# 1. 查看目标 Pod 的 CEP，确认 identity-id
kubectl get cep <pod-name> -n <namespace> -o yaml | grep identity-id

# 2. 查看该 Identity 对应的标签集合
kubectl get ciliumidentity 1024 -o yaml

# 3. 对比 Pod 标签与 Identity 标签是否一致
kubectl get pod <pod-name> -n <namespace> --show-labels

# 4. 若不一致，手动删除 CEP 触发重建
kubectl delete cep <pod-name> -n <namespace>

可视化排障技巧： 使用 cilium endpoint list 命令可实时查看节点上所有 Endpoint 的 Identity ID 和标签映射状态。结合 Hubble UI 的 Identity 视图，可以直观看到哪些 Pod 属于同一个安全组。

4.6 Identity 与网络策略的关联

Security Identity 是 CiliumNetworkPolicy 和 CiliumClusterwideNetworkPolicy 的匹配基础。策略规则中的 fromEndpoints / toEndpoints 字段实际上是在匹配 Identity 而非 Pod IP。

策略字段 匹配对象 底层机制
fromEndpoints 源端 Identity 匹配源 Pod 所属的 Security Identity
toEndpoints 目的端 Identity 匹配目的 Pod 所属的 Security Identity
fromCIDR IP 地址段 直接匹配 IP，不经过 Identity 映射
toCIDR IP 地址段 直接匹配 IP，不经过 Identity 映射

最佳实践： 优先使用 fromEndpoints / toEndpoints 编写策略，避免硬编码 IP。这样在 Pod 滚动更新或扩缩容时，策略自动适配，无需人工干预。

← 上一章 📖 返回目录 下一章 →