Antigravity CLI と SRE 拡張機能を使用して GKE の停止を調査し、美しい事後分析を作成する

1. はじめに

856ff52e60953a92.png

最終更新日: 2026 年 5 月 13 日

SRE 拡張機能を使用して GKE の停止を調査し、美しい事後分析を作成する

この SRE ワークショップへようこそ。このワークショップは、Google Cloud で SRE ハーネスを試してみたいオペレーターを対象としています。

この Codelab では、次の手順について説明します。

  1. よく知られているオープンソースの microservices-demo に基づいて GKE クラスタをインストールします。
  2. さまざまな方法で（より印象的な方法や、より微妙な方法など）中断を作成します。
  3. 次の部分では、Antigravity CLI（または同様のハーネス）+ SRE 拡張機能をインストールして使用します。
  4. 停止を調査して修正します。
  5. 事後検証を作成します。
  6. グラフ作成のスキルを使用して、視聴者が何がいつ起こったかを理解できるグラウンディングされたグラフを生成します。

Codelab の手順ごとの構造は次のとおりです。

Codelab 構造図

このワークショップの目標は次のとおりです。

  1. SRE 拡張機能の機能と、OneMCP の設定、Safe Executor、調査、事後検証の生成、グラフと CSV の要約など、SRE 拡張機能でできることを示します。
  2. 独自の Google Cloud シナリオを調査するためのスキルを習得できます。

マイルストーン 1: 環境の設定と停止のシミュレーション

このマイルストーンの目標は、GKE Autopilot で Kubernetes デモ アプリケーションを設定し、Antigravity CLI をインストールし、GKE クラスタの破損シナリオを人工的にトリガーして、本番環境のインシデントをシミュレートすることです。

マイルストーン 2: SRE 拡張機能による調査と緩和策

環境を破壊した後、SRE 拡張機能を備えたエージェント CLI ツールを使用して、インフラストラクチャを体系的に検出し、問題をトリアージし、修正の安全な実行パターンを実装し、クラスタの健全性を検証します。

マイルストーン 3: 事後分析とグラフの生成

解決したら、構造化されたインシデント事後分析ドキュメントを作成し、GCM（Google Cloud Monitoring）API を使用して実際の指標データを取得し、停止がいつどのように発生したかを記録するグラフを作成します。

作成するアプリの概要

この Codelab では、SRE 拡張機能を使用して GKE の停止を調査し、修正します。次のことを行います。

  • ネットワーク ポリシーのブロック、バグのあるカナリア デプロイ、ファイアウォール ルールの更新を使用して、GKE の停止をシミュレートします。
  • SRE 拡張機能を利用した CLI アシスタントを使用して、クラスタの停止をトリアージします。
  • Safe Executor パターンを使用して、修復手順を安全に実装します。
  • 包括的な事後分析ドキュメントを生成します。
  • Google Cloud Monitoring の時系列クエリを使用してインシデント指標をグラフ化します。

学習内容

  • SRE 拡張機能のスキルを使用して GKE Kubernetes リソースとポリシーを検査する方法。
  • Safe Executor パターンを活用して、エージェントが提案したコマンドを適切なリスク評価で実行する方法。
  • monitoring-graphs スキルを使用して、GCM から直接指標のグラウンディングされたグラフを生成する方法。
  • 構造化された事後検証形式でインシデントの調査結果を文書化する方法。

必要なもの

  • 課金が有効な Google Cloud プロジェクトが用意されていること。
  • コマンドライン ツール: gcloud、kubectl、terraform。
  • Antigravity CLI がローカルまたは Cloud Shell にインストールされている。
  • IDE（vscode、IntelliJ、RubyMine、Vim など）。

SRE 拡張機能とエージェント型 CLI を使用する理由

本番環境の停止はペースが速く、複数のサブシステム（Kubernetes リソース、VPC ネットワーク、Cloud Monitoring 指標、IAM 権限）間の関連付けが必要です。SRE 拡張機能を使用すると、エージェント CLI ヘルパー（Antigravity CLI など）が自律型の副操縦士として機能し、事前にコンパイルされたハンドブックを実行したり、モニタリング グラフをクエリしたり、安全な修復を提案したりできます。その間、人間のオペレーターは常に状況を把握できます。

2. 設定方法

この

自分のマシンで Codelab を実行するか、この Codelab をクラウドで実行する場合は Cloud Shell を起動します。

セルフペース型の環境設定

  1. Google Cloud Console にログインして、プロジェクトを新規作成するか、既存のプロジェクトを再利用します。Gmail アカウントも Google Workspace アカウントもまだお持ちでない場合は、アカウントを作成してください。

295004821bab6a87.png

37d264871000675d.png

96d86d3d5655cdbe.png

  • プロジェクト名は、このプロジェクトの参加者に表示される名称です。Google API では使用されない文字列です。いつでも更新できます。
  • プロジェクト ID は、すべての Google Cloud プロジェクトにおいて一意でなければならず、不変です（設定後は変更できません）。Cloud コンソールでは一意の文字列が自動生成されます。通常は、この内容を意識する必要はありません。ほとんどの Codelab では、プロジェクト ID（通常は PROJECT_ID と識別されます）を参照する必要があります。生成された ID が好みではない場合は、ランダムに別の ID を生成できます。または、ご自身で試して、利用可能かどうかを確認することもできます。このステップ以降は変更できず、プロジェクトを通して同じ ID になります。
  • なお、3 つ目の値として、一部の API が使用するプロジェクト番号があります。これら 3 つの値について詳しくは、こちらのドキュメントをご覧ください。
  1. 次に、Cloud のリソースや API を使用するために、Cloud コンソールで課金を有効にする必要があります。この Codelab の操作をすべて行って、費用が生じたとしても、少額です。このチュートリアルの終了後に請求が発生しないようにリソースをシャットダウンするには、作成したリソースを削除するか、プロジェクトを削除します。Google Cloud の新規ユーザーは、300 米ドル分の無料トライアル プログラムをご利用いただけます。

Cloud Shell を起動する

Google Cloud はノートパソコンからリモートで操作できますが、この Codelab では、Google Cloud Shell（Cloud 上で動作するコマンドライン環境）を使用します。

Google Cloud コンソールで、右上のツールバーにある Cloud Shell アイコンをクリックします。

Cloud Shell をアクティブにする

プロビジョニングと環境への接続にはそれほど時間はかかりません。完了すると、次のように表示されます。

環境が接続されていることを示す Google Cloud Shell ターミナルのスクリーンショット

この仮想マシンには、必要な開発ツールがすべて用意されています。永続的なホーム ディレクトリが 5 GB 用意されており、Google Cloud で稼働します。そのため、ネットワークのパフォーマンスと認証機能が大幅に向上しています。この Codelab での作業はすべて、ブラウザ内から実行できます。インストールは不要です。

3. 前提条件（インストール）

このチュートリアルでは、次のものをインストールする必要があります。

1. Python と uv

python と uv（Python のパッケージ マネージャー）。uv がインストールされていることを確認します。

$ curl -LsSf https://astral.sh/uv/install.sh | sh

uv を使用する理由任意の Python マネージャーを使用できますが、uv を使用すると、Python の ENV/PATH 設定がユーザーと Antigravity CLI で同じになるため、シェル エクスペリエンスは Antigravity CLI とほぼ同じになります。たとえば、virtualenv を使用すると、Antigravity CLI は環境を模倣するために「source .env/venv/bin/activate && my-original-command」のような処理を強制的に実行します。

2. Antigravity CLI（agy）

公式の Antigravity CLI（agy コマンド）をインストールするには、ターミナルを開いてブートストラップ インストーラを実行します。

macOS と Linux の場合:

$ curl -fsSL https://antigravity.google/cli/install.sh | bash

Windows（PowerShell）の場合:

irm https://antigravity.google/cli/install.ps1 | iex

このスクリプトは、OS とアーキテクチャを動的に検出し、最新のコンパイル済み

agy

バイナリをダウンロードして、PATH を構成します。変更を反映するには、ターミナルを再起動するか、シェル構成を再読み込みします。

efade99623113f1.png

認証

Google AI Studio API キーが必要です。

API キーをエクスポートします。

export GEMINI_API_KEY="your-api-key"

gcloud で認証します。

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
gcloud auth application-default login

作業環境を設定してマイクロサービスのデモ アプリケーションをデプロイする

マイクロサービスのデモ アプリケーションを複製し、Terraform を使用してインフラストラクチャとアプリケーションをデプロイしましょう。

ここで IDE（Visual Studio Code、IntelliJ、RubyMine など）を開き、フォルダを開きます。

# 1. Find an empty directory, and download this repo.
git clone https://github.com/GoogleCloudPlatform/microservices-demo.git
cd microservices-demo/terraform

# 2. Update project ID to your gcloud project ID
sed -i 's/<project_id_here>/YOUR_ACTUAL_PROJECT_ID/g' terraform.tfvars

# 3. Deploy the microservices-demo application in GKE autopilot
# If there is a prompt answer yes and continue. This step can take up to 10 mins for provision gke autopilot cluster and deploy microservices-demo application
terraform init
terraform plan
terraform apply

# 4. Verify the IP address of frontend-service to access the online-boutique application
kubectl get service frontend-external | awk '{print $4}'

# 5. Find an empty directory , and download this repo.
git clone https://github.com/palladius/sre-testing-suite.git
cd sre-testing-suite/test-scenarios/microservices-demo-gke/breakage-scenarios

設定をテストするには、http://[IP アドレス] にアクセスして online-boutique アプリを読み込みます。

sre-antigravity-cli-extension の作業環境を設定する

# 1. Install the SRE Extension plugin globally
git clone https://github.com/gemini-cli-extensions/sre.git ~/.gemini/config/plugins/sre-extension

# 2. Launch the Antigravity CLI (agy)
agy  # This runs the CLI under your current breakage-scenarios folder.
# Login with your corporate or personal account when prompted.

# 3. Within the agy agent prompt, configure your MCP servers and GCP project
Use the gcp-mcp-setup skill to setup my GCP project "<gcp_project_id>" with email jane-doe-sre@credible-company.com

4. ステップ 1: 停止をシミュレートする（破損シナリオ）

このステップでは、デプロイされた GKE クラスタを意図的に破損させて、実際の運用環境で発生するインシデントをシミュレートします。次の 3 つのシナリオから選択できます（または、3 つすべてを順番に試すこともできます）。

シナリオ 1: 購入手続きサービスのネットワーク ブロック（標準/Autopilot）

このシナリオでは、トラフィックの「ブラックホール」として機能する Kubernetes NetworkPolicy を適用して、フロントエンドと購入手続きサービス間の接続の切断をシミュレートします。

  1. シナリオ フォルダに移動します。
    cd breakage1-checkout
  2. 互換性の問題をトリガーします。
    ./break.sh
    これにより、default Namespace に update-checkout-from-frontend という名前の NetworkPolicy が作成されます。この NetworkPolicy は、ラベル app: frontend-checkout-test（存在しない）を持つ Pod からのトラフィックを除き、checkoutservice への上り（内向き）トラフィックを拒否します。
  3. Online Boutique のフロントエンドで商品の購入を試します。購入手続きページがハングアップするか、HTTP 500 エラーが表示されます。

シナリオ 2: バグのあるカナリア ロールアウト（Istio を使用した Autopilot）

このシナリオでは、Kubernetes カナリア デプロイを介してバグのあるバージョンのフロントエンドがロールアウトされる、不良なデプロイをシミュレートします。

  1. シナリオ フォルダに移動します。
    cd ../breakage2-canary
  2. 互換性の問題をトリガーします。
    ./break.sh
    これにより、環境変数に誤字脱字があるカナリア デプロイ frontend-canary がデプロイされます。PRODUCT_CATALOG_SERVICE_ADDR は productcatalogservice:3550 ではなく productcatalogservices:3550 に構成されています。
  3. フロントエンドのホームページを読み込みます。カナリア サービスがプロダクト カタログを解決できないため、ルーティングの重みに応じて失敗することがあります。

シナリオ 3: VPC ファイアウォール クラスタのブロック

このシナリオでは、GKE クラスタへの上り（内向き）トラフィックをすべてブロックする VPC ファイアウォール構成の誤りをシミュレートします。

  1. シナリオ フォルダに移動します。
    cd ../breakage3-firewall
  2. 互換性の問題をトリガーします。
    ./break.sh
    これにより、priority=1 とアクション DENY を使用して、ポート 80、443、8080 への上り（内向き）トラフィックをターゲットとする frontend-ingress-v2 という名前の VPC レベルのファイアウォール ルールが作成されます。
  3. Online Boutique ウェブサイトに完全にアクセスできなくなり、リクエストがタイムアウトします。

5. ステップ 2: SRE 拡張機能を使用した停止の調査

アプリケーションがダウンしたので、CLI アシスタント（Antigravity CLI）を使用して調査を開始しましょう。

  1. メインの破損シナリオ フォルダに戻り、CLI ヘルパーを起動します。
    cd ..
agy
  2. アシスタントにインフラストラクチャの検出と診断チェックの実行を依頼します。
    Investigate my GKE cluster for outages. Are all services healthy?
  3. エージェントの機能:
    • investigation-entrypoint スキルと gcp-playbooks スキルを有効にするため。
    • Kubernetes Pod、Deployment、Service を一覧表示して、失敗したターゲットを特定します。
    • ネットワーク ポリシー（シナリオ 1）、デプロイ構成（シナリオ 2）、ファイアウォール ルール（シナリオ 3）を検査します。
  4. シナリオ 1 の場合、エージェントは次のように報告する必要があります。🔴 インシデントが特定されました: update-checkout-from-frontend という名前の NetworkPolicy が checkoutservice Pod を分離しています。
  5. シナリオ 2 の場合、エージェントは 🔴 インシデントが特定されました: デプロイ frontend-canary が productcatalogservice:3550 ではなく無効なサービス エンドポイント productcatalogservices:3550 で構成されていることを報告する必要があります。
  6. シナリオ 3 の場合、エージェントは次のように報告する必要があります。🔴 インシデントが特定されました: VPC ファイアウォール ルール frontend-ingress-v2 が、ポート 80、443、8080 で上り（内向き）トラフィックを拒否しています。

6. ステップ 3: 停止の緩和と修正

CLI の Safe Executor パターンを使用して、停止を修復しましょう。

  1. CLI アシスタントに修正案の提案と適用を依頼します。
    Propose a fix for the outage and apply it.
  2. Safe Executor の動作:
    • コマンド候補を実行する前に、SRE 拡張機能は safe-sre-investigator スキルを使用して安全監査を実行します。
    • 実行するコマンドとリスクの評価（低、中、高など）が表示されます。
    • シナリオ 1 の場合、次のような提案が表示されます。
      kubectl delete networkpolicy update-checkout-from-frontend
    • シナリオ 2 では、次の提案が行われます。
      kubectl delete deployment frontend-canary
    • シナリオ 3 では、次の提案が行われます。
      gcloud compute firewall-rules delete frontend-ingress-v2 --quiet
  3. CLI からプロンプトが表示されたら、コマンドの実行を確定します。
  4. Online Boutique のホームページを更新して、ウェブサイトが復旧し、完全に機能していることを確認します。
  5. シェルで、対応するシナリオ チェック スクリプトを実行して、健全性を確認できます。
    ./breakage1-checkout/check.sh
# or ./breakage2-canary/check.sh
# or ./breakage3-firewall/check.sh

7. ステップ 4: インシデントの事後分析を生成する

SRE ライフサイクルの重要な部分は、チームがインシデントから学べるようにインシデントを文書化することです。postmortem-create スキルを使用して、これを自動化しましょう。

  1. CLI アシスタントに、事後調査ドキュメントの作成を依頼します。
    Create a postmortem for the checkout service network policy outage.
  2. エージェントは次の詳細情報を収集します。
    • インシデントの開始時間（CLI コマンドの履歴/ログから取得）。
    • 根本原因（ブロックしている NetworkPolicy）。
    • 軽減策として実施されたアクション。
  3. ワークスペースに postmortem.md という名前の新しい Markdown ファイルが書き込まれます。
  4. postmortem.md を開いて詳細を確認します。次のようなセクションが表示されます。
    • インシデントの概要
    • イベントのタイムライン
    • 根本原因分析（RCA）
    • アクション アイテム / 予防措置

8. ステップ 5: グラウンデッド指標グラフを追加する

事後分析をプロフェッショナルなものにするには、インシデントの視覚的な証拠が必要です。monitoring-graphs スキルを使用して、Google Cloud Monitoring（GCM）から時系列データを取得し、エラーの急増を示す PNG グラフを生成します。

  1. CLI ヘルパーにグラフを生成して、事後分析に追加するよう依頼します。
    Query GCM for frontend HTTP request error rates over the last 1 hour, generate a line chart, and embed it into postmortem.md.
  2. ボンネットの下:
    • エージェントは monitoring-graphs Python スクリプトを呼び出して Cloud Monitoring をクエリします。
    • 指標（kubernetes.io/container/restart_count や loadbalancing.googleapis.com/https/request_count など）を取得します。
    • matplotlib を使用してグラフをプロットし、incident_metrics.png として保存します。
    • 商品画像リンクを挿入して postmortem.md ファイルを更新します。
      ![Incident Metric Graph](incident_metrics.png)
  3. 生成された incident_metrics.png ファイルを開いて、クラスタがダウンした正確なタイミングとトラフィックが正常に戻ったタイミングを示すグラフを確認します。

9. ステップ 6: クリーンアップ

Google Cloud アカウントに不要な料金が発生しないように、デプロイされたインフラストラクチャをクリーンアップしましょう。

  1. terraform フォルダに移動します。
    cd ../../microservices-demo/terraform
  2. destroy コマンドを実行します。
    terraform destroy -auto-approve
  3. すべての GCP GKE リソースが正常に削除されたことを確認します。

10. 完了

GKE クラスタの破損と停止の調査に関する Codelab を完了しました。

学習した内容:

  • 10 階層の Online Boutique マイクロサービス デモを GKE にデプロイしました。
  • 実際の SRE 停止（ネットワーク ポリシーの拒否、バグのあるカナリア リリース、VPC ファイアウォール ルールの拒否）を 3 つシミュレートしました。
  • SRE Extension for Antigravity CLI を使用して、停止を検出して診断しました。
  • Safe Executor パターンを活用して、修復コマンドを確認して実行しました。
  • プロフェッショナルな Markdown の事後分析を作成しました。
  • Cloud Monitoring の指標をクエリして、グラウンディングされたインシデント グラフを自動的に生成して埋め込みます。

CLI エージェントの拡張の詳細については、SRE 拡張機能の GitHub ページをご覧ください。