Container Service for Kubernetes:Terway Datapath V2 のベストプラクティス

Prometheus メトリクスの有効化

Datapath V2 は Cilium エージェントのメトリクスエンドポイントを再利用します。Terway の ConfigMap にある cilium_args に --prometheus-serve-addr 引数を追加します。

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

• :9962 は Cilium の規約上のメトリクスポートです (無効にするには空文字列に設定します)。0.0.0.0 でリッスンするため、Pod の hostNetwork ポートから直接スクレイピングできます。

• 変更を有効にするには、terway-eniip Pod を再起動します。

• Pod またはサービスにスクレイピング用のアノテーションを追加するか、自動的な Prometheus ディスカバリのために ServiceMonitor を作成します。

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

主要な BPF マップメトリクス

一部のメトリクスには Terway v1.14.0 以降が必要です。最新バージョンにアップグレードしてください。

アラートとクエリの例

# いずれかの BPF マップの使用率が 5 分間 80% を超えた場合にアラートを発行
max by (map_name) (cilium_bpf_map_pressure) > 0.8

# 各ノードの LB Service Map の使用率
cilium_bpf_map_pressure{map_name=~"cilium_lb[46]_services_v2"}

# 各エンドポイントの Policy Map の使用率 (トップ 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

# マップ書き込み失敗率
sum by (map_name) (rate(cilium_bpf_map_ops_total{operation="update",outcome="fail"}[5m])) > 0

cilium_bpf_map_pressure が継続的に 0.8 を超える場合は、「BPF マップキャパシティのチューニング」セクションで説明されているように、対応するパラメーターを調整してください。値が 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 — のキャパシティは、このパラメーターとノードの物理メモリから動的に計算されます。

• 値の範囲：(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] (マップあたり約 1 GiB のメモリ) にクランプされます。マップあたりの最大エントリ数：2^24 = 16,777,216。

• チューニングの推奨事項：

  • 高同時実行ノード (ノードあたり 10,000 以上の長寿命接続) の場合、大容量メモリノードでより多くの CT/NAT エントリを許可するために、0.005–0.01 に増やしてください。

  • bpf-ct-global-tcp-max、bpf-ct-global-any-max、または bpf-nat-global-max が明示的に設定されているマップは影響を受けません。

  • BPF マップ使用率のモニタリングで cilium_ct4_global などのマップの cilium_bpf_map_pressure が継続的に 0.8 を超える場合は、この比率を調整するか、影響を受けるマップのキャパシティを明示的に設定してください。

bpf-policy-map-max

• スコープ：各 Pod は、データプレーンの NetworkPolicy 適用のために、許可されたピアアイデンティティ、ポート、プロトコルの組み合わせを格納する独自の cilium_policy_* マップを持ちます。

• デフォルト値：16384。最小値：256 (2^8)、最大値：65536 (2^16)。範囲外の値は警告とともにクランプされます。

• 調整するタイミング：

  • クラスターで NetworkPolicy が有効になっており、アイデンティティの数が多い場合 (「アイデンティティ数の制限」を参照)。

  • 単一の Pod に対するピアアイデンティティと公開されているポート/プロトコルの組み合わせの積が 16384 に近づく場合。

  • メトリクス cilium_bpf_map_pressure{map_name=~"cilium_policy_.*"} が継続的に 0.8 を超える場合。

• 調整方法：Terway の ConfigMap にある cilium_args に --bpf-policy-map-max=32768 を追加し、terway-eniip Pod を再起動します。

• 注意：マップあたりのメモリは max_entries に比例し、各ノードは Pod ごとに 1 つのマップをホストします。評価なしに 65536 を設定すると、ノードのメモリオーバーヘッドが大幅に増加します。

bpf-node-map-max

• 機能：クラスターが認識できるノードの最大数を制御します。ノード間通信、IPsec/WireGuard 暗号化、およびエグレスゲートウェイのために、単一のグローバルマップにノード ID と IP のマッピングを格納します。いっぱいになると、新しいノードが認識できなくなり、ノード間トラフィックの障害を引き起こします。

• スコープ：ノード間通信、暗号化、およびエグレスゲートウェイのためにクラスター全体で共有される単一の cilium_node_map_v2 マップ。

• デフォルト値：16384 (約 16,000 の一意のノード IP を保持可能)。

• 制限：ソースコードは、デフォルトの 16384 より低い値を設定することを禁止しています。起動時に bpf-node-map-max < 16384 の場合、エージェントはエラーで終了します。上限：uint32 (理論的には 4,294,967,295)、ノードのメモリによって制約されます。

• 調整するタイミング：

  • クラスターサイズが 16,000 ノードに近づいている場合、または 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 サービス — ClusterIP、NodePort、および LoadBalancer — のデータプレーンキャパシティを制御します。これには、バックエンド、リバース NAT、セッションアフィニティ、および Maglev ハッシュテーブルが含まれます。いっぱいになると、新しいサービスやバックエンドをプログラミングできなくなり、到達不能なサービス IP やエンドポイント更新の遅延を引き起こします。

• スコープ：cilium_lb{4,6}_services_v2 (ClusterIP および NodePort のロードバランシングエントリ) と、以下の LB サブマップのキャパシティを設定します (個別に上書きされない限り)：

  • 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 (64K)。いっぱいになると、Cilium はサービスエンドポイントを更新できなくなり、接続性や新しいサービスの作成に影響を与えます。

• キャパシティの見積もり：サービスごとのエントリ数 = バックエンド Pod 数 × Service spec 内のポート/プロトコルの組み合わせ数。

必要な LB マップサイズを見積もります：

ClusterIP/NodePort サービスごとのエントリ数 = サービスに選択されたバックエンド Pod 数 × Service spec 内のポート/プロトコルエントリ数。

$$\text{サービスあたりのエントリ数}=(\text{バックエンド Pod 数})\times (\text{ポート/プロトコルの組み合わせ数})$$

推定合計マップサイズ：

$$\text{LB の合計エントリ数}\approx (\text{サービス数})\times (\text{サービスあたりの平均エンドポイント数})\times (\text{サービスあたりの平均ポート/プロトコルの組み合わせ数})$$

これは、サービスごとの Pod とポート/プロトコルエントリがほぼ正規分布していることを前提としています。著しい外れ値 (たとえば、多くのバックエンドを持つ 1 つのサービス) がある場合は、より詳細な見積もりを実行してください。