etcd v3.7.0のRangeStreamを実務で理解する：Kubernetes運用者のための導入・設計・注意点

Mon, 10 Aug 2026 11:43:47 +0000

はじめに

Kubernetesクラスタの安定性は、その裏側で動くetcdの挙動に大きく依存します。APIサーバーが遅い、リストリクエストでメモリが跳ねる、コントロールプレーンのCPUが慢性的に高い——こうした症状を追いかけていくと、最終的にetcdの読み取り経路にたどり着くことは珍しくありません。

2026年7月8日、SIG etcdからetcd v3.7.0のリリースが発表されました。今回のリリースは、単なるバージョン更新ではなく、大きな結果セットの扱い方そのものを変える機能が入っている点が特徴です。

この記事では、公式アナウンス（Kubernetes Blog）で明示されている内容を軸に、etcd v3.7.0の主要な変更点と、Kubernetes運用者が実務で何を気にすべきかを整理します。なお、公式ページで確認できなかった項目については、推測で補わず「未確認」と明記します。

etcd v3.7.0の目玉：RangeStream RPC

今回のリリースで最も注目されているのが、新しいRPCである RangeStream です。

公式アナウンスでは、従来の課題が次のように説明されています。

In etcd v3.6 and earlier, it is challenging to work with requests that return large result sets. The database would buffer the full result set before sending, leading to unpredictable latency and memory usage, both on the server and the client.

つまり、v3.6以前は大きな結果セットを返すリクエストにおいて、データベース側が結果セット全体をバッファしてから送信していたため、サーバー・クライアント双方でレイテンシとメモリ使用量が予測しづらくなっていた、ということです。

RangeStreamは、この結果セットをチャンク単位で受け取れるようにするRPCです。呼び出し側のアプリケーションが分割して結果を受け取れるため、レイテンシが下がり、バッファに使うメモリ量も予測しやすくなります。

実務上の意味

Kubernetesの文脈で考えると、影響が出やすいのは次のようなケースです。

大量のPodやSecret、ConfigMapを抱えるNamespaceに対する全件リスト
コントローラーやオペレーターの初期同期（初回List）
監視・バックアップ系ツールによる広範囲なキー走査

これらは「一発のリクエストで巨大なレスポンスが返る」という共通点があります。バッファリング方式ではこのタイミングでメモリのスパイクが起きますが、ストリーミングであれば、そのピークをならせる可能性があります。

具体的な使い方については、公式ドキュメントにgRPC呼び出し向けの解説（learning/api の RangeStream セクション）と、etcdctl 向けの解説（dev-guide/interacting_v3 の Read keys セクション）が用意されています。本記事執筆時点で、これらのページ内の具体的なコマンド例やオプション名までは筆者が確認できていないため、詳細な構文は未確認とします。実際に試す際は必ず公式ドキュメントを参照してください。

Kubernetes側の対応状況

公式アナウンスによると、RangeStreamはKubernetes v1.37において EtcdRangeStream というフィーチャーゲート経由で利用可能になる予定とされています。

ここで押さえておきたいのは、etcdをv3.7.0に上げただけではKubernetes APIサーバーが自動的にRangeStreamを使い始めるわけではないという点です。あくまでフィーチャーゲートによる制御であり、有効化の判断はクラスタ管理者側に委ねられます。フィーチャーゲートの既定値（デフォルトで有効か無効か）やアルファ・ベータの段階については、本記事では未確認です。

パフォーマンス改善：keys-only Rangeの最適化

もう一つ、運用者にとって効き目が大きいのが keys-only Rangeの最適化（PR #21791）です。

公式アナウンスの説明は次の通りです。

When processing a keys_only Range request or etcdctl get --keys-only, etcd reads solely from its in-memory index. It returns the matched keys without loading all serialized values from bbolt as it did previously.

keys_only を指定したRangeリクエスト、あるいは etcdctl get --keys-only の処理において、etcdはインメモリインデックスのみを読むようになりました。以前のようにbboltからシリアライズされた値をすべて読み込むことはしません。これにより、不要なバックエンド読み取りとメモリ使用量が削減されます。

ただし例外があり、SortTarget に VALUE が指定されている場合は、従来通りbboltからの読み込みが発生します。値でソートする以上、値を読まざるを得ないためです。

期待される効果として、公式アナウンスは次のように述べています。

Kubernetes users should see a significant decrease in overall CPU usage by the etcd members, compared with v3.6.

v3.6と比較して、etcdメンバー全体のCPU使用率が大きく下がることが見込まれる、という記述です。これは「Kubernetesユーザー」と明示されている点が重要で、Kubernetesのワークロード特性（keys-onlyに近い走査が多い）に合致した改善だと読めます。

なお、具体的に何パーセント削減されるかという数値は公式アナウンス上では示されていません。自環境での効果は、実測して判断する必要があります。

その他の変更点

公式アナウンスで確認できた変更点を整理します。

レガシーv2storeの削除

etcd v3.7では、起動が完全にv3storeベースになり、レガシーなv2 storeへの長年の依存が解消されました。これはコードベースの整理という意味合いが強い変更ですが、v2 API時代の資産を何らかの形で残している環境では、事前確認が必要になる可能性があります。v2store削除に伴う具体的な非互換や移行手順については未確認です。

Protobufの刷新

古くなっていたprotobufライブラリを、現在もサポートされているライブラリへ置き換える「modernization」が完了したと記載されています。

リースの改善

「faster and more reliable leases（より高速で信頼性の高いリース）」が挙げられていますが、筆者が確認できた範囲では詳細が示されていません。リースはKubernetesのリーダー選出やノードのハートビートに関わる要素であるため、具体的な変更内容は変更履歴（CHANGELOG-3.7.md）で確認することを推奨します。この記事の時点では未確認です。

依存ライブラリの更新

bbolt v1.5.1（ストレージエンジン）
raft v3.7.0（合意アルゴリズムライブラリ）

いずれもetcdの中核を成すコンポーネントであり、バージョンが上がっています。

導入・アップグレード時の注意点

ここからは、実際に本番クラスタへ適用する際に踏まえておきたい点をまとめます。

1. アップグレード手順は必ず公式を確認する

etcdのマイナーバージョンアップは、一段ずつ順に上げる（例：3.5 → 3.6 → 3.7）ことが原則とされてきました。ただし、v3.7における最小要件・許容されるスキップ可否・ロールバック手順については、本記事では未確認です。公式のアップグレードドキュメントとCHANGELOG-3.7.mdを必ず参照してください。

2. バックアップとリストア訓練を先に済ませる

v2store削除やprotobuf刷新といった内部構造に関わる変更が含まれるため、アップグレード前のスナップショット取得は必須です。加えて、取得したスナップショットから実際にリストアできることを事前に検証しておくべきです。バックアップは「取れていること」ではなく「戻せること」が価値です。

3. 効果測定の指標を先に決める

keys-only最適化によるCPU削減を評価するなら、アップグレード前に以下を記録しておきます。

etcdメンバーごとのCPU使用率（プロセス単位）
etcd_disk_backend_commit_duration_seconds などのディスク系メトリクス
APIサーバー側のリクエストレイテンシ（特にLIST操作）
メモリのピーク値（RSS）

前後比較ができなければ、「効果があったかどうか」を議論できません。

4. RangeStreamは段階的に有効化する

RangeStreamはetcd側の機能ですが、Kubernetesから使う場合はフィーチャーゲートを介します。フィーチャーゲートで制御できるということは、問題があれば無効化して切り戻せるということでもあります。まず開発・ステージング環境で有効化し、メモリとレイテンシの挙動を観測してから本番に展開する流れが安全です。

5. クライアント側の対応状況を確認する

RangeStreamは新しいRPCであるため、etcdを直接叩いているツール（バックアップツール、監視エージェント、自作のオペレーターなど）が自動的に恩恵を受けるわけではありません。クライアントライブラリ側の対応が必要です。手元のツールチェーンがどのetcdクライアントバージョンを使っているかを棚卸ししておくとよいでしょう。

まとめ

etcd v3.7.0の要点を整理します。

RangeStream RPC が追加され、大きな結果セットをチャンク単位で受け取れるようになりました。これによりレイテンシとメモリ使用量の予測可能性が向上します。Kubernetesではv1.37の EtcdRangeStream フィーチャーゲート経由で利用可能になる予定です。
keys-only Rangeの最適化 により、keys_only なリクエストはインメモリインデックスのみを参照するようになりました。公式は、v3.6比でetcdメンバーのCPU使用率が大きく下がることを見込んでいます（ただし SortTarget が VALUE の場合は例外）。
レガシーv2storeが削除され、起動が完全にv3storeベースになりました。protobufの刷新、bbolt v1.5.1およびraft v3.7.0への更新も含まれます。
リースの改善は挙げられているものの、詳細は本記事では未確認です。アップグレード手順の詳細、フィーチャーゲートの既定値、RangeStreamの具体的な構文も同様に未確認であり、公式ドキュメントとCHANGELOGでの確認が必要です。

大量のオブジェクトを抱えるクラスタや、コントロールプレーンのCPU・メモリが慢性的に厳しい環境では、検討する価値の高いリリースだと言えます。一方で、内部構造に踏み込んだ変更が含まれる以上、バックアップ検証と段階的な展開という基本を省略しないことが、結果的に一番の近道になります。

Etcd on AI2CORE - AI技術ブログ