Access global Google APIs through backends

This page describes how to access global Google APIs by usingPrivate Service Connectbackends that are based oncross-region internal Application Load Balancers.

This configuration lets you target one or moreindividual global Google APIs while applying thevisibility and controlthat Private Service Connect backends provide.

  • You can configure custom hostnames, local to your Virtual Private Cloud (VPC) andconnected on-premises networks, that route traffic to your chosen globalGoogle APIs.
  • You can access the backends from any region, and the backend can loadbalance traffic to Private Service Connect network endpointgroups (NEGs) that are located in any region.
  • You can send traffic to the backends from peered VPCnetworks.

For a list of the available global Google APIs, seeGlobal Google API targets.

Before you begin

  • To get the permissions that you need to configure a backend to access global Google APIs, ask your administrator to grant you the following IAM roles on your Google Cloud project:

    For more information about granting roles, seeManage access to projects, folders, and organizations.

    You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

  • EnabletheCompute Engine API in your project.

  • EnabletheCertificate Manager API inyour project.

  • Create a private key and a signed certificate from a certificate authority(CA). Follow the instructions inStep 1: Create a private key andcertificate.The private key and certificate are needed to create a self-managed SSLcertificate with Certificate Manager.

  • Create a certificate resource for a cross-region internal Application Load Balancer by using theprivate key and signed certificate that you created. When youupload the certificate you must set the scope toall-regions. For more information, seeUpload a self-managed certificate toCertificate Manager.The certificate resource is needed to configure the target HTTPS proxy for theload balancer.

  • Create aproxy-only subnetif you don't already have one. There must be a single proxy-only subnetin the VPC network and region where you intend to create thecross-region internal Application Load Balancer's forwarding rule. This subnet is used by allinternal Application Load Balancers within that network and region.

Create a Private Service Connect NEG

For each global Google API that you want to access, create aPrivate Service Connect NEG.Private Service Connect NEGs are regional, even when they areused to connect to global Google APIs.

A Private Service Connect NEG can't be updated after it iscreated.

Console

  1. In the Google Cloud console, go to theCreate a network endpoint grouppage.

    Go to Create a network endpoint group

  2. On theCreate network endpoint group page, enter aName for thenetwork endpoint group.

  3. For theNetwork endpoint group type, selectPrivate Service Connect NEG (Regional).

  4. ForTarget, selectGlobal Google APIs.

  5. Select theRegion for the network endpoint group.

  6. Select theTarget service for the network endpoint group.

  7. ClickCreate.

gcloud

Use thenetwork-endpoint-groups create command.

gcloud compute network-endpoint-groups createNEG_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 youwant to connect to—for example,pubsub.googleapis.com. See thelist of supported global Google API targets.

  • REGION: the region to create the network endpoint groupin.

API

Make aPOST request to theregionNetworkEndpointGroups.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 endpointgroup.
  • REGION: the region to create the network endpoint groupin.
  • NEG_NAME: a name for the network endpoint group.
  • TARGET_SERVICE: the global Google API target that youwant to connect to—for example,pubsub.googleapis.com. See thelist of supported global Google API targets.

Configure the load balancer

To access global Google APIs, configure a cross-region internal Application Load Balancer.

Console

Select the load balancer type

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

    Go to Load balancing

  2. ClickCreate load balancer.
  3. ForType of load balancer, selectApplication Load Balancer (HTTP/HTTPS) and clickNext.
  4. ForPublic facing or internal, selectInternal and clickNext.
  5. ForCross-region or single region deployment, selectBest for cross-region workloads and clickNext.
  6. ClickConfigure.

Basic configuration

  1. Enter aName for the load balancer.

  2. Select aNetwork for the load balancer.

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

Frontend configuration

  1. ClickFrontend configuration.
  2. Enter aName for the load balancer's forwarding rule.
  3. In theProtocol field, selectHTTPS (includes HTTP/2 and HTTP/3).
  4. Select aSubnetwork region for the load balancer's subnetwork.
  5. Select aSubnetwork for the load balancer.
  6. ClickIP address, and then do one of the following:
    • To automatically assign an ephemeral IP address, selectEphemeral (Automatic).
    • To choose an ephemeral IP address, selectEphemeral (Custom), andthen enter aCustom ephemeral IP address from the IP address rangeof the load balancer's subnet.
    • To reserve and use a static internal IP address, clickCreate IP address, and then do the following:
      1. Enter aName for the IP address.
      2. ClickStatic IP address, and then do one of the following:
        • To automatically assign a static IP address, selectAssign automatically.
        • To configure a specific IP address, selectLet me choose,and then enter aCustom IP address from the IP address rangeof the load balancer's subnet.
      3. ClickReserve.
  7. Ensure that thePort field is set to443, to allow HTTPS traffic.
  8. Click theCertificate list, and then select yourself-managed certificate.
  9. ClickDone.

Backend configuration

  1. ClickBackend configuration.

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

    1. From theCreate or select backend services menu, selectCreate abackend service.
    2. Enter aName for the backend service.
    3. Set theBackend type toPrivate Service Connect network endpoint group.
    4. Set thePrivate Service Connect target type toGlobal Google API.
    5. SelectHTTPS for the protocol.

    6. In theBackends section, click theNew backend menu, and selecta Private Service Connect network endpoint group.

      If you need to create a new Private Service Connectnetwork endpoint group, clickCreate PSC NEG.

    7. ClickDone.

    8. ClickCreate.

  3. Ensure that each backend service that you want to add is selected in theCreate or select backend services menu, and then clickOK.

Routing rules

The set of rules for routing incoming HTTPS requests tospecific backend services is called aURL map.To learn more about URL maps, seeURL maps overview.

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

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

  1. If you have more than one backend service, clickRouting rules.
  2. SelectSimple host and path rule.
  3. For each backend, do the following:
    1. ClickAdd host and path rule.
    2. ForHost, enter the hostname that will be used to send requests tothis service—for example,pubsub.example.com.
    3. ForPaths, enter the path—for example,/*.
    4. ForBackends, select the backend service.

Review and finalize

  1. ClickReview and finalize to review the configuration.
  2. ClickCreate.

gcloud

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

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

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

      ReplaceBACKEND_SERVICE_NAME with thename of the backend service.

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

      gcloud compute backend-services add-backendBACKEND_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 globalURL map forthe load balancer, use thegcloud compute url-maps create command.

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

    gcloud compute url-maps createURL_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 loadbalancer's default backend service. The default is used when no hostrule matches the requested hostname.

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

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

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

    gcloud compute url-maps add-path-matcherURL_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 requeststo for the backend service—for example,pubsub.example.com. You can enter multiple hostnames in acomma-separated list.

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

    gcloud compute target-https-proxies createPROXY_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 certificateresource.

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

    gcloud compute forwarding-rules createRULE_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 theforwarding rule. This network must contain a proxy-only subnet in theregion where you are creating the load balancer.
    • IP_ADDRESS: the internal IP address of theforwarding rule, which must be within the IP address range of theforwarding rule's subnet. To use a specific ephemeral IP address, enterthe IP address—for example,10.0.0.5. To use a static internalIP address, enter the name of the IP address. To let Google Cloudselect an ephemeral IP address, omit this flag.
    • SUBNET: the subnet of the forwarding rule.
    • SUBNET_REGION: the region of the forwardingrule'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 aPOST request to thebackendServices.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 backendservice.

    2. To add a NEG to the corresponding backend service, make aPATCHrequest to thebackendServices.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 groupto add.

  2. To create a globalURL map forthe load balancer, make aPOST request to theurlMaps.insert method.

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

     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 loadbalancer's default. The default is used when no host rule matches therequested hostname.
    • URL_MAP_NAME: a name for the URL map.

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

    To add additional backend services to the URL map, make aPATCH requestto theurlMaps.patch method.

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

    You can add multiple path matchers and host rules by making a singleAPI 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 pathmatcher.
    • BACKEND_SERVICE_NAME_1: the name of the firstbackend service.
    • PATH_MATCHER_NAME_2: a name for the second pathmatcher.
    • BACKEND_SERVICE_NAME_2: the name of the secondbackend service.
    • HOSTNAME_1: the hostname to send requests to forthe first service—for example,pubsub.example.com.
    • HOSTNAME_2: the hostname to send requests to forthe second service.

  4. To create a target HTTPS proxy, make aPOST request to thetargetHttpsProxies.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 certificateresource.
    • URL_MAP_NAME: the name of the URL map.

  5. To create a global forwarding rule for your load balancer, make aPOSTrequest to theglobalForwardingRules.insert method.The forwarding rule's network must contain a proxy-only subnet in thesubnet 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 theforwarding rule, which must be within the IP address range of theforwarding rule's subnet. To use a specific ephemeral IP address,provide the IP address—for example,10.0.0.5. To use a staticinternal IP address, provide the name of the IP address. To letGoogle Cloud select an ephemeral IP address, omit this field.
    • FORWARDING_RULE_NAME: the name of the forwardingrule.
    • NETWORK_NAME: the name of the forwarding rule'sVPC network. This network must contain a proxy-onlysubnet in the region where you are creating the load balancer.
    • SUBNET_REGION: the region of the forwarding rule'ssubnet.
    • SUBNET_NAME: the name of the forwarding rule'ssubnet.

Verify the configuration

To test your backend's connection to global Google APIs, do the following:

  1. If you don't have one, create a virtual machine (VM) instance in theVPC network where you configured the backend.
  2. Ensure that you haven't created firewall rules or firewall policies thatoverride theimplied IPv4 allow egress rule.
  3. Connect to the VM.

  4. From the VM, usecurl to verify that you can query each API. This commandsets theHost header and bypasses DNS resolution by specifying auser-defined IP address.

    You can skip certificate validation using the-k flag. You might need toskip validation if you used a self-signed certificate to configure the targetHTTPS proxy or if the VM doesn't have the certificate of the certificateauthority that signed your certificate.

    curl -iv --resolveHOSTNAME:443:IP_ADDRESS \   'https://HOSTNAME/RESOURCE_URI'

    Replace the following:

    • HOSTNAME: the hostname that you configured in yourURL map—for example,pubsub.example.com.
    • IP_ADDRESS: the IP address of your load balancer'sforwarding rule.
    • RESOURCE_URI: the rest of the URI of the resourcethat you want to use for verification. For example, if the load balanceris forwarding requests to a regional endpoint for Pub/Sub,you could use$discovery/rest?version=v1.

Configure DNS records

Configure DNS records for each host that you added to the URL map, pointing tothe IP address of the forwarding rule. If you're using Cloud DNS to manageDNS, seeAdd, modify, and delete records.Otherwise, configure DNS records on your DNS server.

For example, say you have created the following configurations:

  • A Private Service Connect NEG that uses target servicepubsub.googleapis.com.

  • A cross-region internal Application Load Balancer that uses that Private Service Connect NEGas a backend.

  • A URL map that defines a host rule forpubsub.example.com.

For this configuration to work correctly, you must create a DNS record thatpointspubsub.example.com to the IP address of the forwarding rule.

With this configuration, any requests sent topubsub.example.com are sentto the load balancer, which forwards the request topubsub.googleapis.com.

Configure clients to send requests to the backend

To send requests through the backend instead of the public service endpoints,you must configure clients to send requests to the hostname that you defined inthe load balancer's URL map—for example,pubsub.example.com. See thedocumentation for your client or client library for information aboutconfiguring it to use custom endpoints. The following pages includeconfiguration steps for some common clients:

  • Python: you can configureapi_endpoint inClientoptions.

  • Go: you can configureWithEndpoint inClientOptions.

  • .NET: you can configureEndpoint inthe client's builder class.

  • Java: you can configuresetEndpoint in theclient's settings class.

  • gcloud: you can configureapi_endpoint_overrides in thegcloud CLI.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.