Access Google APIs using Private Service Connect
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.
Enable 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 IPv4 address or an internal IPv4 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 subnetREGION
: the region for the subnetNETWORK_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.
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
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 and a Service Directory namespace.
- 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.
When you create the first Private Service Connect endpoint for Google APIs in a VPC network, the region that you select is used as the default region for all subsequent endpoints created in that network. If a region is not already set for a network, and you don't specify a region, the region is set to
us-central1
. All endpoints in a network must use the same Service Directory region.- Service Directory namespace
When you create the first Private Service Connect endpoint for Google APIs in a VPC network, the namespace that you select is used as the default namespace for all subsequent endpoints created in that network. If the namespace is not already set for a network, and you don't specify a namespace, a system-generated namespace is used. All endpoints in a network must use the same Service Directory namespace. The namespace that you choose must be used only for Private Service Connect endpoints that are used to access Google APIs. You can use the same namespace for endpoints in multiple networks.
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 some commonly used Google APIs and services that are available using Private Service Connect and have default DNS names that end ingoogleapis.com
.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
vpc-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 asprivate.googleapis.com
.The
vpc-sc
bundle provides access to the same APIs asrestricted.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 Google 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 match:
|
Choose
|
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
. Although VPC Service Controls are enforced for
compatible and configured services, regardless of the bundle you use,
vpc-sc
provides additional risk mitigation for data
exfiltration. Using vpc-sc
denies access to Google APIs and
services that are not supported by VPC Service Controls. See
Setting up private
connectivity in the VPC Service Controls documentation for more details.
Choose an IP address for the Private Service Connect endpoint
When you configure Private Service Connect on a VPC network, you provide an IP address to use 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 for10.10.10.10/32
, you cannot reserve address10.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.
Create 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
In the Google Cloud console, go to Private Service Connect.
Click the Connected endpoints tab.
Click Connect endpoint.
For Target, select the target API bundle that you want to use:
- All Google APIs
- VPC-SC
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:
- Click Create IP address.
- Enter a Name and Description for the IP address.
- 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.
All endpoints that are used to access Google APIs and services in a given VPC network use the same Service Directory region.
If a Service Directory namespace is not already configured for this VPC network, configure the namespace you want to use:
To use an automatically-assigned namespace, click the Namespace drop-down menu and select the automatically-assigned namespace.
To select an existing namespace that is used in another network, click the Namespace drop-down menu and select a namespace from the list. The list displays all namespaces in the project. You must select a namespace that is used only for Private Service Connect endpoints that are used to access Google APIs.
To create a new namespace, click the Namespace drop-down menu and click Create namespace. Enter the namespace and click Create.
All endpoints that you use to access Google APIs and services in a given VPC network use the same Service Directory namespace.
Click Add endpoint.
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 \ --target-google-apis-bundle=API_BUNDLE \ [ --service-directory-registration=REGION_NAMESPACE_URI ]
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.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_NAMESPACE_URI
: the URI of the Service Directory region or namespace that you want to use. This URI must reference the same project that you are creating the Private Service Connect endpoint in.You can define a region only with
projects/PROJECT_NAME/locations/REGION
.You can define a region and namespace with
projects/PROJECT_NAME/locations/REGION/namespaces/NAMESPACE
.
If you you omit
--service-directory-registration
completely, or set a region without a namespace, the following occurs:If a region or namespace is already configured for this VPC network, those defaults are used.
If a region is not configured, the region is set to
us-central1
. If a namespace is not configured, a system-generated namespace is assigned.
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 orgcloud 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, "namespace": "NAMESPACE" } ], }
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 orgcloud 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 orgcloud 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
. If you omitREGION
, and a region is already configured for this VPC network, that region is used. If a region is not configured, the region is set tous-central1
.NAMESPACE
: the name of the Service Directory namespace that you want to use. If you omitNAMESPACE
, and a namespace is already configured for this VPC network, that namespace is used. If a namespace is not configured, a system-generated namespace is assigned.
Terraform
You can use the following Terraform resources to create a Private Service Connect endpoint:
Verify that the endpoint is working
Create a VM instance in the VPC network where Private Service Connect is configured. Run the following command on the VM to verify that the Private Service Connect endpoint is working. Private Service Connect endpoints do not respond to ping (ICMP) requests.
curl -v ENDPOINT_IP/generate_204
Replace ENDPOINT_IP
with the IP address of the
Private Service Connect endpoint.
If the endpoint is working, you see an HTTP 204
response code.
List endpoints
You can list all configured Private Service Connect endpoints.
Console
In the Google Cloud console, go to Private Service Connect.
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
Get information about an endpoint
You can view all configuration details of a Private Service Connect endpoint.
Console
In the Google Cloud console, go to Private Service Connect.
Click the Connected endpoints tab.
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
Label an endpoint
You can manage labels for Private Service Connect endpoints. See labeling resources for more information.
Delete an endpoint
You can delete a Private Service Connect endpoint.
Console
In the Google Cloud console, go to Private Service Connect.
Click the Connected endpoints tab.
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.
Use an endpoint
To use a Private Service Connect endpoint, you send requests to a DNS hostname that resolves to the IP address of the endpoint.
You can use the automatically-created
p.googleapis.com
DNS names if you can configure your clients to use a custom endpoint and ifp.googleapis.com
DNS records are created for the APIs and services that you want to use. For more information, see Usep.googleapis.com
DNS names.For example, if your endpoint name is
xyz
, DNS records are created forstorage-xyz.p.googleapis.com
,compute-xyz.p.googleapis.com
, and other commonly used APIs in the API bundle.You can create DNS records by using the default DNS names if you are using a client that hasn't been configured to use a custom endpoint, or if a
p.googleapis.com
DNS record does not exist for the service that you want to use. For more information, see Create DNS records by using default DNS names.For example, create DNS records for
storage.googleapis.com
andcompute.googleapis.com
.
Use p.googleapis.com
DNS names
When you create a Private Service Connect endpoint,
Service Directory creates DNS records for commonly used APIs and
services that are available using the endpoint. DNS records are created only for
APIs and services that have default DNS names that end with googleapis.com
,
and only for a subset of those APIs and services.
The DNS records are created in a p.googleapis.com
private zone. The records
point to the endpoint IP address, and use this format:
SERVICE-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.
Clients that can be configured to use a custom endpoint can use the
p.googleapis.com
DNS names to send requests to a
Private Service Connect endpoint.
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 the Client options class in thegoogle-api-core
package.Go: You can configure
WithEndpoint
in the Client options package in theapi
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/
Create DNS records by using default DNS names
You need to create DNS records to direct the default DNS names for APIs and services to your Private Service Connect endpoint in these circumstances:
Your client or application cannot be configured to use a
p.googleapis.com
DNS name.You need to access a supported service, but there is no automatically-created
p.googleapis.com
DNS name for that service.
To create DNS records that point to your Private Service Connect endpoint, follow these instructions:
Create a DNS zone for the domain you need to use (for example,
googleapis.com
orgcr.io
). Consider creating a Cloud DNS private zone for this purpose.In this DNS zone:
Create an
A
record for the domain (zone) name itself; for example,googleapis.com
orgcr.io
. Point thisA
record to the IP address of the Private Service Connect endpoint. If you're using Cloud DNS, see adding a record.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 thisCNAME
record to theA
record in the same zone. For example, point*.googleapis.com
togoogleapis.com
or point*.gcr.io
togcr.io
.
Access the endpoint 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 VLAN attachments.
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 VLAN attachment.
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 VLAN attachments 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 VLAN attachment 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 VLAN attachment, 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 VLAN attachment 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 VLAN attachments, 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 VLAN attachment.
You can also use multiple VLAN attachments 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 VLAN attachment 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:
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
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.