Skip to content

Deploy Kaeso on Google Cloud

Two Terraform configurations run Kaeso on Google Cloud. The quick server puts the Compose package on one Compute Engine instance from Cloud Shell; the managed configuration runs it on Cloud Run with a load balancer, Cloud SQL and Memorystore.

Published
Reading time
3 min
Author
Kaeso Team
A deep gradient of deep and pale blue, folding diagonally downward, with a warm light in one corner

deploy/gcp/ in the Kaeso repository holds two Terraform configurations, which OpenTofu applies too. The quick server is the Compose package on one virtual machine, as on your own server. The managed configuration runs Kaeso on Cloud Run with Google's data stores, for installs that outgrow one machine.

The quick server

deploy/gcp/quick-server/ creates one Compute Engine instance with Ubuntu 24.04, a static address, firewall rules for HTTP, HTTPS and HTTP/3, SSH from the address ranges you choose, and an optional Cloud DNS record. At first boot, the instance runs Kaeso's installer, which installs Docker, writes the settings and starts the Compose package with Caddy, a bundled ClickHouse and the updater.

The quickest way in is Open in Cloud Shell (opens in a new tab). It clones the branch prod, which holds the latest release, with this folder open. Cloud Shell has terraform rather than tofu, so use that name:

cd deploy/gcp/quick-servertofu inittofu apply -var project=my-project -var domain=kaeso.example.com \  -var 'ssh_source_ranges=["203.0.113.0/24"]'
VariableWhat it is
project, region, zoneWhere the instance runs; europe-west3-a by default
domainThe domain Kaeso answers on; without dns_zone, point its A record at the public_ip output
kaeso_versionA release to install; empty installs the newest stable release
machine_type, disk_size_gbe2-medium and 40 GB by default
ssh_source_rangesWho may reach SSH, which kaeso setup-link needs
dns_zoneA Cloud DNS managed zone of the domain, to create its record

Once the instance is up and the certificate is issued, run the setup_link output to print the one-time link that creates the first user. Update in the console works from then on, as on any Compose install.

The managed configuration

deploy/gcp/managed/ builds Kaeso from Google Cloud services:

  • a VPC with a subnet, a serverless VPC connector and private services access;
  • Cloud SQL for PostgreSQL 17 with a private address only, and Memorystore for Valkey with noeviction, reachable only over the VPC;
  • Secret Manager secrets for the master keys, the PostgreSQL URL, the SMTP password and the ClickHouse URL, read by the gateway's service account;
  • Cloud Run services for the gateway, with 2 CPUs and 4 GB by default, at least one instance kept warm and a request timeout of an hour, and for the console, both reachable only through the load balancer;
  • a global external Application Load Balancer with a managed certificate, HTTP redirected to HTTPS, path rules for the gateway and the console, and a backend timeout of an hour for long streams;
  • an optional Cloud DNS record.
cd deploy/gcp/managedtofu inittofu apply -var project=my-project -var domain=kaeso.example.com \  -var "master_keys=$(docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate)" \  -var setup_email=owner@example.com -var smtp_host=smtp.example.com \  -var smtp_user=kaeso -var smtp_password=secret \  -var 'smtp_from=Kaeso <kaeso@example.com>'

Keep a copy of the master key in a password manager: Kaeso encrypts provider keys with it. gateway_cpu, gateway_memory, gateway_min_instances and gateway_max_instances size the gateway, and several instances share limits, caches and route cooldowns through Valkey. database_tier, database_disk_gb and cache_node_type size the data stores. For request logs, set clickhouse_url to a ClickHouse such as ClickHouse Cloud.

The managed certificate is issued once the domain points at the load balancer's address, which can take up to an hour. Then the gateway emails the one-time setup link to setup_email.

Memorystore is reached without a password and without TLS, over the private network only, because the gateway can't present Google's IAM tokens or its private certificate authority. The gateway trusts X-Forwarded-For only from the load balancer's proxy ranges and Cloud Run's own front end.

Update and roll back

On the quick server, update from the console, automatically, or by hand. On the managed configuration, a release changes the image tags in main.tf: apply the new configuration, and Cloud Run creates new revisions and shifts traffic once they are healthy. The gateway migrates the databases at start, forward only. To roll back on purpose, apply the previous release's configuration, or shift traffic to the previous revision in Cloud Run.

What was tested

On 2026-11-07 the quick server was deployed in a new project in europe-west3, with the eighth release candidate. It created the first user, served the console and the APIs on one HTTPS origin, streamed five events whose text was exactly Kaeso stream works., wrote the request to ClickHouse, and ignored a forged X-Forwarded-For address. The managed configuration is linted and formatted in CI, and hasn't been deployed yet.

Next steps

By Kaeso Team

On this page

Own the gateway.Own the record.

curl -fsSLhttps://kaeso.app/install.sh | sh