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 VPC network:

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

For more information about granting roles, see Manage access.

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

Before you begin

1. Install the Google Cloud CLI, then initialize it by running the following command:

   $ gcloud init

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

   Enable the APIs

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

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

5. Read the Known issues.

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 Supported regions and services.

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 beta network-connectivity regional-endpoints create ENDPOINT_NAME \
    --region=REGION \
    --network=NETWORK_URI \
    --subnetwork=SUBNET_URI \
    --target-google-api=REP_NAME

List endpoints

You can list all configured endpoints.

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

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.

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

2. 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.googelapis.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.googelapis.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 beta network-connectivity regional-endpoints describe \
    ENDPOINT_NAME --region=REGION

Delete an endpoint

You can delete an endpoint.

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

Access endpoints from hybrid networks

• The VLAN attachment or Cloud VPN tunnel must terminate in the same 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.

Known issues

• When you create a regional Private Service Connect endpoint, it is viewable in the Google Cloud console with an automatically generated name in this format: rep-autogen-fr-ENDPOINT_NAME. However, don't edit the endpoint by using the Google Cloud console or by modifying the forwarding rule.

  If you need to change the name or enable global access, delete the endpoint and create a new endpoint.