GenAI Factory — Cloud Run Single (cloud-run-single)
Overview
Deploys a single Cloud Run Gen2 service (cloud-run-single) fronted by an optional External or Internal Application Load Balancer, Cloud Armor, and Model Armor, supporting five sample workloads under 1-apps/apps/: chat, adk, adk-a2a, gemma (on NVIDIA L4 GPU), and mcp-server.
When to Use
- Deploying or customizing
0-prereqs/ or 1-apps/ in cloud-run-single.
- Enabling NVIDIA L4 GPU acceleration (
cloud_run_config.node_selector) or deploying any of the 5 sample apps (chat, adk, adk-a2a, gemma, mcp-server).
- REQUIRED SUB-SKILL: Load
genai-factory-prerequisites-and-fast for Stage 0 (0-prereqs), BYO Shared VPC, Fabric FAST, and aiplatform.<eu|us>.rep.googleapis.com + modelarmor.<region>.rep.googleapis.com PSC/DNS setup.
- REQUIRED SUB-SKILL: Load
genai-factory-cloud-run-and-load-balancers for lbs_configs, Cloud Armor, CAS (ca_pool_name_suffix), and Direct Cloud Run ingress.
- REQUIRED SUB-SKILL: Load
genai-factory-model-armor for model_armor_template_config and model_armor_floorsetting_config.
- REQUIRED SUB-SKILL: Load
genai-factory-operations-and-teardown for CLOUDSDK_BILLING_QUOTA_PROJECT and clean teardown.
- For contributor test inventory workflows (
plan_summary.py / pytest), see AGENTS.md.
Quick Reference
| Attribute |
Value / Definition |
Projects (0-prereqs) |
Service: gf-srun-0 (service-01.yaml); Host: gf-srun-hp-0 (host.yaml) |
Default Name (var.name) |
gf-srun-0 (1-apps/variables.tf) |
Required SA Keys (1-apps) |
service-01/iac-rw, service-01/crun-0 (aiplatform.user, modelarmor.user), service-01/crun-build-0 |
| Regional PSC Endpoints |
aiplatform.<eu/us>.rep.googleapis.com and modelarmor.<region>.rep.googleapis.com (0-prereqs/networking.tf) |
Core Patterns
NVIDIA L4 GPU Acceleration for Gemma / Ollama (1-apps/terraform.tfvars)
cloud_run_config = {
gpu_zonal_redundancy_disabled = true
node_selector = { accelerator = "nvidia-l4" }
containers = {
ai = {
image = "us-docker.pkg.dev/cloudrun/container/gemma/gemma3-4b:latest"
resources = {
limits = { cpu = "8", memory = "32Gi", "nvidia.com/gpu" = "1" }
}
}
}
}
Sample Workloads (1-apps/apps/)
Run terraform output -raw commands after terraform apply in 1-apps/:
| Workload |
Directory |
Port |
Key Env Vars & Verification |
| Chat |
apps/chat/ |
8080 |
PROJECT_ID, REGION, GOOGLE_CLOUD_LOCATION (eu/us), MODEL_NAME (gemini-4-argon), THINKING_LEVEL (MEDIUM), MODEL_ARMOR_TEMPLATE. Verify: POST /predict ({"prompt":"hello"}). |
| ADK Agent |
apps/adk/ |
8080 |
Same as chat + SERVE_WEB_INTERFACE, SESSION_DB_URL. Verify: GET /list-apps, POST /apps/capital_agent/users/u1/sessions/s1, POST /run_sse. |
| ADK + A2A |
apps/adk-a2a/ |
8003 |
Same as chat + A2A_URL (LB or Run URL) and --port=8003. Verify: GET /.well-known/agent-card.json. |
| Gemma 3 GPU |
apps/gemma/ |
8080 |
OLLAMA_NUM_PARALLEL=4 (uses pre-built image, no Cloud Build step). Verify: POST /api/generate. |
| MCP Server |
apps/mcp-server/ |
8080 |
PORT=8080 (caller needs roles/compute.securityAdmin). Verify: uv run client.py https://<DOMAIN>/mcp list. |
Common Mistakes
| Symptom / Error |
Cause |
Fix |
apps/adk-a2a fails health check or returns wrong URL in agent-card.json |
adk-a2a listens on port 8003 and requires A2A_URL |
Pass --port=8003 and A2A_URL=https://<DOMAIN> on gcloud run deploy. |
| Model Armor calls time out from Cloud Run |
Missing regional PSC endpoint for modelarmor.<region>.rep.googleapis.com in BYO-VPC |
Provision the regional PSC endpoint and DNS rule per genai-factory-prerequisites-and-fast. |
1---2name: genai-factory-cloud-run-single3description: Use when deploying or configuring the genai-factory cloud-run-single blueprint for a single Cloud Run GenAI application (chat, Google ADK agent, ADK with A2A server, Gemma 3 on NVIDIA L4 GPU, or FastMCP server) with External/Internal Application Load Balancer, Cloud Armor, and Model Armor.4metadata:5 source: https://skillmd.com/skills/googlecloudplatform/genai-factory-cloud-run-single6---78# GenAI Factory — Cloud Run Single (`cloud-run-single`)910## Overview1112Deploys a single **Cloud Run Gen2** service ([`cloud-run-single`](./README.md)) fronted by an optional **External or Internal Application Load Balancer**, **Cloud Armor**, and **Model Armor**, supporting five sample workloads under [`1-apps/apps/`](./1-apps/apps/): `chat`, `adk`, `adk-a2a`, `gemma` (on NVIDIA L4 GPU), and `mcp-server`.1314## When to Use1516- Deploying or customizing [`0-prereqs/`](./0-prereqs/README.md) or [`1-apps/`](./1-apps/README.md) in `cloud-run-single`.17- Enabling NVIDIA L4 GPU acceleration (`cloud_run_config.node_selector`) or deploying any of the 5 sample apps (`chat`, `adk`, `adk-a2a`, `gemma`, `mcp-server`).18- **REQUIRED SUB-SKILL:** Load [`genai-factory-prerequisites-and-fast`](../.agents/skills/genai-factory-prerequisites-and-fast/SKILL.md) for Stage 0 (`0-prereqs`), BYO Shared VPC, Fabric FAST, and `aiplatform.<eu|us>.rep.googleapis.com` + `modelarmor.<region>.rep.googleapis.com` PSC/DNS setup.19- **REQUIRED SUB-SKILL:** Load [`genai-factory-cloud-run-and-load-balancers`](../.agents/skills/genai-factory-cloud-run-and-load-balancers/SKILL.md) for `lbs_configs`, Cloud Armor, CAS (`ca_pool_name_suffix`), and Direct Cloud Run ingress.20- **REQUIRED SUB-SKILL:** Load [`genai-factory-model-armor`](../.agents/skills/genai-factory-model-armor/SKILL.md) for `model_armor_template_config` and `model_armor_floorsetting_config`.21- **REQUIRED SUB-SKILL:** Load [`genai-factory-operations-and-teardown`](../.agents/skills/genai-factory-operations-and-teardown/SKILL.md) for `CLOUDSDK_BILLING_QUOTA_PROJECT` and clean teardown.22- For contributor test inventory workflows (`plan_summary.py` / `pytest`), see [`AGENTS.md`](./AGENTS.md).2324## Quick Reference2526| Attribute | Value / Definition |27| :--- | :--- |28| **Projects (`0-prereqs`)** | Service: `gf-srun-0` ([`service-01.yaml`](./0-prereqs/data/projects/service-01.yaml)); Host: `gf-srun-hp-0` ([`host.yaml`](./0-prereqs/data/projects/host.yaml)) |29| **Default Name (`var.name`)** | `gf-srun-0` ([`1-apps/variables.tf`](./1-apps/variables.tf)) |30| **Required SA Keys (`1-apps`)** | `service-01/iac-rw`, `service-01/crun-0` (`aiplatform.user`, `modelarmor.user`), `service-01/crun-build-0` |31| **Regional PSC Endpoints** | `aiplatform.<eu/us>.rep.googleapis.com` and `modelarmor.<region>.rep.googleapis.com` ([`0-prereqs/networking.tf`](./0-prereqs/networking.tf)) |3233## Core Patterns3435### NVIDIA L4 GPU Acceleration for Gemma / Ollama (`1-apps/terraform.tfvars`)3637```hcl38cloud_run_config = {39 gpu_zonal_redundancy_disabled = true40 node_selector = { accelerator = "nvidia-l4" }41 containers = {42 ai = {43 image = "us-docker.pkg.dev/cloudrun/container/gemma/gemma3-4b:latest"44 resources = {45 limits = { cpu = "8", memory = "32Gi", "nvidia.com/gpu" = "1" }46 }47 }48 }49}50```5152### Sample Workloads (`1-apps/apps/`)5354Run `terraform output -raw commands` after `terraform apply` in `1-apps/`:5556| Workload | Directory | Port | Key Env Vars & Verification |57| :--- | :--- | :--- | :--- |58| **Chat** | [`apps/chat/`](./1-apps/apps/chat) | `8080` | `PROJECT_ID`, `REGION`, `GOOGLE_CLOUD_LOCATION` (`eu`/`us`), `MODEL_NAME` (`gemini-4-argon`), `THINKING_LEVEL` (`MEDIUM`), `MODEL_ARMOR_TEMPLATE`. Verify: `POST /predict` (`{"prompt":"hello"}`). |59| **ADK Agent** | [`apps/adk/`](./1-apps/apps/adk) | `8080` | Same as `chat` + `SERVE_WEB_INTERFACE`, `SESSION_DB_URL`. Verify: `GET /list-apps`, `POST /apps/capital_agent/users/u1/sessions/s1`, `POST /run_sse`. |60| **ADK + A2A** | [`apps/adk-a2a/`](./1-apps/apps/adk-a2a) | `8003` | Same as `chat` + `A2A_URL` (LB or Run URL) and `--port=8003`. Verify: `GET /.well-known/agent-card.json`. |61| **Gemma 3 GPU** | [`apps/gemma/`](./1-apps/apps/gemma) | `8080` | `OLLAMA_NUM_PARALLEL=4` (uses pre-built image, no Cloud Build step). Verify: `POST /api/generate`. |62| **MCP Server** | [`apps/mcp-server/`](./1-apps/apps/mcp-server) | `8080` | `PORT=8080` (caller needs `roles/compute.securityAdmin`). Verify: `uv run client.py https://<DOMAIN>/mcp list`. |6364## Common Mistakes6566| Symptom / Error | Cause | Fix |67| :--- | :--- | :--- |68| `apps/adk-a2a` fails health check or returns wrong URL in `agent-card.json` | `adk-a2a` listens on port `8003` and requires `A2A_URL` | Pass `--port=8003` and `A2A_URL=https://<DOMAIN>` on `gcloud run deploy`. |69| Model Armor calls time out from Cloud Run | Missing regional PSC endpoint for `modelarmor.<region>.rep.googleapis.com` in BYO-VPC | Provision the regional PSC endpoint and DNS rule per [`genai-factory-prerequisites-and-fast`](../.agents/skills/genai-factory-prerequisites-and-fast/SKILL.md). |