Access regional Google APIs through endpoints

This document explains how to use Private Service Connect endpoints to connect to regional endpoints of supported Google APIs.

For information about other Private Service Connect configurations, see Private 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:

Compute Network Admin role (roles/compute.networkAdmin)
DNS Administrator role (roles/dns.admin)

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

You might also be able to get the required permissions through custom roles or other predefined roles.

Before you begin

Install the Google Cloud CLI, then initialize it by running the following command:
```
$ gcloud init
```
Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
Enable the Compute Engine, Network Connectivity Center, Cloud DNS, and Service Directory APIs.
Enable the APIs
Enable the Google APIs that you want to access through Private Service Connect endpoints, by using the APIs & services page in the Google Cloud console. Private Service Connect does not automatically enable any API.
Ensure that egress firewall rules permit traffic to the endpoint. The default firewall configuration for a VPC network permits this traffic because it contains an implied allow egress rule. Verify that you have not created a higher priority egress rule that blocks the traffic.
Read the Limitations.

Create a regional Private Service Connect endpoint

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

For a list of supported regional endpoints, see Regional service endpoints.

Regional endpoint hostnames have two forms:

Public hostnames: SERVICE.REGION.rep.DOMAIN
Private hostnames: SERVICE.REGION.p.rep.DOMAIN

The private hostname adds a p subdomain between REGION and rep.

When you configure the target Google API, you specify the private form of the hostname, for example, spanner.me-central2.p.rep.googleapis.com. After you create the endpoint, you create a private DNS record for the endpoint, using the same private regional endpoint hostname.

Although you can configure the Private Service Connect endpoint with any name, for ease of maintenance we recommend using the service name of the target Google API, so that the DNS name matches the endpoint name. For example, if the endpoint has a target of spanner.me-central2.p.rep.googleapis.com, use spanner as the endpoint name.

gcloud

Use the gcloud network-connectivity regional-endpoints create command.

gcloud network-connectivity regional-endpoints create ENDPOINT_NAME \
    --region=REGION \
    --network=NETWORK_URI \
    --subnetwork=SUBNET_URI \
    --target-google-api=REP_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 the endpoint in.
NETWORK_URI: the URI of the VPC network for the endpoint: projects/PROJECT_ID/global/networks/NETWORK_NAME.
SUBNET_URI: the URI of the subnet that you want to connect the endpoint to: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME.
REP_NAME: the name of the regional service endpoint that you want to connect to. For example, spanner.me-central2.p.rep.googleapis.com.

List endpoints

You can list all configured endpoints.

Console

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

Go to Private Service Connect
Click the Connected endpoints tab.

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

gcloud

Use the gcloud network-connectivity regional-endpoints list command.

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

Replace REGION with the region of the endpoints that you want to list.

Verify that the endpoint is working

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

curl --connect-to SERVICE.REGION.p.rep.DOMAIN:443:ENDPOINT_IP:443 \
'SERVICE.REGION.p.rep.DOMAIN/PATH'

Replace the following:

SERVICE: the service that your endpoint is pointing to. For example, spanner or logging.
REGION: the region of the endpoint.
DOMAIN: the domain of the service. For example, googleapis.com.
ENDPOINT_IP: the IP address of the endpoint.
PATH: the path to a resource that is served by this service. 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 address 192.168.1.100 can request the Cloud Spanner API discovery document from the regional endpoint in me-central2.

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

Create a private DNS entry for the endpoint

You must create DNS entries for the endpoints in this format: SERVICE.REGION.p.rep.DOMAIN. You can use Cloud DNS to create the DNS entries.

Create a private DNS zone that has this format: REGION.p.rep.DOMAIN.

For example, if you want to use a regional endpoint in the googleapis.com domain, in region me-central2, create a private DNS zone with this name: me-central2.p.rep.googleapis.com.
Create a DNS record that points to the IP address that is assigned to the endpoint. The hostname must match the service name, SERVICE. For example, spanner or logging are service names.

For example, if your endpoint is configured with the target spanner.me-central2.p.rep.googleapis.com, you create a private DNS zone called me-central2.p.rep.googleapis.com, and an A record called spanner that points to the endpoint IP address. The fully qualified domain name of the endpoint is spanner.me-central2.p.rep.googleapis.com.

Configure clients to use the private endpoint name

You must configure clients to use the private DNS names instead of the public DNS names. See the documentation for your client or client library for information about configuring it to use custom endpoints. For example:

Python: You can configure api_endpoint in Client options.
Go: You can configure WithEndpoint in ClientOptions.
.NET: You can configure Endpoint in the client's builder class.
gcloud: You can configure api_endpoint_overrides in the gcloud CLI.

Get detailed information about an endpoint

You can view the configuration details of an endpoint.

gcloud

Use the gcloud network-connectivity regional-endpoints describe command.

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.

Delete an endpoint

You can delete an endpoint.

gcloud

Use the gcloud network-connectivity regional-endpoints delete command.

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.

Access endpoints from hybrid networks

Clients in networks that are connected to Google Cloud with VLAN attachments for Cloud Interconnect or Cloud VPN tunnels can reach Private Service Connect endpoints.

The VLAN attachment or Cloud VPN tunnel must terminate in the same VPC 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 reach endpoints in another region if global access is configured.
Both Dataplane v1 and Dataplane v2 are supported for the VLAN attachments. For more information about Dataplane versions, see Dataplane v2.

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

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

Create an inbound server policy in the VPC network to which your other network connects.
Identify the inbound forwarder entry points in the region where your VLAN attachment or Cloud VPN tunnel is located, in the VPC network to which your other network connects.
Configure systems and DNS name servers in the other network to forward the DNS names for the endpoint to an inbound forwarder entry point in the same region as the VLAN attachment or Cloud VPN tunnel that connects to the VPC network.