Configure private IP

This page describes how to configure a Cloud SQL instance to use private IP.

For information about how private IP works, as well as environment and management requirements, see Private IP.

Before you begin

API and IAM requirements

  • You must enable the Service Networking API for your Google Cloud project.

    • If you are using a Shared VPC network, you also need to enable this API for the host project.

  • In order to manage a private services access connection, the user must have the following Identity and Access Management (IAM) permissions. If you don't have the required permissions you can get insufficient-permissions errors.
    • compute.networks.list
    • compute.addresses.create
    • compute.addresses.list
    • servicenetworking.services.addPeering

    If you are using a Shared VPC network, you also need to add your user to the host project and assign the same permissions to the user on the host project.

Private services access

When you create a new Virtual Private Cloud (VPC) network in your project, you need to configure private services access to allocate an IP address range and create a private service connection. This allows resources in the VPC network to connect to Cloud SQL instances. The Google Cloud console provides a wizard to help you set up this configuration.

Configure an instance to use private IP

You can configure a Cloud SQL instance to use private IP when you create the instance, or for an existing instance.

Configure private IP for a new instance

To configure a Cloud SQL instance to use private IP when creating an instance:

Console

  1. In the Google Cloud console, go to the Cloud SQL Instances page.

    Go to Cloud SQL Instances

  2. Click Create instance.
  3. Expand Show configuration options.
  4. Expand Connections.
  5. Select Private IP.

    A drop-down list shows the available VPC networks in your project. If your project is the service project of a Shared VPC, then VPC networks from the host project are also shown.

  6. Select the VPC network you want to use.

    7. If you see a message indicating that you need to set up a private service connection, do the following:

    1. Click Set up connection.
    2. In the Allocate an IP range section, select one of the following options:
      • Select one or more existing IP ranges or create a new one from the dropdown. The dropdown includes previously allocated ranges, if there are any, or you can select Allocate a new IP range and enter a new range and name.
      • Use an automatically allocated IP range in your network.
    3. Click Continue.
    4. Click Create connection.
    5. Verify that you see the message: Private service connection for network VPC_NETWORK_NAME has been successfully created.
  7. Optionally, you can specify an allocated IP range for your instances to use for connections.
    1. Expand Show allocated IP range option.
    2. Select an IP range from the drop-down menu.
  8. Optional. If you want to allow other Google Cloud services, such as BigQuery, to access data in Cloud SQL and make queries against this data over a private IP connection, then select Enable private path.
  9. Finish configuring your instance.
  10. Click Create instance.

gcloud

Before you create an instance using a private IP address, ensure that your project is configured for private services access.

Before using any of the request data, make the following replacements:

  • INSTANCE_ID: The instance ID
  • PROJECT_ID: The project ID

  • NETWORK_PROJECT_ID: The project ID of the VPC network

  • VPC_NETWORK_NAME: The name of the VPC network
  • RANGE_NAME: Optional. If specified, sets a range name for which an IP range is allocated. The range name must comply with RFC-1035 and contain 1-63 characters.
  • DATABASE_VERSION: The version of the PostgreSQL database (for example, POSTGRES_14)
  • NUMBER_OF_CPU: The number of CPUs
  • MEMORY_IN_GB: The amount of memory (in GB)
  • REGION_NAME: The region name
To specify the name of your VPC network, use the --network parameter. To disable public IP, use the --no-assign-ip flag.

Also, optionally, use the --enable-google-private-path parameter to allow other Google Cloud services such as BigQuery to access data in Cloud SQL and make queries against this data over a private IP connection. This parameter is valid only if:

  • You use the --no-assign-ip parameter.
  • You use the --network parameter to specify the name of the VPC network that you want to use to create a private connection.

gcloud beta sql instances create INSTANCE_ID \
--project=PROJECT_ID \
--network=projects/NETWORK_PROJECT_ID/global/networks/VPC_NETWORK_NAME \
--no-assign-ip \
--allocated-ip-range-name=RANGE_NAME \
--enable-google-private-path \
--database-version=DATABASE_VERSION \
--cpu=NUMBER_OF_CPU \
--memory=MEMORY_IN_GB \
--region=REGION_NAME

Terraform

To configure private IP for a new instance, use the following Terraform resources: 


resource "google_compute_network" "peering_network" {
  name                    = "private-network"
  auto_create_subnetworks = "false"
}

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
}

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]
}

resource "google_sql_database_instance" "default" {
  name             = "private-ip-sql-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"

  depends_on = [google_service_networking_connection.default]

  settings {
    tier = "db-custom-2-7680"
    ip_configuration {
      ipv4_enabled    = "false"
      private_network = google_compute_network.peering_network.id
    }
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

resource "google_compute_network_peering_routes_config" "peering_routes" {
  peering              = google_service_networking_connection.default.peering
  network              = google_compute_network.peering_network.name
  import_custom_routes = true
  export_custom_routes = true
}

# [START  cloud_sql_postgres_instance_private_ip_dns]

## Uncomment this block after adding a valid DNS suffix

# resource "google_service_networking_peered_dns_domain" "default" {
#   name       = "example-com"
#   network    = google_compute_network.peering_network.id
#   dns_suffix = "example.com."
#   service    = "servicenetworking.googleapis.com"
# }

Apply the changes

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

Prepare Cloud Shell

  1. Launch Cloud 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 (also called a root module).

  1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && 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 created main.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 entering yes 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.

Delete the changes

To delete your changes, do the following:

  1. To disable deletion protection, in your Terraform configuration file set the deletion_protection argument to false. 
    deletion_protection =  "false"
  2. Apply the updated Terraform configuration by running the following command and entering yes at the prompt: 
    terraform apply

  1. Remove resources previously applied with your Terraform configuration by running the following command and entering yes at the prompt:

    terraform destroy

REST v1

Create a new instance with a private IP address:

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID
  • INSTANCE_ID: The instance ID
  • VPC_NETWORK_NAME: Specify the name of the Virtual Private Cloud (VPC) network that you want to use for this instance. Private services access must already be configured for the network.
  • RANGE_NAME: Optional. If specified, sets a range name for which an IP range is allocated. The range name must comply with RFC-1035 and contain 1-63 characters.
  • AUTHORIZED_NETWORKS: For public IP connections, specify the connections from authorized networks that can connect to your instance.

For the ipv4Enabled parameter, set the value to true if you're using a public IP address for your instance or false if your instance has a private IP address.

If you set the enablePrivatePathForGoogleCloudServices parameter to true, then you allow other Google Cloud services, such as BigQuery, to access data in Cloud SQL and make queries against this data over a private IP connection. By setting this parameter to false, other Google Cloud services can't access data in Cloud SQL over a private IP connection.

HTTP method and URL: 

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

Request JSON body: 

{
  "name": "INSTANCE_ID",
  "region": "region",
  "databaseVersion": "database-version",
  "settings": {
    "tier": "machine-type",
    "ipConfiguration": {
      "ipv4Enabled": false,
      "privateNetwork": "projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME",
      "allocatedIpRange": "RANGE_NAME"
      "authorizedNetworks": [AUTHORIZED_NETWORKS],
      
      "enablePrivatePathForGoogleCloudServices": true
      
    }
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

REST v1beta4

Create a new instance with a private IP address:

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID
  • INSTANCE_ID: The instance ID
  • VPC_NETWORK_NAME: Specify the name of the Virtual Private Cloud (VPC) network that you want to use for this instance. Private services access must already be configured for the network.
  • RANGE_NAME: Optional. If specified, sets a range name for which an IP range is allocated. The range name must comply with RFC-1035 and contain 1-63 characters.
  • AUTHORIZED_NETWORKS: For public IP connections, specify the connections from authorized networks that can connect to your instance.

For the ipv4Enabled parameter, set the value to true if you're using a public IP address for your instance or false if your instance has a private IP address.

If you set the enablePrivatePathForGoogleCloudServices parameter to true, then you allow other Google Cloud services, such as BigQuery, to access data in Cloud SQL and make queries against this data over a private IP connection. By setting this parameter to false, other Google Cloud services can't access data in Cloud SQL over a private IP connection.

HTTP method and URL: 

POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

Request JSON body: 

{
  "name": "INSTANCE_ID",
  "region": "region",
  "databaseVersion": "database-version",
  "settings": {
    "tier": "machine-type",
    "ipConfiguration": {
      "ipv4Enabled": false,
      "privateNetwork": "projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME",
      "allocatedIpRange": "RANGE_NAME"
      "authorizedNetworks": [AUTHORIZED_NETWORKS],
      
      "enablePrivatePathForGoogleCloudServices": true
      
    }
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

Configure private IP for an existing instance

Configuring an existing Cloud SQL instance to use private IP causes the instance to restart, resulting in downtime.

To configure an existing instance to use private IP:

Console

  1. In the Google Cloud console, go to the Cloud SQL Instances page.

    Go to Cloud SQL Instances

  2. To open the Overview page of an instance, click the instance name.
  3. Select Connections from the Cloud SQL navigation menu.
  4. On the Networking tab, select the Private IP checkbox.

    A drop-down list shows the available networks in your project.

  5. Select the VPC network you want to use:

    6. If you see Private service connection required:

    1. Click Set up connection.
    2. In the Allocate an IP range section, choose one of the following options:
      • Select one or more existing IP ranges or create a new one from the dropdown. The dropdown includes previously allocated ranges, if there are any, or you can select Allocate a new IP range and enter a new range and name.
      • Use an automatically allocated IP range in your network.
    3. Click Continue.
    4. Click Create connection.
    5. Verify that you see the Private service connection for network VPC_NETWORK_NAME has been successfully created status.
  6. Optional. If you want to allow other Google Cloud services, such as BigQuery, to access data in Cloud SQL and make queries against this data over a private IP connection, then select the Enable private path check box.
  7. Click Save.

gcloud

Ensure your project is configured for private services access.

Update your Cloud SQL instance by using the --network parameter to specify the name of your selected VPC network.

gcloud beta sql instances patch INSTANCE_ID \
--project=PROJECT_ID \
--network=projects/NETWORK_PROJECT_ID/global/networks/VPC_NETWORK_NAME \
--no-assign-ip \
--enable-google-private-path

REST v1

Create a new instance with a private IP address:

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID
  • INSTANCE_ID: The instance ID
  • VPC_NETWORK_NAME: Specify the name of the Virtual Private Cloud (VPC) network that you want to use for this instance. Private services access must already be configured for the network.
  • RANGE_NAME: Optional. If specified, sets a range name for which an IP range is allocated. The range name must comply with RFC-1035 and contain 1-63 characters.
  • AUTHORIZED_NETWORKS: For public IP connections, specify the connections from authorized networks that can connect to your instance.

For the ipv4Enabled parameter, set the value to true if you're using a public IP address for your instance or false if your instance has a private IP address.

If you set the enablePrivatePathForGoogleCloudServices parameter to true, then you allow other Google Cloud services, such as BigQuery, to access data in Cloud SQL and make queries against this data over a private IP connection. By setting this parameter to false, other Google Cloud services can't access data in Cloud SQL over a private IP connection.

HTTP method and URL: 

PATCH https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID

Request JSON body: 

{
  "settings":
  {
    "ipConfiguration": {
      "ipv4Enabled": false,
      "privateNetwork": "projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME",
      "allocatedIpRange": "RANGE_NAME"
      "authorizedNetworks": [AUTHORIZED_NETWORKS],
      
      "enablePrivatePathForGoogleCloudServices": true
      
    }
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

REST v1beta4

Create a new instance with a private IP address:

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID
  • INSTANCE_ID: The instance ID
  • VPC_NETWORK_NAME: Specify the name of the Virtual Private Cloud (VPC) network that you want to use for this instance. Private services access must already be configured for the network.
  • RANGE_NAME: Optional. If specified, sets a range name for which an IP range is allocated. The range name must comply with RFC-1035 and contain 1-63 characters.
  • AUTHORIZED_NETWORKS: For public IP connections, specify the connections from authorized networks that can connect to your instance.

For the ipv4Enabled parameter, set the value to true if you're using a public IP address for your instance or false if your instance has a private IP address.

If you set the enablePrivatePathForGoogleCloudServices parameter to true, then you allow other Google Cloud services, such as BigQuery, to access data in Cloud SQL and make queries against this data over a private IP connection. By setting this parameter to false, other Google Cloud services can't access data in Cloud SQL over a private IP connection.

HTTP method and URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID

Request JSON body: 

{
  "settings":
  {
    "ipConfiguration": {
      "ipv4Enabled": false,
      "privateNetwork": "projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME",
      "allocatedIpRange": "RANGE_NAME"
      "authorizedNetworks": [AUTHORIZED_NETWORKS],
      
      "enablePrivatePathForGoogleCloudServices": true
      
    }
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

Connect to an instance using its Private IP

You use private services access to connect to Cloud SQL instances from Compute Engine or Google Kubernetes Engine instances in the same VPC network (defined here as internal sources) or from outside of that network (an external source).

Connect from an internal source

To connect from a source in the same Google Cloud project as your Cloud SQL instance, such as the Cloud SQL Auth Proxy running on a Compute Engine resource, that resource must be in the same VPC network where private services access has been established for the Cloud SQL instance.

To connect from a serverless source, such as App Engine standard environment, Cloud Run, or Cloud Run functions, your application or function connects directly to your instance through Serverless VPC Access without the Cloud SQL Auth Proxy.

Connect from an external source

If an external network (for example, an on-premises network or a VPC network), is connected to the VPC network to which your Cloud SQL instance is connected, then you can use Cloud VPN or Cloud Interconnect to connect to the instance from a client in the external network.

To permit connections from an external network, do the following:

  1. Ensure your VPC network is connected to the external network using a Cloud VPN tunnel or a VLAN attachment for Dedicated Interconnect or Partner Interconnect.
  2. Ensure the Border Gateway Protocol (BGP) sessions on the Cloud Routers managing your Cloud VPN tunnels and Cloud Interconnect attachments (VLANs) have received specific prefixes (destinations) from your on-premises network.

    Default routes (destination 0.0.0.0/0) cannot be imported into the Cloud SQL VPC network because that network has its own local default route. Local routes for a destination are used even though the Cloud SQL peering is configured to import custom routes from your VPC network.

  3. Identify the peering connections produced by the private services connection. Depending on the service, the private services connection might create one or more of the following peering connections, but not necessarily all of them:
    • cloudsql-mysql-googleapis-com
    • cloudsql-postgres-googleapis-com
    • servicenetworking-googleapis-com
  4. Update all of the peering connections to enable Export custom routes.
  5. Identify the allocated range used by the private services connection.
  6. Configure Cloud Router custom advertisement mode for the allocated range on the Cloud Routers managing BGP sessions for your Cloud VPN tunnels or Cloud Interconnect attachments (VLANs).

Connect from Cloud Shell

Cloud Shell doesn't support connecting to a Cloud SQL instance that has only a private IP address.

Connect from non-RFC 1918 IP addresses

RFC 1918 specifies IP addresses that are assigned to be used internally (that is, within an organization) and will not route on the Internet. Specifically, these are:

  • 10.0.0.0/8
  • 172.16.0.0/12
  • 192.168.0.0/16

Connections to a Cloud SQL instance using a private IP address are automatically authorized for RFC 1918 address ranges. This way, all private clients can access the database without going through the proxy.

To connect from a non-RFC 1918 IP address, you must set per-instance IP authorization to allow traffic from non-RFC 1918 IP address ranges.

For example, use a gcloud command like the following:

gcloud sql instances patch INSTANCE_NAME \
--authorized-networks=192.88.99.0/24,11.0.0.0/24

Cloud SQL doesn't learn non-RFC 1918 subnet routes from your VPC network by default. You need to update the network peering to Cloud SQL to export any non-RFC 1918 routes.

gcloud compute networks peerings update cloudsql-postgres-googleapis-com \
--network=VPC_NETWORK_NAME \
--export-subnet-routes-with-public-ip \
--project=PROJECT_ID

    Replace the following:

  • cloudsql-postgres-googleapis-com is a Private Service Connection name from your VPC network page.

    Select your network, then look for the Private Service Connection section.

  • VPC_NETWORK_NAME is the name of your VPC network.
  • PROJECT_ID is the ID of the project of the VPC network. If you're using Shared VPC, then use the host project ID.

To mitigate IP address exhaustion, you can use privately used public IP addresses.

Connect from privately used public IP addresses

If you want to configure your instance in a privately used public IP address range, then enable export-subnet-routes-with-public-ip on the network peering between your network and the Cloud SQL network.

gcloud compute networks peerings update cloudsql-postgres-googleapis-com \
--network=VPC_NETWORK_NAME \
--export-subnet-routes-with-public-ip \
--project=PROJECT_ID

    Replace the following:

  • cloudsql-postgres-googleapis-com is a Private Service Connection name from your VPC network page.

    Select your network, and then look for the Private Service Connection section.

  • VPC_NETWORK_NAME is the name of your VPC network.
  • PROJECT_ID is the ID of the project of the VPC network. If you're using Shared VPC, then use the host project ID.

Connect to an instance configured with privately used public IP addresses

If your instance is configured in a privately used public IP address range and you want to connect to it, then enable import-subnet-routes-with-public-ip on the network peering between your network and the Cloud SQL network.

gcloud compute networks peerings update cloudsql-postgres-googleapis-com \
--network=VPC_NETWORK_NAME \
--import-subnet-routes-with-public-ip \
--project=PROJECT_ID

    Replace the following:

  • cloudsql-postgres-googleapis-com is a Private Service Connection name from your VPC network page.

    Select your network, then look for the Private Service Connection section.

  • VPC_NETWORK_NAME is the name of your VPC network.
  • PROJECT_ID is the ID of the project of the VPC network. Use the host project ID if you're using Shared VPC.

Connect by using a write endpoint

In addition to a private IP address, you can use a write endpoint in a SQL connection string. A write endpoint is a global domain name service (DNS) name that resolves to the IP address of the current primary instance automatically. By using a write endpoint, you can avoid having to make application connection changes when a regional outage occurs.

If a replica failover or switchover occurs, then the write endpoint can help manage private IP addresses of instances. When this happens, use the write endpoint to connect to the instance that acts as the primary instance.

How Cloud SQL creates a write endpoint

If you enable the Cloud DNS API for your Google Cloud project, and then you create a primary Cloud SQL Enterprise Plus edition instance, promote the replica for the instance, or upgrade the instance from Cloud SQL Enterprise edition, Cloud SQL generates a write endpoint automatically and assigns it to the instance.

For more information about obtaining the write endpoint for the instance, see View instance information.

Assign a write endpoint to an instance

If you don't enable the Cloud DNS API for your Google Cloud project, and then you create, promote, or upgrade your instance, Cloud SQL doesn't assign the write endpoint to the instance automatically.

To have Cloud SQL generate a write endpoint and assign it to the instance, complete the following steps:

  1. Enable the Cloud DNS API.

    Console

    1. In the Google Cloud console, go to the APIs page.

      Go to APIs

    2. Click the Cloud DNS API.
    3. Enable the API.

    gcloud

    1. Click the following button to open Cloud Shell, which provides command-line access to your Google Cloud resources directly from the browser.

      Open Cloud Shell

    2. To enable the API, run the following gcloud services enable command:

      gcloud services enable dns.googleapis.com

  2. Create a replica that's enabled for advanced disaster recovery. As a result, Cloud SQL generates the write endpoint and assigns it to the instance.

  3. To retrieve the write endpoint, use the gcloud sql instances describe command: 
    gcloud sql instances describe INSTANCE_NAME | grep psaWriteEndpoint

    Replace INSTANCE_NAME with the name of your Cloud SQL instance.

Troubleshoot

See troubleshooting for known connectivity issues, and also debugging connection issues for help with self-diagnostics.

What's next