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

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

  • Establishing private services access requires the compute.networkAdmin IAM role.

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

    After private services access is established for your network, you no longer need the compute.networkAdmin IAM role to configure an instance to use private IP.

Private services access

When you create a new 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.

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

Configuring private IP for a new instance

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

Console

  1. Go to the Cloud SQL Instances page in the Google Cloud Console.

    Go to the Cloud SQL Instances page

  2. Click CREATE INSTANCE
  3. In the Creation wizard, under Configuration Options, expand the Connectivity section.
  4. Select the Private IP checkbox.

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

  5. Select the VPC network you want to use:
  6. If you have configured private services access:

    1. Select the VPC network you want to use.
    2. Click Connect.
    3. A drop-down shows the IP address range you allocated.

    4. Click Create.
    5. Click Save.

    To let Cloud SQL allocate the range for you and create the private connection:

    1. Select the default VPC network.
    2. Click Allocate and connect.
    3. Click Save.

gcloud

If you have not previously done so, follow the instructions below to configure private services access for Cloud SQL. Create your Cloud SQL instance, using the --network parameter to specify the name of your chosen VPC network, and the --no-assign-ip flag to disable public IP.

Unless the VPC network is a Shared VPC network, the --network parameter value is in the format: https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/global/networks/[VPC_NETWORK_NAME]

If the VPC network is a Shared VPC network, the --network parameter value is in the format projects/HOST_PROJECT_ID/global/networks/VPC_NETWORK_NAME, where HOST_PROJECT_ID is the name of the Shared VPC host project and VPC_NETWORK_NAME is the name of the Shared VPC network.

gcloud --project=[PROJECT_ID] beta sql instances create [INSTANCE_ID]
       --network=[VPC_NETWORK_NAME]
       --no-assign-ip

Configuring 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. Go to the Cloud SQL Instances page in the Google Cloud Console.
    Go to the Cloud SQL Instances page
  2. Click the instance name to open its Overview page.
  3. Select the Connections tab.
  4. Select the Private IP checkbox.

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

  5. If you have configured private services access:
    1. Select the VPC Network you want to use
    2. A drop-down shows the IP address range you allocated.

    3. Click Connect.
    4. Click Save.
  6. To let Cloud SQL allocate an IP address for you.
    1. Select the 'default' VPC network.
    2. Click Allocate and connect.
    3. Click Save.

gcloud

If you have not previously done so, follow the instructions below to configure private services access for Cloud SQL. Update your Cloud SQL instance, using the --network parameter to specify the name of your chosen VPC network.

VPC_NETWORK_NAME is the name of your chosen VPC network, for example: my-vpc-network. The --network parameter value is in the format: https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/global/networks/[VPC_NETWORK_NAME]

gcloud --project=[PROJECT_ID] beta sql instances patch [INSTANCE_ID]
       --network=[VPC_NETWORK_NAME]
       --no-assign-ip

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

Connecting 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 Proxy running on a Compute Engine resource, that resource must be in the same VPC network as the Cloud SQL instance.

Connecting from an external source

You can connect from a client in an on-premises network if the on-premises network is connected to the VPC network to which your Cloud SQL instance is connected. To permit connections from an on-premises network, do the following:

  1. Ensure your VPC network is connected to your on-premises network using a Cloud VPN tunnel or a VLAN attachment for Dedicated Interconnect or Partner Interconnect.
  2. Identify the peering connections produced by the private services connection:
    • cloudsql-mysql-googleapis-com
    • cloudsql-postgres-googleapis-com
    • servicenetworking-googleapis-com
  3. Update all of the peering connections to enable Export custom routes.
  4. Identify the allocated range used by the private services connection.
  5. Create a Cloud Router custom route advertisement for the allocated range on the Cloud Routers managing BGP sessions for your Cloud VPN tunnels or Cloud Interconnect attachments (VLANs).

Connecting from non-RFC 1918 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.

Non-RFC 1918 address ranges (addresses not within the RFC 1918 address space) must be configured as authorized networks.

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

For example, use a gcloud command like the following:

gcloud sql instances patch INSTANCE_NAME --authorized-networks 172.16.12.0/28,172.16.1.0/24,172.16.10.0/24,172.16.2.0/24,172.16.11.0/24,192.88.99.0/24,11.0.0.0/24

Cloud SQL doesn't learn Non-RFC 1918 subnet routes from your VPC 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=NETWORK --export-subnet-routes-with-public-ip --project=PROJECT
  • 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.

  • NETWORK is the name of your VPC network.

Troubleshooting

Click the links in the table for details:

For this problem... The issue might be... Try this...
SSL error: invalid padding. Server certificate error. Create new server certificate and rotate.
You want to find out who is connected. N/A See these things to try.
Unauthorized to connect errors. There can be many root causes. See these things to try.
Network association failed. Service Networking API is not enabled in the project. Enable the Service Networking API in the project.
Remaining connection slots are reserved. The maximum number of connections has been reached. Increase the max_connections flag.
Set Service Networking service account as servicenetworking.serviceAgent role on consumer project. Networking permissions on the service account are missing or incorrect. Disable and re-enable the Service Networking API.
error x509: certificate is not valid for any names, but wanted to match project-name:db-name. Known issue: The Cloud SQL Proxy Dialer is not compatible with Go 1.15 at this time. Until fixed, see this discussion on GitHub, which includes a workaround.

Aborted connection

You see the error message Got an error reading communication packets , or Aborted connection xxx to db: DB_NAME.

The issue might be

  • Networking instability.
  • No response to TCP keep-alive commands (either the client or the server is not responsive, possibly overloaded).
  • The database engine connection lifetime was exceeded and the server ends the connection.

Things to try

Applications must tolerate network failures and follow best practices such as connection pooling and retrying. Most connection poolers catch these errors where possible. Otherwise the application must either retry or fail gracefully.

For connection retry, we recommend the following methods:

  1. Exponential backoff. Increase the time interval between each retry, exponentially.
  2. Add randomized backoff also.
Combining these methods helps reduce throttling.


SSL Error: Invalid padding

You see the error message SSL error: invalid padding when trying to connect to a PostgreSQL instance using SSL.

The issue might be

Something might be wrong with the server-ca certificate.

Things to try

Create a new server-ca certificate and rotate the server certs.


Want to find out who is connected

You want to find out who is connected and for how long.

The issue might be

N/A

Things to try

Log into the database and run this command: SELECT datname, usename, application_name as appname, client_addr, state, now() - backend_start as conn_age, now() - state_change as last_activity_age FROM pg_stat_activity WHERE backend_type = 'client backend' ORDER BY 6 DESC LIMIT 20</code>


Unauthorized to connect

You see the error message Unauthorized to connect.

The issue might be

There can be many causes, as authorization occurs at many levels.

  • At the database level, the database user must exist and its password must match.
  • At the project level, the user may lack the correct IAM permissions.
  • At the Cloud SQL level, the root cause can depend on how you connect to your instance. If you are connecting directly to an instance through the public IP, the connection's source IP must be in the authorized network of the instance.

    Private IP connectivity is allowed by default, except when you are connecting from a non-RFC 1918 address. Non-RFC 1918 client addresses must be configured as authorized networks.

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

    gcloud compute networks peerings update cloudsql-postgres-googleapis-com --network=NETWORK --export-subnet-routes-with-public-ip --project=PROJECT
    

    If you are connecting through the Cloud SQL Proxy, ensure that the IAM permissions are set up correctly.

  • At the network level, if the Cloud SQL instance is using public IP, the connection's source IP must be in an authorized network.

Things to try

  • Check the username and password.
  • Check the user's IAM roles and permissions.
  • If using public IP, make sure the source is in the authorized networks.

Network association failed

You see the error message Error: Network association failed due to the following error: set Service Networking service account as servicenetworking.serviceAgent role on consumer project.

The issue might be

The Service Networking API is not enabled in the project.

Things to try

Enable the Service Networking API in your project. If you see this error when you are trying to assign a private IP address to a Cloud SQL instance, and you are using a shared VPC, you also need to enable the Service Networking API for the host project.


Remaining connection slots are reserved

You see the error message FATAL: remaining connection slots are reserved for non-replication superuser connections.

The issue might be

The maximum number of connections has been reached.

Things to try

Edit the max_connections flag value.


Set Service Networking service account as servicenetworking.serviceAgent role on consumer project

You see the error message set Service Networking service account as servicenetworking.serviceAgent role on consumer project..

The issue might be

User or service account permissions are not correct. This can happen during automated setup scripts, such as a Terraform configuration script.

Things to try

To repair service permissions, disable the Service Networking API , wait five minutes and then re-enable it.

You can also try using these gcloud commands to assign the role to the project

gcloud beta services identity create --service=servicenetworking.googleapis.com --project=project-id
gcloud projects add-iam-policy-binding project-id --member="service-account-prefix@service-networking.iam.gserviceaccount.com" --role="roles/servicenetworking.serviceAgent"

Error x509: certificate is not valid for any names

You see the error message error x509: certificate is not valid for any names, but wanted to match project-name:db-name

The issue might be ...

Known issue: The Cloud SQL Proxy Dialer is not compatible with Go 1.15 at this time.

Things to try

Until the bug is fixed, see this discussion on GitHub, which includes a workaround.


What's next