Configuring Private Service Connect to access Google APIs

Private Service Connect lets you connect to service producers using endpoints with internal IP addresses in your VPC network.

This document explains how to use Private Service Connect endpoints to connect to Google APIs. Instead of sending API requests to the publicly available IP addresses for service endpoints such as storage.googleapis.com, you can send the requests to the internal IP address of a Private Service Connect endpoint.

You can also use Private Service Connect to access services in another VPC network and to publish services.

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.

  • Private Service Connect endpoints are not accessible from peered VPC networks.

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

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

gcloud

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

  2. Run the following command to enable Private Google Access:

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

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

Terraform

You can use the Terraform resource to enable Private Google Access on a subnet.

examples/private_service_connect_google_apis/main.tf 
resource "google_compute_network" "network" {
  provider                = google-beta
  project                 = var.project # Replace this with your project ID in quotes
  name                    = "tf-test"
  auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "vpc_subnetwork" {
  provider                 = google-beta
  project                  = google_compute_network.network.project
  name                     = "test-subnetwork"
  ip_cidr_range            = "10.2.0.0/16"
  region                   = "us-central1"
  network                  = google_compute_network.network.id
  private_ip_google_access = true
}

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 is created for p.googleapis.com

  • DNS records are created in p.googleapis.com for commonly used Google APIs and services that are available using Private Service Connect.

    See creating DNS records for instructions to create DNS records for APIs and services that do not have a DNS record in p.googleapis.com.

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.

Supported APIs

When you create a Private Service Connect endpoint to access Google APIs and services, you choose which bundle of APIs you need access to: All APIs (all-apis) or VPC-SC (vpc-sc).

The API bundles give access to the same APIs that are available through the Private Google Access VIPs.

  • The all-apis bundle provides access to the same APIs as private.googleapis.com.

  • The vpc-sc bundle provides access to the same APIs as restricted.googleapis.com.

The API bundles support only HTTP-based protocols over TCP (HTTP, HTTPS, and HTTP/2). All other protocols, including MQTT and ICMP are not supported.

API bundle Supported services Example usage
all-apis Enables API access to most Google APIs and services regardless of whether they are supported by VPC Service Controls. Includes API access to Maps, Google Ads, Google Cloud, and most other Google APIs, including the lists below. Does not support Google Workspace web applications. Does not support any interactive websites.

Domain names that end with:
  • googleapis.com
  • googleadapis.com
  • ltsapis.goog
  • gcr.io
  • pkg.dev
  • gstatic.com
  • appspot.com
  • cloudfunctions.net
  • pki.goog
  • cloudproxy.app
  • run.app
  • datafusion.googleusercontent.com
  • datafusion.cloud.google.com
  • notebooks.cloud.google.com
  • notebooks.googleusercontent.com
Host/domain names that match:
  • appengine.google.com
  • gcr.io
  • packages.cloud.google.com
  • pkg.dev
  • pki.goog
  • source.developers.google.com
 Choose all-apis under these circumstances:
  • You don't use VPC Service Controls.
  • You do use VPC Service Controls, but you also need to access Google APIs and services that are not supported by VPC Service Controls.
vpc-sc Enables API access to Google APIs and services that are supported by VPC Service Controls.

Blocks access to Google APIs and services that do not support VPC Service Controls. Does not support Google Workspace web applications or Google Workspace APIs.

Choose vpc-sc when you only need access to Google APIs and services that are supported by VPC Service Controls. The vpc-sc bundle does not permit access to Google APIs and services that do not support VPC Service Controls.

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. It can be an RFC 1918 address or a non-RFC 1918 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.

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.

Console

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

    Go to Private Service Connect

  2. Click the Connected endpoints tab.

  3. Click Connect endpoint.

  4. For Target, select the target API bundle that you want to use:

    • All Google APIs
    • VPC-SC

  5. For Endpoint name, enter a name for the endpoint.

  6. Select a Network for the endpoint.

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

  8. If a Service Directory region is not already configured for this VPC network, select the region you want to use.

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

  9. Click Add endpoint.

gcloud

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

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

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

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

Terraform

You can use the following Terraform resources to create a Private Service Connect endpoint:

examples/private_service_connect_google_apis/main.tf 
resource "google_compute_global_address" "default" {
  provider     = google-beta
  project      = google_compute_network.network.project
  name         = "global-psconnect-ip"
  address_type = "INTERNAL"
  purpose      = "PRIVATE_SERVICE_CONNECT"
  network      = google_compute_network.network.id
  address      = "10.3.0.5"
}
examples/private_service_connect_google_apis/main.tf 
resource "google_compute_global_forwarding_rule" "default" {
  provider              = google-beta
  project               = google_compute_network.network.project
  name                  = "globalrule"
  target                = "all-apis"
  network               = google_compute_network.network.id
  ip_address            = google_compute_global_address.default.id
  load_balancing_scheme = ""
}

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.

Console

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

    Go to Private Service Connect

  2. Click the Connected endpoints tab.

    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.

Console

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

    Go to Private Service Connect

  2. Click the Connected endpoints tab.

    The Private Service Connect endpoints are displayed.

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

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.

Console

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

    Go to Private Service Connect

  2. Click the Connected endpoints tab.

  3. Select the Private Service Connect endpoint 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, DNS records are automatically created for commonly used APIs and services that are available using Private Service Connect. If you want to use a service, but a DNS record for that service isn't present in the p.googleapis.com zone, follow the instructions in Creating DNS records using default DNS names to add DNS records for those services.

The automatically-created DNS records point to your Private Service Connect endpoint IP address, and are in this format: SERVICE_NAME-ENDPOINT.p.googleapis.com. For example, if your endpoint name is xyz, DNS records are created for storage-xyz.p.googleapis.com, compute-xyz.p.googleapis.com, and other supported APIs.

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/compute https://compute-xyz.p.googleapis.com/compute/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, compute.googleapis.com. See Creating DNS records using default DNS names.

Creating DNS records using default DNS names

You might need to create DNS records that point to your Private Service Connect endpoint for these reasons:

  • Your client or application cannot be configured to use a different endpoint.

  • You want to use DNS names to access Google APIs and services that do not have DNS entries in the private p.googleapis.com DNS zone.

To create DNS records that point to your Private Service Connect endpoint, follow these instructions:

  1. Create a DNS zone for the domain you need to use (for example, googleapis.com or gcr.io). Consider creating a Cloud DNS private zone for this purpose.

  2. In this DNS zone:

    1. Create an A record for the domain (zone) name itself; for example, googleapis.com or gcr.io. Point this A record to the IP address of the Private Service Connect endpoint. If you're using Cloud DNS, see adding a record.

    2. Create a CNAME record for all of the additional domain's possible host names by using an asterisk and a dot followed by the domain (zone) name; for example, *.googleapis.com or *.gcr.io. Point this CNAME record to the A record in the same zone. For example, point *.googleapis.com to googleapis.com or point *.gcr.io to gcr.io.

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.

Use cases

You can create multiple Private Service Connect endpoints in the same VPC network. There is no limit on total bandwidth sent to a particular endpoint. Because Private Service Connect endpoints use global internal IP addresses, they can be used by any resource in your VPC network or an on-premises network connected using Cloud VPN tunnels or Cloud Interconnect attachments.

With multiple endpoints, you can specify different network paths using Cloud Router and firewall rules.

  • You can create firewall rules to prevent some VMs from accessing Google APIs through a Private Service Connect endpoint, while allowing other VMs to have access.

  • You can have a firewall rule on a VM instance that disallows all traffic to the internet; traffic sent to Private Service Connect endpoints still reaches Google.

  • If you have on-premises hosts that are connected to a VPC using a Cloud VPN tunnel or a Cloud Interconnect attachment (VLAN), you can send some requests through the tunnel or VLAN while sending other requests over the public internet. This configuration lets you bypass the tunnel or VLAN for services such as Google Books that are not supported by Private Google Access.

    To create this configuration, create a Private Service Connect endpoint, advertise the Private Service Connect endpoint IP addresses using Cloud Router custom route advertisements, and enable a Cloud DNS inbound forwarding policy. The application can send some requests through the Cloud VPN tunnel or Cloud Interconnect attachment (VLAN) by using the name of the Private Service Connect endpoint, and others over the internet by using the default DNS name.

  • If you connect your on-premises network to your VPC network using multiple Cloud Interconnect attachments (VLANs), you can send some traffic from on-premises over one VLAN and the rest over others, as shown in figure 3. This lets you use your own wide-area networking instead of Google's, and to control data movement to meet geographic requirements.

    To create this configuration, create two Private Service Connect endpoints. Create a custom route advertisement for the first endpoint on the BGP session of the Cloud Router managing the first VLAN, and create a different custom route advertisement for the second endpoint on the BGP session of the Cloud Router managing the second VLAN. On-premises hosts that are configured to use the Private Service Connect endpoint name send traffic over the corresponding Cloud Interconnect attachment (VLAN).

  • You can also use multiple Cloud Interconnect attachments (VLANs) in an active/active topology. If you advertise the same Private Service Connect endpoint IP address using custom route advertisements for the BGP sessions on the Cloud Routers managing the VLANs, packets sent from on-premises systems to the endpoints are routed across the VLANs using ECMP.

    Figure 3. By configuring Private Service Connect, Cloud Router, and on-premises hosts, you can control which Cloud Interconnect attachment (VLAN) is used to send traffic to Google APIs.

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:

  1. Verify that the Cloud DNS API is enabled in your project.

  2. Verify that you have the required permissions to create the Service Directory DNS zone:

    • dns.managedZones.create
    • servicedirectory.namespaces.associatePrivateZone

  3. Delete the DNS zone.

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

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

  2. Delete the DNS zone.