To return faster responses to your users around the world, you need to deploy services in multiple regions and route your users to the nearest region.
Because Cloud Run services are deployed into individual regions, you need to configure an external Application Load Balancer to route your users to different regions of your service.
This guide shows you how to configure an external Application Load Balancer with a domain secured with a managed TLS certificate pointing to a global anycast IP address, which routes users to the nearest Google data center that has your service deployed.
The architecture described in this guide does not automatically route requests to a different region when a regional Cloud Run service becomes unresponsive or starts returning errors. To increase the availability of your multi-regional service, you can configure outlier detection to identify unhealthy Cloud Run services based on their HTTP error rate and diverge some requests to another region.
Create a load balancer
Creating an external load balancer involves creating various networking resources and connecting them together:
Command line
- Reserve a static IP address so you don't have to update your DNS records
when you recreate your load balancer.
In the command above, replace SERVICE_IP with a name for the IP address resource (e.g.gcloud compute addresses create --global SERVICE_IP
myservice-ip
).This IP address is a global anycast IPv4 address that routes to the Google datacenter or point of presence closest to your visitors.
-
Create a backend service.
gcloud compute backend-services create --global BACKEND_NAME
In the command above, replace BACKEND_NAME with a name you want to give to the backend service (e.g.
myservice-backend
). - Create a URL map.
gcloud compute url-maps create URLMAP_NAME --default-service=BACKEND_NAME
Replace URLMAP_NAME with a name you want to give to the URL map (e.g.
myservice-urlmap
). - Create a managed TLS certificate for your domain to serve HTTPS
traffic. (Replace example.com with your domain name.)
gcloud compute ssl-certificates create CERT_NAME \ --domains=example.com
Replace CERT_NAME with the name you want the managed SSL certificate to have (e.g.
myservice-cert
). - Create a target HTTPS proxy.
gcloud compute target-https-proxies create HTTPS_PROXY_NAME \ --ssl-certificates=CERT_NAME \ --url-map=URLMAP_NAME
Replace HTTPS_PROXY_NAME with the name you want to give to the target HTTPS proxy (e.g.
myservice-https
). - Create a forwarding rule connecting the networking resources you created
to the IP address.
gcloud compute forwarding-rules create --global FORWARDING_RULE_NAME \ --target-https-proxy=HTTPS_PROXY_NAME \ --address=SERVICE_IP \ --ports=443
Replace FORWARDING_RULE_NAME with the name of the forwarding rule resource you want to create (e.g.
myservice-lb
).
Terraform
Alternatively to the steps described in this section, you can use the Global HTTP Load Balancer Terraform Module.
Add the following to your terraform file (for example main.tf
):
-
Configure the IP address:
Configures your IP address resource name to be
myservice-service-ip
. You can change this to your own value. This IP address is a global anycast IPv4 address that routes to the Google datacenter or point of presence closest to your visitors. -
Create and configure the backend service:
This resource configures the backend service to be named
myservice-backend
. You can change this to your own value. -
Configure the url map:
Connects the backend service resource (
myservice-backend
) to the new url map resource (myservice-lb-urlmap
). You can change these to your own values. -
Create a managed TLS certificate for your domain to serve HTTPS traffic. Replace
example.com
with your domain name in thegoogle_compute_managed_ssl_certificate
resource: -
Configure the HTTPS proxy:
Creates
google_compute_target_https_proxy
resource with target namemyservice-https-proxy
and connects previously created TLS certificate (myservice-ssl-cert
) and url mapping resources (myservice-lb-urlmap
). You can change these to your own values. -
Configure the forwarding rule:
Creates
google_compute_global_forwarding_rule
resource with target namemyservice-https-proxy
and connects previously created HTTPS proxy target (myservice-https-proxy
) and IP Address resource (myservice-service-ip
). You can change these to your own values. -
Apply this config:
To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.
Prepare Cloud Shell
- Launch Cloud Shell.
-
Set the default Google Cloud project where you want to apply your Terraform configurations.
You only need to run this command once per project, and you can run it in any directory.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
Environment variables are overridden if you set explicit values in the Terraform configuration file.
Prepare the directory
Each Terraform configuration file must have its own directory (also called a root module).
-
In Cloud Shell, create a directory and a new
file within that directory. The filename must have the
.tf
extension—for examplemain.tf
. In this tutorial, the file is referred to asmain.tf
.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
If you are following a tutorial, you can copy the sample code in each section or step.
Copy the sample code into the newly created
main.tf
.Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.
- Review and modify the sample parameters to apply to your environment.
- Save your changes.
-
Initialize Terraform. You only need to do this once per directory.
terraform init
Optionally, to use the latest Google provider version, include the
-upgrade
option:terraform init -upgrade
Apply the changes
-
Review the configuration and verify that the resources that Terraform is going to create or
update match your expectations:
terraform plan
Make corrections to the configuration as necessary.
-
Apply the Terraform configuration by running the following command and entering
yes
at the prompt:terraform apply
Wait until Terraform displays the "Apply complete!" message.
- Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Deploy to multiple regions
Deploy your Service to available Cloud Run regions. For ease of management, you can use the same service name across multiple regions.
Command line
- Choose regions where you want to make your service available.
- Deploy your Cloud Run service to individual regions.
-
gcloud run deploy SERVICE_NAME \ --allow-unauthenticated \ --image=IMAGE_URL \ --region=REGION
Replace the following variables:
- REGION with one of the regions you want to deploy to.
- SERVICE_NAME with the name of your service. Using the same service name across multiple region makes it easier to keep track of your multi-region deployments.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
- Repeat the previous step for each region.
Terraform
Configures a service for each region specified in run_regions
variable.
Loops through all regions specified in run_regions
variable and names each new service like so:
myservice-run-app-${var.run_regions[count.index]}
. Defining service location is similarly applied.
Replace default image us-docker.pkg.dev/cloudrun/container/hello"
with your own image.
Cloud Run locations
Cloud Run is regional, which means the infrastructure that
runs your Cloud Run services is located in a specific region and is
managed by Google to be redundantly available across
all the zones within that region.
Meeting your latency, availability, or durability requirements are primary
factors for selecting the region where your Cloud Run services are run.
You can generally select the region nearest to your users but you should consider
the location of the other Google Cloud
products that are used by your Cloud Run service.
Using Google Cloud products together across multiple locations can affect
your service's latency as well as cost.
Cloud Run is available in the following regions:
Subject to Tier 1 pricing
asia-east1
(Taiwan)asia-northeast1
(Tokyo)asia-northeast2
(Osaka)europe-north1
(Finland)Low CO2
europe-southwest1
(Madrid)Low CO2
europe-west1
(Belgium)Low CO2
europe-west4
(Netherlands)Low CO2
europe-west8
(Milan)europe-west9
(Paris)Low CO2
me-west1
(Tel Aviv)us-central1
(Iowa)Low CO2
us-east1
(South Carolina)us-east4
(Northern Virginia)us-east5
(Columbus)us-south1
(Dallas)Low CO2
us-west1
(Oregon)Low CO2
Subject to Tier 2 pricing
africa-south1
(Johannesburg)asia-east2
(Hong Kong)asia-northeast3
(Seoul, South Korea)asia-southeast1
(Singapore)asia-southeast2
(Jakarta)asia-south1
(Mumbai, India)asia-south2
(Delhi, India)australia-southeast1
(Sydney)australia-southeast2
(Melbourne)europe-central2
(Warsaw, Poland)europe-west10
(Berlin)Low CO2
europe-west12
(Turin)europe-west2
(London, UK)Low CO2
europe-west3
(Frankfurt, Germany)Low CO2
europe-west6
(Zurich, Switzerland)Low CO2
me-central1
(Doha)me-central2
(Dammam)northamerica-northeast1
(Montreal)Low CO2
northamerica-northeast2
(Toronto)Low CO2
southamerica-east1
(Sao Paulo, Brazil)Low CO2
southamerica-west1
(Santiago, Chile)Low CO2
us-west2
(Los Angeles)us-west3
(Salt Lake City)us-west4
(Las Vegas)
If you already created a Cloud Run service, you can view the region in the Cloud Run dashboard in the Google Cloud console.
Configure regional network endpoint groups
For each region you deployed to in the previous step, you need to create serverless network endpoint groups (NEGs) and add them to the backend service, using the following instructions:
Command line
-
Create a network endpoint group for the Cloud Run service in
REGION
:gcloud compute network-endpoint-groups create NEG_NAME \ --region=REGION \ --network-endpoint-type=SERVERLESS \ --cloud-run-service=SERVICE_NAME
In the command above, replace:
- NEG_NAME with the name of the network endpoint group resource. (e.g. `myservice-neg-uscentral1`)
- REGION with the [region][loc] your service is deployed in.
- SERVICE_NAME with the name of your service.
-
Add the network endpoint group to the backend service:
gcloud compute backend-services add-backend --global BACKEND_NAME \ --network-endpoint-group-region=REGION \ --network-endpoint-group=NEG_NAME
Specify the NEG_NAME you have created in the previous step for the region.
-
Repeat the steps above for each region.
Terraform
-
Configure a network endpoint group with name
myservice-neg
for the Cloud Run service for each region specified inrun_regions
variable: -
Configure a backend service to attach the network endpoint group (
myservice-neg
):
Configure DNS records on your domain
To point your domain name to the forwarding rule you created, you need to update its DNS records with the IP address you created.
Find the reserved IP address of the load balancer by running:
gcloud compute addresses describe --global SERVICE_IP --format='value(address)'
Replace SERVICE_IP with the name of the IP address you created previously. This command will print the IP address to the output.
Update your domain's DNS records by adding an
A
record with this IP address.
Configure custom audience if using authenticated services
Authenticated services are protected by IAM. Such Cloud Run services require client authentication that declares the intended recipient of a request at credential generation time (the audience).
Audience is usually the full URL of the target service, which by default for Cloud Run
services is a generated URL ending in run.app
. However, in a multi-region deployment,
it is not possible for a client to know in advance which regional service a request will be routed to.
So, for a multi-region deployment, configure your service to use
custom audiences.
Wait for load balancer to provision
After configuring the domain with the load balancer IP address, you need to wait a while for DNS records to propagate. Similarly you need to wait a while for the managed TLS certificate to be issued for your domain and become ready to start serving HTTPS traffic globally.
It may take up to 30 minutes for your load balancer to start serving traffic.
Once it's ready, visit your website's URL with https://
prefix to try it out.
Verify status
To check the status of your DNS record propagation, using the
dig
command-line utility:dig A +short example.com
The output should show the IP address you configured in your DNS records.
Check the status of your managed certificate issuance, run:
gcloud compute ssl-certificates describe CERT_NAME
Replace CERT_NAME with the name you have previously chosen for the SSL certificate resource.
The output should show a line containing
status: ACTIVE
.
Set up HTTP-to-HTTPS redirect
By default, a forwarding rule only handles a single protocol and therefore
requests to your http://
endpoints will respond with 404 Not Found. If you
need requests to your http://
URLs to be redirected to the https://
protocol, you need to create an additional URL map and a forwarding rule, using
the following instructions:
Command line
-
Create a URL map with a redirect rule.
gcloud compute url-maps import HTTP_URLMAP_NAME \ --global \ --source /dev/stdin <<EOF name: HTTP_URLMAP_NAME defaultUrlRedirect: redirectResponseCode: MOVED_PERMANENTLY_DEFAULT httpsRedirect: True EOF
Replace the HTTP_URLMAP_NAME with the name of the URL map resource you will create (e.g.
myservice-httpredirect
). -
Create a target HTTP proxy with the URL map.
gcloud compute target-http-proxies create HTTP_PROXY_NAME \ --url-map=HTTP_URLMAP_NAME
Replace HTTP_PROXY_NAME with the name of the target HTTP proxy you will create (e.g.
myservice-http
). -
Create a forwarding rule on port
80
with the same reserved IP address.gcloud compute forwarding-rules create --global HTTP_FORWARDING_RULE_NAME \ --target-http-proxy=HTTP_PROXY_NAME \ --address=SERVICE_IP \ --ports=80 \
Replace HTTP_FORWARDING_RULE_NAME with the name of the new forwarding rule you will create (e.g.
myservice-httplb
).
Terraform
-
Create a URL map resource with a redirect rule:
-
Create a target HTTP proxy with the newly created URL map resource (
myservice-https-urlmap
): -
Create a forwarding rule on port
80
with the same reserved IP address resource (myservice-http-proxy
):
Use authenticated Pub/Sub push subscriptions with multi-region deployment
A Pub/Sub service by default delivers messages to push endpoints in the same Google Cloud region where the Pub/Sub service stores the messages. For a workaround to this behavior, refer to Using an authenticated Pub/Sub push subscription with a multi-region Cloud Rundeployment.