Skip to main content

Deploy to GCP Cloud Run

declaragent deploy gcp-cloud-run takes your agent.yaml + secrets and emits a Cloud Run-ready Dockerfile + service.yaml. We deliberately stop short of invoking gcloud ourselves — the user's GCP auth flow is theirs to own.

Prerequisites​

  • A GCP project with billing enabled.
  • gcloud installed and authenticated (gcloud auth login, gcloud config set project <PROJECT>).
  • The roles/run.admin, roles/iam.serviceAccountUser, and roles/secretmanager.admin roles on the deploying principal.

Generate artifacts​

declaragent deploy gcp-cloud-run

Produces:

.declaragent/deploy/
├── Dockerfile
├── service.yaml
├── .dockerignore
└── README.md               # the three commands to run

Verify locally (dry-run)​

The generated Dockerfile COPYs a prebuilt linux binary and a config dir — stage both first (the generated .declaragent/deploy/README.md lists the exact steps):

mkdir -p .declaragent/deploy/bin .declaragent/deploy/config
# place bin/declaragent-linux-x64 + your config files per the generated README
docker build -t declaragent-agent .declaragent/deploy/
docker run --rm -p 8787:8787 declaragent-agent

Apply​

gcloud builds submit .declaragent/deploy/ --tag us-central1-docker.pkg.dev/<PROJECT>/declaragent/agent:latest
gcloud run services replace .declaragent/deploy/service.yaml --region us-central1
declaragent deploy gcp-cloud-run --verify

The --verify step hits the daemon's /health endpoint + runs gcloud run services describe. On 200, the command prints a shareable URL + the Slack / Telegram / WhatsApp webhook configuration snippet.

Cost​

Cloud Run at the baseline preset (cpu=1, memory=512MiB, minInstances=1) costs roughly $40–$60 / month before provider tokens. Daemons need minInstances = 1 so webhooks can arrive at any time. Users running infrequent workloads can drop minInstances to 0 but must accept cold-start latency on inbound events.

Troubleshooting​

  • 403 at deploy. See Troubleshooting → my deploy got 403 — it includes the gcloud projects get-iam-policy check for the three required roles (there is no built-in IAM preflight; --verify is a post-deploy health check).
  • Secret Manager binding failed. Each ${secret:...} reference maps to a Secret Manager binding in service.yaml. If the service account lacks roles/secretmanager.secretAccessor, the revision fails to start.

The nightly Cloud Run soak workflow (.github/workflows/cloud-run-soak.yml) exercises this deploy path in CI.