Containerizing & Deploying ADK Agents to Cloud Run

While local terminal scripts work well during prototyping, production-grade ADK agent harnesses run as stateless web services behind load balancers. Deploying in production requires automatic scaling, secrets management, non-root container isolation, and persistent database session storage.

This guide details how to containerize an ADK agent harness using Docker and deploy it to Google Cloud Run.

Why Cloud Run for ADK Agents

Google Cloud Run is a managed serverless container platform tailored for containerized microservices like ADK agent applications:

• Zero-to-N Auto-scaling: Scales down to zero instances when idle to eliminate compute costs, and scales up seamlessly to handle high request concurrency.
• Fully Managed Infrastructure: Eliminates cluster management and node maintenance overhead.
• Native OpenTelemetry & Observability: OpenTelemetry spans stream automatically into Google Cloud Trace and Cloud Logging.
• Secret Manager Integration: Securely mounts runtime credentials into container environment variables without exposing plaintext secrets.

Production Dockerfile

Use a multi-stage Docker build leveraging Astral’s uv package manager for ultra-fast dependency installation and minimal runtime image size:

# Stage 1: Build & Dependency Resolution
FROM python:3.11-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

# Stage 2: Final Minimal Runtime Image
FROM python:3.11-slim
WORKDIR /app

# Create non-root system user for security
RUN adduser --disabled-password --gecos "" appuser
USER appuser

COPY --from=builder /app/.venv /app/.venv
COPY . /app

ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8080

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "4"]

Key Security & Optimization Features

• Multi-Stage Build: Excludes build toolchains and temporary cache artifacts from the production image.
• Non-Root Execution: Runs the service under appuser rather than root to reduce container escape risks.
• Pinned Dependencies: uv sync --frozen installs exact package lockfile versions from uv.lock.

Deploying to Google Cloud Run

Execute the following shell commands to build the container, upload it to Container Registry / Artifact Registry, and launch the service on Cloud Run:

# 1. Build and tag the Docker container image
docker build -t gcr.io/my-project/adk-agent:v1 .

# 2. Push image to Google Container Registry
docker push gcr.io/my-project/adk-agent:v1

# 3. Deploy to Cloud Run with Secret Manager integrations
gcloud run deploy adk-agent-harness \
  --image=gcr.io/my-project/adk-agent:v1 \
  --region=us-central1 \
  --platform=managed \
  --allow-unauthenticated \
  --set-env-vars="PROJECT_ID=my-gcp-project" \
  --set-secrets="DATABASE_URL=adk-db-url:latest,GEMINI_API_KEY=gemini-api-key:latest" \
  --min-instances=1 \
  --max-instances=10

Cloud Run vs. Vertex AI Agent Engine

Feature	Cloud Run	Vertex AI Agent Engine
Architectural Control	Full control over web framework (FastAPI, Flask)	Managed agent runtime
Session Persistence	Configured via custom DatabaseSessionService	Built-in managed persistence
Auto-scaling	Serverless scaling (0 to N instances)	Managed serverless scaling
Custom Docker Image	Fully supported	No (deployment via agents-cli)
Primary Target	Custom APIs & complex microservice architectures	Pure ADK agents with minimal infrastructure ops

Production Security & Architecture Checklist

1. Never Hardcode Credentials: Store keys in Google Secret Manager and reference them via --set-secrets.
2. Apply Least-Privilege IAM: Restrict the Cloud Run service account permissions to essential roles:
   • roles/secretmanager.secretAccessor: Fetch runtime secrets
   • roles/aiplatform.user: Invoke Vertex AI Gemini models
   • roles/cloudsql.client: Connect to Cloud SQL instance for database persistence
3. Use Database Session Storage: Always configure DatabaseSessionService (rather than InMemorySessionService) to ensure multi-instance state persistence across scaling events.

Key Takeaway

Packaging your ADK agent using a multi-stage Dockerfile and deploying to Google Cloud Run creates a secure, resilient, and auto-scaling microservice environment. Combine Secret Manager bindings with database-backed session state to guarantee production readiness.