adk-deploy-guide

ADK デプロイガイド

スキャフォールド済みのプロジェクトですか？ このガイドでは、make コマンドを使用してください。Terraform、Docker、デプロイを、テスト済みのパイプラインにまとめています。

スキャフォールドされていませんか？ 以下のクイックデプロイ、またはADK のデプロイに関するドキュメントを参照してください。 本番環境のインフラストラクチャには、/adk-scaffold でスキャフォールドしてください。

リファレンスファイル

詳しい情報については、references/ にある以下のリファレンスファイルを参照してください。

• cloud-run.md — スケーリングのデフォルト、Dockerfile、セッションタイプ、ネットワーキング
• agent-engine.md — deploy.py CLI、AdkApp パターン、Terraform リソース、デプロイメタデータ、CI/CD の違い
• gke.md — GKE Autopilot クラスター、Terraform で管理する Kubernetes リソース、Workload Identity、セッションタイプ、ネットワーキング
• terraform-patterns.md — カスタムインフラストラクチャ、IAM、状態管理、リソースのインポート
• event-driven.md — カスタムの fast_api_app.py エンドポイントを介した Pub/Sub、Eventarc、BigQuery Remote Function のトリガー

オブザーバビリティ： Cloud Trace、プロンプトと応答のロギング、BigQuery Analytics、サードパーティ統合については、adk-observability-guide スキルを参照してください。

---

デプロイ先の選択基準

要件に基づいて、適切なデプロイ先を選択してください。

基準	Agent Engine	Cloud Run	GKE
言語	Python	Python	Python（カスタムコンテナを介してその他の言語にも対応）
スケーリング	マネージド自動スケーリング（最小／最大数、同時実行数を設定可能）	完全に設定可能（インスタンスの最小／最大数、同時実行数、CPU 割り当て）	Kubernetes の完全なスケーリング（HPA、VPA、ノードの自動プロビジョニング）
ネットワーキング	VPC-SC と PSC に対応	VPC を全面的にサポート、直接 VPC エグレス、IAP、イングレスルール	Kubernetes のネットワーキングを全面的にサポート
セッション状態	ネイティブの VertexAiSessionService（永続的、マネージド）	インメモリ（開発時）、Cloud SQL、または Agent Engine セッションバックエンド	インメモリ（開発時）、Cloud SQL、または Agent Engine セッションバックエンド
バッチ／イベント処理	非対応	Pub/Sub、Eventarc、BigQuery 用の /invoke エンドポイント	カスタム（Kubernetes Jobs、Pub/Sub）
コストモデル	vCPU 時間＋メモリ時間（アイドル時は課金されません）	インスタンス秒あたり＋最小インスタンスのコスト	ノードプールのコスト（常時稼働または自動プロビジョニング）
セットアップの複雑さ	低（マネージド、エージェント専用に設計）	中（Dockerfile、Terraform、ネットワーキング）	高（Kubernetes の専門知識が必要）
最適な用途	マネージドインフラストラクチャ、運用を最小限に抑えたい場合	カスタムインフラ、イベント駆動型ワークロード	Kubernetes を全面的に制御したい場合

要件に合うデプロイ先をユーザーに確認してください。それぞれトレードオフは異なりますが、どれも本番環境に適した選択肢です。

---

クイックデプロイ（ADK CLI）

Agent Starter Pack のスキャフォールドを使用していないプロジェクト向けです。Makefile、Terraform、Dockerfile は不要です。

# Cloud Run
adk deploy cloud_run --project=PROJECT --region=REGION path/to/agent/

# Agent Engine
adk deploy agent_engine --project=PROJECT --region=REGION path/to/agent/

# GKE (requires existing cluster)
adk deploy gke --project=PROJECT --cluster_name=CLUSTER --region=REGION path/to/agent/

すべてのコマンドで --with_ui を指定すると、ADK 開発 UI をデプロイできます。Cloud Run では、-- の後に追加の gcloud フラグも指定できます（例：-- --no-allow-unauthenticated）。

すべてのフラグについては、adk deploy --help またはADK のデプロイに関するドキュメントを参照してください。

CI/CD、オブザーバビリティ、本番環境のインフラストラクチャには、/adk-scaffold でスキャフォールドし、以下のセクションを使用してください。

---

開発環境のセットアップとデプロイ（スキャフォールド済みプロジェクト）

開発インフラのセットアップ（任意）

make setup-dev-env は deployment/terraform/dev/ で terraform apply を実行します。これにより、次のサポート用インフラがプロビジョニングされます。

• サービスアカウント（エージェント用の app_sa。実行時の権限に使用）
• Artifact Registry リポジトリ（コンテナイメージ用）
• IAM バインディング（アプリの SA に必要なロールを付与）
• テレメトリリソース（Cloud Logging バケット、BigQuery データセット）
• deployment/terraform/dev/ で定義されたカスタムリソース

この手順は任意です。make deploy は、この手順を行わなくても動作します（Cloud Run が gcloud run deploy --source . を通じてサービスをその場で作成します）。ただし、この手順を実行すると、適切なサービスアカウント、可観測性、IAM の設定が利用できます。

make setup-dev-env

注: make deploy は Terraform で作成された app_sa を自動的には使用しません。--service-account を明示的に指定するか、Makefile を更新してください。

デプロイ

1. 人間に確認します：「評価スコアがしきい値を満たし、テストも合格しました。開発環境にデプロイしてもよいですか？」
2. 明示的な承認を待ちます
3. 承認されたら、make deploy を実行します

重要：人間の明示的な承認なしに、make deploy を実行してはいけません。

---

本番環境へのデプロイ — CI/CD パイプライン

適した用途： 本番アプリケーション、ステージングから本番環境への昇格を必要とするチーム。

前提条件：

1. プロジェクトが gitignore 対象のフォルダー内にないこと
2. ユーザーがステージング用と本番用の GCP プロジェクト ID を指定すること
3. GitHub リポジトリ名とオーナー

手順：

1. プロトタイプの場合は、まず Agent Starter Pack CLI を使って Terraform/CI-CD ファイルを追加します（すべてのオプションについては /adk-scaffold を参照してください）。

   uvx agent-starter-pack enhance . --cicd-runner github_actions -y -s
   

2. GitHub CLI にログインしていることを確認します。

   gh auth login  # (skip if already authenticated)
   

3. setup-cicd を実行します。

   uvx agent-starter-pack setup-cicd \
     --staging-project YOUR_STAGING_PROJECT \
     --prod-project YOUR_PROD_PROJECT \
     --repository-name YOUR_REPO_NAME \
     --repository-owner YOUR_GITHUB_USERNAME \
     --auto-approve \
     --create-repository
   

4. コードをプッシュしてデプロイを開始します

setup-cicd の主なフラグ

フラグ	説明
--staging-project	ステージング環境用の GCP プロジェクト ID
--prod-project	本番環境用の GCP プロジェクト ID
--repository-name / --repository-owner	GitHub リポジトリ名とオーナー
--auto-approve	Terraform のプラン確認プロンプトをスキップ
--create-repository	GitHub リポジトリが存在しない場合に作成
--cicd-project	CI/CD インフラ用の別の GCP プロジェクト。既定では本番プロジェクト
--local-state	GCS ではなくローカルに Terraform の状態を保存（references/terraform-patterns.md を参照）

すべてのフラグのリファレンス（Cloud Build のオプション、開発用プロジェクト、リージョンなど）については、uvx agent-starter-pack setup-cicd --help を実行してください。

CI/CD ランナーの選択

ランナー	メリット	デメリット
github_actions（既定）	PAT 不要、gh auth を使用、WIF ベース、完全自動化	GitHub CLI の認証が必要
google_cloud_build	GCP とのネイティブ統合	対話形式のブラウザー認証が必要（プログラムモードでは PAT とアプリのインストール ID でも可）

認証の仕組み（WIF）

どちらのランナーも**Workload Identity Federation（WIF）**を使用します。GitHub/Cloud Build の OIDC トークンは GCP Workload Identity Pool によって信頼され、cicd_runner_sa の偽装が許可されます。長期間有効なサービスアカウントキーは不要です。setup-cicd の Terraform が、プール、プロバイダー、SA バインディングを自動的に作成します。認証に失敗した場合は、CI/CD Terraform ディレクトリで terraform apply を再実行してください。

CI/CD パイプラインのステージ

パイプラインには3つのステージがあります。

1. CI（PR チェック） — プルリクエスト時にトリガーされます。単体テストと統合テストを実行します。
2. ステージング CD — main へのマージ時にトリガーされます。コンテナをビルドし、ステージングにデプロイして、負荷テストを実行します。

   パスフィルター： ステージング CD では paths: ['app/**'] を使用しており、app/ 配下のファイルが変更された場合にのみトリガーされます。setup-cicd の実行後、最初のプッシュでは app/ 内のファイルを変更しない限り、ステージング CD はトリガーされません。プッシュ後に何も起きない場合は、これが理由です。

3. 本番 CD — workflow_run を介して、ステージングへのデプロイが成功した後にトリガーされます。本番環境へのデプロイ前に手動承認が必要になる場合があります。

   承認方法： GitHub Actions → 本番ワークフローの実行 → 「Review deployments」をクリック → 保留中の production 環境を承認します。これは GitHub の環境保護ルールであり、カスタムの仕組みではありません。

重要： setup-cicd はインフラストラクチャを作成しますが、自動ではデプロイしません。Terraform は必要なすべての GitHub シークレットと変数（WIF 認証情報、プロジェクト ID、サービスアカウント）を設定します。コードをプッシュしてパイプラインをトリガーしてください。

git add . && git commit -m "Initial agent implementation"
git push origin main

本番環境へのデプロイを承認するには：

# GitHub Actions: Approve via repository Actions tab (environment protection rules)

# Cloud Build: Find pending build and approve
gcloud builds list --project=PROD_PROJECT --region=REGION --filter="status=PENDING"
gcloud builds approve BUILD_ID --project=PROD_PROJECT

---

Cloud Run の詳細

インフラストラクチャ設定の詳細（スケーリングのデフォルト値、Dockerfile、FastAPI エンドポイント、セッションの種類、ネットワーク）については、references/cloud-run.md を参照してください。Cloud Run へのデプロイに関する ADK ドキュメントは、https://adk.dev/deploy/cloud-run/index.md を取得してください。

---

Agent Engine の詳細

Agent Engine は、Python ADK エージェントのデプロイに使用するマネージド Vertex AI サービスです。deploy.py と AdkApp クラスを介したソースベースのデプロイを使用します（Dockerfile は不要です）。

Agent Engine 用の gcloud CLI はありません。 deploy.py または adk deploy agent_engine を使ってデプロイしてください。Python の vertexai.Client SDK を使ってクエリを実行してください。

デプロイには5～10分かかることがあります。make deploy がタイムアウトした場合は、エンジンが作成されているか確認し、エンジンのリソース ID を deployment_metadata.json に手動で設定してください（詳細はリファレンスを参照してください）。

インフラストラクチャ設定の詳細（deploy.py のフラグ、AdkApp パターン、Terraform リソース、デプロイメントメタデータ、セッション／アーティファクトサービス、CI/CD の違い）については、references/agent-engine.md を参照してください。Agent Engine へのデプロイに関する ADK ドキュメントは、https://adk.dev/deploy/agent-engine/index.md を取得してください。

---

GKE の詳細

インフラストラクチャ設定の詳細（Terraform で管理される Kubernetes リソース、Workload Identity、セッションの種類、ネットワーク）については、references/gke.md を参照してください。GKE へのデプロイに関する ADK ドキュメントは、https://adk.dev/deploy/gke/index.md を取得してください。

---

サービスアカウントのアーキテクチャ

スキャフォールドされたプロジェクトでは、2つのサービスアカウントを使用します。

• app_sa（環境ごと） — デプロイされたエージェントの実行時 ID です。ロールは deployment/terraform/iam.tf で定義されています。
• cicd_runner_sa（CI/CD プロジェクト） — CI/CD パイプライン（GitHub Actions / Cloud Build）の ID です。CI/CD プロジェクト（デフォルトでは本番プロジェクト）に属し、ステージングと本番の両方のプロジェクトで権限が必要です。

正確なロールバインディングは deployment/terraform/iam.tf を確認してください。プロジェクト間の権限（Cloud Run サービスエージェント、アーティファクトレジストリへのアクセス）もここで設定されています。

よくある403エラー：

• 「Cloud Run の権限が拒否されました」→ cicd_runner_sa に対象プロジェクトでのデプロイロールがありません
• 「サービスアカウントとして操作できません」→ app_sa に iam.serviceAccountUser のバインディングがありません
• 「シークレットへのアクセスが拒否されました」→ app_sa に secretmanager.secretAccessor がありません
• 「Artifact Registry の読み取りが拒否されました」→ Cloud Run サービスエージェントに CI/CD プロジェクトでの読み取り権限がありません

---

シークレットマネージャー（API 認証情報用）

機密性の高いキーを環境変数として渡す代わりに、GCP Secret Manager を使用してください。

# Create a secret
echo -n "YOUR_API_KEY" | gcloud secrets create MY_SECRET_NAME --data-file=-

# Update an existing secret
echo -n "NEW_API_KEY" | gcloud secrets versions add MY_SECRET_NAME --data-file=-

アクセス権の付与： Cloud Run では、app_sa に secretmanager.secretAccessor を付与します。Agent Engine では、プラットフォーム管理の SA（service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com）に付与します。GKE では、app_sa に secretmanager.secretAccessor を付与します。Kubernetes Secrets 経由、または Workload Identity を使用して Secret Manager API に直接アクセスします。

デプロイ時にシークレットを渡す（Agent Engine）：

make deploy SECRETS="API_KEY=my-api-key,DB_PASS=db-password:2"

形式：ENV_VAR=SECRET_ID または ENV_VAR=SECRET_ID:VERSION（デフォルトは latest）です。コードでは os.environ.get("API_KEY") を使用してアクセスします。

---

可観測性

可観測性の設定（Cloud Trace、プロンプトと応答のログ記録、BigQuery Analytics、サードパーティ統合）については、adk-observability-guide スキルを参照してください。

---

デプロイしたエージェントのテスト

Agent Engine のデプロイ

オプション 1：テスト用ノートブック

jupyter notebook notebooks/adk_app_testing.ipynb

オプション 2：Python スクリプト

import json
import vertexai

with open("deployment_metadata.json") as f:
    engine_id = json.load(f)["remote_agent_engine_id"]

client = vertexai.Client(location="us-central1")
agent = client.agent_engines.get(name=engine_id)

async for event in agent.async_stream_query(message="Hello!", user_id="test"):
    print(event)

オプション 3：プレイグラウンド

make playground

Cloud Run のデプロイ

デフォルトで認証が必要です。 Cloud Run は --no-allow-unauthenticated を指定してデプロイされるため、すべてのリクエストに ID トークンを含む Authorization: Bearer ヘッダーが必要です。403 エラーが発生しますか？このヘッダーが不足している可能性があります。一般公開するには、--allow-unauthenticated を指定して再デプロイしてください。

SERVICE_URL="https://SERVICE_NAME-PROJECT_NUMBER.REGION.run.app"
AUTH="Authorization: Bearer $(gcloud auth print-identity-token)"

# Test health endpoint
curl -H "$AUTH" "$SERVICE_URL/"

# Step 1: Create a session (required before sending messages)
curl -X POST "$SERVICE_URL/apps/app/users/test-user/sessions" \
  -H "Content-Type: application/json" \
  -H "$AUTH" \
  -d '{}'
# → returns JSON with "id" — use this as SESSION_ID below

# Step 2: Send a message via SSE streaming
curl -X POST "$SERVICE_URL/run_sse" \
  -H "Content-Type: application/json" \
  -H "$AUTH" \
  -d '{
    "app_name": "app",
    "user_id": "test-user",
    "session_id": "SESSION_ID",
    "new_message": {"role": "user", "parts": [{"text": "Hello!"}]}
  }'

よくある間違い： {"message": "Hello!", "user_id": "...", "session_id": "..."} を使用すると、422 Field required が返されます。ADK HTTP サーバーでは、上記の new_message / parts スキーマが想定されており、セッションがすでに存在している必要があります。

GKE のデプロイ

GKE LoadBalancer サービスはデフォルトで一般公開されるため、Cloud Run とは異なり、認証ヘッダーは不要です。curl の例とエンドポイントの詳細については、references/gke.md を参照してください。

負荷テスト

make load-test

設定、デフォルト設定、CI/CD 統合の詳細については、tests/load_test/README.md を参照してください。

---

UI を使用したデプロイ（IAP）

Google ID 認証で保護された Web UI を使用してエージェントを公開するには：

# Deploy with IAP (built-in framework UI)
make deploy IAP=true

# Deploy with custom frontend on a different port
make deploy IAP=true PORT=5173

IAP（Identity-Aware Proxy）は Cloud Run サービスを保護し、許可された Google アカウントのみがアクセスできるようにします。デプロイ後、Cloud Console の IAP 設定からユーザーにアクセス権を付与します。

カスタムフロントエンドを使用する Agent Engine では、分離デプロイを使用します。フロントエンドを Cloud Run または Cloud Storage に別途デプロイし、Agent Engine バックエンド API に接続します。

---

ロールバックと復旧

主なロールバック方法は git ベースです。問題を修正し、コミットして main にプッシュします。CI/CD パイプラインが新しいバージョンを自動的にビルドし、ステージングから本番環境へデプロイします。

新しいコミットを作成せずに Cloud Run をすぐにロールバックするには、リビジョンのトラフィック振り分けを使用します。

gcloud run revisions list --service=SERVICE_NAME --region=REGION
gcloud run services update-traffic SERVICE_NAME \
  --to-revisions=REVISION_NAME=100 --region=REGION

Agent Engine はリビジョンベースのロールバックをサポートしていません。問題を修正し、make deploy で再デプロイしてください。

GKE をロールバックするには、kubectl rollout undo を使用します。

kubectl rollout undo deployment/DEPLOYMENT_NAME -n NAMESPACE
kubectl rollout status deployment/DEPLOYMENT_NAME -n NAMESPACE

---

カスタムインフラストラクチャ（Terraform）

カスタムインフラストラクチャのパターン（Pub/Sub、BigQuery、Eventarc、Cloud SQL、IAM）については、references/terraform-patterns.md を参照してください。

• カスタム Terraform ファイルの配置場所（開発環境と CI/CD）
• リソースの例（Pub/Sub、BigQuery、Eventarc トリガー）
• カスタムリソースの IAM バインディング
• Terraform の状態管理（リモートとローカル、リソースのインポート）
• よくあるインフラストラクチャのパターン

---

トラブルシューティング

問題	解決方法
Terraform の状態がロックされている	deployment/terraform/ で terraform force-unlock -force LOCK_ID を実行します
GitHub Actions の認証に失敗した	CI/CD の terraform ディレクトリで terraform apply を再実行し、WIF プール／プロバイダーを確認します
Cloud Build の認可が保留中	代わりに github_actions ランナーを使用します
リソースがすでに存在する	terraform import を実行します（references/terraform-patterns.md を参照）
Agent Engine のデプロイがタイムアウトする／停止する	デプロイには 5～10 分かかります。エンジンが作成されたか確認します（「Agent Engine 固有の情報」を参照）
シークレットを利用できない	（デフォルトの compute SA ではなく）app_sa に secretAccessor が付与されていることを確認します
デプロイ時に 403 が発生する	deployment/terraform/iam.tf を確認します。cicd_runner_sa には、対象プロジェクトでデプロイ用および SA のなりすまし用のロールが必要です
Cloud Run のテスト時に 403 が発生する	デフォルトでは --no-allow-unauthenticated が指定されています。Authorization: Bearer $(gcloud auth print-identity-token) ヘッダーを含めます
コールドスタートが遅すぎる	Cloud Run の Terraform 設定で min_instance_count > 0 に設定します
Cloud Run で 503 エラーが発生する	リソース制限（メモリ／CPU）を確認し、max_instance_count を増やすか、コンテナのクラッシュログを確認します
IAM ロールの付与直後に 403 が発生する	IAM の反映には時間がかかります。再試行する前に数分待ちます。同じロールを繰り返し付与しないでください
Terraform で作成されたはずのリソースが見つからない	terraform state list を実行し、Terraform が実際に管理しているリソースを確認します。null_resource と local-exec 経由で作成されたリソース（例：BQ のリンク済みデータセット）は、gcloud CLI の出力には表示されません