Connect to an instance using Private Service Connect

MySQL | PostgreSQL | SQL Server

This page describes how to use Private Service Connect to connect to a Cloud SQL instance.

You can use Private Service Connect to connect to either a primary Cloud SQL instance or any of its read replicas from multiple Virtual Private Cloud (VPC) networks that belong to different groups, teams, projects, or organizations.

Before you begin

Support for using Private Service Connect with a Cloud SQL instance is available for gcloud CLI versions 416.0.0 and later.

User roles

The following table provides information about the roles required to use Private Service Connect with a Cloud SQL instance:

Role	Description
`compute.networkAdmin`	Grants full control over the VPC network that initiates a connection to a Cloud SQL instance. You can create and manage IP addresses, firewall rules, service connection policies, and Private Service Connect endpoints. If you use Private Service Connect to connect to a Cloud SQL instance from multiple VPC networks, then each network has its own administrator.
`dns.admin`	Grants full control over Cloud DNS resources, including DNS zones and records.
`cloudsql.admin`	Provides full control of a Cloud SQL instance and controls the instance over its lifecycle.
`cloudsql.instanceUser`	Provides access to the Cloud SQL instance. If you connect through the Cloud SQL Auth Proxy client, then you must have the Cloud SQL Client role. If you connect directly, then you don't need any Identity and Access Management (IAM) roles and permissions.

Create a Private Service Connect endpoint

Private Service Connect endpoints are internal IP addresses in a consumer VPC network, which clients in that network can access directly. Clients can use these endpoints to connect to Cloud SQL instances.

You can either have Cloud SQL create a Private Service Connect endpoint automatically in your VPC, or you can create the endpoint manually.

Create the endpoint automatically

To have Cloud SQL create the Private Service Connect endpoint automatically, do the following:

Create a service connection policy in your VPC network. With this policy, you can provision Private Service Connect endpoints automatically.
Create a Cloud SQL instance with Private Service Connect enabled for the instance, and configure the instance to create Private Service Connect endpoints automatically.
Retrieve the endpoint for the instance. This lets you use the endpoint to connect to the instance.

Create a service connection policy

A service connection policy lets you authorize a specified service class to create a Private Service Connect endpoint in your consumer VPC network. You can use the service connection policy to let Cloud SQL create Private Service Connect endpoints automatically.

You can create a service connection policy by using the Google Cloud console, gcloud CLI, or the API.

Console

In the Google Cloud console, go to the Private Service Connect page.

Go to Private Service Connect
Click the Connection Policies tab.
Click Create connection policy.
Enter a Name for the connection policy.
Specify the service class by doing the following:
1. For Source service class, select Google services.
2. From the Service class menu, select google-cloud-sql because Cloud SQL is the managed service for the connection policy.
In the Target endpoints scope section, select a Network and Region to which this policy applies.
In the Policy section, select one or more subnets from the Subnetworks menu. The subnets are used to allocate IP addresses for endpoints.
Optional: Specify a Connection limit for the policy. The limit determines how many endpoints can be created by using this connection policy. If you don't specify a connection limit, then there's no limit.
Click Create policy.

gcloud

To create a service connection policy, use the service-connection-policies create command.

gcloud network-connectivity service-connection-policies create POLICY_NAME \
    --network=NETWORK \
    --project=PROJECT_ID \
    --region=REGION \
    --service-class=SERVICE_CLASS \
    --subnets=https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETS \
    --psc-connection-limit=LIMIT \
    --description="DESCRIPTION" \
    --producer-instance-location=PRODUCER_INSTANCE_LOCATION \
    --allowed-google-producers-resource-hierarchy-level=RESOURCE_HIERARCHY_LEVEL

Replace the following:

POLICY_NAME: the name of your service connection policy.
NETWORK: the network to which this policy applies.
PROJECT_ID: the project ID or number of the VPC network's project. For Shared VPC networks, you must deploy service connection policies in the host project because these policies aren't supported in service projects.
REGION: the region to which this policy applies. The same policy must exist for every region in which you want to automate service connectivity.
SERVICE_CLASS: the producer-supplied resource identifier of the service class. For Cloud SQL, the service class is google-cloud-sql.
SUBNETS: one or more regular consumer subnets that are used to allocate IP addresses for Private Service Connect endpoints. These IP addresses are allocated automatically and returned to the subnet's pool as managed service instances are created and deleted. The subnets must be in the same region as the service connection policy. If multiple connection policies share the same region, then you can reuse the same subnetwork in these policies. You can enter multiple subnets in a comma-separated list.
LIMIT: the maximum number of endpoints that you can create by using this policy. If you don't specify a limit, then there's no limit.
DESCRIPTION: an optional description of the service connection policy.
PRODUCER_INSTANCE_LOCATION: use this optional flag to specify whether to authorize a custom hierarchy of the locations for a Cloud SQL instance. You can set the value of PRODUCER_INSTANCE_LOCATION to only one of the following:
- custom-resource-hierarchy-levels: the instance must be located in one of the projects, folders, or organizations that you provide as a value for the allowed-google-producers-resource-hierarchy-level parameter.
- none: the instance is in the same project as the service connection policy.
RESOURCE_HIERARCHY_LEVEL: a list of projects, folders, or organizations where the instance is located. This list is in the form of projects/PROJECT_ID, folders/FOLDER_ID, or organizations/ORGANIZATION_ID.

For example, the following command creates a service connection policy for the
google-cloud-sql service class that allocates IP addresses from the managed-services subnet. A maximum of 10 Private Service Connect endpoints can be created by using this policy. The endpoints must be created in projects that are in the same organization as the managed service instance. The Cloud SQL instance is located in the myproject project.

gcloud network-connectivity service-connection-policies create cloud-sql-policy \
    --network=default \
    --project=my-project \
    --region=us-central1 \
    --service-class=google-cloud-sql \
    --subnets=managed-service-subnet \
    --psc-connection-limit=10 \
    --producer-instance-location=custom-resource-hierarchy-levels \
    --allowed-google-producers-resource-hierarchy-level=projects/myproject

REST

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

PROJECT_ID: the ID of your project.
REGION: the region of your service connection policy.
POLICY_NAME: the name of your service connection policy.
DESCRIPTION: an optional description of your service connection policy.
NETWORK: the network of your service connection policy.
LIMIT: the maximum number of endpoints that you can create by using this policy. If you don't specify a limit, then there's no limit.
SUBNETS: one or more regular consumer subnets that are used to allocate IP addresses for Private Service Connect endpoints. These IP addresses are allocated automatically and returned to the subnet's pool as managed service instances are created and deleted. The subnets must be in the same region as the service connection policy. If multiple connection policies share the same region, then you can reuse the same subnetwork in these policies. You can enter multiple subnets in a comma-separated list.
SERVICE_CLASS: the producer-supplied resource identifier of the service class.

HTTP method and URL:

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies?serviceConnectionPolicyId=POLICY_NAME

Request JSON body:

{
  "description": "DESCRIPTION",
  "network": "projects/PROJECT_ID/global/networks/NETWORK",
  "pscConfig": {
    "limit": "LIMIT",
    "subnetworks": [
      "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET"
    ]
  },
  "serviceClass": "SERVICE_CLASS"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies?serviceConnectionPolicyId=POLICY_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies?serviceConnectionPolicyId=POLICY_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.networkconnectivity.v1.OperationMetadata",
    "createTime": "2023-08-15T16:59:29.236110917Z",
    "target": "projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Create a Cloud SQL instance

You can create an instance with Private Service Connect enabled for the instance and configure the instance to create endpoints automatically by using gcloud CLI or the API.

gcloud

To create an instance with Private Service Connect enabled for the instance, use the gcloud sql instances create command:

gcloud sql instances create INSTANCE_NAME \
--project=PROJECT_ID \
--region=REGION_NAME \
--enable-private-service-connect \
--allowed-psc-projects=ALLOWED_PROJECTS \
--availability-type=AVAILABILITY_TYPE \
--no-assign-ip \
--tier=MACHINE_TYPE \
--database-version=DATABASE_VERSION \
--psc-auto-connections=network=CONSUMER_NETWORK,project=CONSUMER_PROJECT \
--enable-bin-log

Make the following replacements:

INSTANCE_NAME: the name of the instance.
PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance.
REGION_NAME: the region name for the instance.
ALLOWED_PROJECTS: a comma-separated list of allowed project IDs or numbers from where Private Service Connect endpoints can connect to Cloud SQL instances.
If a project isn't contained in this list, then you can't create Private Service Connect endpoints in the project to connect to the instance.
AVAILABILITY_TYPE: enables high availability for the instance. For this parameter, specify one of the following values:
- REGIONAL: enables high availability and is recommended for production instances. The instance fails over to another zone within your selected region.
- ZONAL: provides no failover capability. This is the default value.
For more information about setting and removing high availability for instances, see Configure an existing instance for high availability and Deactivate high availability for an instance.
MACHINE_TYPE: the machine type for the instance.
DATABASE_VERSION: the database version for the instance (for example, MYSQL_8_0).
CONSUMER_NETWORK: the path to the VPC network from where Private Service Connect endpoints need to be created. For example:
projects/my-host-project/global/networks/default.
CONSUMER_PROJECT: the project where the Private Service Connect endpoint is created. If you're using a Shared VPC network, then this can be either the host project or the service project.

Any projects that you specify in the auto-connection parameters are added to your allowed projects automatically. Optionally, for any projects where you want to create Private Service Connect endpoints manually, you can add these projects to your list of allowed projects.

REST

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

PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance.
INSTANCE_NAME: the name of the instance.
REGION_NAME: the region name for the instance.
AVAILABILITY_TYPE: enables high availability for the instance. For this parameter, specify one of the following values:
- REGIONAL: enables high availability and is recommended for production instances. The instance fails over to another zone within your selected region.
- ZONAL: provides no failover capability. This is the default value.
For more information about setting and removing high availability for instances, see Configure an existing instance for high availability and Deactivate high availability for an instance.
ALLOWED_PROJECTS: a comma-separated list of allowed project IDs or numbers from where Private Service Connect endpoints can connect to Cloud SQL instances.
If a project isn't contained in this list, then you can't create Private Service Connect endpoints in the project to connect to the instance.
MACHINE_TYPE: the machine type for the instance.
CONSUMER_NETWORK: the VPC network where you want to allow automatic creation of Private Service Connect endpoints.
PARENT_PROJECT: the project that contains the network CONSUMER_NETWORK. If you don't specify a different project in CONSUMER_PROJECT, endpoints are automatically created in PARENT_PROJECT
CONSUMER_PROJECT: Optional. Only specify this if CONSUMER_NETWORK is a Shared VPC network and you want to allow automatic creation of Private Service Connect endpoints in a service project.

Any projects that you specify in the auto-connection parameters are added to your allowed projects automatically. Optionally, for any projects where you want to create Private Service Connect endpoints manually, you can add these projects to your list of allowed projects.

HTTP method and URL:

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

Request JSON body:

{
  "name": "INSTANCE_NAME",
  "project": PROJECT_ID",
  "region": "REGION_NAME",
  "databaseVersion": "MYSQL_8_0",
  "kind": "sql#instance",
  "settings": {
    "availabilityType": "AVAILABILITY_TYPE",
    "backupConfiguration": {
      "binaryLogEnabled": true,
      "enabled": true,
      "kind": "sql#backupConfiguration",
      "startTime": "00:00"
    },
    "ipConfiguration": {
      "ipv4Enabled": false,
      "pscConfig": {
        "allowedConsumerProjects": [
          "ALLOWED_PROJECTS"
        ],
        "pscAutoConnections": [
          {
            "consumerProject":"CONSUMER_PROJECT",
            "consumerNetwork":"projects/PARENT_PROJECT/global/networks/CONSUMER_NETWORK"
          }
        ],
        "pscEnabled": true
      }
    },
    "kind": "sql#settings",
    "pricingPlan": "PER_USE",
    "replicationType": "SYNCHRONOUS",
    "tier": "MACHINE_TYPE"
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances"

PowerShell (Windows)

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "RUNNING",
  "user": "[email protected]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "startTime": "2023-06-14T18:48:35.499Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Retrieve the endpoint

By retrieving the internal IP address, which is the Private Service Connect endpoint for an instance, you can use this endpoint to connect to the instance.

gcloud

To view information about an instance, including the IP address that's the Private Service Connect endpoint for the instance, use the gcloud sql instances describe command:

gcloud sql instances describe INSTANCE_NAME \
--project=PROJECT_ID \
--format='json(settings.ipConfiguration.pscConfig.pscAutoConnections)'

Make the following replacements:

INSTANCE_NAME: the name of the Cloud SQL instance. If this instance has Private Service Connect enabled for it, then Private Service Connect endpoints in VPC networks can connect to it.
PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance.

In the response, note the value that appears next to the pscConfig:pscAutoConnections:ipAddress field. This value is the internal IP address that's also the Private Service Connect endpoint for the instance.

REST

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

PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance.
INSTANCE_NAME: the name of the Cloud SQL instance. If this instance has Private Service Connect enabled for it, then Private Service Connect endpoints in VPC networks can connect to it.

HTTP method and URL:

GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "kind": "sql#instance",
  "state": "RUNNABLE",
  "databaseVersion": "MYSQL_8_0",
  "settings": {
    "authorizedGaeApplications": [],
    "tier": "db-custom-2-7680",
    "kind": "sql#settings",
    "availabilityType": "REGIONAL",
    "pricingPlan": "PER_USE",
    "replicationType": "SYNCHRONOUS",
    "activationPolicy": "ALWAYS",
    "ipConfiguration": {
      "authorizedNetworks": [],
      "pscConfig": {
        "allowedConsumerProjects": [
          "ALLOWED_PROJECTS"
        ],
      "pscAutoConnections": {
        consumerNetwork:"projects/PARENT_PROJECT/global/networks/CONSUMER_NETWORK",
        consumerNetworkStatus:"CONSUMER_NETWORK_STATUS",
        consumerProject:"CONSUMER_PROJECT",
        ipAddress:"IP_ADDRESS",
        status:"STATUS"
        },
        "pscEnabled": true
      },
      "ipv4Enabled": false
    },
}

The following fields exist for instances that have Private Service Connect enabled for them:

allowedConsumerProjects: a list of the allowed projects for the instance. You can create Private Service Connect endpoints from any VPC networks in these projects to the service attachment of the instance.
pscAutoConnections: the allowed VPC network, the status of the service connection policy, and the status of the IP address that's the endpoint for the instance.
pscEnabled: whether an instance has Private Service Connect enabled for it.

To see how to construct the underlying REST API request for this task, see the instances:get page.

Create the endpoint manually

To create the Private Service Connect endpoint manually, do the following:

Create a Cloud SQL instance with Private Service Connect enabled for the instance.
Get the service attachment URI. You use this URI to create the Private Service Connect endpoint.
Reserve an internal IP address for the Private Service Connect endpoint and create an endpoint with that address.

Create a Cloud SQL instance

You can create an instance with Private Service Connect enabled for the instance by using gcloud CLI, Terraform, or the API.

gcloud

To create an instance with Private Service Connect enabled for the instance, use the gcloud sql instances create command:

gcloud sql instances create INSTANCE_NAME \
--project=PROJECT_ID \
--region=REGION_NAME \
--enable-private-service-connect \
--allowed-psc-projects=ALLOWED_PROJECTS \
--availability-type=AVAILABILITY_TYPE \
--no-assign-ip \
--tier=MACHINE_TYPE \
--database-version=DATABASE_VERSION \
--enable-bin-log

Make the following replacements:

INSTANCE_NAME: the name of the instance.
PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance.
REGION_NAME: the region name for the instance.
ALLOWED_PROJECTS: a comma-separated list of allowed project IDs or numbers from where Private Service Connect endpoints can connect to Cloud SQL instances.
If a project isn't contained in this list, then you can't create Private Service Connect endpoints in the project to connect to the instance.
AVAILABILITY_TYPE: enable high availability for the instance. For this parameter, specify one of the following values:
- REGIONAL: enables high availability and is recommended for production instances. The instance fails over to another zone within your selected region.
- ZONAL: provides no failover capability. This is the default value.
For more information about setting and removing high availability for instances, see Configure an existing instance for high availability and

Connect to an instance using Private Service Connect Stay organized with collections Save and categorize content based on your preferences.

Before you begin

User roles

Create a Private Service Connect endpoint

Create the endpoint automatically

Create a service connection policy

Console

gcloud

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Create a Cloud SQL instance

gcloud

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Retrieve the endpoint

gcloud

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Create the endpoint manually

Create a Cloud SQL instance

gcloud

Connect to an instance using Private Service Connect