adk-deploy-guide

ADK Deployment Guide

Scaffolded project? Use make commands — they wrap Terraform, Docker, and deployment.

No scaffold? See Quick Deploy below. For production infrastructure, see the /scaffold-adk command or load the architecture-design skill for infrastructure planning.

Iron Law

NEVER create GCP resources manually via gcloud for production. Define all infrastructure in Terraform. Exception: quick experimentation only — console or gcloud for throwaway resources is fine.

Reference Files

For agent code patterns and testing strategies, see google-adk skill. For evaluations and observability, see adk-eval-guide and adk-observability-guide skills.

Deployment Target Decision Matrix

Ask the user which target fits their needs before proceeding.

Quick Deploy (ADK CLI)

No Makefile, Terraform, or Dockerfile required.

# 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/

Both support --with_ui to deploy the ADK dev UI. Cloud Run accepts extra gcloud flags after --.

Process

1. Gather requirements — target (Agent Engine vs Cloud Run), project ID, region, secrets needed
2. Choose target — use the decision matrix above; ask if unclear
3. Scaffold or write Terraform — run /scaffold-adk or manually write deployment/terraform/
4. Configure secrets — use Secret Manager, not env vars, for API keys and credentials
5. Deploy — make deploy (scaffolded) or adk deploy <target> (CLI)
6. Verify — health check endpoint, test with curl or testing notebook, run load tests

Secret Manager

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

# Update
echo -n "NEW_KEY" | gcloud secrets versions add MY_SECRET_NAME --data-file=-

# Agent Engine: pass at deploy time
make deploy SECRETS="API_KEY=my-api-key,DB_PASS=db-password:2"

Grant secretmanager.secretAccessor to app_sa (Cloud Run) or service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com (Agent Engine).

Documentation Sources

Production Deployment — CI/CD Pipeline

Best for: Production applications, teams requiring staging → production promotion.

Prerequisites:

1. Project must NOT be in a gitignored folder
2. User must provide staging and production GCP project IDs
3. GitHub repository name and owner

Steps:

1. If prototype, first add Terraform/CI-CD files using the Agent Starter Pack CLI:

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

2. Ensure you're logged in to GitHub CLI:

   gh auth login  # (skip if already authenticated)
   

3. Run 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. Push code to trigger deployments

Key setup-cicd Flags

Choosing a CI/CD Runner

How Authentication Works (WIF)

Both runners use Workload Identity Federation (WIF) — GitHub/Cloud Build OIDC tokens are trusted by a GCP Workload Identity Pool, which grants cicd_runner_sa impersonation. No long-lived service account keys needed. Terraform in setup-cicd creates the pool, provider, and SA bindings automatically. If auth fails, re-run terraform apply in the CI/CD Terraform directory.

CI/CD Pipeline Stages

The pipeline has three stages:

1. CI (PR checks) — Triggered on pull request. Runs unit and integration tests.
2. Staging CD — Triggered on merge to main. Builds container, deploys to staging, runs load tests.

   Path filter: Staging CD uses paths: ['app/**'] — it only triggers when files under app/ change. If nothing happens after the first push after setup-cicd, this is why.

3. Production CD — Triggered after successful staging deploy. May require manual approval before deploying to production.

   Approving: Go to GitHub Actions → the production workflow run → click "Review deployments" → approve the pending production environment. This is GitHub's environment protection rules.

IMPORTANT: setup-cicd creates infrastructure but doesn't deploy automatically. Push code to trigger the pipeline:

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

To approve production deployment:

# 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

Service Account Architecture

Scaffolded projects use two service accounts:

• app_sa (per environment) — Runtime identity for the deployed agent. Roles defined in deployment/terraform/iam.tf.
• cicd_runner_sa (CI/CD project) — CI/CD pipeline identity (GitHub Actions / Cloud Build). Needs permissions in both staging and prod projects.

Troubleshooting