Configuring Private Service Connect

Private Service Connect lets you create an endpoint that directs traffic to Google APIs. Instead of sending API requests to public service endpoints such as storage.googleapis.com, you can send the requests to the Private Service Connect endpoint, which is private and internal to your VPC network.

Roles

The following IAM roles provide the permissions needed to perform the tasks in this guide.

Task	Roles
Create a Private Service Connect endpoint	All of the following roles: Compute Network Admin (`roles/compute.networkAdmin`), Service Directory Editor (`roles/servicedirectory.editor`), and DNS Administrator (`roles/dns.admin`)
Configure Private Google Access (optional)	Compute Network Admin (`roles/compute.networkAdmin`)

Before you begin

Private Service Connect does not automatically enable any API. You must separately enable the Google APIs you need to use from the APIs & services page in the Google Cloud Console.
You must enable the Compute Engine API in your project.
You must enable the Service Directory API in your project.
You must enable the Cloud DNS API in your project.
Egress firewall rules must permit traffic to the Private Service Connect 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.
Virtual machine (VM) instances without an external IP address assigned must use a subnet with Private Google Access enabled to access Google APIs and services using a Private Service Connect endpoint.

A VM with an external IP address can access Google APIs and services using Private Service Connect endpoints even if Private Google Access is disabled for its subnet. Connectivity to the Private Service Connect endpoint stays within Google's network.
If your VPC network does not contain any Private Service Connect endpoints, check if a Cloud DNS private zone exists for p.googleapis.com. If the zone exists, delete it before you create the Private Service Connect endpoint. If you don't delete it, creation of the Service Directory DNS zone used for Private Service Connect fails. For more information, see troubleshooting.

Enabling Private Google Access for a subnet

VMs without an external IP address assigned must be connected to a subnet with Private Google Access enabled to access Google APIs and services using a Private Service Connect endpoint.

If the VM has more than one interface, connect the interface that is configured with a default route (usually nic0).

The source IP address of packets sent from the VM must match the VM interface's primary internal IP address or an internal IP address from an alias IP range.

To enable Private Google Access on a subnet, follow these steps.

Console

In the Google Cloud Console, go to VPC networks.
Go to VPC networks
Click the name of the network that contains the subnet for which you need to enable Private Google Access.
Click the name of the subnet. The Subnet details page is displayed.
Click Edit.
In the Private Google Access section, select On.
Click Save.

gcloud

Determine the name and region of the subnet. To list the subnets for a particular network, use the following command:
```
gcloud compute networks subnets list --filter=NETWORK_NAME
```

Run the following command to enable Private Google Access:

gcloud compute networks subnets update SUBNET_NAME \
--region=REGION \
--enable-private-ip-google-access

Verify that Private Google Access is enabled by running this command:

gcloud compute networks subnets describe SUBNET_NAME \
--region=REGION \
--format="get(privateIpGoogleAccess)"

In all above commands, replace the following with valid values:

SUBNET_NAME: the name of the subnet
REGION: the region for the subnet
NETWORK_NAME: the name of the VPC network that contains the subnet

Private Service Connect and Service Directory

Private Service Connect endpoints are registered with Service Directory. Service Directory is a platform to store, manage, and publish services. When you create a Private Service Connect endpoint to access Google APIs and services, you select a Service Directory region. Service Directory is a regional service; the region you select defines where the Service Directory control plane resides. There is no functional difference between regions, but you might have a preference for administrative reasons.

If you don't already have a Private Service Connect endpoint in a VPC network, the default region is us-central1. When you create the first endpoint in a VPC network, the region that you select is used as the default region for all subsequent endpoints that you create in that VPC network. All endpoints in this VPC network must use this Service Directory region.

When you create a Private Service Connect endpoint, the following DNS configurations are created:

A Service Directory private DNS zone for p.googleapis.com
DNS records for each service made available using the endpoint

The available services vary depending on whether you select the all-apis or vcp-sc API bundle.

One Service Directory DNS zone is created for each VPC network that contains a Private Service Connect endpoint.

The DNS names for a Private Service Connect endpoint are accessible in all regions in your VPC network.

Choosing an IP address for the Private Service Connect endpoint

When you configure Private Service Connect on a VPC network, you provide an IP address which is used for the Private Service Connect endpoint.

The address counts toward the project's quota for Global internal IP addresses.

The IP address must meet the following specifications:

It must be a single IP address and not an address range.
It must be a valid IPv4 address. IPv6 addresses are not supported for Private Service Connect.
It cannot be within the range of subnets configured in the VPC network.
It cannot be within a primary or secondary IP address range of any subnet in the VPC network or a network connected to the VPC network using VPC Network Peering.
It cannot overlap with a /32 custom static route in the local VPC network. For example, if the VPC network has a custom static route for 10.10.10.10/32, you cannot reserve address 10.10.10.10 for Private Service Connect.
It cannot overlap with a /32 peering custom static route if you've configured the peered network to export custom routes and you've configured your VPC network to import custom routes.
It cannot be within any of the auto-mode IP ranges (in 10.128.0.0/9) if the local VPC network is an auto mode network or if it is peered with an auto mode network.
It cannot be within an allocated IP range in the local VPC network. However, it can be within an allocated IP range in a peered VPC network.
If a Private Service Connect endpoint overlaps with a custom dynamic route whose destination is the same /32, the Private Service Connect endpoint takes priority.
If a Private Service Connect endpoint IP address is located within the destination range of a custom static route, custom dynamic route, or peering custom route, and that route has a subnet mask shorter than /32, the Private Service Connect endpoint has higher priority.
Using non-RFC 1918 addresses for Private Service Connect endpoints results in unexpected costs due to a billing issue. To prevent this issue, avoid using non-RFC 1918 IP addresses and instead use RFC 1918 IP addresses for Private Service Connect endpoints. If you are affected by this issue, contact your account team for remediation.

Creating a Private Service Connect endpoint

Once you have chosen an IP address that meets the requirements, you can create a Private Service Connect endpoint.

A Private Service Connect endpoint connects to Google APIs and services using a global forwarding rule. Each forwarding rule counts toward the per VPC network quota for Private Service Connect.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.globalForwardingRules.pscCreate
compute.globalForwardingRules.create
compute.networks.use
compute.globalAddresses.use
servicedirectory.namespaces.create
servicedirectory.namespaces.associatePrivateZone
dns.managedZones.create

Roles

See Roles for role information.

Console

In the Google Cloud Console, go to Private Service Connect.

Go to Private Service Connect
Click Connect endpoint.
Select the target API bundle.
For Endpoint name, enter a name for the endpoint.
Select a Network for the endpoint.
Select an IP Address for the endpoint.

The IP address must meet these requirements.

If you need a new IP address, you can create one:
1. Click Create IP address.
2. Enter a Name and Description for the IP address.
3. Enter the IP address you want to use and click Save .
If a Service Directory region is not already configured for this VPC network, select the region you want to use.
Click Add endpoint.

All endpoints used to access Google APIs and services in a given VPC network use the same Service Directory region.

gcloud

Reserve a global internal IP address to assign to the endpoint.
```
gcloud compute addresses create ADDRESS_NAME \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=ENDPOINT_IP \
  --network=NETWORK_NAME
```
Replace the following:
- ADDRESS_NAME: the name to assign to the reserved IP address.
- ENDPOINT_IP: the IP address to reserve for the endpoint.
  
  The IP address must meet these requirements.
- NETWORK_NAME: the name of the VPC network for the endpoint.
Create a forwarding rule to connect the endpoint to Google APIs and services.
```
gcloud compute forwarding-rules create ENDPOINT_NAME \
  --global \
  --network=NETWORK_NAME \
  --address=ADDRESS_NAME \
  --service-directory-registration=REGION_URI
  --target-google-apis-bundle=API_BUNDLE
```
Replace the following:
- ENDPOINT_NAME: the name to assign to the endpoint. The name must be a string of 1-20 characters, containing only lower-case letters and numbers. The name must start with a letter.
- NETWORK_NAME: the name of the VPC network for the endpoint.
- ADDRESS_NAME: the name of the reserved address on the associated network.
- REGION_URI: the URI of the Service Directory region that you want to use. This URI must reference the same project that you are creating the Private Service Connect endpoint in. The REGION_URI has this format: projects/PROJECT_NAME/locations/REGION.
- API_BUNDLE: the bundle of APIs to make available using the endpoint. See the list of supported APIs.
  - Use all-apis to give access to all supported APIs.
  - Use vpc-sc to restrict access to Google APIs that support VPC Service Controls.

API

Reserve a global internal IP address to assign to the endpoint.
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/addresses

{
"name": ADDRESS_NAME,
"address": ENDPOINT_IP,
"addressType": "INTERNAL",
"purpose": PRIVATE_SERVICE_CONNECT,
"network": NETWORK_URL
}
```
Replace the following:
- PROJECT_ID: your project ID.
- ADDRESS_NAME: the name to assign to the reserved IP address.
- ENDPOINT_IP: the IP address to reserve for the endpoint.
  
  The IP address must meet these requirements.
- NETWORK_URL: the VPC network for the endpoint. Use the network.list method or gcloud compute networks list --uri to find the URLs of your networks.
Create a forwarding rule to connect the endpoint to Google APIs and services.
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/forwardingRules
{
 "IPAddress": ADDRESS_URL,
 "network": NETWORK_URL,
 "name": ENDPOINT_NAME,
 "target": API_BUNDLE,
 "serviceDirectoryRegistrations : [
   {
     "service_directory_region": REGION,
   }
 ],
}
```
Replace the following:
- PROJECT_ID: your project ID.
- ENDPOINT_NAME: the name to assign to the endpoint. The name must be a string of 1-20 characters, containing only lower-case letters and numbers. The name must start with a letter.
- NETWORK_URL: the VPC network for the endpoint. Use the network.list method or gcloud compute networks list --uri to find the URLs of your networks.
- ADDRESS_URL: the URL of the reserved address on the associated network. Use the globalAddresses.list method or gcloud compute addresses list --uri to find the URLs of your reserved addresses.
- API_BUNDLE: the bundle of APIs to make available using the endpoint. See the list of supported APIs.
  - Use all-apis to give access to all supported APIs.
  - Use vpc-sc to restrict access to Google APIs that support VPC Service Controls.
- REGION: the Service Directory region you want to use. For example, us-central1.

Verifying that the endpoint is working

Create a VM instance in the VPC network where Private Service Connect is configured, and run this command on the VM to verify that the Private Service Connect endpoint is working.

curl -v ENDPOINT_IP/generate_204

Replace the following:

ENDPOINT_IP: the IP address of the Private Service Connect endpoint.

If the endpoint is working, you see an HTTP 204 response code.

Listing endpoints

You can list all configured Private Service Connect endpoints.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.globalForwardingRules.list

Roles

See Roles for role information.

Console

In the Google Cloud Console, go to Private Service Connect.

Go to Private Service Connect

The Private Service Connect endpoints are displayed.

gcloud

gcloud compute forwarding-rules list  \
--filter target="(all-apis OR vpc-sc)" --global

The output is similar to the following:

NAME  REGION  IP_ADDRESS  IP_PROTOCOL  TARGET
RULE          IP          TCP          all-apis

Getting information about an endpoint

You can view all configuration details of a Private Service Connect endpoint.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.globalForwardingRules.get

Roles

See Roles for role information.

Console

In the Google Cloud Console, go to Private Service Connect.

Go to Private Service Connect

The Private Service Connect endpoints are displayed.
Click the Private Service Connect endpoint that you want to view details for.

gcloud

gcloud compute forwarding-rules describe \
    ENDPOINT_NAME --global

Labeling an endpoint

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.globalForwardingRules.pscSetLabels
compute.globalForwardingRules.setLabels

Roles

See Roles for role information.

You can manage labels for Private Service Connect endpoints. See labeling resources for more information.

Deleting an endpoint

You can delete a Private Service Connect endpoint.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.globalForwardingRules.pscDelete
compute.globalForwardingRules.delete
servicedirectory.namespaces.delete
dns.managedZones.delete

Roles

See Roles for role information.

Console

In the Google Cloud Console, go to Private Service Connect.

Go to Private Service Connect
Select the connection you want to delete, and click Delete.

gcloud

    gcloud compute forwarding-rules delete \
        ENDPOINT_NAME --global

Replace the following:

ENDPOINT_NAME: the name of the endpoint that you want to delete.

Using an endpoint

When you create a Private Service Connect endpoint, Service Directory creates DNS records for the APIs and services that are made available using that endpoint.

The DNS records point to your Private Service Connect endpoint IP address, and are in this format: SERVICE-ENDPOINT.p.googleapis.com.

You can use these DNS names in your API requests to direct the request to your Private Service Connect endpoint. You can also use these DNS names in the Host header of your request.

If you want to use a Private Service Connect endpoint with a client or application that accesses Google APIs and services, update your client or application to use the p.googleapis.com DNS names.

See the documentation for your client or client library for details. For example:

Python: You can configure api_endpoint in the Client options class in the google-api-core package.
Go: You can configure WithEndpoint in the Client options package in the api package.
gcloud: You can configure api_endpoint_overrides using this command.

gcloud config set api_endpoint_overrides/SERVICE ENDPOINT_URL

For example: gcloud config set api_endpoint_overrides/storage https://storage-xyz.p.googleapis.com/storage/v1/

If you can't configure your client or application to use a different endpoint, create DNS records to match the default DNS names. For example, storage.googleapis.com. See Creating DNS records using default DNS names.

Creating DNS records using default DNS names

If your client or application cannot be configured to use a different endpoint, you can create DNS records so that the default DNS names (for example, storage.googleapis.com) point to your Private Service Connect endpoint.

Create a private DNS zone for googleapis.com. Consider creating a Cloud DNS private zone for this purpose.
For each service that you want to use, add a DNS record in the googleapis.com private zone that points to the Private Service Connect endpoint IP address.

If you're using Cloud DNS, add the records to the googleapis.com private zone.

For example, if you want to access Cloud Storage, create a record for the hostname storage in the private googleapis.com zone that points to the Private Service Connect endpoint IP address.

Using Private Service Connect from on-premises hosts

If your on-premises network is connected to a VPC network, you can use Private Service Connect to access Google APIs and services from on-premises hosts using the internal IP address of the Private Service Connect endpoint.

Your on-premises network must be connected to a VPC network using either Cloud VPN tunnels or Cloud Interconnect attachments (VLANs).
The Private Service Connect endpoint is in the VPC network that is connected to your on-premises network.
The on-premises network must have appropriate routes for the Private Service Connect endpoint. Configure a Cloud Router custom route advertisement to announce routes for the Private Service Connect endpoint on the BGP session that manages routes for the Cloud VPN tunnel or Cloud Interconnect attachment (VLAN).
You must configure on-premises systems so that they can make queries to your private DNS zones.

If you've implemented the private DNS zones using Cloud DNS, complete the following steps:
- Create an inbound server policy in the VPC network to which your on-premises network connects.
- Identify the inbound forwarder entry points, in the regions where your Cloud VPN tunnels and Cloud Interconnect attachments (VLANs) are located, in the VPC network to which your on-premises network connects.
- Configure on-premises systems and on-premises DNS name servers to forward the DNS names for the Private Service Connect endpoints to an inbound forwarder entry point in the same region as the Cloud VPN tunnel or Cloud Interconnect attachment (VLAN) that connects to the VPC network.

Troubleshooting

Private DNS zone creation fails

When you create a Private Service Connect endpoint, a Service Directory DNS zone is created. Zone creation can fail for these reasons:

You haven't enabled the Cloud DNS API in your project.
You don't have the required permissions to create a Service Directory DNS zone.
A DNS zone with the same zone name exists in this VPC network.
A DNS zone for p.googleapis.com already exists in this VPC network.

Conflicting zones might exist because a previous deletion failed.

To create the Service Directory DNS zone, do the following:

Verify that the Cloud DNS API is enabled in your project.
Verify that you have the required permissions to create the Service Directory DNS zone:
- dns.managedZones.create
- servicedirectory.namespaces.associatePrivateZone
Delete the DNS zone.
Create a Service Directory DNS zone backed by the Service Directory namespace associated with your Private Service Connect endpoint.

Use the following values when you create the zone:
- Zone name: Use the same zone name that the system used during the failed creation attempt. The error message displays what zone name was used.
- DNS name: p.googleapis.com. (include the trailing dot).
- Service Directory namespace: Find the Service Directory namespace for the Private Service Connect endpoint you created, and use this namespace when you create the Service Directory DNS zone.
The Service Directory namespace has the following format: goog-psc-NETWORK_NAME-NETWORK_ID.

Private DNS zone deletion fails

When you delete the last Private Service Connect endpoint in a VPC network, the associated Service Directory configuration including the DNS zone is deleted.

This deletion can fail for these reasons:

You don't have the required permissions to delete the DNS zone.
The zone contains user-defined DNS entries that were not created by Service Directory.

To resolve this issue, do the following:

Verify that you have the dns.managedZones.delete permission. For more information, see Access Control in the Cloud DNS documentation.
Delete the DNS zone.