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 from ghcr.io directly. (Set image to 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.