Access regional Google APIs through endpoints

This document explains how to use Private Service Connectendpoints to connect toregional endpoints of supported GoogleAPIs.

For information about other Private Service Connectconfigurations, seePrivate Service Connect.

Roles

To get the permissions that you need to create a regional Private Service Connect endpoint, ask your administrator to grant you the following IAM roles on your VPC network:

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.

Before you begin

  1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

    $gcloudinit

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  2. Enable the Compute Engine, Network Connectivity Center, and Cloud DNS APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the APIs

  3. Additionally,enable the API forthe target service that you want to access through thePrivate Service Connect endpoint. For example, if youwant to accessspanner.me-central2.rep.googleapis.com, enable theCloud Spanner API. Private Service Connect doesn'tautomatically enable any APIs.

  4. Ensure that egress firewall rules permit traffic to the endpoint. Thedefault firewall configuration for a VPC network permits thistraffic because it contains an implied allow egress rule. Verify that youhaven't created a higher priority egress rule that blocks the traffic.

Create a regional Private Service Connect endpoint

You can create a regional Private Service Connect endpoint tosend requests to a regional endpoint for a target Google API.

For a list of supported regional endpoints, seeRegional serviceendpoints.

Console

  1. In the Google Cloud console, go to thePrivate Service Connect page.

    Go to Private Service Connect

  2. ClickConnect endpoint.

  3. InTarget, selectGoogle API.

  4. In theScope list, selectRegional.

  5. In theRegion list, select the region that you want to use.

  6. In theTarget service list, select the service that you want toaccess.

  7. InEndpoint name, enter a name for the endpoint.

  8. InNetwork, select a network.

  9. InSubnetwork, select a subnetwork.

  10. InIP address, do one of the following to configure an IP address:

    • SelectAuto-allocate to automatically allocate and reserve a newIP address.
    • Select a reserved IP address from the list.
    • ClickCreate IP address to reserve a new IP address.

  11. Optional: To make the endpoint available from all regions in theVPC network, selectEnable global access.

  12. ClickAdd endpoint.

gcloud

Use thegcloud network-connectivity regional-endpoints createcommand.

gcloud network-connectivity regional-endpoints createENDPOINT_NAME \    --region=REGION \    --address=ADDRESS \    --network=projects/PROJECT_ID/global/networks/NETWORK_NAME \    --subnetwork=projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \    --target-google-api=REP_DNS_NAME

If you want to make the endpoint available to resources in other regions,add the--enable-global-access flag.

Replace the following:

  • ENDPOINT_NAME: a name for the endpoint.

  • REGION: the region that you want to create theendpoint in.

  • ADDRESS: the IPv4 or IPv6 address that you want touse for the endpoint. If omitted, an IPv4 address from the subnetwork isallocated. Use one of the following formats:

    • IPv4 address—for example,10.0.0.2.
    • IPv4 or IPv6 address resource URI—for example,projects/PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME.

  • PROJECT_ID: the project that you're creating theendpoint in.

  • NETWORK_NAME: the name of the VPCnetwork for the endpoint.

  • SUBNET_NAME: the subnet that you're connecting theendpoint to.

  • REP_DNS_NAME: the hostname of the regional serviceendpoint that you're connecting to. For example,spanner.me-central2.rep.googleapis.com.

API

Use theprojects.locations.regionalEndpoints.create method.

HTTP method and URL:

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints?regionalEndpointId=ENDPOINT_NAME
{  "accessType": "REGIONAL",  "address": "ADDRESS",  "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",  "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME",  "targetGoogleApi": "REP_DNS_NAME"}

Replace the following:

  • PROJECT_ID: the project ID of the endpoint.
  • REGION: the region that you want to create theendpoint in.
  • ENDPOINT_NAME: a name for the endpoint.
  • ADDRESS: the IPv4 or IPv6 address that you want touse for the endpoint. If omitted, an IPv4 address from the subnetwork isallocated. Use one of the following formats:
    • IPv4 address—for example,10.0.0.2.
    • IPv4 or IPv6 address resource URI—for example,projects/PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME.
  • NETWORK_NAME: the name of the VPCnetwork for the endpoint.
  • SUBNET_NAME: the name of the subnet that you want toconnect the endpoint to.
  • REP_DNS_NAME: the hostname of the regional serviceendpoint that you want to connect to. For example,spanner.me-central2.rep.googleapis.com.

List endpoints

You can list all configured endpoints.

Console

  1. In the Google Cloud console, go to thePrivate Service Connect page.

    Go to Private Service Connect

  2. Click theConnected endpoints tab.

    All endpoints are displayed, including endpoints with regional endpoint targets.

gcloud

Use thegcloud network-connectivity regional-endpoints listcommand.

gcloud network-connectivity regional-endpoints list \    --region=REGION

ReplaceREGION with the region of the endpoints that youwant to list.

API

Use theprojects.locations.regionalEndpoints.list method.

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints

Replace the following:

  • PROJECT_ID: the project ID of the endpoint.
  • REGION: the region of the endpoints that you want tolist.

Verify that the endpoint is working

Create a virtual machine (VM) instance in the VPC network andregion where the endpoint is configured. Run the following command on the VM toverify that the Private Service Connect endpoint is working.Endpoints don't respond to ping (ICMP) requests.

  • To verify an IPv4 endpoint, do the following:

    curl --connect-toREP_DNS_NAME:443:ADDRESS:443 \'https://REP_DNS_NAME/PATH'

  • To verify an IPv6 endpoint, do the following:

    curl -6 --connect-toREP_DNS_NAME:443:[ADDRESS]:443 \'https://REP_DNS_NAME/PATH'

Replace the following:

  • REP_DNS_NAME: the public DNS name of the target regionalendpoint—for example,spanner.me-central2.rep.googleapis.com.
  • ADDRESS: the IP address of the endpoint.
  • PATH: the path to a resource that is served by thisservice. For example, many services offer a discovery document with the path$discovery/rest?version=v1.

The following example request tests that an endpoint with IP address192.168.1.100 can request theCloud Spanner APIdiscovery document from the regional endpoint inme-central2.

curl --connect-to spanner.me-central2.rep.googleapis.com:443:192.168.1.100:443 \'https://spanner.me-central2.rep.googleapis.com/$discovery/rest?version=v1'

Create a private DNS entry for the endpoint

You must create private DNS entries so that clients can direct requests to yourPrivate Service Connect endpoint.

We recommend creating a private zone that uses the same hostname as thetarget regional endpoint:SERVICE.REGION.rep.DOMAINand create an apex record in that zone.

For example, if your Private Service Connect endpoint has atarget ofspanner.me-central2.rep.googleapis.com, create a private zone forspanner.me-central2.rep.googleapis.com that contains an apex record forspanner.me-central2.rep.googleapis.com. Creating records in the domain apexmeans that you can access the public hostname of other regional endpoints—for example,logging.me-central2.rep.googleapis.com.

The following sections describe how to use Cloud DNS to create aprivate zone and an apex DNS record.

Create a private zone

Console

  1. In the Google Cloud console, go to theCreate a DNS zone page.

    Go to Create a DNS zone

  2. For theZone type, selectPrivate.

  3. ForZone name, enter a name. For example, if yourPrivate Service Connect endpoint points tospanner.me-central2.rep.googleapis.com, enterspanner-me-central2-rep-googleapis-com.

  4. ForDNS name, specify the hostname of the target regionalendpoint followed by a trailing dot. For example,spanner.me-central2.rep.googleapis.com..

  5. Optional: Add a description.

  6. UnderOptions, selectDefault (private).

  7. Select the VPC networks where you want the privatezone to be visible. Only the VPC networks that youselect are authorized to query records in the zone.

  8. ClickCreate.

gcloud

Run thedns managed-zonescreate command:

gcloud dns managed-zones createZONE_NAME \    --dns-name=REP_DNS_NAME. \    --networks=VPC_NETWORK_LIST \    --visibility=private \    --description="Private zone forREP_DNS_NAME"

Replace the following:

  • ZONE_NAME: a name for your zone—for example,spanner-me-central2-rep-googleapis.com.
  • DESCRIPTION: a description for your zone
  • REP_DNS_NAME: the DNS suffix for your zone; use thetarget regional endpoint hostname—for example,spanner.me-central2.rep.googleapis.com
  • VPC_NETWORK_LIST: a comma-delimited list ofVPC networks that are authorized to query the zone

API

Send aPOST request using themanagedZones.create method:

HTTP method and URL:

POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones

Request JSON body:

{  "name": "ZONE_NAME",  "dnsName": "REP_DNS_NAME.",  "description": "DESCRIPTION",  "visibility": "private",  "privateVisibilityConfig": {    "kind": "dns#managedZonePrivateVisibilityConfig",    "networks": [      {        "kind": "dns#managedZonePrivateVisibilityConfigNetwork",        "networkUrl": "NETWORK_1_URL"      },      {        "kind": "dns#managedZonePrivateVisibilityConfigNetwork",        "networkUrl": "NETWORK_2_URL"      }    ]  }}

Replace the following:

  • PROJECT_ID: the project ID of the DNS zone.
  • ZONE_NAME: the name of the private zone thatyou created for this regional endpoint.
  • REP_DNS_NAME: the FQDN of the record you're creating;use the target regional endpoint hostname—for example,spanner.me-central2.rep.googleapis.com.
  • DESCRIPTION: a description for the DNS zone.
  • NETWORK_1_URL andNETWORK_2_URL:the full URLs of the VPC networks that are authorized to querythe zone—for example,https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/NETWORK_NAME.

Add a DNS record to the zone

Console

  1. In the Google Cloud console, go to theCloud DNS zones page.

    Go to Cloud DNS zones

  2. Click the name of the managed zone that you want to add the record to.

  3. On theZone details page, clickAdd standard.

  4. On theCreate record set page, leave theDNS name fieldblank. Leaving the field blank creates a resource record at the domain apex.

  5. ForResource record type, selectA.

  6. In theIPv4 address field, enter or select the IP address of thePrivate Service Connect endpoint.

  7. ClickCreate.

gcloud

To add a resource record set, use thegcloud dns record-sets createcommand:

gcloud dns record-sets createREP_DNS_NAME \    --rrdatas=ADDRESS \    --type=RECORD_TYPE \    --ttl=TTL \    --zone=ZONE_NAME

Replace the following:

  • REP_DNS_NAME: the FQDN of the record you're creating;use the target regional endpoint hostname—for example,spanner.me-central2.rep.googleapis.com.
  • ADDRESS: the IP address of thePrivate Service Connect endpoint.
  • RECORD_TYPE: the type of DNS record, such asA for IPv4 records orAAAA for IPv6 records.
  • TTL: the TTL in seconds that the resolver caches thisresource record set—for example,300.
  • ZONE_NAME: the name of the private zone thatyou created for this regional endpoint.

API

To add a resource record set, use theresourceRecordSets.create method:

HTTP method and URL:

POST https://www.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/ZONE_NAME/rrsets

Request JSON body:

{  "name": "REP_DNS_NAME.",  "type": "RECORD_TYPE",  "ttl":TTL,  "rrdatas": [ "ADDRESS" ]}

Replace the following:

  • PROJECT_ID: the project ID of the DNS zone.
  • ZONE_NAME: the name of the private zone thatyou created for this regional endpoint.
  • REP_DNS_NAME: the FQDN of the record you're creating;use the target regional endpoint hostname—for example,spanner.me-central2.rep.googleapis.com.
  • RECORD_TYPE: the type of DNS record, such asA for IPv4 records orAAAA for IPv6 records.
  • TTL: the TTL in seconds that the resolver caches thisresource record set—for example,300.
  • ADDRESS: the IP address of thePrivate Service Connect endpoint.

Configure clients to use the private endpoint name

You must configure clients to use the private DNS names instead of the publicDNS names. See the documentation for your client or client library forinformation about configuring it to use custom endpoints. The following pagesinclude configuration 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.

  • gcloud: you can configureapi_endpoint_overrides in thegcloud CLI.

Get detailed information about an endpoint

You can view the configuration details of an endpoint.

gcloud

Use thegcloud network-connectivity regional-endpoints describecommand.

gcloud network-connectivity regional-endpoints describe \ENDPOINT_NAME --region=REGION

Replace the following:

  • ENDPOINT_NAME: the name of the endpoint.
  • REGION: the region of the endpoint.

API

Use theprojects.locations.regionalEndpoints.get command.

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints/ENDPOINT_NAME

Replace the following:

  • PROJECT_ID: the project ID of the endpoint.
  • REGION: the region of the endpoints that you want tolist.
  • ENDPOINT_NAME: the name of the endpoint.

Update the global access configuration

You can't update a Private Service Connect endpoint that has aregional endpoint target. If you need to change the global access setting forthe endpoint,delete the endpoint andcreate a newendpoint that has the required global accesssetting.

Delete an endpoint

You can delete an endpoint.

gcloud

Use thegcloud network-connectivity regional-endpoints deletecommand.

gcloud network-connectivity regional-endpoints delete \ENDPOINT_NAME --region=REGION

Replace the following:

  • ENDPOINT_NAME: the name of the endpoint.
  • REGION: the region of the endpoint.

API

Use theprojects.location.regionalEndpoints.delete command.

DELETE https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints/ENDPOINT_NAME

Replace the following:

  • PROJECT_ID: the project ID of the endpoint.
  • REGION: the region of the endpoint.
  • ENDPOINT_NAME: the name of the endpoint.

Access endpoints from hybrid networks

Clients in networks that are connected to Google Cloud with VLANattachments for Cloud Interconnect or Cloud VPN tunnels can reachPrivate Service Connect endpoints.

  • The VLAN attachment or Cloud VPN tunnel must terminate in the sameVPC network (or Shared VPC network) as the endpoint.Clients in peered VPC networks cannot reach endpoints.

  • Client traffic from VLAN attachments or Cloud VPN tunnels can reachendpoints in another region ifglobal access is configured.

  • Both Dataplane v1 and Dataplane v2 are supported for the VLAN attachments.For more information about Dataplane versions, seeDataplane v2.

You must configure systems in the other network so thatthey can make queries to your private DNS zones.

If you implemented the private DNS zones by using Cloud DNS, completethe following steps:

  • Create aninbound server policy in theVPC network to which your other network connects.

  • Identify theinbound forwarder entry pointsin the region where your VLAN attachment or Cloud VPN tunnel islocated, in the VPC network to which your other networkconnects.

  • Configure systems and DNS name servers in the other network to forward theDNS names for the endpoint to an inbound forwarder entrypoint in the same region as the VLAN attachment or Cloud VPN tunnelthat connects to the VPC network.

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 2025-12-17 UTC.