Kubernetes v1.33、APIサーバーのメモリ使用量削減のためストリーミングリストレスポンスを導入

2025年5月のKubernetes Blogの投稿で、メンテナのMarek Siarkowicz氏とWei Fu氏は、Kubernetes v1.33における主要なアーキテクチャ変更について説明しました。このアップデートでは、大規模データセットを処理する際のAPIサーバーのメモリ消費を大幅に削減するために設計された、Listレスポンス向けのストリーミングエンコーディング機能が導入されました。この改善により、広範なリソースリストの取得が以前はアウトオブメモリエラーを引き起こすリスクがあった大規模クラスタにおける長年の安定性問題に対処しています。

何が起きたか

大規模なKubernetesクラスタの運用には、常にデータのアクセシビリティとリソース消費のトレードオフ管理が伴ってきました。最も持続的な課題の一つは、クラスタ状態から大量のデータセットを取得するListリクエストの処理でした。以前のバージョンでは、APIサーバーはクライアントに送信する前に、応答全体をメモリ内の単一の連続したブロックとしてシリアライズしていました。HTTP/2では転送のために応答をより小さなフレームに分割できますが、基盤となるサーバーは全体の転送が完了するまで完全なデータバッファをメモリに保持していました。これは、ネットワークの混雑により転送が遅くなった場合、数百メガバイトのメモリが数秒または数分間ロックされたままになることを意味します。

この非効率性は、スケールアップした際に深刻になりました。複数の大きなListリクエストが同時に発生すると、累積メモリ使用量が急激にスパイクし、クラスタの安定性を損なうアウトオブメモリー（OOM）状況につながる可能性がありました。Goのencoding/jsonパッケージがメモリを管理する方法によって、問題はさらに複雑化しました。同パッケージはバッファを再利用するためにsync.Poolを使用しており、一定のワークロードには効率的ですが、断続的な大容量応答には問題があります。一度大きな応答によってメモリプールが拡張されると、その過剰サイズのバッファは subsequent な小規模リクエスト用に予約されたまま残り、ガベージコレクションを防ぎ、重い負荷が去った後も長い間メモリ使用量を人工的に高い水準に保ちます。

仕組み

新しいストリーミングエンコーダーは、コレクション構造内のデータの大部分を含むItemsフィールドに焦点を当てることで、APIサーバーがListレスポンスを処理する方法を変更します。配列全体をモノリシックなブロックとしてエンコードする代わりに、サーバーは各アイテムを個別に処理および送信します。各チャンクがクライアントに送信されるたびに、関連付けられたメモリは直ちに解放されます。この増分的なアプローチにより、リスト内のオブジェクトの総数に関係なく、APIサーバーのメモリフットプリントが予測可能かつ管理可能な状態で維持されます。

Kubernetesオブジェクトは通常、etcd内で1.5 MiBに制限されているため、ストリーミングにより個々のメモリ割り当ては小さく抑えられます。システムは、有効化する前にGoのstructタグを検証することで厳格な後方互換性を維持し、出力が元のエンコーダーとバイト単位で同一であることを保証します。標準的なエンコーディングはItems以外のすべてのフィールドを引き続き処理するため、クライアントはコードを変更する必要はなく、基盤メカニズムが変化したことに気づく必要もありません。このシームレスな統合は、組み込みリストやCustom Resource UnstructuredListsなど、すべてのKubernetes Listタイプをサポートします。

主要な詳細

• バージョン: この機能は2025年5月に発表されたKubernetes v1.33で導入されました。
• メモリ削減: ベンチマークでは、大規模なリスト操作においてメモリ使用量が70〜80GBからわずか3GBへと低下し、20倍の改善が見られました。
• メカニズム: エンコーダーは配列全体を一度にシリアライズするのではなく、Itemsフィールド内の個々のアイテムをストリーム配信します。
• 互換性: クライアント側の変更は不要です。出力は以前のバージョンとバイト単位で一貫しています。
• トリガー: ストリーミングエンコーダーは、安全性を確保するためのstructタグの厳格な検証後にのみアクティブになります。
• 適用範囲: 標準リソースおよびカスタムリソースを含む、すべてのKubernetes Listタイプに適用されます。

なぜ重要か

大規模なKubernetesインフラストラクチャを構築・保守するエンジニアにとって、このアップデートは信頼性とコスト効率に直接影響します。kube-apiserverでの高メモリ使用量は、ピークロードに対応するためにハードウェアを過剰にプロビジョニングすることをチームに強いることが多く、運用コストを増加させます。大きなListリクエストのメモリフットプリントをこれほど大幅に削減することで、組織はパフォーマンスを犠牲にすることなく、より軽量なコントロールプレーンを運用できます。また、予期せぬOOMキルのリスクも低減され、これはサービス障害の原因となり、インシデント対応中のデバッグ作業を複雑にする可能性があります。

さらに、この変更は負荷下でのクラスタ挙動の予測可能性を向上させます。監視ツール、コントローラー、CI/CDパイプラインが多数のリソースを頻繁にリストする環境では、従来のメモリスパイクが連鎖的な障害を引き起こす可能性がありました。ストリーミングエンコーディングにより、これらの操作は転送遅延中に過度なメモリを保持しなくなります。これにより、APIサーバーはより多くの同時リクエストとより大きなデータセットをスムーズに処理できるようになり、数千ノードや数万ポッドをサポートするためにクラスタをスケールしやすくなります。

実施できること

• ストリーミングエンコーダーの恩恵を受けるために、コントロールプレーンをKubernetes v1.33以降にアップグレードしてください。
• 大きなList操作中のkube-apiserverのメモリ使用量を監視し、ピーク消費量の減少を観察してください。
• 大きなList呼び出しを実行するカスタムコントローラーやオペレーターを確認し、ストリーミングレスポンスを適切に処理しているか検証してください（ただし、コード変更は必須ではありません）。
• APIサーバーの負荷軽減により、より厳しいスケーリング閾値を設定できる可能性があるため、クラスタのHorizontal Pod Autoscaler設定を確認してください。
• バイト単位の互換性により問題は防止されるはずですが、監視スタックがAPIレスポンス解析のために固定バッファサイズに依存していないか確認してください。
• OOMリスクを緩和するために以前にメモリを過剰にプロビジョニングしていた場合は、kube-apiserverのリソース要求と制限の調整を検討してください。