Container Service for Kubernetes：Datapath V2下最佳實務

啟用 Prometheus 指標

Datapath V2 複用 Cilium Agent 的指標端點。在 Terway ConfigMap 的cilium_args中追加--prometheus-serve-addr：

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

• :9962是 Cilium 上遊約定的 metrics 連接埠；置Null 字元串關閉。監聽在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 後端），則可能需要進行更詳細的估算。