Serve traffic from multiple regions

gcloud

• To create and deploy a multi-region service, run the gcloud beta run deploy command using the --regions flag:

  gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --regions=REGIONS

  Replace the following:

  • SERVICE_NAME: The name of the multi-region service that you want to deploy.
  • IMAGE_URL: A reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest.
  • REGIONS: The list of multiple regions that you want to deploy to. For example, us-central1,asia-east1.

YAML

1. Create the YAML file for your service, using the run.googleapis.com/regions attribute to set the multiple regions that you want to deploy your service to:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE_NAME
     annotations:
       run.googleapis.com/launch-stage: BETA
       run.googleapis.com/regions: REGIONS
   spec:
     template:
       spec:
         containers:
         - image: IMAGE_URL

   Replace the following:

   • SERVICE_NAME: The name of the multi-region service that you want to deploy to.
   • REGIONS: The list of multiple regions that you want to update. For example, us-central1,asia-east1.
   • IMAGE_URL: A reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest.

2. Create the service using the following command:

   gcloud beta run multi-region-services replace service.yaml

gcloud

To add or remove regions from a multi-region service, run the gcloud beta run multi-region-services update command.

• To add the multi-region service to an additional region or regions, use the --add-regions flag:

  gcloud beta run multi-region-services update SERVICE_NAME \
    --add-regions=REGIONS

• To remove the multi-region service from a region or regions, use the --remove-regions flag:

  gcloud beta run multi-region-services update SERVICE_NAME \
    --remove-regions=REGIONS

  Replace the following:

  • SERVICE_NAME: The name of the multi-region service that you want to update.
  • REGIONS: The region or regions that you want to add your service to or remove your service from. For example, us-central1,asia-east1.

YAML

1. To update an existing multi-region service, download its YAML configuration:

   gcloud beta run multi-region-services describe SERVICE_NAME --format export > service.yaml

2. Update the run.googleapis.com/regions attribute to add or remove the list of regions that you want the service to deploy to:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE_NAME
     annotations:
       run.googleapis.com/launch-stage: BETA
       run.googleapis.com/regions: REGIONS

   Replace the following:

   • SERVICE_NAME: The name of the multi-region service that you want to deploy to.
   • REGIONS: The new list of multiple regions that you want the service revision to deploy to.

3. Update the service using the following command:

   gcloud beta run multi-region-services replace service.yaml

gcloud CLI

1. Reserve a static IP address so you don't have to update your DNS records when you recreate your load balancer.

   gcloud compute addresses create --global SERVICE_IP

   In the command above, replace SERVICE_IP with a name for the IP address resource (e.g. 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.

2. 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).

3. 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).

4. 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).

5. 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).

6. 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):

1. Configure the IP address:

   resource "google_compute_global_address" "lb_default" {
     provider = google-beta
     name     = "myservice-service-ip"
   
     # Use an explicit depends_on clause to wait until API is enabled
     depends_on = [
       google_project_service.compute_api
     ]
   }
   output "load_balancer_ip_addr" {
     value = google_compute_global_address.lb_default.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 data center or point of presence closest to your visitors.

2. Create and configure the backend service:

   resource "google_compute_backend_service" "lb_default" {
     provider              = google-beta
     name                  = "myservice-backend"
     load_balancing_scheme = "EXTERNAL_MANAGED"
   
     backend {
       group = google_compute_region_network_endpoint_group.lb_default[0].id
     }
   
     backend {
       group = google_compute_region_network_endpoint_group.lb_default[1].id
     }
   
     # Use an explicit depends_on clause to wait until API is enabled
     depends_on = [
       google_project_service.compute_api,
     ]
   }

   This resource configures the backend service to be named myservice-backend. You can change this to your own value.

3. Configure the URL map:

   resource "google_compute_url_map" "lb_default" {
     provider        = google-beta
     name            = "myservice-lb-urlmap"
     default_service = google_compute_backend_service.lb_default.id
   
     path_matcher {
       name            = "allpaths"
       default_service = google_compute_backend_service.lb_default.id
       route_rules {
         priority = 1
         url_redirect {
           https_redirect         = true
           redirect_response_code = "MOVED_PERMANENTLY_DEFAULT"
         }
       }
     }
   }

   Connects the backend service resource (myservice-backend) to the new URL map resource (myservice-lb-urlmap). You can change these to your own values.

4. Create a managed TLS certificate for your domain to serve HTTPS traffic. Replace example.com with your domain name in the google_compute_managed_ssl_certificate resource:

   resource "google_compute_managed_ssl_certificate" "lb_default" {
     provider = google-beta
     name     = "myservice-ssl-cert"
   
     managed {
       domains = ["example.com"]
     }
   }

5. Configure the HTTPS proxy:

   resource "google_compute_target_https_proxy" "lb_default" {
     provider = google-beta
     name     = "myservice-https-proxy"
     url_map  = google_compute_url_map.lb_default.id
     ssl_certificates = [
       google_compute_managed_ssl_certificate.lb_default.name
     ]
     depends_on = [
       google_compute_managed_ssl_certificate.lb_default
     ]
   }

   Creates google_compute_target_https_proxy resource with target name myservice-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.

6. Configure the forwarding rule:

   resource "google_compute_global_forwarding_rule" "lb_default" {
     provider              = google-beta
     name                  = "myservice-lb-fr"
     load_balancing_scheme = "EXTERNAL_MANAGED"
     target                = google_compute_target_https_proxy.lb_default.id
     ip_address            = google_compute_global_address.lb_default.id
     port_range            = "443"
     depends_on            = [google_compute_target_https_proxy.lb_default]
   }

   Creates google_compute_global_forwarding_rule resource with target name myservice-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.

7. Apply this config:

   To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

   Prepare Cloud Shell

   1. Launch Cloud Shell.

   2. 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).

   1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf.

      mkdir DIRECTORY && cd DIRECTORY && touch main.tf

   2. 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.

   3. Review and modify the sample parameters to apply to your environment.
   4. Save your changes.
   5. 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

   1. 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.

   2. 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.

   3. 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.

gcloud CLI

1. 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

   Replace the following:

   • 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.

2. 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 created in the previous step for the region.

3. Repeat the preceding steps for each region.

Terraform

1. Configure a network endpoint group with name myservice-neg for the Cloud Run service for each region specified in run_regions variable:

   resource "google_compute_region_network_endpoint_group" "lb_default" {
     provider              = google-beta
     count                 = length(local.run_regions)
     name                  = "myservice-neg"
     network_endpoint_type = "SERVERLESS"
     region                = local.run_regions[count.index]
     cloud_run {
       service = google_cloud_run_v2_service.run_default[count.index].name
     }
   }

2. Configure a backend service to attach the network endpoint group (myservice-neg):

   resource "google_compute_backend_service" "lb_default" {
     provider              = google-beta
     name                  = "myservice-backend"
     load_balancing_scheme = "EXTERNAL_MANAGED"
   
     backend {
       group = google_compute_region_network_endpoint_group.lb_default[0].id
     }
   
     backend {
       group = google_compute_region_network_endpoint_group.lb_default[1].id
     }
   
     # Use an explicit depends_on clause to wait until API is enabled
     depends_on = [
       google_project_service.compute_api,
     ]
   }

gcloud CLI

1. 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 (for example, myservice-httpredirect).

2. 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 (for example, myservice-http).

3. 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 (for example, myservice-httplb).

Terraform

1. Create a URL map resource with a redirect rule:

   resource "google_compute_url_map" "https_default" {
     provider = google-beta
     name     = "myservice-https-urlmap"
   
     default_url_redirect {
       redirect_response_code = "MOVED_PERMANENTLY_DEFAULT"
       https_redirect         = true
       strip_query            = false
     }
   }

2. Create a target HTTP proxy with the newly created URL map resource (myservice-https-urlmap):

   resource "google_compute_target_http_proxy" "https_default" {
     provider = google-beta
     name     = "myservice-http-proxy"
     url_map  = google_compute_url_map.https_default.id
   
     depends_on = [
       google_compute_url_map.https_default
     ]
   }

3. Create a forwarding rule on port 80 with the same reserved IP address resource (myservice-http-proxy):

   resource "google_compute_global_forwarding_rule" "https_default" {
     provider   = google-beta
     name       = "myservice-https-fr"
     target     = google_compute_target_http_proxy.https_default.id
     ip_address = google_compute_global_address.lb_default.id
     port_range = "80"
     depends_on = [google_compute_target_http_proxy.https_default]
   }