Datapath V2下最佳实践

启用 Prometheus 指标

Datapath V2 复用 Cilium Agent 的指标端点。在 Terway ConfigMap 的cilium_args中追加--prometheus-serve-addr：

"cilium_args": "--prometheus-serve-addr=:9962"

• :9962是 Cilium 上游约定的 metrics 端口；置空字符串关闭。监听在0.0.0.0，可通过 Pod 的 hostNetwork 端口直接抓取。

• 修改后重启 terway-eniip Pod 生效。

• 在 Pod/Service 上添加抓取注解，或编写 ServiceMonitor，使集群内 Prometheus 自动发现：

  metadata:
    annotations:
      prometheus.io/scrape: "true"
      prometheus.io/port: "9962"
      prometheus.io/path: "/metrics"

重点关注的 BPF Map 指标

部分指标在Terway >=v1.14.0 版本后才提供，请升级至最新版本。

推荐告警与查询示例

# 任意 BPF Map 使用率超过 80% 持续 5 分钟
max by (map_name) (cilium_bpf_map_pressure) > 0.8

# 每个节点的 LB Service Map 使用率
cilium_bpf_map_pressure{map_name=~"cilium_lb[46]_services_v2"}

# 每个 Endpoint 的 Policy Map 使用率（Top 10）
topk(10, cilium_bpf_map_pressure{map_name=~"cilium_policy_.*"})

# Node Map 容量告警（>80% 即应扩容 bpf-node-map-max）
cilium_bpf_map_pressure{map_name="cilium_node_map_v2"} > 0.8

# 全局 Conntrack Map 压力（与 bpf-map-dynamic-size-ratio 调优联动）
cilium_bpf_map_pressure{map_name=~"cilium_ct.*_global"} > 0.7

# Map 写入失败速率
sum by (map_name) (rate(cilium_bpf_map_ops_total{operation="update",outcome="fail"}[5m])) > 0

观察到cilium_bpf_map_pressure持续超过 0.8，应对照BPF Map 容量调优章节按 Map 类别调整对应参数；超过 0.95 时应视为紧急情况立即扩容，否则可能在短时间内出现条目下发失败。

bpf-map-dynamic-size-ratio

• 功能：决定节点上同时可跟踪的连接数与 NodePort/SNAT 翻译条目数。表的容量 = 节点物理内存 × 此比例 / 单条记录大小，容量满时新连接无法建立，已有连接也可能被驱逐导致丢包。

• 作用范围：CT (cilium_ct4_global / cilium_ct_any4_global)、NAT (cilium_snat_v4_external)、Neighbor (cilium_nodeport_neigh4)、SockRevNAT 这几张全局 Map 的容量，会按本参数 × 节点物理内存的比例动态计算。

• 取值范围：(0.0, 1.0]，默认 0.0025（即约 0.25% 的物理内存）。

• 典型推算（参考 Cilium 默认元素大小）：

  节点物理内存	CT TCP 条目	CT Any 条目	NAT 条目
  512 MiB	33,140	16,570	33,140
  1 GiB	66,280	33,140	66,280
  4 GiB	265,121	132,560	265,121
  16 GiB	1,060,485	530,242	1,060,485

• 上下限保护：动态计算结果会被钳制到 [1Ki, 16Mi]（约 1GiB 内存/张 Map）之间，单 Map 上限为 2^24 = 16,777,216 条目。

• 调优建议：

  • 高并发服务（每节点万级以上长连接）的节点，建议适度提升至 0.005~0.01，让 CT/NAT 在大内存节点上获得更多条目。

  • 显式设置了bpf-ct-global-tcp-max/bpf-ct-global-any-max/bpf-nat-global-max的 Map 不会被本参数覆盖。

  • 如果通过监控 BPF Map 使用率观察到 cilium_ct4_global 等 Map 的cilium_bpf_map_pressure持续 >0.8，应优先调整本比例或为相应 Map 显式指定容量。

bpf-policy-map-max

• 作用范围：每个 Endpoint（每个 Pod）独立持有一张 cilium_policy_* Map，存放允许该 Endpoint 收发流量的对端 Identity × 端口/协议 条目，用于 NetworkPolicy 数据面执行。

• 默认值：16384。最小值 256 (2^8)，最大值 65536 (2^16)；超出范围会被自动裁剪并打印 warning。

• 何时需要调整：

  • 集群启用了 NetworkPolicy 且 Identity 数量较多（参见限制Identity数量章节）。

  • 单个 Pod 需要访问的对端 Identity 数 × 暴露端口/协议组合数接近默认 16384。

  • 通过指标 cilium_bpf_map_pressure{map_name=~"cilium_policy_.*"} 观察到压力持续 >0.8。

• 调整方式：在 Terway ConfigMap 的cilium_args中追加 --bpf-policy-map-max=32768，重启 terway-eniip Pod 生效。

• 注意：每张 Map 占用的内存与max_entries成正比，每个节点上 Map 数量等于该节点 Pod 数量。盲目设置到 65536 会显著增加节点内存开销，请结合实际 Identity 规模评估。

bpf-node-map-max

• 功能：决定集群可识别的最大节点规模。所有节点的 Node ID ↔ IP 映射存在这一张全局 Map 中，是跨节点 Pod 通信、IPsec/WireGuard 加密、Egress Gateway 等节点级特性的基础数据。表满后新加入的节点无法被数据面识别，跨节点流量会失败。

• 作用范围：单张 cilium_node_map_v2 存放集群内所有 Node 的 Node ID ↔ IP 映射，用于跨节点 Pod 通信、Encryption、Egress Gateway 等场景。

• 默认值：16384（约可承载 1.6 万个唯一 Node IP）。

• 限制：源码硬编码 不允许设置低于默认值 16384，启动时如果 bpf-node-map-max < 16384 会直接报错退出；上限受uint32约束（理论最大 4,294,967,295），但实际取决于节点内存。

• 何时需要调整：

  • 集群规模即将逼近 1.6 万节点，或开启 IPsec/WireGuard 等需要每节点条目膨胀的功能时。

  • 通过指标 cilium_bpf_map_pressure{map_name="cilium_node_map_v2"} 观察到压力 >0.8。

• 调整方式：在cilium_args中追加 --bpf-node-map-max=32768，重启 terway-eniip Pod 生效。

bpf-lb-map-max

• 功能：决定全集群 Kubernetes Service 在数据面的下发能力，覆盖 ClusterIP、NodePort、LoadBalancer 三种类型，以及它们对应的后端、反向 NAT、会话亲和性、Maglev 哈希表等所有 LB 子 Map。表满后，新创建的 Service / 新增的后端 Pod 无法写入 BPF，表现为 Service IP 访问不通或端点更新延迟。

• 作用范围：Cilium 使用名为 cilium_lb{4,6}_services_v2 的 LB Service Maps 来保存 ClusterIP 和 NodePort 类型服务的负载均衡条目。本参数同时作为以下 LB 子 Map 的默认上限（如未单独指定）：

  • cilium_lb4_services_v2 / cilium_lb6_services_v2

  • cilium_lb4_backends_v3 / cilium_lb6_backends_v3

  • cilium_lb4_reverse_nat / cilium_lb6_reverse_nat

  • cilium_lb4_affinity / cilium_lb6_affinity

  • cilium_lb4_source_range / cilium_lb6_source_range

• 默认值：65536（64Ki）。如果此映射已满，Cilium 可能无法更新服务端点，影响服务 IP 的连通性或创建新服务的能力。

• 容量估算：每个 ClusterIP/NodePort 服务创建的条目数等于该服务后端 Pod 数 × Service spec 中端口/协议组合数。

服务 LB 映射所需的大小取决于多个因素。

每个 ClusterIP/NodePort 服务创建的条目数量等于该服务选择的后端 Pod 数量乘以相应 Service spec 中的端口、协议条目数量。

$$\text{每个Service的 LB 映射条目数}=(\text{每个Service关联的后端 Pod 数})\times (\text{每个Service定义的端口/协议组合数})$$

利用这一点，我们可以粗略估算所需的映射大小为：

$$\text{LB Map条目数}\approx (\text{LB Service数量})\times (\text{单个 Service 平均 Endpoints 数量})\times (\text{单个 Service 平均端口/协议组合数})$$

注意这种估算假设每个服务选择的 Pod 数量和端口/协议条目数大致呈正态分布。如果您的用例存在较大的异常值（例如，某个服务选择了非常大量的 Pod 后端），则可能需要进行更详细的估算。