Skip to content

Deploying on Cloud Run

How to run my on Google Cloud with the OpenTofu module mycroblog-gcp: Cloud Run, Cloud Tasks, Cloud Scheduler, Cloud Storage, and Pub/Sub, with a PostgreSQL database on Neon, behind a global external Application Load Balancer. The service runs no instance while nobody uses it, except for a tick that wakes the server each minute. A server costs money: expect about $37 a month before storage, traffic, and open streams, and read Costs for what care can reduce.

The module needs OpenTofu 1.11 or later. Terraform is not supported.

One block of mycroblog-gcp creates all of this. Each row is a section of the module, and its default is what this guide deploys; the module’s README lists the other kinds.

Part Section Resources
Server service, jobs A Cloud Run service with role = all, a migration job, a console job while you need it, a service account, and public access
Traffic ingress A global external Application Load Balancer with a certificate. A domain mapping or Cloudflare are the other kinds, and a media host on Cloudflare can sit beside any
Jobs queue A Cloud Tasks queue, a Cloud Scheduler job, and a service account that calls the server
Media media A private bucket
Real-time updates stream A topic and a custom role. The server creates and removes its own subscriptions
Database database A secret for its URL: you create the database by hand
Email mail A secret for the SMTP password: any SMTP service
Secrets A generated VAPID key, and the secrets that only you can fill, empty
KEK kek A generated secret mounted as a file. Cloud KMS is the other kind
Metrics, traces, errors observability The APIs of Cloud Monitoring, Cloud Trace, and Error Reporting, which read what Cloud Run sends them

Secret values never reach the OpenTofu plan or state: you add the ones that come from elsewhere yourself, and the module generates the KEK and the VAPID key through write-only attributes.

  • tofu 1.11 or later, gcloud, and jq, where you apply: an apply that changes the version runs the migration from there, through gcloud.
  • A Google Cloud project with billing, used for this instance alone, and an account on it with the Owner role.
  • A domain for host. It cannot change later: read Settings you cannot change later.
  • A version of my from the releases. There is no latest tag.
Terminal window
gcloud services enable --project="$PROJECT" run.googleapis.com cloudtasks.googleapis.com cloudscheduler.googleapis.com \
pubsub.googleapis.com secretmanager.googleapis.com storage.googleapis.com iam.googleapis.com \
iamcredentials.googleapis.com cloudresourcemanager.googleapis.com logging.googleapis.com compute.googleapis.com \
monitoring.googleapis.com

compute.googleapis.com is for the load balancer.

Expect the Launch plan: with the default tick, the compute never stops. The Free plan works too, with the trade-offs under Costs.

In the Neon console, create a project in a region near your Cloud Run region, and copy its connection strings. The module never creates it, so its password stays out of the OpenTofu state. A project has two connection strings, and the deployment uses each where it belongs:

  • The direct one (the host without -pooler) is required. The migration job and the console always use it: my schema apply holds a session-level lock, which a pooler in transaction mode does not keep.
  • The pooled one (the host with -pooler) is optional, for the service. Neon’s pooler handles what the server needs: see Through a connection pooler. Set database = { pooled = true }, and the module creates a second secret for it.

Without a pooled string, the service uses the direct one too, at the database’s connection limit, which service.max_instances bounds. To raise the pool from its default of 4 per instance, for the 80 requests a Cloud Run instance takes at once, add pool_max_conns to the string the service uses, for example postgres://...-pooler...neon.tech/neondb?sslmode=require&pool_max_conns=8. See Waiting for a database connection.

Start from a copy in an empty directory, with the provider lock file, from the release you deploy:

Terminal window
VERSION=v0.1.0
git clone --depth 1 --branch "$VERSION" https://github.com/mycroblog/my.git my-source
mkdir my-deployment
cp -r my-source/deploy/opentofu/examples/gcp-cloud-run-neon/. my-deployment/
rm -rf my-source
cd my-deployment
cp terraform.tfvars.example terraform.tfvars

main.tf is the google provider and one block, module "mycroblog". Set ref to that release. The block names a release with ?ref=, which a stable release’s copy already has right. The server image is the same release, so ref alone names what runs. For a prerelease, set both yourself: sed -i "s/?ref=[^&]*/?ref=$VERSION/" main.tf, and image = { version = "0.1.0-rc.4" } in the block, the version without its v, since the module of a prerelease does not default to its own image. The module exists only from the first release that contains it, so an earlier tag has no example to copy. Keep this directory: it holds your state and your settings.

Fill in terraform.tfvars. mail_from, mail_smtp_host, and mail_smtp_username configure email; the port is 587, since Google Cloud blocks outbound port 25. To change anything else, add the section to the block in main.tf, such as ingress = { kind = "domain-mapping" }: every section and what it refuses is in the module’s README.

settings takes any other setting from the configuration reference by its key, and secrets the keys of secret settings, each of which gets an empty secret to fill. A key that a section or the module sets fails the plan, and so does a key the module does not take on Cloud Run, such as listen; the error says why. Decide on account_domain now, as settings = { account_domain = "example.org" }, if handles use another domain.

The state stays in this directory by default. It holds no secret values, but it is the only record of what was created: keep it in a bucket with a backend "gcs" block if more than one person runs this.

4. Create the secrets and add their values

Section titled “4. Create the secrets and add their values”

This creates the secrets, and generates the KEK and the VAPID key:

Terminal window
tofu init
tofu apply -target=module.mycroblog.module.secrets -target=module.mycroblog.module.kek_secret_manager

tofu init also fetches the scripts of that release: migrate.sh, which an apply runs, and console.sh, which a later step uses:

Terminal window
SCRIPTS=.terraform/modules/mycroblog/deploy/opentofu

Copy the KEK now, and keep the copy apart from the database, for example in a password manager. Without it a backup cannot be restored, and the accounts’ keys are lost. tofu output kek has the command. Do the same with the VAPID key, whose loss ends every Web Push subscription:

Terminal window
gcloud secrets versions access latest --secret=my-kek --project="$PROJECT"
gcloud secrets versions access latest --secret=my-vapid-key --project="$PROJECT"

Then add the values that come from elsewhere. tofu output secrets_to_fill lists each secret the module created empty, with what goes in it and the command that adds it. An instance whose secret cannot be read does not start, so add them before the service:

Terminal window
printf '%s' 'postgres://...' | gcloud secrets versions add my-database-url --project="$PROJECT" --data-file=- # the direct string
printf '%s' '<the SMTP password>' | gcloud secrets versions add my-smtp-password --project="$PROJECT" --data-file=-

The KEK reaches the server as a mounted file, named by MY_KEK_FILE. The others are environment variables resolved when an instance starts, so a new version takes effect on the next instance: deploy a new revision to make sure.

OpenTofu generates the KEK once and never again. The secret and its version have prevent_destroy, and the version number that would write a new value is fixed in the module: a new random KEK makes everything the old one encrypted unreadable. To rotate, follow Rotate the KEK, adding the new value with gcloud secrets versions add. OpenTofu does not track what you add there.

To keep the KEK in Cloud KMS from the start, set kek = { kind = "kms" } before this step, target module.mycroblog.module.kek_kms in place of kek_secret_manager, and enable cloudkms.googleapis.com.

Terminal window
tofu apply

This creates everything else, in an order that the service’s startup probe needs: the probe waits for /health/ready, which answers 503 until the schema exists. The migration job comes first, with what it depends on, which includes the load balancer’s address, since the server’s settings name it. Then the apply runs my upgrade as an execution of the job, from your machine through gcloud, and waits for it: my config check, my db upgrade -check, my schema apply, and my db upgrade, which stops at the first that fails. Its output appears in the apply’s. The first command that uses the database records host and account_domain in it. Only then does the apply create the services.

If the migration fails, the apply stops before the services. Fix the cause, often a secret without a value, and run tofu apply again: it runs the migration again.

tofu output dns_records lists one A record, of host to the load balancer’s address. Add it at your DNS provider. If that provider has a proxy of its own, leave it off for this record.

The certificate is Google-managed and becomes active only once DNS points at the address, which can take a while. Until then https://{host} fails with a TLS error, so federation and browsers cannot reach the server yet. Nothing else waits for it: Cloud Tasks and Cloud Scheduler call the service’s default run.app URL, https://<service>-<project number>.<region>.run.app. Do not disable the default URL, or jobs stop. That URL refuses requests from the internet, and Cloud Run counts these two as internal only from the same project and on that URL, not on a custom domain.

See How traffic reaches the service for what else you can choose.

Cloud Run jobs have no terminal and no standard input, so my admin create prints a link that sets the password instead of reading one. Turn the console on, and run:

Terminal window
tofu apply -var console_enabled=true
tofu output -json console | "$SCRIPTS/console.sh" admin create -username alice -email alice@example.com -password-link
tofu apply -var console_enabled=false

Open the link right away and set the password. It works once, for one hour. It stays in Cloud Logging until then, where anyone who can read the project’s logs can use it. If it expires, run my admin account password-reset-link @alice through the console. Then turn on two-factor authentication.

Go through the production checklist, starting with email: SPF, DKIM, and DMARC on the domain of mail_from.

The console runs one my command with the image, settings, and secrets of the service. It exists only while console_enabled is on, so turn it off when you finish:

Terminal window
tofu apply -var console_enabled=true
tofu output -json console | "$SCRIPTS/console.sh" instance set registration_mode open
tofu apply -var console_enabled=false

console.sh waits for the command, prints its output and exit code, and exits with that code. It needs roles/logging.viewer, because a job’s output goes to Cloud Logging. It uses the image the service runs: after an upgrade that stopped at the migration, that is the previous release, which the database still fits.

The command has no standard input and no terminal, so a command that reads a password or a file from them cannot run this way. What it prints stays in the logs, so do not run a command whose output you would not write there.

Read Upgrading and the release notes first, and go one minor version at a time. An upgrade is an apply of the new release: the plan shows every service and job taking its image, and the apply runs the migration before any of them serves it.

Terminal window
# 1. Back up the database while nothing writes: see "The maintenance mode" below, and Backup and restore.
pg_dump --format=custom --file=my-before-upgrade.dump "$DATABASE_URL"
# 2. Name the new release in main.tf, as ?ref=v0.2.0, and fetch it.
tofu init
# 3. Read the plan, then apply it.
tofu plan
tofu apply

The image is the release that ref names, so changing ref is the whole upgrade. Read the plan before you apply it: a new release’s module may change resources too. The apply does this, and stops at the first step that fails:

  1. Gives the migration and console jobs the new image, with the rest of the plan that the services do not depend on.
  2. Runs my upgrade as an execution of the migration job, from where you apply, and waits for it: my config check, my db upgrade -check, my schema apply, and my db upgrade. Its output appears in the apply’s.
  3. Deploys the new revision of each worker, then of the service. A revision takes traffic only when its startup probe passes on /health/ready.

Where you apply needs gcloud and jq, and credentials that may execute the job and read its logs (roles/run.developer and roles/logging.viewer, which Owner includes). The same holds for a CI job that applies.

When a step fails, the services stay on their revisions, and the release notes or the migration’s output say why. Fix the cause and run tofu apply again, with the same version: it runs the migration again, and the steps that completed find nothing left to do. An apply that was interrupted, or that lost its connection, leaves the execution running on Cloud Run; the next apply waits for it to end before it starts its own. To go back after the schema changed, restore the backup: see Rolling back. An apply with an earlier version stops at the migration, since that release refuses a newer schema, and changes no service.

To try a release candidate, or to keep the image of an earlier release under a newer module, set the version yourself; it is the image tag, without the v of the release:

image = { version = "0.2.0-rc.1" }

The plan does not show the SQL of the migration. To read it before the apply, give the migration job the new image alone, and run my upgrade -dry-run in it, which changes nothing:

Terminal window
tofu apply -target='module.mycroblog.module.app.google_cloud_run_v2_job.one_off["migrate"]'
gcloud run jobs execute my-migrate --project="$PROJECT" --region=asia-northeast1 --args=upgrade,-dry-run --wait
gcloud logging read 'resource.type="cloud_run_job" AND resource.labels.job_name="my-migrate"' --project="$PROJECT" \
--freshness=1h --format='value(textPayload)' --order=asc

When the release notes call for -allow-destructive, name that version in the block:

upgrade = { allow_destructive_for = "0.3.0" }

my upgrade gets -allow-destructive only on the apply of that version, so a value left in place lets no later release drop data.

The production checklist recommends a digest, from the release notes:

image = { digest = "sha256:..." }

A digest names one image, whatever the tag beside it says, so change it in the same edit as ref: a digest left from the previous release keeps that release’s image under the new version.

The maintenance mode takes three applies, since the services change before the upgrade and after it. Add it to the settings of the block and apply, take the backup, raise ref and apply, then remove it and apply:

settings = { maintenance = "true" }

Without it, the old revision keeps serving during the migration, which is not guaranteed to work. Settings changed by hand with gcloud do not last: the next apply puts back what the block says.

The module adds an uptime check of /health/live, log-based metrics, and alert policies with the names of the runbook, which notify the addresses of monitoring.notification_emails (alert_emails in the example) or the channels of notification_channels. The input has no default: name who is notified, or set monitoring = null to leave all of it out. It has never been applied, so try it once by making a check fail. Each run of the check wakes an instance, which adds to the tick’s trade-off: uptime_period, 15 minutes by default, is how often.

Change the kind of its section. Each kind sets what it needs on the server, and the plan says what changes. Changing the database also means moving its data, since a new one is empty: take a backup of the old one and restore it into the new one while nothing writes. For example, Cloud SQL in place of Neon:

database = { kind = "cloud-sql" }

For a store outside Google Cloud, set media.kind to s3, for any S3-compatible service with its endpoint, or to r2, with cloudflare.account_id. Both read an access key from the secrets that secrets_to_fill lists.

This guide needs none: Neon, Cloud Tasks, Cloud Storage, and Pub/Sub are all reached over the internet with the service’s own identity, so Cloud Run attaches to nothing and there is nothing to pay for or look after.

You need one to put Memorystore in the deployment, since it has only private addresses, or to give Cloud SQL a private address in place of its public one. network = { kind = "vpc" } creates one, and network = { kind = "existing", ... } attaches to a VPC you have, which you describe by network, subnetwork, private_services_range, and memorystore_connection_policy:

network = { kind = "vpc" }
kv = { kind = "memorystore" }

Only private ranges go through the network, so the service reaches the internet as it did, with no Cloud NAT. nat = true sends everything through Cloud NAT instead, for a static source address. Enable the Service Networking and Network Connectivity APIs first, and the Compute Engine API. A network adds to the cold start of an instance, and Memorystore bills while the server is idle.

When one kind of job holds up the rest, give it its own service. Decide what to split from the metrics, as Splitting workers by job type says. One value, workers, goes to the service, the queue, and the monitoring, and every queue, URL, route, and setting comes from its keys, so you write none of them:

workers = {
delivery = {
job_types = ["federation.fanout", "federation.deliver"]
max_instances = 20
concurrency = 16
}
}

The plan refuses a split of the types that must stay together. It also needs a broker that reaches every process, which stream.kind = pubsub is.

The two common layouts of that page look like this. To keep deliveries from delaying the rest, use the value above. To keep email and notifications quick:

workers = {
notify = {
job_types = [
"identity.verification_email", "identity.password_reset_email", "identity.password_notice_email",
"identity.closure_email", "identity.deactivation_email",
"notification.email", "notification.moderator_email", "notification.supporter_email",
"notification.push", "notification.post_subscribers",
"instance.notify_announcement", "voice.notify_started",
]
max_instances = 10
}
}

Leave out the types of settings you have not set, as that page says: a type the server has not registered stops the start, and the plan cannot see which those are. With workers, the default service does not help with these types when it is free, since their tasks go to their own queue.

Each worker takes job_types, and min_instances, max_instances, cpu, memory_mib, concurrency, max_concurrent_dispatches, and max_dispatches_per_second, each the service’s or the queue’s where it is not named. A worker’s service takes no traffic from outside. An upgrade moves each after the migration and before the default service, and with nothing to tell it: only a step that fails stops it. Each worker can bring what the service costs, and the connections of its instances count against the database’s limit.

ingress.kind decides this. The default is the load balancer, which is meant for production. The domain mapping is for trying a deployment cheaply: set ingress = { kind = "domain-mapping" }.

load-balancer (the default) domain-mapping
Monthly fee About $18 for the forwarding rules, plus a charge per GB. Check the pricing page: this figure could not be confirmed there None
Status Google Cloud’s recommended way A Preview feature that Google Cloud does not recommend for production, because of latency
Regions Any asia-northeast1, us-central1, and a few others
DNS An A record, from tofu output dns_records The records that the same output lists
Certificate Google-managed, active once DNS points at the address Google-managed, up to 24 hours
Domain ownership Nothing beyond DNS You, and every other account that applies, must be a verified owner before you apply
run.app URL Refused from the internet, so nobody goes around the load balancer Reachable by anyone: a domain mapping cannot add a header, so the origin stays open
MY_TRUSTED_PROXIES 169.254.0.0/16 and the load balancer’s address 169.254.0.0/16

Cloud Tasks and Cloud Scheduler arrive through neither: they call the default run.app URL directly.

ingress = { kind = "cloudflare" } puts Cloudflare in front of host, with the cache bypassed for everything, and ingress.media_host adds a cached media host beside any kind. Both need cloudflare = { zone_id = "..." }, and the token goes in CLOUDFLARE_API_TOKEN. They have run only on mocked providers.

  • Your plan decides the origin. Cloud Run routes by Host, and Cloudflare offers the Host header override on the Enterprise plan only. On any other plan the origin must accept your host itself, so the module creates a domain mapping of each host, with the trade-offs of the table above, and Cloudflare connects to it. Whether its certificate is issued and renewed behind the proxy is unverified, so start with cloudflare.proxied = false. On the Enterprise plan, cloudflare.host_header_override = true connects to the run.app URL instead, with no domain mapping.
  • A header closes the origin. The module adds a request header transform rule, and the server refuses a request without the header with a 403, apart from health checks and the jobs’ own POSTs, which check their tokens. So nobody goes around Cloudflare through the run.app URL, and a caller’s own Cloudflare Worker cannot choose the client address the rate limits see.
  • The value lands in the state. The module generates it and writes it to the secret my-origin-secret, but the Cloudflare provider has no write-only form of a rule’s header value, so keep the state private. The CDN guide has how rotation works.
  • Nothing adds the header while a record is not proxied, so the server refuses everything but its health checks: with proxied = false for a domain mapping’s certificate, turn the proxy on once the certificate is active.
  • Turn off Bot Fight Mode in the dashboard. It covers the whole zone and no rule can skip it, and a challenge on /ap/, /.well-known/, or /api/ breaks federation, because other servers are not browsers. Jobs do not come through Cloudflare. The module adds no challenge and turns off Browser Integrity Check, but it does not manage Bot Fight Mode. Do not turn on “I’m Under Attack” for the same reason.
  • Email Address Obfuscation can stay on. It rewrites email addresses in HTML into [email protected] and adds a script to restore them, which the server’s Content-Security-Policy refuses. The server’s own pages, such as the one that says where the confirmation email went, mark their content so that it leaves the addresses alone.
  • Turn on Always Use HTTPS in the dashboard if you want http:// redirected. It covers the whole zone, so the module leaves it to you.
  • Timeouts: Cloudflare answers 524 when the origin sends nothing for 125 seconds. Jobs are not affected, since they call the run.app URL directly. Streams send a heartbeat every 30 seconds, under the 900-second idle limit. Whether it buffers streams on an ordinary proxied host is unverified.
  • Uploads: 100 MB on Free and Pro, above Cloud Run’s 32 MiB, which remains the limit.
  • Video: Cloudflare’s terms restrict serving video and a disproportionate amount of large files on Free, Pro, and Business, and it may redirect the content or take other action. Decide this before you cache video on the media host.

A deleted file stays cached. The media host follows the server’s Cache-Control, so a deleted local file can stay visible for up to a year, and a remote one for remote_media_cache_ttl_seconds. The server does not purge it. When something must disappear, purge it by hand, under Caching > Configuration > Custom Purge in the dashboard, or:

Terminal window
curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/purge_cache \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-d '{"files": ["https://media.example.org/media/<path>"]}'

A proxy URL holds its sig in the query string, which is part of what is cached, so give the whole URL.

Changing kek.kind is one line in main.tf, but on an instance with data it is not free. The database holds secrets wrapped with the current key, so an instance that loses it can no longer read them, and every account’s keys are among them.

Follow Move between the local KEK and a KMS. From the secret to Cloud KMS, keep the current KEK as kek_previous while the secrets move: add secrets = ["kek_previous"], and fill the secret my-kek-previous with the current KEK. Run my kek rewrap through the console, then remove it when my kek status no longer counts local: keys. Keep the KEK for as long as you keep database backups from before the rewrap.

On a new instance with no data, nothing needs to move.

  • Uploads: Cloud Run refuses an HTTP/1 request above 32 MiB, and the server speaks HTTP/1.1. The module therefore sets MY_MEDIA_MAX_AV_BYTES to 30 MiB, against the default of 100 MiB, so that a larger upload gets the server’s own answer.
  • Streams: the request timeout, 15 minutes by default, ends an open stream, and the client connects again.
  • Client addresses: the rate limits rely on MY_TRUSTED_PROXIES, which the module sets from the ingress. No document we have read says what Cloud Run adds to X-Forwarded-For for a direct request or what peer address a container sees, and the container contract says nothing about either, so 169.254.0.0/16 is an assumption. The external load balancer’s documented form is [<supplied>,]<client-ip>,<lb-ip>. Check the addresses in the first request logs: a client IP that is a 169.254 address or a Google address means that the setting is wrong for your project.
  • Public access: the service grants roles/run.invoker to allUsers, which an organization policy on domain-restricted sharing refuses. Such a project needs an exception.

A server costs money. These figures are a guide to what to expect and to where care reduces it, not limits that the deployment is held to. They are approximate list prices for one region, from 2026-10 and 2026-11. Check them on the Cloud Run and Neon pricing pages. Compute is free per billing account up to 180,000 vCPU-seconds and 360,000 GiB-seconds a month.

Part Idle What adds to it
Load balancer About $18 a month, not confirmed on the pricing page A charge per GB; see How traffic reaches the service
Neon, on the Launch plan About $19 a month, with the default tick Storage at $0.35 per GB-month. database.kind = cloud-sql instead has a fixed cost of about $9.40 a month, for a smaller machine
Cloud Run $0: min instances is 0 and CPU is billed only during requests Each open stream keeps an instance billed; see below
Cloud Tasks $0 1 million operations free, then $0.40 per million. A job takes about 2
Cloud Scheduler $0: 3 jobs free per billing account $0.10 per job above that
Cloud Storage About $0.02 per GiB a month 5 GiB are free only in us-east1, us-west1, and us-central1. Media goes out through Cloud Run
Pub/Sub $0: 10 GiB free Only while streams are open
Secret Manager Cents A few free versions, then a few cents per version

The tick keeps Neon awake. Each tick reads and writes the database, and Neon stops a compute only after 5 minutes without activity, so with the default * * * * * the compute never stops. That is 730 hours a month, or 182.5 CU-hours at 0.25 CU, which is the $19 above. The tick stays at every minute so that periodic jobs run on time, and a lost wake-up signal is recovered soon.

An open stream keeps an instance billed. Under request-based billing, an instance is billed while it handles any request, and the real-time updates are one long request. One client that keeps its stream open all month costs one instance around the clock: about $60 a month at 1 vCPU and 512 MiB, after the free allowance. More streams share the instance, up to concurrency. If streams stay open most of the time, compare with instance-based billing, or with a small VM and Docker Compose.

  • The domain mapping in place of the load balancer takes the $18 away, with the trade-offs above. It suits trying a deployment.
  • Neon’s Free plan takes the $19 away, and a small instance can run on it, with these trade-offs:
    • It allows 100 CU-hours a month, which the default tick uses up after about 17 days. Stay inside it with a longer schedule, such as queue = { tick_schedule = "*/10 * * * *" }: at most half the time awake, about 91 CU-hours, before anything else wakes it. Periodic jobs then run up to 10 minutes late, and a lost wake-up signal is recovered later.
    • A federated server receives deliveries around the clock, which also wakes the database, so a busy instance outgrows it whatever the schedule.
    • It holds 1 GB per project and a 6-hour history to restore from, and its compute always stops after 5 minutes idle, so the first request after that waits for it.

For LLMs and coding agents:this page as Markdown, llms.txt,llms-full.txt, llms-small.txt

Analytics on this site