Access global Google APIs through backends

Console

1. In the Google Cloud console, go to the Create a network endpoint group page.

   Go to Create a network endpoint group

2. On the Create network endpoint group page, enter a Name for the network endpoint group.

3. For the Network endpoint group type, select Private Service Connect NEG (Regional).

4. For Target, select Global Google APIs.

5. Select the Region for the network endpoint group.

6. Select the Target service for the network endpoint group.

7. Click Create.

gcloud

Use the network-endpoint-groups create command.

gcloud compute network-endpoint-groups create NEG_NAME \
    --network-endpoint-type=private-service-connect \
    --psc-target-service=TARGET_SERVICE \
    --region=REGION

Replace the following:

• NEG_NAME: a name for the network endpoint group.

• TARGET_SERVICE: the global Google API target that you want to connect to—for example, pubsub.googleapis.com. See the list of supported global Google API targets.

• REGION: the region to create the network endpoint group in.

API

Make a POST request to the regionNetworkEndpointGroups.insert method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/networkEndpointGroups
{
  "name": "NEG_NAME",
  "networkEndpointType": "PRIVATE_SERVICE_CONNECT",
  "pscTargetService": "TARGET_SERVICE"
}

Replace the following:

• PROJECT_ID: the project ID of the network endpoint group.
• REGION: the region to create the network endpoint group in.
• NEG_NAME: a name for the network endpoint group.
• TARGET_SERVICE: the global Google API target that you want to connect to—for example, pubsub.googleapis.com. See the list of supported global Google API targets.

Console

Start your configuration

1. In the Google Cloud console, go to the Load balancing page.

   Go to Load balancing

2. Click Create load balancer.
3. For Type of load balancer, select Application Load Balancer (HTTP/HTTPS) and click Next.
4. For Public facing or internal, select Internal and click Next.
5. For Cross-region or single region deployment, select Best for cross-region workloads and click Next.
6. Click Configure.

Basic configuration

1. Enter a Name for the load balancer.

2. Select a Network for the load balancer.

   The network must contain a proxy-only subnet in the region where you are creating the load balancer.

Frontend configuration

1. Click Frontend configuration.
2. Enter a Name for the load balancer's forwarding rule.
3. In the Protocol field, select HTTPS (includes HTTP/2 and HTTP/3).
4. Select a Subnetwork region for the load balancer's subnetwork.
5. Select a Subnetwork for the load balancer.
6. Click IP address, and then do one of the following:
   • To automatically assign an ephemeral IP address, select Ephemeral (Automatic).
   • To choose an ephemeral IP address, select Ephemeral (Custom), and then enter a Custom ephemeral IP address from the IP address range of the load balancer's subnet.
   • To reserve and use a static internal IP address, click Create IP address, and then do the following:
     1. Enter a Name for the IP address.
     2. Click Static IP address, and then do one of the following:
        • To automatically assign a static IP address, select Assign automatically.
        • To configure a specific IP address, select Let me choose, and then enter a Custom IP address from the IP address range of the load balancer's subnet.
     3. Click Reserve.
7. Ensure that the Port field is set to 443, to allow HTTPS traffic.
8. Click the Certificate list, and then select your self-managed certificate.
9. Click Done.

Backend configuration

1. Click Backend configuration.

2. For each global Google API that you want to access, create a global backend service. To create a global backend service, do the following:

   1. From the Create or select backend services menu, select Create a backend service.
   2. Enter a Name for the backend service.
   3. Set the Backend type to Private Service Connect network endpoint group.
   4. Set the Private Service Connect target type to Global Google API.
   5. Select HTTPS for the protocol.

   6. In the Backends section, click the New backend menu, and select a Private Service Connect network endpoint group.

      If you need to create a new Private Service Connect network endpoint group, click Create PSC NEG.

   7. Click Done.

   8. Click Create.

3. Ensure that each backend service that you want to add is selected in the Create or select backend services menu, and then click OK.

Routing rules

The set of rules for routing incoming HTTPS requests to specific backend services is called a URL map. To learn more about URL maps, see URL maps overview.

If you are configuring only one backend service for the load balancer, the default routing rule is sufficient, and you can skip to Review and finalize.

If you are configuring multiple backend services, you must create one path matcher for each backend service. Each host rule can reference only one path matcher, but two or more host rules can reference the same path matcher.

1. If you have more than one backend service, click Routing rules.
2. Select Simple host and path rule.
3. For each backend, do the following:
   1. Click Add host and path rule.
   2. For Host, enter the hostname that will be used to send requests to this service—for example, pubsub.example.com.
   3. For Paths, enter the path—for example, /*.
   4. For Backends, select the backend service.

Review and finalize

1. Click Review and finalize to review the configuration.
2. Click Create.

gcloud

1. For each global Google API that you want to access, do the following:

   1. To create a global backend service, use the gcloud compute backend-services create command.

      gcloud compute backend-services create BACKEND_SERVICE_NAME \
          --load-balancing-scheme=INTERNAL_MANAGED \
          --protocol=HTTPS \
          --global
      

      Replace BACKEND_SERVICE_NAME with the name of the backend service.

   2. To add a NEG to the corresponding backend service, use the gcloud compute backend-services add-backend command.

      gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
          --network-endpoint-group=NEG_NAME \
          --network-endpoint-group-region=REGION \
          --global
      

      Replace the following:

      • NEG_NAME: the name of the Private Service Connect NEG.
      • REGION: the region of the Private Service Connect NEG.

2. To create a global URL map for the load balancer, use the gcloud compute url-maps create command.

   A URL map must reference a default backend service. If you're configuring your load balancer with one backend service, set that backend service as the default. If you're configuring your load balancer to use multiple backend services, pick one of the backend services to be the URL map default.

   gcloud compute url-maps create URL_MAP_NAME \
       --default-service=DEFAULT_BACKEND_SERVICE_NAME
   

   Replace the following:

   • URL_MAP_NAME: a name for the URL map.
   • DEFAULT_BACKEND_SERVICE_NAME: the name of the load balancer's default backend service. The default is used when no host rule matches the requested hostname.

3. Optional: If you're configuring your load balancer to use multiple backend services, complete this step. If your URL map only references one backend service, skip this step.

   To add additional backend services to the URL map, use the gcloud compute url-maps add-path-matcher command.

   For each backend service, add a path matcher and one or more host rules. You must create one path matcher for each backend service. Each host rule can reference only one path matcher, but two or more host rules can reference the same path matcher.

   gcloud compute url-maps add-path-matcher URL_MAP_NAME \
       --path-matcher-name=PATH_MATCHER \
       --default-service=BACKEND_SERVICE_NAME \
       --new-hosts=HOSTNAMES
   

   Replace the following:

   • PATH_MATCHER: a name for the path matcher.
   • BACKEND_SERVICE_NAME: the name of the backend service.
   • HOSTNAMES: one or more hostnames to send requests to for the backend service—for example, pubsub.example.com. You can enter multiple hostnames in a comma-separated list.

4. To create a target HTTPS proxy, use the gcloud compute target-https-proxies create command.

   gcloud compute target-https-proxies create PROXY_NAME \
       --url-map=URL_MAP_NAME \
       --certificate-manager-certificates=CERTIFICATE_NAME
   

   Replace the following:

   • PROXY_NAME: a name for the target HTTPS proxy.
   • URL_MAP_NAME: the name of the URL map.
   • CERTIFICATE_NAME: the name of the certificate resource.

5. To create a global forwarding rule for your load balancer, use the gcloud compute forwarding-rules create command.

   gcloud compute forwarding-rules create RULE_NAME \
       --load-balancing-scheme=INTERNAL_MANAGED \
       --network=NETWORK \
       --address=IP_ADDRESS \
       --ports=443 \
       --target-https-proxy=PROXY_NAME \
       --subnet=SUBNET \
       --subnet-region=SUBNET_REGION \
       --global
   

   Replace the following:

   • RULE_NAME: the name of the forwarding rule.
   • NETWORK: the VPC network of the forwarding rule. This network must contain a proxy-only subnet in the region where you are creating the load balancer.
   • IP_ADDRESS: the internal IP address of the forwarding rule, which must be within the IP address range of the forwarding rule's subnet. To use a specific ephemeral IP address, enter the IP address—for example, 10.0.0.5. To use a static internal IP address, enter the name of the IP address. To let Google Cloud select an ephemeral IP address, omit this flag.
   • SUBNET: the subnet of the forwarding rule.
   • SUBNET_REGION: the region of the forwarding rule's subnet.

API

1. For each global Google API that you want to access, do the following:

   1. To create a global backend service, make a POST request to the backendServices.insert method.

      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices
      {
        "loadBalancingScheme": "INTERNAL_MANAGED",
        "name": "BACKEND_SERVICE_NAME",
        "protocol": "HTTPS"
      }
      

      Replace the following:

      • PROJECT_ID: the project ID of your project.
      • BACKEND_SERVICE_NAME: the name of the backend service.

   2. To add a NEG to the corresponding backend service, make a PATCH request to the backendServices.patch method.

      PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME
      {
        "backends": [
          {
            "group": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/networkEndpointGroups/NEG_NAME"
          }
        ]
      }
      

      Replace the following:

      • REGION: the region of the NEG.
      • NEG_NAME: the name of the network endpoint group to add.

2. To create a global URL map for the load balancer, make a POST request to the urlMaps.insert method.

   A URL map must reference a default backend service. If you're configuring your load balancer with one backend service, set that backend service as the default. If you're configuring your load balancer to use multiple backend services, pick one of the backend services to be the URL map default.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps
    {
      "defaultService": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/DEFAULT_BACKEND_SERVICE_NAME",
      "name": "URL_MAP_NAME"
    }
    

   Replace the following:

   • DEFAULT_BACKEND_SERVICE_NAME: the name of the load balancer's default. The default is used when no host rule matches the requested hostname.
   • URL_MAP_NAME: a name for the URL map.

3. If you're configuring your load balancer to use multiple backend services, complete this step. If your URL map only references one backend service, skip this step.

   To add additional backend services to the URL map, make a PATCH request to the urlMaps.patch method.

   For each backend service, add a path matcher and one or more host rules. You must create one path matcher for each backend service. Each host rule can reference only one path matcher, but two or more host rules can reference the same path matcher.

   You can add multiple path matchers and host rules by making a single API request.

    PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/URL_MAP_NAME
    {
      "pathMatchers": [
        {
          "name": "PATH_MATCHER_NAME_1",
          "defaultService": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME_1"
        },
        {
          "name": "PATH_MATCHER_NAME_2",
          "defaultService": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME_2"
        }
      ],
      "hostRules": [
        {
          "hosts": ["HOSTNAME_1"],
          "pathMatcher": "PATH_MATCHER_NAME_1"
        },
        {
          "hosts": ["HOSTNAME_2"],
          "pathMatcher": "PATH_MATCHER_NAME_2"
        }
      ]
    }
    

   Replace the following:

   • PATH_MATCHER_NAME_1: a name for the first path matcher.
   • BACKEND_SERVICE_NAME_1: the name of the first backend service.
   • PATH_MATCHER_NAME_2: a name for the second path matcher.
   • BACKEND_SERVICE_NAME_2: the name of the second backend service.
   • HOSTNAME_1: the hostname to send requests to for the first service—for example, pubsub.example.com.
   • HOSTNAME_2: the hostname to send requests to for the second service.

4. To create a target HTTPS proxy, make a POST request to the targetHttpsProxies.insert method.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/targetHttpsProxies
    {
      "name": "PROXY_NAME",
      "sslCertificates": [
        "https://certificatemanager.googleapis.com/v1/projects/PROJECT_ID/locations/global/certificates/CERTIFICATE_NAME"
      ],
      "urlMap": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/URL_MAP_NAME"
    }
    

   Replace the following:

   • PROJECT_ID: the ID of the project.
   • PROXY_NAME: a name for the target HTTPS proxy.
   • CERTIFICATE_NAME: the name of the certificate resource.
   • URL_MAP_NAME: the name of the URL map.

5. To create a global forwarding rule for your load balancer, make a POST request to the globalForwardingRules.insert method. The forwarding rule's network must contain a proxy-only subnet in the subnet of your forwarding rule's region.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/forwardingRules
    {
      "IPAddress": "IP_ADDRESS",
      "loadBalancingScheme": "INTERNAL_MANAGED",
      "name": "FORWARDING_RULE_NAME",
      "network": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/NETWORK_NAME",
      "portRange": "443",
      "subnetwork": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/SUBNET_REGION/subnetworks/SUBNET_NAME",
      "target": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/targetHttpsProxies/PROXY_NAME"
    }
    

   Replace the following:

   • IP_ADDRESS: the internal IP address of the forwarding rule, which must be within the IP address range of the forwarding rule's subnet. To use a specific ephemeral IP address, provide the IP address—for example, 10.0.0.5. To use a static internal IP address, provide the name of the IP address. To let Google Cloud select an ephemeral IP address, omit this field.
   • FORWARDING_RULE_NAME: the name of the forwarding rule.
   • NETWORK_NAME: the name of the forwarding rule's VPC network. This network must contain a proxy-only subnet in the region where you are creating the load balancer.
   • SUBNET_REGION: the region of the forwarding rule's subnet.
   • SUBNET_NAME: the name of the forwarding rule's subnet.