Nov 18, 20266 min read

How to Map a Custom Domain to Cloud Run

The three ways to put your own domain in front of a Cloud Run service, a global external Application Load Balancer, Cloud Run domain mapping and Firebase Hosting, with gcloud and Terraform steps and the limits of each.

Illustration for How to Map a Custom Domain to Cloud Run

A Cloud Run service gets a run.app URL the moment it deploys, which works until a webhook provider or a mobile app needs a stable api.example.com. Google offers three ways to get there, and the simplest one in the console is the one Google says not to use in production.

This guide walks through all three, with the load balancer setup in Terraform, then shows how custom domains work when Encore deploys the same service to your own GCP project.

Cloud Run custom domain options at a glance

Encore custom domainGlobal external Application Load BalancerCloud Run domain mappingFirebase Hosting
Launch stageAvailable on every Encore environmentGA, recommended by GooglePreview, limited availabilityGA
DNS recordCNAME to custom-domain.encr.appA record to a static IPRecords returned by the mappingRecords from Firebase
CertificateIssued by EncoreGoogle-managed or your ownGoogle-managed onlyManaged by Firebase
RegionsAny region you deploy toAny Cloud Run regionTen listed regionsAny Cloud Run region
ExtrasCloudflare WAFCloud CDN, Cloud Armor, path routingNoneStatic hosting, CDN
Resources to manageOne DNS recordNEG, backend, URL map, proxy, certificate, rule, IPOne mappingA Firebase project and firebase.json

The domain mapping limits come from Google's custom domain docs for Cloud Run, and the Encore column comes from the custom domains docs.

Option 1: Global external Application Load Balancer

The load balancer is the option Google recommends, and it is also the one with the most resources. Traffic reaches a global anycast IP, the HTTPS proxy terminates TLS with a managed certificate, and a serverless network endpoint group (NEG) forwards to the Cloud Run service in its region. In return you can bring your own certificate, route paths to different services, and add Cloud CDN or Cloud Armor in front.

resource "google_compute_global_address" "api" { name = "api-ip" } resource "google_compute_region_network_endpoint_group" "api" { name = "api-neg" region = "europe-west1" network_endpoint_type = "SERVERLESS" cloud_run { service = google_cloud_run_v2_service.api.name } } resource "google_compute_backend_service" "api" { name = "api-backend" load_balancing_scheme = "EXTERNAL_MANAGED" backend { group = google_compute_region_network_endpoint_group.api.id } } resource "google_compute_url_map" "api" { name = "api-urlmap" default_service = google_compute_backend_service.api.id } resource "google_compute_managed_ssl_certificate" "api" { name = "api-cert" managed { domains = ["api.example.com"] } } resource "google_compute_target_https_proxy" "api" { name = "api-https-proxy" url_map = google_compute_url_map.api.id ssl_certificates = [google_compute_managed_ssl_certificate.api.id] } resource "google_compute_global_forwarding_rule" "api" { name = "api-https" load_balancing_scheme = "EXTERNAL_MANAGED" target = google_compute_target_https_proxy.api.id ip_address = google_compute_global_address.api.id port_range = "443" }

After terraform apply, create an A record for api.example.com that points at the address in google_compute_global_address.api. The managed certificate stays in a provisioning state until DNS resolves to the load balancer, so expect it to take a while after the record propagates. To keep clients from bypassing the load balancer through the run.app URL, set ingress = "INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER" on the google_cloud_run_v2_service resource, and add a second forwarding rule on port 80 with a redirecting URL map if plain HTTP should redirect to HTTPS.

Option 2: Cloud Run domain mapping

Domain mapping attaches a domain straight to a service, without a load balancer, and Google issues the certificate. The command is short:

gcloud domains verify example.com gcloud beta run domain-mappings create \ --service api \ --domain api.example.com \ --region europe-west1 gcloud beta run domain-mappings describe \ --domain api.example.com \ --region europe-west1

gcloud domains verify opens Search Console for the base domain, and the describe output lists the DNS records under resourceRecords to add at your registrar. The limits are what rule it out for production: Google lists domain mappings as Preview, says they are not production-ready because of latency issues, makes them available in ten regions such as europe-west1 and us-central1, does not let you disable TLS 1.0 and 1.1 or upload your own certificate, and caps the domain at 64 characters. The certificate usually takes about 15 minutes and can take up to 24 hours.

Option 3: Firebase Hosting

Firebase Hosting can rewrite every path to a Cloud Run service and serve it on a domain connected in the Firebase console. It is a reasonable choice when the same domain also serves a static frontend, and it brings Firebase's CDN with it.

{ "hosting": { "rewrites": [ { "source": "**", "run": { "serviceId": "api", "region": "europe-west1" } } ] } }

Deploying it with firebase deploy --only hosting puts a Firebase project in the request path of a backend API and adds a second place where routing lives, next to your Cloud Run configuration.

How do custom domains work with Encore?

Encore

Encore brings infrastructure from code and deploys it to Cloud Run in your own GCP project, so the services, their routes and the infrastructure they use come from the application, and the domain becomes a setting on the environment. Every environment is reachable on an encr.app subdomain from the first deploy. For your own domain, the custom domains docs describe two steps: a CNAME record for each domain pointing at custom-domain.encr.app, then Settings > Custom Domains in the Encore app, where you pick the environment the domain serves.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

// api/api.go package api import "context" type Health struct { Status string `json:"status"` } // Served on https://api.example.com/health once the domain is active. //encore:api public method=GET path=/health func Check(ctx context.Context) (*Health, error) { return &Health{Status: "ok"}, nil }

The DNS side is one record at your provider, with the 30 minute TTL that the docs recommend:

api.example.com. 1800 IN CNAME custom-domain.encr.app.

Encore issues the SSL certificate for the domain, shows its progress from Waiting for CNAME to Active in the settings page, and puts Cloudflare WAF in front of the domain. Wildcard CNAMEs such as *.example.com are not supported, so each hostname gets its own record. The encr.app subdomain keeps serving the same environment, which lets older clients move to the new domain over time.

A coding agent working on this app adds endpoints in Go and checks them with encore run locally, and the domain stays an environment setting that the agent does not need to touch.

Best fit: Go or TypeScript backends on Cloud Run in your own GCP project that want an HTTPS domain per environment from one DNS record.

Which option should you pick?

Use the global external Application Load Balancer when you manage Cloud Run yourself and need your own certificate, path routing across services, Cloud CDN or Cloud Armor. Use Firebase Hosting when a static frontend and the API share one domain and you already use Firebase. Treat Cloud Run domain mapping as a development convenience in its ten regions, since Google does not recommend it for production. Use Encore when the backend is deployed with Encore, so the domain is a CNAME and a setting rather than seven load balancer resources.

Frequently asked questions

How do I add a custom domain to Cloud Run?

Google recommends a global external Application Load Balancer: create a serverless network endpoint group for the service, a backend service, a URL map, a Google-managed certificate and an HTTPS forwarding rule on a static IP, then point an A record at that IP. Cloud Run domain mapping is simpler but is in Preview and not recommended for production.

Are Cloud Run domain mappings production-ready?

No. Google lists Cloud Run domain mappings as Preview and limited availability, says they are not production-ready because of latency issues, and supports them in only ten regions. They also cannot disable TLS 1.0 and 1.1 or use your own certificate.

How long does a Cloud Run custom domain certificate take?

For domain mappings, Google says the managed certificate usually takes about 15 minutes and can take up to 24 hours. A Google-managed certificate on a load balancer also waits until the A record points at the load balancer IP before it becomes active.

How do I use a custom domain with Encore on GCP?

Add a CNAME record for the domain pointing at custom-domain.encr.app, then add the domain in the app's Custom Domains settings and pick the environment. Encore issues the SSL certificate and starts serving the environment on that domain once the CNAME is active.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders