インテントからインフラストラクチャへ: エージェント主導の GKE への移行

1. はじめに

この Codelab では、AI エージェントを使用して複雑なインフラストラクチャの移行を自動的に行う方法について学習します。Kubernetes マニフェストを手動で作成したり、自動化スクリプトを実行したりする代わりに、自然言語でインテント を表現します。エージェントはModel Context Protocol（MCP） と Gemini Cloud Assist サーバーを使用して、構成を生成して適用します。

重要: この Codelab では、現在限定公開プレビュー版の Gemini Cloud Assist（GCA）MCP サーバーについて説明します。すべての機能にアクセスできない場合でも、Codelab を進めることができます。ただし、変更機能（特に invoke_operation ツール）へのアクセス権が付与されていない場合、エージェントは変更を自動的に適用できません。その場合は、生成された Kubernetes マニフェストを手動で適用する必要があります。詳細については、Google のアカウント担当者にお問い合わせください。

GCA MCP サーバーの機能

GCA MCP サーバーは、エージェントにいくつかの専用ツールを提供します。

• ask_cloud_assist: これは、Google Cloud Platform のアシスタンスと Gemini Cloud Assist エージェントの主要なインターフェースです。Gemini Cloud Assist のすべての機能にこのツールからアクセスできます。また、他の MCP ツールの機能も含まれています。
• design_infra: Google Cloud Platform でインフラストラクチャを設計および構築するためのワークフローをサポートします。
• investigate_issue: Google Cloud でのトラブルシューティングのワークフローをサポートします。調査リソースを使用して、迅速なトラブルシューティングや詳細なトラブルシューティングを行うことができます。
• invoke_operation: Google Cloud でのリソースの作成、更新、削除のワークフローをサポートします。このツールは、エージェント アクションが有効になっている場合にのみ機能します。Gemini Cloud Assist での書き込みオペレーションは、このツールの呼び出しによってのみ実行できます。
• optimize_costs: Google Cloud の費用の分析、追跡、最適化のワークフローをサポートします。費用の詳細な内訳を提供し、アイドル状態または使用率の低いリソースを見つけて、費用対効果を高める機会を特定します。

まず、GKE クラスタとダウンロードしたモデルを含む、事前ステージングされた環境から始めます。次に、gemini-cli を使用して、Cloud Run から GKE にワークロードを移行し、ストレージ バケット内のステージングされたモデルを使用して vLLM で Gemma 推論インスタンスを起動するようにエージェントに指示します。

演習内容

• Terraform を使用して GKE クラスタをステージングし、Gemma モデルをダウンロードします。
• エージェント ルールと MCP サーバーを使用して gemini-cli を構成します。
• 特定の自然言語プロンプトを使用して、完全な移行とデプロイを行うようにエージェントに指示します。
• エージェントによって実行されたデプロイを確認します。

必要なもの

• ウェブブラウザ（Chrome など）。
• 課金を有効にした Google Cloud プロジェクト。
• Hugging Face トークン（ステージング フェーズで Gemma モデルをダウンロードするために必要）。

この Codelab は、初心者を含むあらゆるレベルのデベロッパーを対象としています。

所要時間: 45 ～ 60 分。

2. 始める前に

Google Cloud プロジェクトを作成または選択する

1. Google Cloud コンソールで、Google Cloud プロジェクトを作成または選択 します。
2. Cloud プロジェクトで課金が有効になっていることを確認します。

Cloud Shell の起動

1. Google Cloud コンソールの上部にある「Cloud Shell をアクティブにする 」アイコンをクリックします。
2. 認証を検証します。

gcloud auth list

3. プロジェクトを確認します。

gcloud config get project

4. 必要に応じて設定します。

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

API を有効にする

次のコマンドを実行して、必要な API をすべて有効にします。

gcloud services enable \
  run.googleapis.com \
  container.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com

また、Gemini Cloud Assist MCP サービスを有効にします。

gcloud beta services mcp enable geminicloudassist.googleapis.com

3. 環境をステージングする

このステップでは、カスタム chatbot イメージをビルドし、GKE クラスタを作成して、Gemma モデルを Cloud Storage バケットにダウンロードして、環境を準備します。

多くの場合、組織は Gemini API から始めますが、後でより詳細な制御やカスタマイズを行うため、またはビジネスに固有のファインチューニングされたバージョンを使用するために、セルフホスト型モデルに移行することにします。この Codelab では、Gemma を GKE でホストできる強力なオープンモデルの例として使用します。Cloud Storage バケットにステージングすることで、クラスタで使用できるようになります。

デモアセットをダウンロードする

GitHub リポジトリから特定のフォルダのクローンを作成します。

git clone --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/next-26-keynotes.git
cd next-26-keynotes
git sparse-checkout set devkey/intent-to-infrastructure
cd devkey/intent-to-infrastructure

chatbot イメージをビルドする

インフラストラクチャをプロビジョニングする前に、カスタム chatbot イメージをビルドして Artifact Registry に push する必要があります。このイメージは、次のステップで Cloud Run によって使用されます。

1. asia-southeast1 に chatbot-repo という名前の Artifact Registry リポジトリを作成します。

   gcloud artifacts repositories create chatbot-repo \
       --repository-format=docker \
       --location=asia-southeast1 \
       --description="Chatbot Docker repository"
   

2. src ディレクトリに移動します。

   cd src
   

3. Cloud Build を使用してイメージをビルドして push します。

   gcloud builds submit --config cloudbuild.yaml \
       --substitutions=_LOCATION="asia-southeast1",_REPOSITORY_ID="chatbot-repo",_IMAGE_NAME="chatbot",_IMAGE_TAG="latest"
   

4. プロジェクトのルートに戻ります。

   cd ..
   

基本インフラストラクチャをプロビジョニングする

terraform ディレクトリに移動し、ステップ 1 を実行して GKE クラスタを作成します。

cd terraform
./deploy.sh demo step1 apply

注: deploy.sh の実行時に「Permission denied」エラーが表示された場合は、chmod +x deploy.sh を実行して実行可能にする必要がある場合があります。

このスクリプトは Terraform を使用して基本インフラストラクチャをプロビジョニングします。VPC、GKE クラスタ、サービス アカウントを作成し、ビルドした chatbot イメージを使用して最初の Cloud Run サービスをデプロイします。

このプロセスでは、Terraform がプランを表示し、確認を求めます。yes と入力して承認し、続行する必要があります。

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

プロセス全体が完了するまでに 15 ～ 20 分かかることがあります。

デプロイが完了したら、ターミナルに表示された Terraform 出力で cloud_run_url を探します。URL をクリックして、ブラウザで chatbot を開きます。これで、現在 Gemini 2.5 Flash に対して実行されている chatbot を操作できます。

モデルをダウンロードする

このステップでは、Gemma モデルを Cloud Storage バケットにステージングします。マネージド Gemini API から開始しますが、カスタム ファインチューニング モデルや別のカスタム オープンモデルを実行することもできます。また、セキュリティやコンプライアンス上の理由から、モデルの実行を独自のクラスタ内で管理することもできます。ここでモデルをステージングすると、マネージド Gemini API から GKE のセルフホスト型モデルへの移行が可能になります。

ステップ 2 を実行して、Gemma モデルを GCS バケットにダウンロードします。Hugging Face トークンが必要です。このプロセスは GKE クラスタで実行され、Hugging Face からモデルをダウンロードしてバケットにアップロードするまでに約 15 分かかります（トラフィックによって異なります）。

./deploy.sh demo step2 apply -var="hf_token=<YOUR_HF_TOKEN>"

この Terraform コマンドは、ダウンロードを処理する Kubernetes Job を GKE クラスタに作成します。ジョブが実行されている限り、Terraform スクリプトはアクティブなままになります。

別のシェル セッションから進行状況をモニタリングする場合や、実行後に完了したことを確認する場合は、次のコマンドを実行します。

kubectl get jobs

4. エージェントと MCP を設定する

移行を行うエージェントを構成します。gemini-cli を使用し、環境を操作するためのルールを設定します。

Gemini Cloud Assist（GCA）MCP サーバー は、このフローの重要なコンポーネントです。クライアントサイド エージェントと Google Cloud の間のブリッジとして機能し、調査の実行、プラン（gcloud コマンドや kubectl コマンドなど）の生成、クラウド プロジェクト内のリソースへの変更の直接適用を可能にします。

roles/geminicloudassist.user などの MCP ツールを呼び出すことができるロールが付与されていることを確認してください。後で権限の問題が発生した場合は、Cloud Assist の IAM ロールの構成に関するドキュメントをご覧ください。

Gemini Cloud Assist をサードパーティ ツールと統合する手順の詳細については、MCP を使用して Gemini Cloud Assist をサードパーティ ツールと統合するをご覧ください。

Gemini Cloud Assist 拡張機能をインストールする

1. 次のコマンドを実行して、アプリケーションのデフォルト認証情報（ADC）を使用して認証します。

gcloud auth application-default login

2. MCP サーバーを Gemini CLI 拡張機能としてインストールします。

gemini extensions install https://github.com/GoogleCloudPlatform/gemini-cloud-assist-mcp

注: このコマンドは、MCP サーバーと専用のスキルをインストールします。このスキルは、Gemini CLI が Cloud Assist ツールを使用する適切なコンテキストを理解するのに役立ちます。

3. スキルが正常にインストールされたことを確認します。gemini を起動し、次のコマンドを実行してアクティブなスキルを一覧表示します。

/skills list

リストに Gemini Cloud Assist に関連するスキルが表示されていることを確認します。exit と入力して Cloud Shell プロンプトに戻ります。

Gemini Cloud Assist で変更を有効にする

エージェントがインフラストラクチャに変更を適用できるようにするには、Gemini Cloud Assist UI で変更機能を有効にする必要があります。

1. Google Cloud コンソール ウィンドウの右上にある Gemini ロゴをクリックして、Gemini Assist サイドバーを開きます。
   
   
2. サイドバーに表示されている必要な API を有効にします。
   
   
3. サイドバーの設定に移動し、[Cloud Assist がアクションを実行できるようにする] をオンにします。
   
   
   

エージェント ルールを構成する

プロジェクト ディレクトリには、フォルダ（intent-to-infrastructure）のルートにカスタム gemini.md ファイルが含まれています。このファイルには、エージェントが正しいツールを使用するためのルールが含まれています。

このファイルがディレクトリに存在することを確認します。Terraform ファイル、アプリケーション コード、gemini.md ルール ファイルにアクセスできるように、このディレクトリから gemini を実行する必要があります。

5. ステップ 1: chatbot を GKE に移行する

エージェントを使用して、移行の最初の部分（chatbot アプリケーションを Cloud Run から GKE に移動する）を行います。

1. intent-to-infrastructure ディレクトリのルートから gemini を起動します（gemini.md にアクセスできることを確認します）。
2. まず、エージェントにプロジェクトを探索して、アプリケーションとインフラストラクチャを把握してもらいます。次のプロンプトを入力します。

Tell me about the app and infrastructure in this project

エージェントはディレクトリ内のファイルを読み取り、chatbot アプリケーションと Terraform 構成の概要を示します。

3. 次のプロンプトを使用して、移行を行うようにエージェントに指示します。

Convert my Cloud Run service to the equivalent on GKE.

4. エージェントの対応:
   • ask_cloud_assist ツールを使用してコンテキストを把握します。
   • design_infra ツールを使用して、chatbot アプリケーションの Kubernetes YAML を生成します。
   • 「この構成を適用しますか？」と尋ねます。

注: gemini がツールを初めて使用しようとすると、MCP サーバーから提供されたツールにアクセスする権限を求められます。[許可] を選択して、エージェントが続行できるようにします。

5. yes と応答して変更を適用します。エージェントは invoke_operation を使用して、リソースを GKE クラスタにデプロイします。

ステップ 1 を確認する

1. サービスの一覧を取得します。

kubectl get services

chatbot アプリケーションのサービスが実行されていることがわかります。

2. chatbot にアクセスするようにサービスをポート転送します。

kubectl port-forward svc/chatbot-service 8080:80

（注:

chatbot-service

を実際のサービス名に置き換えます）。

chatbot をテストします。Gemini API（Cloud Run で構成されている）を使用して応答する必要があります。

6. ステップ 2: vLLM 経由で Gemma をデプロイして再接続する

このステップでは、エージェントを使用して、セルフホスト型 Gemma モデルを GKE にデプロイし、アプリケーションを再接続します。

1. 同じ gemini セッションで、次のプロンプトを入力します。

Now that the chatbot is on GKE, add a vLLM service running the Gemma model from my storage bucket in the same cluster. Make sure to give the vLLM service at least 10 minutes to start up to account for loading the large model. Then, update the chatbot service to reference this vLLM service instead of the Gemini API.

2. エージェントの対応:
   • design_infra を使用して、vLLM デプロイとサービスの YAML を生成します。
   • chatbot デプロイ YAML を更新して、環境変数（または構成）を Gemini API ではなく新しい vLLM サービスを指すように変更します。
   • 変更を適用するための確認を求めます。
3. yes と応答して変更を適用します。

ステップ 2 を確認する

1. もう一度 Pod のリストを取得します。

kubectl get pods

chatbot と vLLM の両方の Pod が表示されます。

注: vLLM Pod が Running 状態になった後でも、モデルサイズが大きいため、サーバーがストレージ バケットからモデルの重みを完全に読み込んでサービングを開始するまでに最大 10 分かかることがあります。読み込みの進行状況は、ログを確認してモニタリングできます。

kubectl logs -f deployment/gemma-vllm -c vllm-server

2. vLLM の準備ができたら、必要に応じて chatbot サービスを再度ポート転送してテストします。これで、セルフホスト型 Gemma モデルが搭載されました。

7. クリーンアップ

Google Cloud アカウントに継続的に課金されないようにするには、この Codelab で作成したリソースを削除します。

基本インフラストラクチャの破棄コマンドを実行します。

cd terraform
./deploy.sh demo step1 destroy

また、ローカル環境をクリーンアップする場合は、Gemini Cloud Assist 拡張機能をアンインストールまたは無効にすることもできます。gemini extensions uninstall または gemini extensions disable の後に拡張機能名を指定します。

8. 次のステップ

Gemini Cloud Assist と上級者向け機能の詳細については、次のリソースをご覧ください。

• Cloud Assist の調査に関するトラブルシューティング
• プロアクティブ モードを設定する

9. 完了

おめでとうございます！自然言語と MCP を使用して、エージェント主導のワークロードの GKE への移行を正常に完了しました。