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
Enable the Compute Engine, Network Connectivity Center, Cloud DNS, and Service Directory 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 betweenREGION
andrep
.
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.
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
orlogging
.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 regionme-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
orlogging
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.