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.
- In order to manage a private services access connection, the user should
have the following 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.
If you are using a Shared VPC network, you also need to enable this API for the host project.
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. The 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
-
In the Google Cloud console, go to the Cloud SQL Instances page.
- Click Create instance.
- Expand Show configuration options.
- Expand Connections.
- 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, VPC networks from the host project are also shown.
- Select the VPC network you want to use.
- Click Set up connection.
- 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.
- Click Continue.
- Click Create connection.
- Verify that you see the message:
Private service connection for network VPN_NAME has been successfully created
. - Optionally, you can specify an allocated IP range for your instances to use for connections.
- Expand Show allocated IP range option.
- Select an IP range from the drop-down menu.
- Finish configuring your instance.
- Click Create instance.
If you see a message indicating that you need to set up a private service connection, do the following:
gcloud
Ensure your project is configured for private services access.
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.
The --network parameter value is in the format projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME
.
The PROJECT_ID
is the project ID of the VPC network.
If the VPC network is a Shared VPC, it should be
the id of the Shared VPC host project.
Optionally, specify the name of a private address range using the
--allocated-ip-range-name
parameter. If specified, this sets an
allocated range name, and a private address range is created for the
primary instance. For example, google-managed-services-default
. The
range name should comply with RFC-1035
and be within 1-63
characters.
(gcloud alpha sql instances create
).
If the VPC network is a Shared VPC, in the following gcloud
command, PROJECT_ID
should be
the ID of the Shared VPC service project.
gcloud beta sql instances create INSTANCE_ID \ --project=PROJECT_ID \ --network=projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME \ --no-assign-ip \ --allocated-ip-range-name=RANGE_NAME
Terraform
To configure private IP for a new instance, use the following Terraform resources:
google_compute_network
google_compute_global_address
google_service_networking_connection
google_sql_database_instance
Apply the changes
To apply your Terraform configuration in a Google Cloud project, complete the following steps:
- Launch Cloud Shell.
-
Set the Google Cloud project where you want to apply the Terraform configuration:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
-
Create a directory and open a new file in that directory. The filename must have the
.tf
extension, for examplemain.tf
:mkdir DIRECTORY && cd DIRECTORY && nano main.tf
- Copy the sample into
main.tf
. - Review and modify the sample parameters to apply to your environment.
- Save your changes by pressing
Ctrl-x
and theny
. -
Initialize Terraform:
terraform init
-
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.
-
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.
- 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:
- To disable deletion protection, in your Terraform configuration file set the
deletion_protection
argument tofalse
.deletion_protection = "false"
- Apply the updated Terraform configuration by running the following command and
entering
yes
at the prompt:terraform apply
-
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-name: The name of the VPC network you want to use for the instance
- allocated-ip-range: Optional. If specified, sets a range name for which an IP range
is allocated. The range name should comply with
RFC-1035
and be within 1-63 characters.
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-name", "allocatedIpRange": "allocated-ip-range" } } }
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-name: The name of the VPC network you want to use for the instance
- allocated-ip-range: Optional. If specified, sets a range name for which an IP range
is allocated. The range name should comply with
RFC-1035
and be within 1-63 characters.
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-name", "allocatedIpRange": "allocated-ip-range" } } }
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
-
In the Google Cloud console, go to the Cloud SQL Instances page.
- To open the Overview page of an instance, click the instance name.
- Select Connections from the SQL navigation menu.
- Select the Private IP checkbox.
A drop-down list shows the available networks in your project.
- Select the VPC network you want to use:
- Click Set up connection.
- 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.
- Click Continue.
- Click Create connection.
- Verify that you see the Private service connection for network VPC_NETWORK_NAME has been successfully created status.
- Click Save.
If you see Private service connection required:
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/PROJECT_ID/global/networks/VPC_NETWORK_NAME \ --no-assign-ip
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-name: The name of the VPC network you want to use for the instance
- allocated-ip-range: Optional. If specified, sets a range name for which an IP range
is allocated. The range name should comply with
RFC-1035
and be within 1-63 characters.
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": "vpc-name", "allocatedIpRange": "allocated-ip-range" } } }
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-name: The name of the VPC network you want to use for the instance
- allocated-ip-range: Optional. If specified, sets a range name for which an IP range
is allocated. The range name should comply with
RFC-1035
and be within 1-63 characters.
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": "vpc-name", "allocatedIpRange": "allocated-ip-range" } } }
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 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
You can connect from a client in an external network (on-premises network or VPC network) if the external network is connected to the VPC network to which your Cloud SQL instance is connected. To permit connections from an external network, do the following:
- 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.
- Ensure the 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 always used, even though the Cloud SQL peering is configured to import custom routes from your VPC network.
-
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
- Update all of the peering connections to enable Export custom routes.
- Identify the allocated range used by the private services connection.
- 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).
Connect from Cloud Shell
Cloud Shell doesn't currently support connecting to a Cloud SQL instance that has only a private IP address.
Connect 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=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_ID
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.
- PROJECT_ID is the ID of the project of the VPC network. Use the host project ID if you're using Shared VPC.
Troubleshoot
See troubleshooting for known connectivity issues, and also debugging connection issues for help with self-diagnostics.
What's next
- Learn more about private IP.
- Learn more about private services access.
- See how to use VPC Service Controls to add a service perimeter.
- Learn more about configuring private services access.
- Learn more about configuring private services access for Cloud SQL.
- Learn more about Cloud VPN.
- Learn more about VPC networks.
- Learn more about VPC peering.
- Learn more about Shared VPC.