Learning path: ADK agents on Google Cloud with Terraform

Nine small, working projects. Do them in order; each builds on the previous one.

#	Folder	You learn	Result
01	01-adk-cloud-run-terraform	ADK basics, Terraform basics, containers, Cloud Run, IAM	A weather agent behind a private HTTPS API (+ dev web UI)
02	02-agent-runtime-registry-terraform	Agent Runtime (managed agent hosting), Agent Registry, Gemini Enterprise	A currency agent on Agent Runtime, discoverable in Agent Registry, addable to Gemini Enterprise
03	03-google-chat-bridge	Google Chat apps (Workspace add-ons), service-to-service auth	Your agent answering in Google Chat for people in your company
04	04-mcp-server-cloud-run-registry	MCP (tool servers), FastMCP, private Cloud Run, Agent Registry MCP entries, registry-driven agents	A product-catalog MCP server any agent (ADK, Claude Code, Gemini CLI) can use, discovered via Agent Registry
05	05-gemini-enterprise-model-armor	Full Gemini Enterprise as code (identity, licences, data, app, assistant, web UI, agents), Model Armor, threat model, detection	A secured company AI assistant: 3 layers of Model Armor, least privilege, EU residency, alerting
06	06-gemini-enterprise-security-baseline	Socle de sécurité Gemini Enterprise (FR, client Acme) : 6 couches — identité, CMEK, connecteurs génériques fédérés, Model Armor + DLP FR, exposition UE, détection ; options Agent Gateway / VPC-SC	Guide pédagogique en français + deck client
07	07-terraform-service-local	Service Terraform « managé » en local : Gitea (≈ GitHub) + Atlantis + MinIO (état), politiques OPA, verrous, approbations	Circuit PR → plan → politiques → approbation → apply, simulé et vérifié automatiquement
08	08-gemini-enterprise-securite-acme	Note de sécurité Acme appliquée : natif console d'abord, puis Terraform (plancher Model Armor sur les agents, Shadow AI, SIEM, Access Approval, VPC-SC élargi, SWP, Agent Registry), tests, journal quotidien	Guide FR + PDF + PPTX, agent sécurisé, scripts de conformité
09	09-agents-multi-projets-gemini-enterprise	Les 6 modalités d'ajout d'un agent dans Gemini Enterprise ; agents d'autres équipes / autres projets ; un agent qui en découvre (Agent Registry) et en appelle un autre ; matrice des droits cross-project	Agent stock (projet A) + orchestrateur (projet B) sur Agent Runtime, publiés dans l'app, script d'ajout de n'importe quel agent

Tested versions (latest as of Sept 2026): google-adk 2.10.0, google-cloud-aiplatform 2.2.0, Terraform 1.16, provider hashicorp/google 8.4, model gemini-3.5-flash.

0. The big picture (names changed in 2026!)

Vertex AI is now called Gemini Enterprise Agent Platform. You'll still see the old names in APIs, Terraform, and blog posts:

Today's name	Older name(s)	Where the old name still shows up
Gemini Enterprise Agent Platform	Vertex AI	`aiplatform.googleapis.com`, `google_vertex_ai_*` Terraform resources
Agent Runtime (console: Deployments)	Agent Engine, Reasoning Engine	`reasoningEngines/…` resource names, `google_vertex_ai_reasoning_engine`
`agentplatform` Python package	`vertexai` package	both ship in `google-cloud-aiplatform`
Agent Registry	(new)	`agentregistry.googleapis.com`, `gcloud agent-registry`
Gemini Enterprise (the app employees use)	Agentspace	`discoveryengine.googleapis.com`

             build                      host                     govern / discover            use
  ┌───────────────────┐   ┌──────────────────────────────┐   ┌──────────────────┐   ┌──────────────────────┐
  │ ADK (Python lib)  │──▶│ Cloud Run  (you run the API) │──▶│  Agent Registry  │──▶│ Gemini Enterprise app│
  │ agent + tools     │   │ Agent Runtime (Google runs it)│  │  (catalog of all │   │ Google Chat          │
  └───────────────────┘   └──────────────────────────────┘   │  agents & tools) │   │ other agents (A2A)   │
                                    ▲                        └──────────────────┘   └──────────────────────┘
                                    │ everything created by Terraform

Cloud Run vs Agent Runtime: which one should you use?

	Cloud Run (01)	Agent Runtime (02)
What you deploy	A container you build (FastAPI server made by ADK)	Just your Python source; Google builds and serves it
Sessions / memory	You bring them (in-memory, SQL DB…)	Managed sessions + Memory Bank included
Gemini Enterprise	Via A2A / Agent Registry	Native: "Add agent → Custom agent via Agent Runtime"
Agent Registry	Manual registration (or alpha auto-registration)	Registered automatically
Control / cost	Full control; scale to zero; cheap	Less plumbing; paid per use
Pick it when	You need custom HTTP routes, a web UI, or other frameworks	You want the enterprise path (Gemini Enterprise, governance)

1. One-time setup (on your laptop, or on the `syctra` VM)

# Tools (already installed on this laptop): gcloud, terraform >= 1.9, python 3.12 (via uv), docker
gcloud --version && terraform version && uv --version && docker --version

# 1. Log in. Two different logins, both needed:
gcloud auth login                         # for the gcloud CLI
gcloud auth application-default login     # "ADC": used by Terraform and Python SDKs  ← was missing here!

# 2. Choose the project
gcloud config set project YOUR_PROJECT_ID
export PROJECT_ID=$(gcloud config get project)

# 3. Billing must be enabled on the project (Cloud Run / Gemini are paid, with free tiers)
gcloud billing projects describe $PROJECT_ID --format='value(billingEnabled)'   # → True

If you work from the syctra VM: it's arm64 and Cloud Run needs amd64 images. The build step uses docker build --platform linux/amd64, which needs QEMU there: docker run --privileged --rm tonistiigi/binfmt --install amd64. The simplest option is to run everything from your laptop (x86_64).

A Python environment for local runs (shared by all projects):

cd ~/Bureau/trash
uv venv -p 3.12 .venv && source .venv/bin/activate
uv pip install "google-adk[a2a,agent-identity]==2.10.0" "google-cloud-aiplatform[agent_engines,adk]==2.2.0" mcp fastmcp==4.0.10 fastapi uvicorn

2. Terraform in 10 minutes (read this before project 01)

Terraform = you describe the infrastructure you want in .tf files; Terraform works out what to create, change, or delete to get there.

The vocabulary

Concept	Example in these projects	Meaning
provider	`hashicorp/google`	A plugin that knows how to talk to one API (GCP)
resource	`google_cloud_run_v2_service.agent`	Something Terraform creates and owns. Address = `TYPE.NAME`
data source	`data.google_project.this`	Something Terraform only reads
variable	`var.project_id`	An input. Set in `terraform.tfvars` or with `-var`
local	`local.image`	A computed value, like a local variable
output	`url`	A value printed after apply; read it with `terraform output -raw url`
state	`terraform.tfstate`	Terraform's memory of what it created. Never edit it by hand, never commit it
module	(each folder is one)	A folder of `.tf` files. All files in a folder are merged; file names are just for humans

The files (same layout in every project)

terraform/
├── versions.tf               # which Terraform/provider versions + provider config (+ backend)
├── variables.tf              # inputs
├── main.tf                   # the resources
├── outputs.tf                # what you want to read afterwards
└── terraform.tfvars.example  # copy to terraform.tfvars and fill in

The loop you'll repeat forever

terraform init       # download providers (once, or after changing versions.tf)
terraform fmt        # format files
terraform validate   # syntax/type check, no cloud calls
terraform plan       # DRY RUN: shows + create, ~ update, - destroy, -/+ replace. READ IT.
terraform apply      # does it (asks "yes")
terraform output     # show outputs
terraform destroy    # delete everything this folder created

Useful extras:

terraform state list                     # what Terraform manages
terraform state show google_cloud_run_v2_service.agent
terraform plan -var model=gemini-3.7-flash    # override a variable once
terraform apply -replace=terraform_data.image # force-rebuild one resource
terraform console                        # try out expressions: > local.image

Patterns used here (and why)

for_each = toset([...]) → one resource per item (enable N APIs, grant N roles) without copy-pasting.
count = var.public ? 1 : 0 → an optional resource.
depends_on → an ordering Terraform can't infer on its own (e.g. IAM must exist before the service starts).
google_project_service with disable_on_destroy = false → enabling APIs is part of the code, and destroy never switches off an API something else still uses.
The image tag = hash of the source files → no code change means no rebuild and no new revision. Deploys stay reproducible.

Best practices

Remote state for teams: uncomment the backend "gcs" block in versions.tf (bucket with versioning enabled). Local state is fine while you learn alone.
Pin versions (~> 8.4 = any 8.x ≥ 8.4) and commit .terraform.lock.hcl.
Never put secrets in .tf / .tfvars. Use Secret Manager and reference it (secret_env / value_source).
Always read plan, especially lines with -/+ (replace) or - (destroy).
Least privilege: each workload gets its own service account with only the roles it needs (done in every project here).
One folder = one state = one lifecycle. That's why 01/02/03 are separate: you can destroy one without touching the others.
In CI/CD: terraform plan -out=tfplan on the PR, then terraform apply tfplan after review.

3. Costs and cleanup

Everything scales to zero, so idle cost is almost nil (Artifact Registry storage costs a few cents). When you're done:

(cd 09-agents-multi-projets-gemini-enterprise/terraform && terraform destroy)
(cd 08-gemini-enterprise-securite-acme/terraform && terraform destroy)
(cd 06-gemini-enterprise-security-baseline/terraform && terraform destroy)
(cd 05-gemini-enterprise-model-armor/terraform && terraform destroy)
(cd 04-mcp-server-cloud-run-registry/terraform && terraform destroy)
(cd 03-google-chat-bridge/terraform && terraform destroy)
(cd 02-agent-runtime-registry-terraform/terraform && terraform destroy)
(cd 01-adk-cloud-run-terraform/terraform && terraform destroy)

4. Official docs

ADK: https://adk.dev · Cloud Run deploy: https://adk.dev/deploy/cloud-run/ · Agent Runtime deploy: https://adk.dev/deploy/agent-runtime/
Agent Runtime + Terraform: https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/use-terraform
Agent Registry: https://docs.cloud.google.com/agent-registry
Register an ADK agent in Gemini Enterprise: https://docs.cloud.google.com/gemini/enterprise/docs/register-and-manage-an-adk-agent
Google Chat + ADK: https://developers.google.com/workspace/add-ons/chat/quickstart-adk-agent
Terraform google provider: https://registry.terraform.io/providers/hashicorp/google/latest/docs