Configure private services access
Private services access is a private connection between your VPC network and a network owned by Google or a third party. Google or the third party, entities who are offering services, are also known as service producers. The private connection enables VM instances in your VPC network and the services that you access to communicate exclusively by using internal IP addresses. VM instances don't need internet access or external IP addresses to reach services that are available through private services access.
To learn more about private services access and other private access options, see Private Access Options for Services.
At a high level, to use private services access, you must allocate an IP address range (CIDR block) in your VPC network and then create a private connection to a service producer.
Before you begin
To establish a private connection, complete the following prerequisites:
- Check that the service you're using supports private services access.
- Create a Google Cloud project or choose an existing one. To learn how to create a Google Cloud project, see Creating and Managing Projects.
- Activate the Service Networking API in your project. The API is required to create a private connection.
- Create or choose a VPC network that you will use to connect to the service producer's network. VM instances must use this VPC network to connect to services over a private connection.
- Install the gcloud CLI if you want to run the
gcloud
command-line examples in this guide.
Permissions
Project owners and IAM members with the Compute Network Admin role
(roles/compute.networkAdmin
) can create allocated IP address ranges and manage
private connections.
For more information about roles, read the VPC IAM roles documentation.
Shared VPC scenario
If you are using Shared VPC, create the allocated IP range and private connection in the host project. Typically, a network administrator in the host project must do these tasks. After the host project is set up, VM instances in service projects can use the private connection.
Quotas and limits
Because a private connection is implemented as a VPC peering connection, the same quota and limits that apply to VPC Network Peering also apply to private services access.
Allocated IP address ranges for services
Before you create a private connection, you must allocate an IPv4 address range to be used by the service producer's VPC network. This ensures that there's no IP address collision between your VPC network and the service producer's network. Create an allocated range for each service producer.
When you allocate a range in your VPC network, that range is ineligible for subnets (primary and secondary ranges) and destinations of custom static routes.
Using IPv6 address ranges with private services access is not supported.
IP address range size
When a service producer creates a subnet on their side of the connection, an open range from the allocation is selected for the subnet's IP address range.
Each service producer requires a minimum IP address range size. For Google, the
minimum size is a single /24
block (256 addresses), but the recommended size
is a /16
block (65,536 addresses).
The size you choose depends on several factors, for example:
- The number of services and regions that you use.
- The requirements for the services that you use.
- The minimum IP address range size for the services.
- Whether the service provider requires separate IP ranges for each instance of the service that you create, or whether it can use the same IP range for multiple instances of the service.
If you don't have a contiguous /16
block, you can start with a smaller
allocation and add new ones if you need more IP addresses
later.
About the service producer's subnet
When you establish a private connection and create a resource with a private IP address, the service creates a subnet in which to provision the resource. The service selects an available IP address range from the allocated range. You cannot select or modify the service producer's subnet IP address range. The subnet is deleted by the service only when you delete all resources in the subnet.
As you provision additional resources, the service provisions them in existing regional subnets that it previously created. If a subnet is full, the service creates a new one in that region.
Considerations
Before you allocate an IP address range, consider the following:
- Select an allocated range that is completely separate from current and future subnet ranges, including subnet ranges from networks connected by using VPC Network Peering, and subnet ranges from VPC spokes connected to the same Network Connectivity Center hub.
Select a range that doesn't exactly match or contain the destinations of any custom static or dynamic routes.
When a service producer selects an unused portion of an allocated range to use as a candidate for new resources, it excludes all custom route destinations that exactly match or fit within the allocated range. When a VPC network contains an allocated range and custom routes with destinations that match or fit within the allocated range, the usable portion of the allocated range is reduced. This configuration can lead to unexpected allocation exhausted errors.
For example, if you create an allocated range for
10.0.0.0/16
, the following applies:If a custom route with a destination for
10.0.0.0/16
exists or is created later, all of the10.0.0.0/16
range is considered unavailable. If a service producer attempts to use the allocated range, Google Cloud returns an allocation exhausted error.If a custom route with a destination for
10.0.0.0/20
exists or is created later, the10.0.0.0/20
portion of the10.0.0.0/16
allocated range is considered unavailable. If a service producer attempts to use the allocated range, and the available portion of your allocated range is insufficient for a service producer, Google Cloud returns an allocation exhausted error.If a custom route with a destination for
10.0.0.0/8
exists or is created later, this does not affect the availability of the10.0.0.0/16
allocated range.
Select a range that doesn't conflict with your other IP address needs:
- Some Google and third-party products use
172.17.0.0/16
for routing within the guest operating system. For example, the default Docker bridge network uses this range. If you depend on a product that uses172.17.0.0/16
, don't use172.17.0.0/16
in an allocated range for private services access. - If you're using an auto mode VPC
network, you can't create an allocated range that matches or overlaps with
10.128.0.0/9
. Google uses the10.128.0.0/9
range for automatically created subnets, including those in future regions.
- Some Google and third-party products use
Select a CIDR block that is large enough to meet your current and future needs. If you later find that the range isn't sufficient in size, expand the range if possible. Although you can assign multiple allocations to a single service producer, Google enforces a quota on the number of IP address ranges that you can allocate but not the size (netmask) of each range.
If you add an additional allocated range to a private connection, it expands the range of IP addresses available to the service producer when creating new service resources for any service they provide. You cannot reserve a specific allocated range within a private connection for use by a particular service.
Don't reuse the same allocated range for multiple service producers. Although it's possible, doing so can lead to IP address overlap. Each service producer has visibility only into their network and can't know which IP addresses other service producers are using.
You can only assign one CIDR block to an allocated range when you create the allocation. If you need to expand the IP address range, you can't add more blocks to an allocation. Instead, you can create another allocation or recreate the existing one by using a larger block that encompasses the new and existing ranges.
If you create the allocation yourself instead of having Google do it (such as through Cloud SQL), you can use the same naming convention to signal to other users or Google services that an allocation for Google already exists. When a Google service allocates a range on your behalf, the service uses the following format to name the allocation:
google-managed-services-[your network name]
. If this allocation exists, Google services use the existing one instead of creating another one.Because a private connection is implemented as a VPC Network Peering connection, the behaviors and constraints of peering connections also apply to private connections such as VPC Network Peering limits.
If you plan to change the internal IP address of an existing service instance that uses VPC, consider whether this action might be disruptive, such as if it requires deleting and recreating the service instance. For more information, review the documentation for the associated managed service. For example, if you are using Cloud SQL, see Change the private IP address of an existing Cloud SQL instance.
Create an IP allocation
The following steps describe how to create an allocated IP address range.
Console
In the Google Cloud console, go to the VPC networks page.
Select the VPC network that will connect to a service producer.
Select the Private services access tab.
In the Private services access tab, select the Allocated IP ranges for services tab.
Click Allocate IP range.
Enter a Name and Description for the allocated range.
Specify an IP range for the allocation:
- To specify an IP address range, select Custom and then enter
a CIDR block, such as
192.168.0.0/16
. - To specify a prefix length and let Google select an available range,
select Automatic and then enter a prefix length, such as
16
.
- To specify an IP address range, select Custom and then enter
a CIDR block, such as
Click Allocate to create the allocated range.
gcloud
To create an allocated range in your VPC network, use the
addresses create
command.
To specify an address range and a prefix length (subnet mask), use the
addresses
andprefix-length
flags. For example, to allocate the CIDR block192.168.0.0/16
, specify192.168.0.0
for the address and16
for the prefix length.gcloud compute addresses create RESERVED_RANGE_NAME \ --global \ --purpose=VPC_PEERING \ --addresses=192.168.0.0 \ --prefix-length=16 \ --description="DESCRIPTION" \ --network=VPC_NETWORK
To specify just a prefix length (subnet mask), just use the
prefix-length
flag. When you omit the address range, Google Cloud automatically selects an unused address range in your VPC network. The following example selects an unused IP address range with a16
bit prefix length.gcloud compute addresses create RESERVED_RANGE_NAME \ --global \ --purpose=VPC_PEERING \ --prefix-length=16 \ --description="DESCRIPTION" \ --network=VPC_NETWORK
Replace the following:
RESERVED_RANGE_NAME
: a name for the allocated range, such asmy-allocated-range
.DESCRIPTION
: a description for the range, such asallocated for my-service
.VPC_NETWORK
: the name of your VPC network, such asmy-vpc-network
.
The following example creates a private connection to Google so that the VM
instances in the my-network
VPC network can use private
services access to reach Google services that support it.
gcloud compute addresses create google-managed-services-my-network \ --global \ --purpose=VPC_PEERING \ --prefix-length=16 \ --description="peering range for Google" \ --network=my-network
Terraform
To create an allocated range in your VPC network, use the
google_compute_global_address
resource.
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
If you see an error about the compute.globalAddresses.list
permission for
the project, see Service account permissions.
List allocated IP address ranges
To list allocated IP address ranges, use the
addresses list
command.
gcloud compute addresses list --global --filter="purpose=VPC_PEERING"
Create a private connection
After you create an allocated range, you can create a private connection to a service producer. The private connection establishes a VPC Network Peering connection between your VPC network and the service producer's network.
Private connections are a one-to-one relationship between your VPC network and a service producer. If a single service producer offers multiple services, you only need one private connection for all of the producer's services.
If a single service producer offers multiple services and you want to control which allocated ranges are used for different service resources, you can use multiple VPC networks each with their own private connections. This configuration lets you select a particular network when creating a new managed service resource to ensure that the associated allocated ranges are used for the new resource.
If you connect to multiple service producers, use a unique allocation for each service producer. This practice helps you manage your network settings, such as routes and firewall rules, for each service producer.
Console
In the Google Cloud console, go to the VPC networks page.
Select the VPC network that will connect to a service producer.
Select the Private services access tab.
In the Private services access tab, select the Private connections to services tab.
Click Create connection to create a private connection between your network and a service producer.
For the Assigned allocation, select one or more existing allocated ranges that are not being used by other service producers.
Click Connect to create the connection.
gcloud
Use the
vpc-peerings connect
command.gcloud services vpc-peerings connect \ --service=servicenetworking.googleapis.com \ --ranges=RESERVED_RANGE_NAME \ --network=VPC_NETWORK
Replace the following:
RESERVED_RANGE_NAME
: the name of one or more allocated ranges.VPC_NETWORK
: the name of your VPC network.
The command initiates a long-running operation, returning an operation name.
To check whether the operation was successful, use the
vpc-peerings operations describe
command.gcloud services vpc-peerings operations describe \ --name=OPERATION_NAME
Replace
OPERATION_NAME
with the operation name that was returned from the previous step.
You can specify more than one allocated range when you create a private connection. For example, if a range has been exhausted, you can assign additional allocated ranges. The service will use IP addresses from all of the provided ranges in the order that you specified.
Terraform
To create a private connection, use the
google_service_networking_connection
resource.
List private connections
After you create a private connection, you can list it to check that it exists. The list also shows the list of allocated ranges that are associated with each connection. For example, if you don't remember which allocated range you assigned to a connection, view the list to find out.
Console
In the Google Cloud console, go to the VPC networks page.
Select the VPC network that contains the connections.
Select the Private services access tab.
In the Private services access tab, select the Private connections to services tab to view all the network's private connections.
gcloud
Use the
vpc-peerings list
command.
gcloud services vpc-peerings list \ --network=VPC_NETWORK
Replace VPC_NETWORK
with the name of your
VPC network.
Modify a private connection
For existing private connections, you can add or remove allocated IP address ranges without disrupting traffic. For example, as you scale, you might add an allocated range if you're close to exhausting the existing one.
You cannot remove allocated IP ranges using Google Cloud console. If you want to
remove an allocated range, use the gcloud
instructions to modify the
connection. When you remove a range from a private connection, the following
applies:
The allocated range is no longer associated with the private connection, but it is not deleted.
- If a removed range is no longer in use you can delete the allocation.
Existing service producer resources might continue to use the removed range.
Private services access will not use the removed ranges to allocate new subnets.
Console
In the Google Cloud console, go to the VPC networks page.
Select the VPC network that contains the connections.
Select the Private services access tab.
In the Private services access tab, select the Private connections to services tab to view all the network's private connections.
Click a connection name in the list.
In the Assigned allocation pull-down menu, select the ranges you want allocated.
Click OK.
gcloud
To add or remove assigned allocated IP address ranges on an existing private
connection, use the vpc-peerings update
command.
gcloud services vpc-peerings update \ --service=servicenetworking.googleapis.com \ --ranges=RESERVED_RANGE_NAME \ --network=VPC_NETWORK \ [--force]
Replace the following:
RESERVED_RANGE_NAME
: a list of one or more names of allocated ranges to assign to the private connection.RESERVED_RANGE_NAME
replaces the previous list of allocated ranges. If you omit a range that was previously associated with this private connection, the range is removed from the connection. You must use the--force
option to remove a range.VPC_NETWORK
: the name of your VPC network.
Delete an allocated IP address range
Before you delete an allocated IP address range, check if the range is in use by a private connection.
If the allocated IP address range is in use, first modify the private connection to remove the range. Then delete the allocated IP address range.
If you delete an allocated IP address that is in use, and you don't modify the private connection, the following applies:
Existing connections remain active, but there's nothing preventing your VPC network from using IP addresses that overlap with the service producer's network.
If you delete the only allocated IP address range that is associated with a private connection, the service can't create new subnets because there's no allocated IP address range to select from.
If you later create an allocated IP address range that matches or overlaps the deleted range, adding the range to a private connection fails.
To avoid these problems, always modify your private connections when you delete an in-use allocated IP address range.
Console
In the Google Cloud console, go to the VPC networks page.
Select the VPC network that contains the allocations to delete.
Select the Private services access tab.
In the Private services access tab, select the Allocated IP ranges for services tab.
Select the allocation to delete.
Click Release to return the allocated IP address range to network's pool of available internal IP addresses.
If the allocated IP address range is still assigned to an existing connection, you must enter additional confirmation before you can release the allocation.
Click Release again to confirm the deletion.
gcloud
Delete the allocation by specifying the name of your allocation.
gcloud compute addresses delete NAME \ --global
ReplaceNAME
with the name of the allocated range
that you want to delete.
Delete a private connection
Before you delete a private connection, you must delete all the service instances that you access through the connection. For example, if you want to delete a private connection that is used to access Cloud SQL, you must first delete the Cloud SQL instances that use that connection. After you delete the service instances, the service producer's resources are deleted, but this deletion might not happen immediately. Some service producers delay the deletion until a waiting period has passed. You can't delete the private connection during the waiting period. You must wait until the service producer's resources have been deleted before you can delete the connection.
For example, if you delete a Cloud SQL instance, you receive a success response, but the service waits for four days before deleting the service producer resources. The waiting period means that if you change your mind about deleting the service, you can request to reinstate the resources. If you try to delete the connection during the waiting period, the deletion fails with a message that the resources are still in use by the service producer.
Console
In the Google Cloud console, go to the VPC networks page.
Select the VPC network that contains the connections to delete.
Select the Private services access tab.
In the Private services access tab, select the Private connection to services tab.
Select the private connection to delete.
Click Delete to delete.
Click Delete again to confirm the deletion.
gcloud
To delete a private connection's VPC Network Peering
connection, use the
vpc-peerings delete
command.
gcloud services vpc-peerings delete \ --service=servicenetworking.googleapis.com \ --network=VPC_NETWORK
Replace VPC_NETWORK
with the name of your
VPC network.
Share private DNS zones with service producers
Cloud DNS private zones are private to your VPC network. If you want to let a service producer network resolve names from your private zone, you can configure DNS peering between the two networks.
When you configure DNS peering, you provide a VPC network and a DNS suffix. If the service producer needs to resolve an address with that DNS suffix, the service producer forwards those queries to your VPC network to be resolved.
These supported services support DNS peering, with the exception of Cloud SQL.
If you want to enable DNS peering, you must enable the Cloud DNS API in your project
Peer DNS with a service producer
gcloud
To set up DNS peering between your VPC network and the
service provider network, use the
peered-dns-domains create
command.
gcloud services peered-dns-domains create PEERING_NAME \ --network=VPC_NETWORK \ --dns-suffix=DNS_SUFFIX
Replace the following:
PEERING_NAME
: a name for this DNS peering configuration.VPC_NETWORK
: the name of your VPC network that is connected to the service producer using private services access.DNS_SUFFIX
: the DNS suffix you want to peer with the service producer. You must provide a complete DNS domain name, including the dot. For example,example.com.
is a valid DNS suffix.
Terraform
To set up DNS peering between your VPC network and the service
provider network, use the
google_service_networking_peered_dns_domain
resource.
List DNS peering configurations
gcloud
Use the
peered-dns-domains list
command.
gcloud services peered-dns-domains list \ --network=VPC_NETWORK
Replace VPC_NETWORK
with the name of your VPC
network.
Delete a DNS peering configuration
gcloud
Use the
peered-dns-domains delete
command.
gcloud services peered-dns-domains delete PEERING_NAME \ --network=VPC_NETWORK
Replace the following:
PEERING_NAME
: the name of the DNS peering configuration.VPC_NETWORK
: the name of your VPC network.
Troubleshooting
How much of my allocation is being used?
When you create a private connection with a service producer, you allocate an IP address range for them to use. If you use multiple services from a service producer, each service will reserve a chunk of IP addresses from that allocated range. You can check which services are using which IP addresses so that, for example, you can see which services are using large blocks of IP addresses and avoid IP address exhaustion.
To view the allocation ratio for your allocated ranges, use Network Analyzer. For more information, see Private services access IP address utilization summary.
Alternatively, to view which service is using a particular IP address range:
- List your private connections.
- Find the peering connection name that connects you to the relevant service producer.
- List the routes for your VPC network.
- Find the routes with a next hop that match the peering connection name. The destination range of the routes indicates which IP addresses each service is using.
IP address range exhaustion
For a given private connection, if you exhaust your allocated IP address
space, Google Cloud will return this error: Failed to create subnetwork.
Couldn't find free blocks in allocated IP ranges.
You might see this error because the allocated range is not sufficient for your usage, or because a custom static or dynamic route is preventing the allocated range from being fully used. For more information about routing considerations, see Considerations.
You can expand the existing allocation or add new ones. The expanded allocation must be a contiguous IP address range that includes the existing range. Expanding an allocation is recommended because there's no limit on the size of an allocation, but there is a limit on the number of allocations that you can create.
To expand an existing allocation:
- List your private connections and record the name of the allocated range you need to expand.
- Delete the existing allocated range.
- Create a new allocated range by using the same name as
the deleted range. Specify an IP address range that includes the deleted IP
address range. That way, existing peered resources that are using the old
allocated range can continue to use the same IP addresses without colliding
with resources in your VPC network. For example, if the
previous allocated range was
192.168.0.0/20
, create a new allocated range as192.168.0.0/16
.
To add allocated ranges to an existing private connection:
- Create a new allocated range. This range doesn't have to be contiguous with existing allocated ranges.
- Add the allocated range to the existing private connection.
On-premises hosts can't communicate with the service producer's network
The service producer's network might not have the correct routes to direct traffic to your on-premises network. By default, the service producer's network only learns the subnet routes from your VPC network. Therefore, any request that's not from a subnet IP range is dropped by the service producer.
To configure connectivity between your on-premises hosts and the service producer's network, do the following:
In your VPC network, update the peering connection to export custom routes to the service producer's network. Exporting routes sends all eligible static and dynamic routes that are in your VPC network, such as routes to your on-premises network, to the service producer's network. The service producer's network automatically imports them and then can send traffic back to your on-premises network through the VPC network.
Ensure that the prefixes that include the allocated IP ranges for private services access are being correctly advertised to your on-premises network. To understand how you can advertise custom IPv4 prefixes using Cloud Router, see Advertised routes.
Check that the VLAN attachment or Cloud VPN tunnel terminates in the same VPC network (or Shared VPC network) as the private connection because VPC Network Peering does not provide transitive routing.
Service account permissions
If you see an error about the compute.globalAddresses.list
permission for a
project when creating an IP allocation, or if you experience errors such as
Error 400: Precondition check failed
while creating, listing, or modifying
private connections, it might be a problem with Identity and Access Management (IAM) roles
for your Service Networking API service account.
This service account is created automatically after you enable the Service
Networking API. It can take time for the account to be provisioned and display
on the IAM page.
Console
To ensure that the service account has the correct IAM role, do the following:
In the Google Cloud console, go to the IAM page.
Select the Include Google-provided role grants checkbox.
In the Name column, find the Service Networking Service Agent principal, and then click
Edit principal in the corresponding row.In the Role field, ensure that the Service Networking Service Agent role (
roles/servicenetworking.serviceAgent
) is present.If the Service Networking Service Agent role is not present, click either
Add role or Add another role.Click Select a role.
In the Filter text box, enter
Service Networking Service Agent
.Select Service Networking Service Agent from the list, and then click Save.
gcloud
To create a Service Networking API service account, use the
add-iam-policy-binding
command.
gcloud projects add-iam-policy-binding HOST_PROJECT_NAME \ --member=serviceAccount:service-HOST_PROJECT_NUMBER@service-networking.iam.gserviceaccount.com \ --role=roles/servicenetworking.serviceAgent
Replace the following:
HOST_PROJECT_NAME
: the name of the host project.HOST_PROJECT_NUMBER
: the number of the host project.
Peering subnet route persists after updating IP allocation
After you update the allocated IP address range of a private services connection, the old peering subnet route might still appear in the routing table of your VPC network. The route persists because the IP address range is still in use.
To resolve this issue, do the following:
- Make sure that if you delete an IP allocation, that you also update the private connection.
- Delete or update any resources that use the old IP address range.
The peering subnet route is removed automatically after the IP address range is no longer in use. There might be a delay between deleting the resource, and the service producer fully deleting the resource. For example, if the old IP address range is being used by a Cloud SQL instance, it can take up to four days for the service producer to fully delete your instance. The peering subnet route is removed after the deletion is complete.