Run the relay on Google Cloud (Cloud Run)
The Terraform module in deploy/relay/terraform/gcp-cloud-run runs the relay as a Cloud Run service that reaches your private network through Direct VPC egress. On GKE, use the Helm chart instead.
What it sets up:
- A Cloud Run service with one instance always running (
min_instance_count = 1) and CPU always allocated (cpu_idle = false). Both are needed: the relay works in the background, polling Guidely, rather than answering requests, and Cloud Run would otherwise throttle its CPU between requests. - Internal ingress only. Nobody needs to call the relay.
- Direct VPC egress with
PRIVATE_RANGES_ONLY: requests to private addresses (your targets) go into your VPC from the subnetwork you choose, carrying the network tags you set; HTTPS to Guidely goes out through Cloud Run's own internet access, so you don't need Cloud NAT. - A dedicated service account that can read only the relay's secrets in Secret Manager.
- An Artifact Registry remote repository that mirrors
ghcr.io, because Cloud Run can't pull fromghcr.iodirectly. (Setimageto skip it and use an image you copied into Artifact Registry.) - Optionally, a firewall rule that lets the relay's network tag reach your targets' ports.
Before you start
- The Cloud Run, Artifact Registry, Secret Manager and Compute Engine APIs enabled.
- A subnetwork in the same region as the service, with a few free addresses, that can reach your targets.
- The relay token in Secret Manager, created outside Terraform so the value stays out of its state:
printf '%s' 'gly_rly_...' | gcloud secrets create guidely-relay-token --data-file=-
printf '%s' 'glsa_...' | gcloud secrets create grafana-sa-token --data-file=-
Deploy
module "guidely_relay" {
source = "github.com/GuidelyTech/Guidely//deploy/relay/terraform/gcp-cloud-run"
project_id = "my-project"
region = "europe-west1"
network = "prod-vpc"
subnetwork = "prod-europe-west1"
relay_token_secret = "guidely-relay-token"
targets = [
{ name = "prom", kind = "prometheus", url = "http://10.10.0.5:9090" },
{ name = "logs", kind = "loki", url = "http://10.10.0.6:3100" },
{ name = "grafana", kind = "grafana", url = "http://10.10.0.8:3000" },
]
target_secrets = { TARGET_GRAFANA_BEARER = "grafana-sa-token" }
firewall_target_ports = ["9090", "3100", "3000"]
}
target_secrets maps a TARGET_<NAME>_… variable to a Secret Manager secret; plain settings such as TARGET_<NAME>_ORG_ID go in environment. The module's README lists every input.
Check it
The check_command output creates a Cloud Run job with the same image, network and secrets that runs guidely-relay check once and waits for it:
eval "$(terraform output -raw check_command)"
gcloud logging read 'resource.type="cloud_run_job" AND resource.labels.job_name="guidely-relay-check"' --limit 20 --format 'value(textPayload)'
Then look in Integrations → Grafana, Prometheus, Tempo, Loki: the relay shows as connected, with its targets.
Notes
- Targets on GKE: give them internal load balancer addresses, or run the relay inside the cluster with the Helm chart.
- Internal DNS names: names that resolve to private addresses reach them through the VPC. If a name in a Cloud DNS private zone doesn't resolve, use the IP address, or set
vpc_egress = "ALL_TRAFFIC"and add Cloud NAT so Guidely stays reachable. - Google Cloud Managed Service for Prometheus: query it through a Grafana that uses it as a data source, or through its Prometheus-compatible frontend.
- Cost: one always-on instance with 1 vCPU and 512 MiB. The relay is idle most of the time.