GCP Cloud Run

Deploy your services to Google Cloud Run with automatic scaling and pay-per-use billing.

Prerequisites

Google Cloud SDK installed and configured
Docker installed
A GCP project with Cloud Run API enabled

# Install gcloud
brew install google-cloud-sdk

# Authenticate
gcloud auth login
gcloud auth configure-docker

# Set project
gcloud config set project YOUR_PROJECT_ID

Service Configuration

name: my-api
provider: gcp
project: my-gcp-project
region: us-central1

build:
  language: go
  version: "1.23"
  env_vars:
    CGO_ENABLED: "0"

cloud_run:
  min_instances: 0
  max_instances: 10
  memory: "512Mi"
  cpu: "1"
  concurrency: 80
  timeout_seconds: 300
  cpu_throttling: true

Required Fields

Field	Description
`name`	Service name
`project`	GCP project ID
`region`	GCP region (e.g., `us-central1`)
`registry_name`	Artifact Registry repository name — bare name, e.g. `my-repo`, not a full host/path
`template`	Dockerfile template name

Optional Fields

Cloud Run Configuration

Field	Type	Default	Description
`cloud_run.min_instances`	int	`0`	Minimum instances (set > 0 to avoid cold starts)
`cloud_run.max_instances`	int	`10`	Maximum instances
`cloud_run.memory`	string	`512Mi`	Memory allocation (`256Mi`, `512Mi`, `1Gi`, `2Gi`)
`cloud_run.cpu`	string	`1`	CPU allocation (`1`, `2`, `4`)
`cloud_run.concurrency`	int	`80`	Max concurrent requests per instance
`cloud_run.timeout_seconds`	int	`300`	Request timeout
`cloud_run.cpu_throttling`	bool	`true`	Throttle CPU when not processing requests
`cloud_run.port`	int	`8080`	Ingress container port (required when `sidecars:` is set)
`cloud_run.cloudsql_instances`	list	-	Cloud SQL connections (`project:region:instance`)
`sidecars`	list	-	Auxiliary containers co-deployed in the same revision

Registry Configuration

Images are pushed to Artifact Registry. registry_name is the bare repository name — Pilum builds the full path from your project and region:

project: my-project
region: us-central1
registry_name: my-repo

becomes us-central1-docker.pkg.dev/my-project/my-repo/<service> — not a value you construct yourself. If you paste a full host (...-docker.pkg.dev/... or gcr.io/...) into registry_name, Pilum detects it and uses it as-is instead of double-wrapping it, but the bare-name form above is the supported convention.

Secrets

Reference secrets from Secret Manager:

secrets:
  - name: DATABASE_URL
    value: projects/123456789/secrets/database-url:latest
  - name: API_KEY
    value: projects/123456789/secrets/api-key:latest

Pilum automatically adds --set-secrets to the deploy command.

Environment Variables

env_vars:
  LOG_LEVEL: info
  ENVIRONMENT: production
  API_TIMEOUT: "30"

Multi-Region Deployment

Use regions: (plural) instead of region: to deploy the same service to several regions at once — Pilum expands it into one deployment per region, each with its own gcloud run deploy --region ..., all sharing the same built image:

name: my-api
provider: gcp
project: my-project
registry_name: my-repo
template: go
regions:
  - us-central1
  - europe-west1
  - asia-northeast1

build:
  language: go
  version: "1.23"
  env_vars:
    CGO_ENABLED: "0"

cloud_run:
  min_instances: 0
  max_instances: 10
  memory: "512Mi"
  cpu: "1"

pilum deploy --dry-run will show three deploy to cloud run commands, one per region, each correctly scoped with --region.

Deployment Steps

The GCP Cloud Run recipe executes:

build binary — Compile the application
build docker image — Create container image
publish to registry — Push to Artifact Registry
deploy to cloud run — Deploy with gcloud run deploy

Example Commands

# Deploy all GCP services
pilum deploy --tag=v1.0.0

# Deploy specific service
pilum deploy my-api --tag=v1.0.0

# Build and push only (no deploy)
pilum publish --tag=v1.0.0

# Deploy only (image must exist)
pilum deploy --only-tags=deploy --tag=v1.0.0

# Preview commands
pilum dry-run --tag=v1.0.0

Generated Deploy Command

Pilum generates:

gcloud run deploy my-api \
  --image us-central1-docker.pkg.dev/my-project/my-repo/my-api:v1.0.0 \
  --region us-central1 \
  --project my-project \
  --platform managed \
  --allow-unauthenticated \
  --min-instances=0 \
  --max-instances=10 \
  --memory 512Mi \
  --cpu 1 \
  --concurrency=80 \
  --timeout=300 \
  --set-secrets=DATABASE_URL=projects/123456789/secrets/database-url:latest

Troubleshooting

Authentication Errors

ERROR: (gcloud.run.deploy) PERMISSION_DENIED

Re-authenticate:

gcloud auth login
gcloud auth configure-docker us-central1-docker.pkg.dev

Image Push Fails

Ensure Docker is authenticated:

gcloud auth configure-docker us-central1-docker.pkg.dev

Service Doesn’t Start

Check logs:

gcloud run services logs read my-api --region us-central1

Next Steps

Service Configuration — Full reference
CLI Commands — All commands
Troubleshooting — Common issues