Configure private services access

MySQL  |  PostgreSQL  |  SQL Server

This page describes how to configureprivate services accessin your VPC network.

Private services access is implemented as aVPC peering connection between yourVPC network and theunderlying Google Cloud VPCnetwork where your Cloud SQL instance resides. The private connectionenables VM instances in your VPC network and the services that you access tocommunicate exclusively by using internal IP addresses. VM instances don't needInternet access or external IP addresses to reach services that are availablethroughprivate services access.

Before you begin

Cloud SQL requiresprivate services access for eachVPC network that's used for private IP connections. To manage aprivate services access connection, the user should have the followingIAM permissions:

  • compute.networks.list
  • compute.addresses.create
  • compute.addresses.list
  • servicenetworking.services.addPeering

If you don't have these permissions, then you can get insufficient-permissions errors.

If you're using aShared VPC network, thenyou must also:

  • Add your user to the host project.
  • Assign the same four permissions to that user on the host project.
  • Grant thecompute.globalAddresses.list IAM permission to the user.
If you're usinggcloud toallocate an IP address range, then you don't have to assign thecompute.globalAddresses.list permission to the user.

Configure private services access for Cloud SQL

Important: When you create a private connection between your VPCnetwork and the Cloud SQL service, it becomes available for use byany Google service that supports private services access. If you later deletethe private connection, you remove private connectivityto your Cloud SQL instances andany other service that is usingthat connection. Removing the private connection does not deleteor deprovision any resources.

There are two parts to the private services access configuration process:

Allocate an IP address range

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. Select the VPC network that you want to use.
  3. Select thePrivate service connection tab.
  4. Select theAllocated IP ranges for services tab.
  5. ClickAllocate IP range.
  6. For theName of the allocated range, specifygoogle-managed-services-VPC_NETWORK_NAME, whereVPC_NETWORK_NAME is the name of the VPC network you are connecting (for example,google-managed-services-default). TheDescription is optional.
  7. Select theCustom option, then enter the IP address range to allocate, in CIDR notation.
  8. ClickAllocate to create the allocated range.

gcloud

Do one of the following:

  • To specify an address range and a prefix length (subnet mask), use theaddresses 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.
  • gcloudcomputeaddressescreategoogle-managed-services-VPC_NETWORK_NAME\--global\--purpose=VPC_PEERING\--addresses=192.168.0.0\--prefix-length=16\--network=projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME
  • To specify a prefix length (subnet mask) only, use theprefix-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.
  • gcloudcomputeaddressescreategoogle-managed-services-VPC_NETWORK_NAME\--global\--purpose=VPC_PEERING\--prefix-length=16\--network=projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME

ReplaceVPC_NETWORK_NAME with the name of your VPC network, such asmy-vpc-network.

The following example allocates an IP range that allows resources in the VPC networkmy-vpc-network to connect to Cloud SQL instances using private IP.

gcloudcomputeaddressescreategoogle-managed-services-my-vpc-network\--global\--purpose=VPC_PEERING\--prefix-length=16\--network=projects/myprojectid/global/networks/myvpcnetwork\--project=my-project

Terraform

To allocate an IP address range, use aTerraform resource.

resource "google_compute_global_address" "private_ip_address" {  name          = "private-ip-address"  purpose       = "VPC_PEERING"  address_type  = "INTERNAL"  prefix_length = 16  network       = google_compute_network.peering_network.id}

Apply the changes

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

  1. LaunchCloud Shell.
  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (alsocalled aroot module).

  1. InCloud Shell, create a directory and a new file within that directory. The filename must have the.tf extension—for examplemain.tf. In this tutorial, the file is referred to asmain.tf.
    mkdirDIRECTORY && cdDIRECTORY && touch main.tf
  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly createdmain.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory.
    terraform init

    Optionally, to use the latest Google provider version, include the-upgrade option:

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

Delete the changes

Remove resources previously applied with your Terraform configuration by running the following command and enteringyes at the prompt:

terraform destroy

Create a private connection

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. Select the VPC network that you want to use.
  3. Select thePrivate service connection tab.
  4. Select thePrivate connections to services tab.
  5. ClickCreate connection to create a private connection between yournetwork and a service producer.
  6. For theAssigned allocation, select one or more existing allocatedranges that are not being used by other service producers.
  7. ClickConnect to create the connection.

gcloud

  1. Create a private connection.

    gcloudservicesvpc-peeringsconnect\--service=servicenetworking.googleapis.com\--ranges=google-managed-services-VPC_NETWORK_NAME\--network=VPC_NETWORK_NAME\--project=PROJECT_ID

    The command initiates a long-running Cloud SQL instance operation,returning an operation ID.

  2. Check whether the operation was successful.

    gcloudservicesvpc-peeringsoperationsdescribe\--name=OPERATION_ID

You can specify more than one allocated range when you create a privateconnection. For example, if a range has been exhausted, you can assignadditional allocated ranges. The service uses IP addresses from all theprovided ranges in the order that you specified.

Terraform

To create a private connection, use aTerraform resource.

resource "google_service_networking_connection" "default" {  network                 = google_compute_network.peering_network.id  service                 = "servicenetworking.googleapis.com"  reserved_peering_ranges = [google_compute_global_address.private_ip_address.name]}

A service account in theservice-HOST_PROJECT_NUMBER@service-networking.iam.gserviceaccount.com format is granted theservicenetworking.serviceAgent role while the private connection is created because the account is provisionedjust-in-time.

If you see an error about either thecompute.globalAddresses.list permission orthecompute.projects.get permission for the project, run thisgcloud command:

gcloudprojectsadd-iam-policy-bindingHOST_PROJECT_NAME\--member=serviceAccount:service-HOST_PROJECT_NUMBER@service-networking.iam.gserviceaccount.com\--role=roles/servicenetworking.serviceAgent

Change the private service access configuration

You can change the allocated address range of a private service connectionwithout modifying any existing Cloud SQL instances. To changethe private IP address of an existing Cloud SQL instance, followthese steps.

To change the allocated address range:

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. Select the VPC network that you want to use.
  3. Select thePrivate service connection tab.
  4. Select theAllocated IP ranges for services tab.
  5. Select the name of the range you want to delete.

    Note: Before you delete the range, make a note of its name. You need this name later in this procedure.
  6. ClickRelease.

  7. ClickAllocate IP range.

  8. Create a new range with the same name and new range

    The name matters because the private connection has already beenestablished using that address name.

Note: After modifying or removing an allocated address range, update VPCpeerings. Use the following command, and make sure to use the--force argument:
gcloudservicesvpc-peeringsupdate\--network=VPC_NETWORK_NAME\--ranges=ALLOCATED_RANGES\--service=servicenetworking.googleapis.com\--force
Cloud SQL does not automatically delete the oldsubnet with the old IP range. The range is marked as unusable and cannot be usedagain in the project. This allows existing instances to stay in that subnet. Topermanently remove the subnet, all Cloud SQL instances using an address inthe range must be deleted. The subnet is deleted four days after the lastinstance in the subnet is deleted.

Change the private IP address of an existing Cloud SQL instance

To change the private IP address of an existing Cloud SQL instance, movethe instance from its original network to a temporary VPCnetwork. Then,change the private service accessconfiguration of the instance's original network and move theCloud SQL instance back to its original network.

To move to a different VPC network, follow all but the final step(moving the instance back) in the following procedure. In this case, theTEMPORARY_VPC_NETWORK_NAMEis the new VPC network. Also,deletethe old private connection.It can take a few days for the deleted private connection to disappear from theGoogle Cloud console.

If the Cloud SQL instance is hosted in a Shared VPC network,theVPC_NETWORK_NAMEvariables used in the following instructions must be the host project'sVPC network names. To specify a network with a Shared VPCnetwork, use the full URL of thenetwork—for example,projects/HOST_PROJECT/global/networks/NETWORK_NAME.

Note:If the project that's hosting theVPC network operates in dual stack mode, then there areconsiderations to keep in mind for using this project. For more information,seePlan to upgrade all Cloud SQL instances in a network project.

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. Create a temporary VPC network.
  3. Create an IP allocation in the temporary VPC network.
  4. Create a private connection in the temporary VPC network.
  5. Move the Cloud SQL instance to the temporary VPC network.

    gcloudbetasqlinstancespatchINSTANCE_ID\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/TEMPORARY_VPC_NETWORK_NAME\--no-assign-ip
  6. Change the private service access configuration inthe original network to add a new allocated range or delete existing ones.

  7. Move the Cloud SQL instance back to the original VPCnetwork.

    gcloudbetasqlinstancespatchINSTANCE_ID\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/ORIGINAL_VPC_NETWORK_NAME\--no-assign-ip

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-16 UTC.