デベロッパー

Compute Engine API マルチバージョニングの概要: 本番環境に影響を与えない予測可能な進化

2026年11月11日

https://storage.googleapis.com/gweb-cloudblog-publish/images/compute-engine-multi-version-hero.max-2500x2500.jpg

Michael Murstein

Software Engineer

※この投稿は米国時間 2026 年 11 月 5 日に、Google Cloud blog に投稿されたものの抄訳です。

本番環境の安定性を損なうことなく、インフラストラクチャをモダナイズしたいとお考えですか？Compute Engine の API マルチバージョニングが一般提供となり、まさにそれを実現できるようになりました。日付ベースの API バージョンにより、Compute Engine は /v1 API の堅牢な安定性を維持しながら、最新の API セマンティクス、強化されたレジリエンスの初期設定、改善されたデベロッパーエクスペリエンスを定期的に提供できるようになりました。

10 年以上にわたり、Google Compute Engine /v1 API は、数百万台の仮想マシン、Google Kubernetes Engine（GKE）クラスタ、大規模な AI インフラストラクチャの基盤となるコントロールプレーンとして機能してきました。Google Cloud で構築を行うプラットフォームチームやデベロッパーにとって、この単一の /v1 エンドポイントは、一度連携システムを構築すれば、その後何年も確実に動作し続けるという、絶大な安心感を提供してきました。

しかし、クラウドアーキテクチャの規模が拡大し高度化するにつれて、インフラストラクチャチームは大きなジレンマに直面するようになっています。まず、ミッションクリティカルな本番環境ワークロードでは、API の絶対的な安定性と厳格な後方互換性が求められます。その一方で、より安全なセキュリティの初期設定、強化されたリージョンのレジリエンス、機械で読み取り可能なエラーモデル、宣言型ツールと相性の良い最新 API などへの迅速なアクセスも求められています。しかし、こうした改善を既存の環境に直接導入すると、既存の自動化が機能しなくなるリスクがあります。新しいバージョニングモデルでは、本番環境のワークロードに手を加えることなく、独自のスケジュールで最新のセマンティクスを柔軟に導入できるため、自動化が正常に機能しなくなる事態を回避できます。

Compute Engine の日付ベースの API バージョン

これまで、Compute Engine はチャネルベースのバージョニング（CBV）を採用し、/v1（一般提供）、/beta、/alpha の 3 つの長期チャネルに依存していました。/v1 は、世界中のすべてのお客様が共有する単一の変更可能な本番環境のインターフェースであったため、動作の改善（直感的でないデフォルト設定の変更やエラー形式の最新化など）であっても、既存スクリプトが動かなくなるリスクや、複数年にわたる移行を強いるリスクを伴っていました。

Google の AIP-185 に準拠したインターフェースベースのバージョニング（IBV）により、Compute Engine では /v1 に加え、変更不可の日付ベースの API スナップショットが導入されます。

安定版（YYYY-MM-DD）: 予測可能な四半期ペース（2026-09-01 から開始）でリリースされます。各安定版は、一般提供されているすべての Compute Engine 機能とデフォルトの動作を、特定の時点で固定した API 仕様です。安定版は、公開後に互換性を破る変更が加えられることはありません。現時点でサポート終了日は設定されていません。
プレビュー版（YYYY-MM-DD-preview）: 迅速なリリースサイクル（2026-10-01-preview など）でリリースされるプレビュー版は、親となる安定版から分岐したもので、デベロッパーは今後の機能や API 設計に早期アクセスできます。検証やフィードバックを行える有効期間はあらかじめ 1 年間と決められています。
継続的な /v1 のサポート: 既存の /v1 API は引き続き完全にサポートされ、日付ベースのバージョンが指定されていない場合はデフォルトとして機能します。既存のアプリケーション、スクリプト、連携システムは、変更を加えることなくそのまま動作します。

ビルダーにとっての主なメリット

1. 安定性とお客様によるアップグレードの管理

従来の単一バージョンの API では、デフォルトの動作を変更すると、プラットフォームの機能進化をとるか、お客様のシステムの安定性をとるかというトレードオフが生じます。しかし、日付ベースのマルチバージョン管理では、お客様自身がアップグレードのタイミングを以下のように完全に制御できます。

既知の仕様に固定: REST を直接呼び出すユーザーと SDK ユーザーは、リクエストとレスポンススキーマが完全に固定されていることを前提に、特定のバージョン識別子（2026-09-01 など）をロックできます。
スケジュールに合わせたアップグレード: 四半期ごとに新しい安定版がリリースされ、デフォルト設定やリソーススキーマが更新された場合でも、チームはリリースノートを確認し、バージョン文字列を 1 か所変更してステージング環境でテストしたうえで、独自のペースで本番環境にロールアウトできます。
一貫したリソース URI: 日付ベースのバージョンでは、引き続き /compute/v1/ ベース URL パスが使用されます。ターゲットバージョンは、X-Goog-Api-Version HTTP ヘッダーまたは $apiVersion クエリパラメータで指定します。つまり、どのようなツールやサービスからアクセスしても、リソースの selfLink URI は変わりません。

読み込んでいます...

2. より安全な初期設定、強化されたレジリエンス、最新の API 標準

動作の変更を日付ベースの新しいバージョンに切り離すことで、Compute Engine はクラウドアプリケーションのレジリエンス、セキュリティ、自動化のしやすさを向上させる以下の改善を実現しています。

デフォルトでレジリエンスのあるグローバルクエリ: 従来の /v1 では、すべてのゾーンとリージョンを対象に AggregatedList を呼び出すと、returnPartialSuccess がデフォルトで false に設定されていました。つまり、呼び出し元が明示的にオプトインしていない場合、単一ゾーンで発生した一時的な問題によってグローバルリストリクエストが失敗することがありました。新しい日付ベースのバージョンでは、一部のデータのみの取得がデフォルトで有効になっているため、局所的なメンテナンスや障害が発生しても、グローバルフリートクエリはレジリエンスを維持できます。
対処可能で機械読み取り可能なエラー（AIP-193）: 日付ベースのバージョンでは、構造化された reason、domain、コンテキスト metadata（無効なバージョン識別子がリクエストされた場合に supported_versions のリストを返すなど）を含む標準化された google.rpc.ErrorInfo ペイロードが採用され、エラー文字列の脆弱な正規表現解析が不要になります。
セキュリティの強化と最小権限のハイジーン向上: 新しい API バージョンでは、/v1 で実行されている従来の自動化に影響を与えることなく、Compute Engine において過度に広範だった従来の IAM 権限チェックを強化し、より安全なデフォルト構成を導入できるようになります。
よりクリーンで宣言型ツールと相性の良い API 設計: マルチバージョニングにより、10 年前の複雑なリソーススキーマを最新の Google API 改善提案（AIP）へと進化させる明確な移行パスが提供されます。

3. クライアントライブラリ、gcloud、Terraform にわたるシームレスな導入

REST API を直接呼び出す場合でも、上位レベルのツールでインフラストラクチャを管理する場合でも、Compute Engine API のマルチバージョニングは、スムーズに動作するように設計されています。

インターフェース	マルチバージョニングの仕組み	ユーザーの責任
クライアントライブラリ（Python、Go、Java、Node.js、C#、Ruby、PHP）	各 SDK リリースは、/v1 パッケージ名前空間（`compute_v1`、`apiv1`）を保持しながら、特定の日付ベースの API バージョンに自動的にバインドされます。列挙型は、シームレスな前方互換性と後方互換性を実現するために文字列として表現されます。	通常どおりクライアントライブラリの依存関係をアップグレードします。インポートパスの書き換えは不要です。`-preview` SDK リリースを使用して、プレビュー機能をテストします。
Google Cloud CLI（gcloud）	`gcloud compute` は、バンドルされた安定版 API バージョンを対象とします。新しい gcloud preview compute コマンドグループは、バンドルされたプレビュー API バージョンを対象とします。	`gcloud` を最新の状態に保ちます。既存の `gcloud compute`、`beta`、`alpha` スクリプトはそのまま機能します。
Terraform（google と google-beta）	`google` プロバイダは安定した日付ベースの API を対象とし、`google-beta` は内部的にプレビュー API を対象とします。	Terraform プロバイダのバージョンをアップグレードすることで、新機能を活用できます。HCL スクリプトで API バージョンを手動で構成する必要はありません。
HTTP / REST の直接呼び出し	`-H "X-Goog-Api-Version: YYYY-MM-DD"` または `?$apiVersion=YYYY-MM-DD` を使用してアクティブなバージョンを選択し、バージョン固有のディスカバリドキュメントを取得できます。	HTTP クライアントでヘッダーまたはクエリパラメータを渡して、特定のバージョン（例: `2026-09-01`、`2026-10-01-preview`）を有効にします。