GCP Deployment Deep Dive

🏗️ Architecture Overview

High-Level System Architecture

Bedsheet's GCP deployment target creates a complete serverless infrastructure using Cloud Run, Cloud Build, and Vertex AI. The generated artifacts include Terraform for infrastructure and a Makefile for developer experience.

Component Responsibilities

Multi-Agent Architecture

Bedsheet supports multi-agent systems with a Supervisor pattern. The Investment Advisor example demonstrates this with three specialized collaborators:

🔐 Authentication Deep Dive

The Authentication Stack

The Google Cloud SDK and Python libraries check credentials in a specific priority order. Understanding this order is crucial for debugging.

The January 2026 Bug

This diagram explains exactly what happened during our debugging session:

Authentication Checklist

Before deploying or debugging, always verify:

# 1. Check if GOOGLE_APPLICATION_CREDENTIALS is set
echo $GOOGLE_APPLICATION_CREDENTIALS
# If set to wrong project's SA, unset it:
unset GOOGLE_APPLICATION_CREDENTIALS

# 2. Check current gcloud auth
gcloud auth list

# 3. Check ADC configuration
cat ~/.config/gcloud/application_default_credentials.json | jq '.quota_project_id'

# 4. Test direct API access (bypasses Python SDK)
curl -s -X POST \
  "https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/global/publishers/google/models/gemini-3-flash-preview:generateContent" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Hi"}]}]}'

🤖 The ADK Integration

What is ADK?

Agent Development Kit (ADK) is Google's framework for building AI agents. Bedsheet generates ADK-compatible agents for GCP deployment, leveraging ADK's runtime and development tools.

ADK Server Modes

ADK Directory Structure

deploy/gcp/
├── agent/                    # ADK agent directory
│   ├── __init__.py          # Exports root_agent
│   ├── agent.py             # Agent definition
│   └── tools.py             # Tool implementations
├── Dockerfile               # Container definition
├── pyproject.toml           # Dependencies
├── Makefile                 # Deployment commands
├── cloudbuild.yaml          # CI/CD pipeline
└── terraform/               # Infrastructure as code
    ├── main.tf
    ├── variables.tf
    └── outputs.tf

The root_agent Pattern

ADK discovers agents by looking for root_agent in the agent module:

# agent/__init__.py
from .agent import root_agent

# agent/agent.py
from google.adk.agents import LlmAgent

root_agent = LlmAgent(
    name="InvestmentAdvisor",
    model="gemini-3-flash-preview",
    instruction="You are an investment advisor...",
    sub_agents=[market_analyst, news_researcher, risk_analyst]
)

📄 Template System

How Templates Work

Key Template: Dockerfile.j2

# {{ config.name }} - Cloud Run Container
# Generated by: bedsheet generate --target gcp

FROM python:3.11-slim

# Install uv (fast Python package manager)
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

# Install dependencies
COPY pyproject.toml .
RUN uv pip install --system -r pyproject.toml

# Copy agent code
COPY agent/ ./agent/

# Cloud Run expects PORT env var
ENV PORT=8080

# ADK serves the agent with Dev UI
CMD ["python", "-m", "google.adk.cli", "web", "--host", "0.0.0.0", "--port", "8080", "."]

Template Variables

🚀 Deployment Flow

Complete Sequence

Make Targets

# Quick reference
make help      # Show all commands
make setup     # One-time setup (auth, project, APIs)
make deploy    # Deploy to Cloud Run via Cloud Build
make dev       # Run locally with ADK Dev UI
make logs      # Stream Cloud Run logs
make url       # Get service URL
make destroy   # Remove all resources

🔧 Troubleshooting Guide

Decision Tree

Common Issues

1. 403 PERMISSION_DENIED on Vertex AI

# Quick fix
unset GOOGLE_APPLICATION_CREDENTIALS
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform"
gcloud auth application-default set-quota-project YOUR_PROJECT

2. Gemini 3 Model Not Found

# Gemini 3 requires global endpoint
export GOOGLE_CLOUD_LOCATION=global

# Check SDK version (need >= 1.51.0)
pip show google-genai | grep Version

3. ADK Dev UI Returns 404

# Wrong - api_server has no UI
CMD ["python", "-m", "google.adk.cli", "api_server", ...]

# Correct - web mode includes Dev UI
CMD ["python", "-m", "google.adk.cli", "web", ...]

🔍 The Great Debugging of January 2026

This is the story of how we spent hours debugging a 403 error that turned out to be a single environment variable. It's now documented here so no one else has to suffer.

The Mystery

The Investigation Timeline

📚 Lessons Learned

1. Check environment variables FIRST when debugging auth issues. GOOGLE_APPLICATION_CREDENTIALS overrides ADC.
2. Credential priority matters: ENV > ADC > Metadata Server. Know the order.
3. curl working but SDK failing = different auth sources. This is the key diagnostic.
4. Trust your instincts: "It works on another project" means the API works - the issue is auth.
5. Multiple GCP projects require careful credential management. Service accounts are project-specific.

⚡ Quick Reference

# 1. Create agent
bedsheet init my-agent && cd my-agent

# 2. Configure bedsheet.yaml
# Set your GCP project, region, model

# 3. Generate deployment artifacts
bedsheet generate --target gcp

# 4. Deploy
cd deploy/gcp
make setup   # One-time
make deploy  # Deploy to Cloud Run

# 5. Access Dev UI
open $(make url)/dev-ui/

Environment Variables

🔮 Future Considerations

Potential Improvements

1. Credential Validation in Makefile

_validate_credentials:
    @if [ -n "$$GOOGLE_APPLICATION_CREDENTIALS" ]; then \
        echo "⚠️  WARNING: GOOGLE_APPLICATION_CREDENTIALS is set"; \
        echo "   Value: $$GOOGLE_APPLICATION_CREDENTIALS"; \
        echo "   This may cause auth issues with different projects."; \
    fi

2. Project-Specific Service Account

resource "google_service_account" "agent_sa" {
  account_id   = "${var.service_name}-sa"
  display_name = "Service Account for ${var.service_name}"
  project      = var.project_id
}

resource "google_project_iam_member" "vertex_ai_user" {
  project = var.project_id
  role    = "roles/aiplatform.user"
  member  = "serviceAccount:${google_service_account.agent_sa.email}"
}

Roadmap