Connect to an instance using Private Service Connect

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

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

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

To use Private Service Connect with a Cloud SQL instance, the following roles are required:

Create a Cloud SQL instance

A Cloud SQL Admin can create an instance with Private Service Connect enabled by using gcloud or the API.

gcloud

The following example shows how to use the gcloud sql instances create command to create an instance with Private Service Connect enabled.

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

Make the following replacements:

  • INSTANCE_NAME with the name of the instance.
  • PROJECT_ID with the ID of the Google Cloud project that contains the instance. You can also use the project number to specify the Google Cloud project.
  • REGION_NAME with the name of the region for the instance.

  • ALLOWED_PROJECTS with a CSV list of allowed project IDs. Any projects not contained in this list are removed from the list of allowed projects automatically. To ensure that existing projects remain allowed while adding new projects, make sure to include the existing projects as part of the list.

  • MACHINE_TYPE with the desired machine type for the instance.
  • DATABASE_VERSION with the version of the database for the instance (for example, MYSQL_8_0).

The following flags are required:

  • enable-private-service-connect: create an instance that allows connections from Private Service Connect endpoints to the instance.

  • allowed-psc-projects: provide a CSV list of allowed project IDs. Network Admins can create Private Service Connect endpoints from any VPC networks in these projects to the service attachment of the instance.

    The Cloud SQL Admin can set this flag only when they're creating or updating an instance with Private Service Connect enabled.

  • no-assign-ip this flag must be used because the instance must have a private IP address. Public IP connections aren't supported.

REST v1

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the instance.
  • INSTANCE_NAME: The name of the instance.
  • REGION_NAME: The name of the region for the instance.

  • ALLOWED_PROJECTS: A CSV list of allowed project IDs. Any projects not contained in this list are removed from the list of allowed projects automatically. To ensure that existing projects remain on the allowlist while adding new projects, make sure to include the existing projects as part of the list.

  • MACHINE_TYPE: The desired machine type for the instance.

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": "REGIONAL",
    "backupConfiguration": {
      "binaryLogEnabled": true,
      "enabled": true,
      "kind": "sql#backupConfiguration",
      "startTime": "00:00"
    },
    "ipConfiguration": {
      "ipv4Enabled": false,
      "pscConfig": {
        "allowedConsumerProjects": [
          "ALLOWED_PROJECTS"
        ],
        "pscEnabled": true
      }
    },
    "kind": "sql#settings",
    "pricingPlan": "PER_USE",
    "replicationType": "SYNCHRONOUS",
    "tier": "MACHINE_TYPE"
  }
}

To send your request, expand one of these options:

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": "user@example.com",
  "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"
}

The following flags are required:

  • allowedConsumerProjects: provide a CSV list of allowed project IDs. Network Admins can create Private Service Connect endpoints from any VPC networks in these projects to the service attachment of the instance.

    The Cloud SQL Admin can set this flag only when they're creating or updating an instance with Private Service Connect enabled.

  • pscEnabled: create an instance that allows connections from Private Service Connect endpoints to the instance.

REST v1beta4

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the instance.
  • INSTANCE_NAME: The name of the instance.
  • REGION_NAME: The name of the region for the instance.

  • ALLOWED_PROJECTS: A CSV list of allowed project IDs. Any projects not contained in this list are removed from the list of allowed projects automatically. To ensure that existing projects remain on the allowlist while adding new projects, make sure to include the existing projects as part of the list.

  • MACHINE_TYPE: The desired machine type for the instance.

HTTP method and URL: 

POST https://sqladmin.googleapis.com/sql/v1beta4/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": "REGIONAL",
    "backupConfiguration": {
      "binaryLogEnabled": true,
      "enabled": true,
      "kind": "sql#backupConfiguration",
      "startTime": "00:00"
    },
    "ipConfiguration": {
      "ipv4Enabled": false,
      "pscConfig": {
        "allowedConsumerProjects": [
          "ALLOWED_PROJECTS"
        ],
        "pscEnabled": true
      }
    },
    "kind": "sql#settings",
    "pricingPlan": "PER_USE",
    "replicationType": "SYNCHRONOUS",
    "tier": "MACHINE_TYPE"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "RUNNING",
  "user": "user@example.com",
  "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/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

The following flags are required:

  • allowedConsumerProjects: provide a CSV list of allowed project IDs. Network Admins can create Private Service Connect endpoints from any VPC networks in these projects to the service attachment of the instance.

    The Cloud SQL Admin can set this flag only when they're creating or updating an instance with Private Service Connect enabled.

  • pscEnabled: create an instance that allows connections from Private Service Connect endpoints to the instance.

Create a read replica of a Cloud SQL instance

A Cloud SQL Admin can create a read replica of an instance with Private Service Connect enabled by using gcloud or the API.

The read replica must be created in the same region as the primary instance. Also, the read replica can't replicate from another instance with a different connectivity type. For example, an instance with Private Service Connect enabled can replicate only from another Private Service Connect instance. It can't replicate from an instance that supports public IP connections or from an instance that's configured to work with private services access.

gcloud

The following example shows how to use the gcloud sql instances create command to create a read replica of an instance.

        gcloud sql instances create REPLICA_INSTANCE_NAME \
        --master-instance-name=PRIMARY_INSTANCE_NAME \
        --project=PROJECT_ID \
        --region=REGION_NAME \
        --enable-private-service-connect \
        --allowed-psc-projects=ALLOWED_PROJECTS \
        --availability-type=regional \
        --no-assign-ip

Make the following replacements:

  • REPLICA_INSTANCE_NAME with the name of the replica instance
  • PRIMARY_INSTANCE_NAME with the name of the primary instance
  • PROJECT_ID with the ID of the Google Cloud project that contains the replica instance. You can also use the project number to specify the Google Cloud project.
  • REGION_NAME with the name of the region for the replica instance

  • ALLOWED_PROJECTS with a CSV list of allowed project IDs. These projects override projects that are already configured to use Private Service Connect.

    Any projects not contained in this list are removed from the list of allowed projects automatically. To ensure that existing projects remain allowlisted while adding new projects, make sure to include the existing projects as part of the list.

Similar to creating a Cloud SQL instance with Private Service Connect enabled, when the read replica of this instance is created, the enable-private-service-connect, allowed-psc-projects, and no-assign-ip flags are required.

The allowed projects for the primary instance aren't copied over to the replica. You must use the allowed-psc-projects flag to provide the CSV list of allowed project IDs for the replica. You must also create a Private Service Connect endpoint for each replica. If you're using the Cloud SQL Auth proxy or Cloud SQL Language Connectors, then you must create a DNS zone and DNS record for the replicas.

REST v1

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the replica instance.
  • PRIMARY_INSTANCE_NAME: The name of the primary instance.
  • REPLICA_INSTANCE_NAME: The name of the replica instance.
  • REGION_NAME: The name of the region for the replica instance.
  • MACHINE_TYPE: The desired machine type for the instance.

  • ALLOWED_PROJECTS: A CSV list of allowed project IDs. These projects override projects that are already configured to use Private Service Connect.

    Any projects not contained in this list are removed from the list of allowed projects automatically. To ensure that existing projects remain on the allowlist while adding new projects, make sure to include the existing projects as part of the list.

HTTP method and URL: 

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

Request JSON body: 

{
  "masterInstanceName": "PRIMARY_INSTANCE_NAME",
  "project": "PROJECT_ID",
  "databaseVersion": "MYSQL_8_0",
  "name": "REPLICA_INSTANCE_NAME",
  "region": "REGION_NAME",
  "kind": "sql#instance",
  "settings":
  {
    "tier": "MACHINE_TYPE",
    "settingsVersion": 0,
    "ipConfiguration": {
      "ipv4Enabled": false,
      "pscConfig": {
        "allowedConsumerProjects": [ALLOWED_PROJECTS],  
        "pscEnabled": true
      }
    },
    "kind": "sql#settings",
    "pricingPlan": "PER_USE",
    "replicationType": "ASYNCHRONOUS",
    "tier": "MACHINE_TYPE"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "CREATE_REPLICA",
  "name": "OPERATION_ID",
  "targetId": "REPLICA_INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Similar to creating a Cloud SQL instance with Private Service Connect enabled, when the read replica of this instance is created, the allowedConsumerProjects and pscEnabledflags are required.

The allowed projects for the primary instance aren't copied over to the replica. You must use the allowedConsumerProjects flag to provide the CSV list of allowed project IDs for the replica. You must also create a Private Service Connect endpoint for each replica. If you're using the Cloud SQL Auth proxy or Cloud SQL Language Connectors, then you must create a DNS zone and DNS record for the replicas.

REST v1beta4

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the replica instance.
  • PRIMARY_INSTANCE_NAME: The name of the primary instance.
  • REPLICA_INSTANCE_NAME: The name of the replica instance.
  • REGION_NAME: The name of the region for the replica instance.
  • MACHINE_TYPE: The desired machine type for the instance.

  • ALLOWED_PROJECTS: A CSV list of allowed project IDs. These projects override projects that are already configured to use Private Service Connect.

    Any projects not contained in this list are removed from the list of allowed projects automatically. To ensure that existing projects remain on the allowlist while adding new projects, make sure to include the existing projects as part of the list.

HTTP method and URL: 

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

Request JSON body: 

{
  "masterInstanceName": "PRIMARY_INSTANCE_NAME",
  "project": "PROJECT_ID",
  "databaseVersion": "MYSQL_8_0",
  "name": "REPLICA_INSTANCE_NAME",
  "region": "REGION_NAME",
  "kind": "sql#instance",
  "settings":
  {
    "tier": "MACHINE_TYPE",
    "settingsVersion": 0,
    "ipConfiguration": {
      "ipv4Enabled": false,
      "pscConfig": {
        "allowedConsumerProjects": [ALLOWED_PROJECTS],  
        "pscEnabled": true
      }
    },
    "kind": "sql#settings",
    "pricingPlan": "PER_USE",
    "replicationType": "ASYNCHRONOUS",
    "tier": "MACHINE_TYPE"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "CREATE_REPLICA",
  "name": "OPERATION_ID",
  "targetId": "REPLICA_INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Similar to creating a Cloud SQL instance with Private Service Connect enabled, when the read replica of this instance is created, the allowedConsumerProjects and pscEnabledflags are required.

The allowed projects for the primary instance aren't copied over to the replica. You must use the allowedConsumerProjects flag to provide the CSV list of allowed project IDs for the replica. You must also create a Private Service Connect endpoint for each replica. If you're using the Cloud SQL Auth proxy or Cloud SQL Language Connectors, then you must create a DNS zone and DNS record for the replicas.

Clone a Cloud SQL instance

A Cloud SQL Admin can clone a Cloud SQL instance with Private Service Connect enabled by using gcloud or the API.

gcloud

The following example shows how to use the gcloud sql instances clone command to clone an instance.

        gcloud sql instances clone SOURCE_INSTANCE_NAME DESTINATION_INSTANCE_NAME \
        --project=PROJECT_ID

Make the following replacements:

  • SOURCE_INSTANCE_NAME with the name of the Cloud SQL instance that you want to clone
  • DESTINATION_INSTANCE_NAME with the name of the cloned instance
  • PROJECT_ID with the ID of the Google Cloud project that contains the source and destination instances

Any flags related to Private Service Connect, such as the
enable-private-service-connect, allowed-psc-projects, and no-assign-ip flags, can't be specified. The cloned instance inherits all Private Service Connect settings from the source instance.

The user or service account that's running the gcloud sql instances clone command must have the cloudsql.instances.clone permission. For more information about required permissions to run gcloud CLI commands, see Cloud SQL permissions.

REST v1

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the source and destination instances
  • SOURCE_INSTANCE_NAME: The name of the Cloud SQL instance that you want to clone
  • DESTINATION_INSTANCE_NAME: The name of the cloned instance

HTTP method and URL: 

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

Request JSON body: 

{
  "cloneContext":
  {
    "destinationInstanceName": "DESTINATION_INSTANCE_NAME"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

Any flags related to Private Service Connect, such as the
allowedConsumerProjects and pscEnabledflags, can't be specified. The cloned instance inherits all Private Service Connect settings from the source instance.

The user or service account that's using the instances.clone API method must have the cloudsql.instances.clone permission. For more information about required permissions to use API methods, see Cloud SQL permissions.

REST v1beta4

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the source and destination instances
  • SOURCE_INSTANCE_NAME: The name of the Cloud SQL instance that you want to clone
  • DESTINATION_INSTANCE_NAME: The name of the cloned instance

HTTP method and URL: 

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

Request JSON body: 

{
  "cloneContext":
  {
    "destinationInstanceName": "DESTINATION_INSTANCE_NAME"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

Any flags related to Private Service Connect, such as the
allowedConsumerProjects and pscEnabledflags, can't be specified. The cloned instance inherits all Private Service Connect settings from the source instance. You must also create a Private Service Connect endpoint, DNS zone, and DNS record for each cloned instance.

The user or service account that's using the instances.clone API method must have the cloudsql.instances.clone permission. For more information about required permissions to use API methods, see Cloud SQL permissions.

View summary information

A Cloud SQL Admin can view summary information about Cloud SQL instances with Private Service Connect enabled in the Google Cloud console, by using gcloud, or by using the API.

Console

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

    Go to Cloud SQL Instances

    The following information appears about Cloud SQL instances with Private Service Connect enabled:

    • Internal connection method: whether Private Service Connect or Private Services Access is used to connect to the instance
    • Private IP address: the IP addresses of the Private Service Connect endpoints in the VPC network that connect to the service attachment of the instance
    • DNS name: the DNS name of the instance

  2. To open the Overview page of an instance, click the instance name.

    In the Connect to this instance card, the following additional information appears about Cloud SQL instances with Private Service Connect enabled:

    • Private IP connectivity: the status is Enabled because the instance must have a private IP address
    • Allowed projects: these projects allow connections from Private Service Connect endpoints to the instance
    • Service attachment: the service attachment of the instance
    • Public IP connectivity: the status is Disabled because public IP connections aren't supported

  3. To see connectivity information about the instance, click the Connections tab.

  4. Click the Networking tab. The following information appears about the instance:

    • The Private IP checkbox is selected, but disabled. The instance must have a private IP address, and this setting can't be changed.
    • The allowed projects for the instance.
    • The Public IP checkbox is selected, but disabled.
    • The Authorized networks field is disabled because the instance uses Private Service Connect, which doesn't support this feature.

    5. For more information about the Connections tab, see About Cloud SQL connections.

gcloud

The following example shows how to use the gcloud sql instances describe command to view summary information about an instance with Private Service Connect enabled.

        gcloud sql instances describe INSTANCE_NAME \ 
        --project=PROJECT_ID

Make the following replacements:

  • INSTANCE_NAME with the name of the Cloud SQL instance to which Private Service Connect endpoints in VPC networks can connect
  • PROJECT_ID with the ID of the Google Cloud project that contains the instance

Here's an example of the output for running this command:

        gcloud sql instances describe myinstance \ 
        --project=12345

        ...
        dnsName: mydnsname
        ...
        pscServiceAttachmentLink: projects/myproject/regions/myregion/serviceAttachments/myserviceattachment
        ...
        settings:
          ...
          ipConfiguration:
          ipv4Enabled: false
          pscConfig:
            allowedConsumerProjects:
              - projects/23456
              - projects/34567
            pscEnabled: true

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

  • dnsName: the DNS name for the instance. We recommend that the Network Admin creates a DNS record with this name and points it to the IP address of the Private Service Connect endpoint. We also recommend that Cloud SQL Instance Users use this name to connect to the instance.
  • pscServiceAttachmentLink: the URI that points to the service attachment of the instance. The Network Admin uses this URI to create the Private Service Connect endpoint.
  • allowedConsumerProjects: a list of the allowed project IDs for the instance. Network Admins can create Private Service Connect endpoints from any VPC networks in these projects to the service attachment of the instance.
  • pscEnabled: whether an instance has Private Service Connect enabled.

REST v1

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the instance
  • INSTANCE_NAME: The name of the Cloud SQL instance to which Private Service Connect endpoints in VPC networks can connect

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:

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"
        ],
        "pscEnabled": true
      },
      "ipv4Enabled": false
    },
  ...
  "createTime": "2023-06-14T18:48:34.975Z",
  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE",
  "pscServiceAttachmentLink": "projects/PROJECT_ID/regions/REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_ID",
  "dnsName": "DNS_NAME"
}

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

  • allowedConsumerProjects: a list of the allowed project IDs for the instance. Network Admins can create Private Service Connect endpoints from any VPC networks in these projects to the service attachment of the instance.
  • pscEnabled: whether an instance has Private Service Connect enabled.
  • pscServiceAttachmentLink: the URI that points to the service attachment of the instance. The Network Admin uses this URI to create the Private Service Connect endpoint.
  • dnsName: the DNS name for the instance. We recommend that the Network Admin creates a DNS record with this name and points it to the IP address of the Private Service Connect endpoint. We also recommend that Cloud SQL Instance Users use this name to connect to the instance.

To see how the underlying REST API request is constructed for this task, see the APIs Explorer on the instances:get page.

REST v1beta4

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the instance
  • INSTANCE_NAME: The name of the Cloud SQL instance to which Private Service Connect endpoints in VPC networks can connect

HTTP method and URL: 

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

To send your request, expand one of these options:

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"
        ],
        "pscEnabled": true
      },
      "ipv4Enabled": false
    },
  ...
  "createTime": "2023-06-14T18:48:34.975Z",
  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE",
  "pscServiceAttachmentLink": "projects/PROJECT_ID/regions/REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_ID",
  "dnsName": "DNS_NAME"
}

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

  • allowedConsumerProjects: a list of the allowed project IDs for the instance. Network Admins can create Private Service Connect endpoints from any VPC networks in these projects to the service attachment of the instance.
  • pscEnabled: whether an instance has Private Service Connect enabled.
  • pscServiceAttachmentLink: the URI that points to the service attachment of the instance. The Network Admin uses this URI to create the Private Service Connect endpoint.
  • dnsName: the DNS name for the instance. We recommend that the Network Admin creates a DNS record with this name and points it to the IP address of the Private Service Connect endpoint. We also recommend that Cloud SQL Instance Users use this name to connect to the instance.
To see how the underlying REST API request is constructed for this task, see the APIs Explorer on the instances:get page.

Update a Cloud SQL instance

Aside from the items listed in the Limitations section, a Cloud SQL Admin can update an instance with Private Service Connect enabled by using gcloud or the API.

For example, the admin can update projects associated with instances for the following purposes:

  • To allow connections from Private Service Connect endpoints to the Cloud SQL instances.
  • To remove projects from the list of allowed projects. For any project that's removed, connections to any existing Private Service Connect endpoints will continue to work, but new endpoints won't be accepted.

gcloud

To update projects that are allowed to use Private Service Connect use the gcloud sql instances patch command.

        gcloud sql instances patch INSTANCE_NAME \ 
        --project=PROJECT_ID \
        --allowed-psc-projects=ALLOWED_PROJECTS

Make the following replacements:

  • INSTANCE_NAME with the name of the Cloud SQL instance to which Private Service Connect endpoints in VPC networks can connect.
  • PROJECT_ID with the ID of the Google Cloud project that contains the instance. You can also use the project number to specify the Google Cloud project.

  • ALLOWED_PROJECTS with a CSV list of allowed project IDs. These projects override projects that are already configured to use Private Service Connect.

    Any projects not contained in this list are removed from the list of allowed projects automatically. To ensure that existing projects remain allowlisted while adding new projects, make sure to include the existing projects as part of the list.

The following example allows two projects (98765 and 87654) to make connections from Private Service Connect endpoints to the myinstance Cloud SQL instance that's contained in the 12345 project.

        gcloud sql instances patch myinstance \ 
        --project=12345 \
        --allowed-psc-projects='98765','87654'

To remove projects from the list of allowed projects so that no projects can use Private Service Connect, use the gcloud sql instances patch command and the optional --clear-allowed-psc-projects flag.

        gcloud sql instances patch INSTANCE_NAME \ 
        --project=PROJECT_ID \
        --clear-allowed-psc-projects

This flag is useful to ensure that no projects are allowlisted inadvertently.

REST v1

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the instance to which Private Service Connect endpoints in VPC networks can connect.
  • INSTANCE_NAME: The name of the Cloud SQL instance.

  • ALLOWED_PROJECTS: A CSV list of allowed project IDs. These projects override projects that are already configured to use Private Service Connect.

    Any projects not contained in this list are removed from the list of allowed projects automatically. To ensure that existing projects remain on the allowlist while adding new projects, make sure to include the existing projects as part of the list.

To clear the list of allowed projects so that no projects can use Private Service Connect, use the optional clear-allowed-psc-projects flag. This flag is useful to ensure that no projects are allowlisted inadvertently.

HTTP method and URL: 

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

Request JSON body: 

{
  "kind": "sql#instance",
  "name": "INSTANCE_NAME",
  "project": "PROJECT_ID",
  "settings": {
    "ipConfiguration": {
      "pscConfig": {
        "allowedConsumerProjects": [ALLOWED_PROJECTS]
      }
    },
    "kind": "sql#settings"
  }
}

To send your request, expand one of these options:

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": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the instance to which Private Service Connect endpoints in VPC networks can connect.
  • INSTANCE_NAME: The name of the Cloud SQL instance.

  • ALLOWED_PROJECTS: A CSV list of allowed project IDs. These projects override projects that are already configured to use Private Service Connect.

    Any projects not contained in this list are removed from the list of allowed projects automatically. To ensure that existing projects remain on the allowlist while adding new projects, make sure to include the existing projects as part of the list.

To clear the list of allowed projects so that no projects can use Private Service Connect, use the optional clear-allowed-psc-projects flag. This flag is useful to ensure that no projects are allowlisted inadvertently.

HTTP method and URL: 

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

Request JSON body: 

{
  "kind": "sql#instance",
  "name": "INSTANCE_NAME",
  "project": "PROJECT_ID",
  "settings": {
    "ipConfiguration": {
      "pscConfig": {
        "allowedConsumerProjects": [ALLOWED_PROJECTS]
      }
    },
    "kind": "sql#settings"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Delete a Cloud SQL instance

A Cloud SQL Admin can delete a Cloud SQL instance with Private Service Connect enabled by using gcloud or the API.

gcloud

The following example shows how to use the gcloud sql instances delete command to delete an instance.

        gcloud sql instances delete INSTANCE_NAME \
        --project=PROJECT_ID

Make the following replacements:

  • INSTANCE_NAME with the name of the Cloud SQL instance that you want to delete
  • PROJECT_ID with the ID of the Google Cloud project that contains the instance

After the instance is deleted, the following actions occur:

  • The service attachment is removed automatically. However, the Private Service Connect endpoint that points to the service attachment isn't deleted automatically. By listing the forwarding rule that's associated with the endpoint, the Network Admin can see that the rule has a CLOSED status. After this admin receives this status, they can delete the endpoint.
  • Cloud SQL Instance Users see the connection to the endpoint time out.

REST v1

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the instance that you want to delete
  • INSTANCE_NAME: The name of the instance

HTTP method and URL: 

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

To send your request, expand one of these options:

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": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-15T00:10:22.078Z",
  "operationType": "DELETE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

After the instance is deleted, the following actions occur:

  • The service attachment is removed automatically. However, the Private Service Connect endpoint that points to the service attachment isn't deleted automatically. By listing the forwarding rule that's associated with the endpoint, the Network Admin can see that the rule has a CLOSED status. After this admin receives this status, they can delete the endpoint.
  • Cloud SQL Instance Users see the connection to the endpoint time out.

Note: It is recommended that you also delete the corresponding DNS zone and DNS record to avoid incurring additional costs.

REST v1beta4

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

  • PROJECT_ID: The ID of the Google Cloud project that contains the instance that you want to delete
  • INSTANCE_NAME: The name of the instance

HTTP method and URL: 

DELETE https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-15T00:10:22.078Z",
  "operationType": "DELETE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

After the instance is deleted, the following actions occur:

  • The service attachment is removed automatically. However, the Private Service Connect endpoint that points to the service attachment isn't deleted automatically. By listing the forwarding rule that's associated with the endpoint, the Network Admin can see that the rule has a CLOSED status. After this admin receives this status, they can delete the endpoint.
  • Cloud SQL Instance Users see the connection to the endpoint time out.

Get the service attachment

After a Cloud SQL Admin creates a Cloud SQL instance with Private Service Connect enabled, the admin can get the service attachment URI. The Network Admin needs this URI to create the Private Service Connect endpoint.

gcloud

The following example shows how to use the gcloud sql instances describe command to view summary information about an instance with Private Service Connect enabled.

        gcloud sql instances describe INSTANCE_NAME \ 
        --project=PROJECT_ID

Make the following replacements:

  • INSTANCE_NAME with the name of the Cloud SQL instance to which Private Service Connect endpoints in VPC networks can connect
  • PROJECT_ID with the ID of the Google Cloud project that contains the instance

Here's an example of the output for running this command:

        gcloud sql instances describe myinstance \ 
        --project=12345

        ...
        pscServiceAttachmentLink: projects/45678/regions/myregion/serviceAttachments/myserviceattachment

The output contains the pscServiceAttachmentLink field. This field displays the URI that points to the service attachment of the instance. The Network Admin uses this URI to create the Private Service Connect endpoint.

Create a Private Service Connect endpoint

A Network Admin can allocate an IP address from their subnets and create a Private Service Connect endpoint with that address.

To create a an endpoint to a Cloud SQL instance, the Network Admin needs the service attachment URI and the projects that are allowlisted for the instance.

gcloud

  1. Use the gcloud compute addresses create command to reserve a private IP address for the Private Service Connect endpoint.

            gcloud compute addresses create ADDRESS_NAME \ 
        --project=PROJECT_ID \
        --region=REGION_NAME \
        --subnet=SUBNET_NAME \
        --addresses=PRIVATE_IP_ADDRESS

    Make the following replacements:

    • ADDRESS_NAME with the name of the private IP address.
    • PROJECT_ID with the ID of the Google Cloud project for the endpoint.
    • REGION_NAME with the name of the region for the endpoint.
    • SUBNET_NAME with the name of the subnet for the IP address.
    • PRIVATE_IP_ADDRESS with the IP address to reserve. This IP address must be within the subnet's primary IP range.

    The IP address doesn't have to be an RFC 1918 address. A subnet with non-RFC 1918 ranges can be specified.

  2. Use the gcloud compute addresses list command to verify that the IP address is reserved.

            gcloud compute addresses list ADDRESS_NAME \ 
        --project=PROJECT_ID
  3. Verify that a RESERVED status appears for the IP address.

  4. Use the gcloud compute forwarding-rules create command to create the Private Service Connect endpoint and point it to the Cloud SQL service attachment.

            gcloud compute forwarding-rules create ENDPOINT_NAME \ 
        --address=ADDRESS_NAME \
        --project=PROJECT_ID \
        --region=REGION_NAME \
        --network=NETWORK_NAME \
        --target-service-attachment=SERVICE_ATTACHMENT_URI

    Make the following replacements:

    • ENDPOINT_NAME with the name of the endpoint
    • NETWORK_NAME with the name of the VPC network for the endpoint
    • SERVICE_ATTACHMENT_URI with the URI of the service attachment

  5. Use the gcloud compute forwarding-rules describe command to verify that the endpoint is accepted by service attachment.

            gcloud compute forwarding-rules describe ENDPOINT_NAME \ 
        --project=PROJECT_ID \
        --region=REGION_NAME
  6. Verify that an ACCEPTED status appears for the pscConnectionStatus field. This status signifies that the endpoint can connect to the service attachment.

List Private Service Connect endpoints

A Network Admin can list all Private Service Connect endpoints and their statuses.

gcloud

Use the gcloud compute forwarding-rules list command to list all endpoints and their statuses.

        gcloud compute forwarding-rules list PROJECT_ID \
        --region=REGION_NAME \
        --filter=pscConnectionStatus=STATUS_NAME

Make the following replacements:

  • PROJECT_ID with the ID of the Google Cloud project that contains the endpoint.
  • REGION_NAME with the name of the region for the endpoint.
  • STATUS_NAME with the name of the status for the endpoint. An endpoint can have an ACCEPTED, REJECTED, or CLOSED status, signifying that the service attachment accepts, rejects, or closes the connection from the endpoint.

Delete a Private Service Connect endpoint

A Network Admin can delete a Private Service Connect endpoint and the IP address that's reserved for it.

gcloud

  1. Use the gcloud compute forwarding-rules delete command to delete an endpoint.

            gcloud compute forwarding-rules delete ENDPOINT_NAME \ 
        --project=PROJECT_ID \
        --region=REGION_NAME

    Make the following replacements:

    • ENDPOINT_NAME with the name of the endpoint
    • PROJECT_ID with the ID of the Google Cloud project that contains the endpoint
    • REGION_NAME with the name of the region for the endpoint

  2. Use the gcloud compute addresses delete command to release the IP address reserved for the endpoint.

            gcloud compute addresses delete ADDRESS_NAME \ 
        --project=PROJECT_ID \
        --region=REGION_NAME

    Replace ADDRESS_NAME with the name of the IP address.

Connect to a Cloud SQL instance

You can connect to a Cloud SQL instance with Private Service Connect enabled by using a private IP address, DNS record, the Cloud SQL Auth proxy, or other Google Cloud applications.

Configure a DNS managed zone and a DNS record

Cloud SQL doesn't create DNS records automatically. Instead, a suggested DNS name is provided from the instance lookup API response. We strongly recommend that you create the DNS record in a private DNS zone in the corresponding VPC network. This provides a consistent way of connecting from different networks using the Cloud SQL Auth proxy.

gcloud

  1. As a Cloud SQL Admin, use the gcloud sql instances describe command to view summary information about a Cloud SQL instance, including the DNS name of the instance.

            gcloud sql instances describe INSTANCE_NAME \ 
        --project=PROJECT_ID

    Make the following replacements:

    • INSTANCE_NAME with the name of the Cloud SQL instance
    • PROJECT_ID with the ID of the Google Cloud project that contains the instance
  2. Verify that the DNS name appears. This name has the following pattern: INSTANCE_UID.PROJECT_DNS_LABEL.REGION_NAME.sql.goog.. An example of a DNS name is 1a23b4cd5e67.1a2b345c6d27.us-central1.sql.goog..
    Note: DNS names always end with a period (.).

  3. As a DNS Administrator, use the gcloud dns managed-zones create command to create a private DNS zone. This zone is associated with the VPC network that's used to connect to the Cloud SQL instance through the Private Service Connect endpoint.

            gcloud dns managed-zones create ZONE_NAME \
        --project=PROJECT_ID \
        --description=DESCRIPTION \ 
        --dns-name=DNS_NAME \
        --networks=NETWORK_NAME \
        --visibility=private

    Make the following replacements:

    • ZONE_NAME with the name of the DNS zone
    • PROJECT_ID with the ID of the Google Cloud project that contains the zone
    • DESCRIPTION with a description of the zone (for example, a DNS zone for the Cloud SQL instance)
    • DNS_NAME with the DNS name for the zone, such as REGION_NAME.sql.goog. (where REGION_NAME is the name of the region for the zone).
      Note: DNS names always end with a period (.).
    • NETWORK_NAME with the name of the VPC network

  4. After the Private Service Connect endpoint is created, use the
    gcloud dns record-sets create command to create a DNS record in the zone.

            gcloud dns record-sets create DNS_NAME \
        --project=PROJECT_ID \
        --type=RRSET_TYPE \ 
        --rrdatas=RR_DATA \
        --zone=ZONE_NAME

    Make the following replacements:

    • DNS_NAME with the DNS name that you retrieved earlier in this procedure.
    • RRSET_TYPE with the resource record type of the DNS record set (for example, A).
    • RR_DATA with the IP address that allocated for the with the IP address that allocated for the Private Service Connect endpoint endpoint (for example, 198.51.100.5). You can also enter multiple values such as rrdata1 rrdata2 rrdata3 (for example, 10.1.2.3 10.2.3.4 10.3.4.5).

Connect directly using a DNS record

Before connecting to a Cloud SQL instance using a DNS record, the following actions must be completed:

  1. A Network Admin must create a Private Service Connect endpoint.
  2. The service attachment of the instance must accept the endpoint. The Network Admin can check the status of the endpoint to verify that the status is ACCEPTED.
  3. A DNS Administrator must configure a DNS managed zone and a DNS record.

After these conditions are met, the DNS name can be used to access the instance. This instance can be accessed from any VPC network in which the endpoint is created.

gcloud

  1. As a Network Admin, use the gcloud compute addresses describe command to retrieve the DNs record of the Private Service Connect endpoint.

            gcloud compute addresses describe DNS_RECORD \ 
        --project=PROJECT_ID \
        --region=REGION_NAME

    Make the following replacements:

    • DNS_RECORD with the DNS record for the endpoint
    • PROJECT_ID with the ID of the Google Cloud project that contains the endpoint
    • REGION_NAME with the name of the region for the endpoint

  2. As a Cloud SQL instance User, use the DNS record to connect to the Cloud SQL instance.

            mysql --host=DNS_RECORD --user=USERNAME -p

    Make the following replacements:

    • DNS_RECORD with the endpoint's DNS record
    • USERNAME with the name of the user that's connecting to the instance

Connect directly through a private IP address

Before connecting to a Cloud SQL instance with Private Service Connect enabled, the following actions must be completed:

  1. A Network Admin must create a Private Service Connect endpoint.
  2. The service attachment of the instance must accept the endpoint. The Network Admin can check the status of the endpoint to verify that the status is ACCEPTED.

After these conditions are met, the endpoint's IP address can be used to access the instance. This instance can be accessed from any VPC network in which the endpoint is created.

gcloud

  1. As a Network Admin, use the gcloud compute addresses describe command to retrieve the IP address of the Private Service Connect endpoint.

            gcloud compute addresses describe ADDRESS_NAME \ 
        --project=PROJECT_ID \
        --region=REGION_NAME

    Make the following replacements:

    • ADDRESS_NAME with the name of the endpoint's IP address
    • PROJECT_ID with the ID of the Google Cloud project that contains the endpoint
    • REGION_NAME with the name of the region for the endpoint

  2. As a Cloud SQL Instance User, use the private IP address to connect to the Cloud SQL instance.

            mysql --host=IP_ADDRESS --user=USERNAME -p

    Make the following replacements:

    • IP_ADDRESS with the endpoint's IP address
    • USERNAME with the name of the user that's connecting to the instance

Connect using the Cloud SQL Auth proxy

The Cloud SQL Auth proxy is a connector that provides secure access to an instance with Private Service Connect enabled without a need for authorized networks or for configuring SSL.

To allow Cloud SQL Auth proxy client connections, a DNS Administrator must set up a DNS record which matches the recommended DNS name that's provided for the instance. The DNS record is a mapping between a DNS resource and a domain name. The Cloud SQL Auth proxy supports connections to instances with Private Service Connect enabled. The binary that a Cloud SQL Admin downloads to install the Cloud SQL Auth proxy depends on the operating system, and whether it uses a 32-bit or 64-bit kernel. Most newer hardware uses a 64-bit kernel.

If you're unsure whether your machine is running a 32-bit or 64-bit kernel, then use the uname -a command for Linux or macOS. For Windows, see the Windows documentation.

Linux amd 64-bit

  1. Download the Cloud SQL proxy:

            curl -o cloud-sql-proxy 
          https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.7.0/cloud-sql-proxy.linux.amd64

  2. Make the Cloud SQL Auth proxy executable:

            chmod +x cloud-sql-proxy

Linux amd 32-bit

  1. Download the Cloud SQL proxy:

            curl -o cloud-sql-proxy
          https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.7.0/cloud-sql-proxy.linux.386
  2. If the curl command isn't found, then run sudo apt install curl and repeat the download command.

  3. Make the Cloud SQL Auth proxy executable:

            chmod +x cloud-sql-proxy

Linux arm 64-bit

  1. Download the Cloud SQL proxy:

            curl -o cloud-sql-proxy 
          https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.7.0/cloud-sql-proxy.linux.arm64

  2. Make the Cloud SQL Auth proxy executable:

            chmod +x cloud-sql-proxy

Linux arm 32-bit

  1. Download the Cloud SQL proxy:

            curl -o cloud-sql-proxy
          https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.7.0/cloud-sql-proxy.linux.arm
  2. If the curl command isn't found, then run sudo apt install curl and repeat the download command.

  3. Make the Cloud SQL Auth proxy executable:

            chmod +x cloud-sql-proxy

macOS 64-bit

  1. Download the Cloud SQL proxy:

            curl -o cloud-sql-proxy
          https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.7.0/cloud-sql-proxy.darwin.amd64

  2. Make the Cloud SQL Auth proxy executable:

            chmod +x cloud-sql-proxy

Mac M1 32-bit

  1. Download the Cloud SQL proxy:

            curl -o cloud-sql-proxy
          https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.7.0/cloud-sql-proxy.darwin.arm64

  2. Make the Cloud SQL Auth proxy executable:

            chmod +x cloud-sql-proxy

Windows 64-bit

  1. Download the Cloud SQL proxy:

            curl -o cloud-sql-proxy
          https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.7.0/cloud-sql-proxy.x64.exe

  2. Make the Cloud SQL Auth proxy executable:

            chmod +x cloud-sql-proxy

Windows 32-bit

  1. Download the Cloud SQL proxy:

            curl -o cloud-sql-proxy
          https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.7.0/cloud-sql-proxy.x86.exe

  2. Make the Cloud SQL Auth proxy executable:

            chmod +x cloud-sql-proxy

Start the Cloud SQL Auth proxy

The Cloud SQL Auth proxy supports connections to instances with Private Service Connect enabled. For more information, see Start the Cloud SQL Auth proxy.

gcloud

  1. Use the gcloud sql instances describe command to view the summary of a Cloud SQL instance, including the connection name of the instance. This connection name is in the format of PROJECT_ID:REGION_NAME:INSTANCE_NAME.

            gcloud sql instances describe INSTANCE_NAME \ 
        --project=PROJECT_ID \
        --format='value(connectionName)'

    Make the following replacements:

    • INSTANCE_NAME with the name of the Cloud SQL instance
    • PROJECT_ID with the ID of the Google Cloud project that contains the instance
  2. Copy the instance connection name.

  3. Launch the Cloud SQL Auth proxy:

            ./cloud-sql-proxy INSTANCE_CONNECTION_NAME --psc

    Replace INSTANCE_CONNECTION_NAME with the instance connection name that you copied in the previous step.

Connect using the Cloud SQL Language Connectors

The Cloud SQL Language Connectors are libraries that provide secure access to a Cloud SQL instance with Private Service Connect enabled without a need for authorized networks or for configuring SSL.

To allow connections with Cloud SQL Language Connectors, a DNS Administrator must set up a DNS record which matches the recommended DNS name that's provided for the instance. The DNS record is a mapping between a DNS resource and a domain name.

The Cloud SQL Language Connectors support Private Service Connect connections through the PSC IP type within their respective libraries.

Connect from App Engine Standard, Cloud Run, or Cloud Functions

An admin can use App Engine Standard, Cloud Run, or Cloud Functions to connect to Cloud SQL instances with Private Service Connect enabled.

In these supported serverless environments, both the Cloud SQL Language Connectors and direct TCP connections by using an IP address and port number are supported. For direct TCP connections, this is the IP address that the Network Admin reserves when they create the Private Service Connect endpoint. The IP address can be specified as the address for the database host.

Or, if the DNS Administrator creates a DNS record for the endpoint, then this record can be specified for the host. This is a requirement for using the Cloud SQL Language Connectors.

Connect from BigQuery

A BigQuery administrator can use the --enable-google-private-path parameter 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.

Test connectivity

A Network Admin can test connectivity to a Cloud SQL instance with Private Service Connect enabled. To test inbound connectivity to the instance, this admin can set the IP address of the Private Service Connect endpoint that's used to connect to the instance to be the destination IP address.

gcloud

Use the gcloud network-management connectivity-tests create command to create a connectivity test for a Cloud SQL instance with Private Service Connect enabled.

        gcloud network-management connectivity-tests create CONNECTIVITY_TEST_NAME \
        --source-network=SOURCE_NETWORK \
        --destination-ip-address=DESTINATION_IP_ADDRESS \
        --destination-network=DESTINATION_NETWORK \
        --destination-port=DESTINATION_PORT \
        --protocol=tcp

Make the following replacements:

  • CONNECTIVITY_TEST_NAME with the name of the connectivity test
  • SOURCE_NETWORK with the URI for the VPC network where the source IP address is located (for example, projects/myproject/zones/myzone/instances/myinstance)
  • DESTINATION_IP_ADDRESS with the IP address of the endpoint that's used to connect to the Cloud SQL instance
  • DESTINATION_NETWORK with the URI for the VPC network where the destination IP address is located (for example, projects/myproject/global/networks/mynetwork)
  • DESTINATION_PORT with the port number reserved for the instance. For Cloud SQL for MySQL instances, the port number is 3306.

Create a firewall rule

A Network Admin can restrict connectivity to Private Service Connect endpoints from service consumers in a VPC network. To do this, the admin adds a network egress firewall rule, which applies to the IP address of an endpoint. For the rule, the admin defines the source to be all VMs in the VPC network and specifies a tag or service account.

gcloud

Use the gcloud compute firewall-rules create command to create an egress firewall rule.

        gcloud compute firewall-rules create FIREWALL_RULE_NAME \
        --project=PROJECT_ID \
        --direction=EGRESS \
        --priority=PRIORITY \
        --network=NETWORK_NAME \
        --action=ALLOW/DENY \
        --rules=all \
        --destination-ranges=DESTINATION_IP_ADDRESS
        --target-tags=TAG_NAMES

Make the following replacements:

  • FIREWALL_RULE_NAME with the name of the firewall rule.
  • PROJECT_ID with the ID of the Google Cloud project that contains the rule.
  • PRIORITY with a numerical value that indicates the priority for the rule. The lower the number, the higher the priority.
  • NETWORK_NAME with the name of the VPC network to which the rule is attached.
  • DESTINATION_IP_ADDRESS with the IP address of the Private Service Connect endpoint.
  • TAG_NAMES with a CSV list of tag names. These names indicate the service consumers in the VPC network where the rule is applied.

Limitations

  • You can set up to 10 Private Service Connect endpoints that connect to the service attachment of a Cloud SQL instance with Private Service Connect enabled.
  • The following flags are invalidated or impacted:
    • --availability-type: You must set this flag to REGIONAL. Only high availability instances are supported.
    • --no-assign-ip: You must use this flag because Cloud SQL instances with Private Service Connect enabled aren't supported to use other connectivity types such as public IP.
    • --authorized-networks: You can't use this flag to add authorized networks.
    • --database-version: You must set this flag to a version of either a MySQL or PostgreSQL database. SQL Server databases aren't supported.
    • --network: You can't use this flag because it's associated with private services access.
    • --allocated-ip-range-name: You can't use this flag because allowed IP range names aren't supported.
  • You can't create an external replica of an instance with Private Service Connect enabled.
  • You can create a replica of an instance with Private Service Connect enabled in the same region as the primary instance only. Cross-region replicas aren't supported.
  • You can't enable or disable Private Service Connect on an existing instance.
  • You can't configure an instance that has Private Service Connect enabled to use private services access or public IP connections.
    • You can't enable public IP connections on an instance with Private Service Connect enabled.
    • You can't enable private services access or add authorized networks to the instance.
    • You can't change the connectivity type of the instance.
  • You can only create instances with Private Service Connect enabled in projects that started using Cloud SQL after Apr 1 2021.
  • You can't use the gcloud sql connect command, Cloud Shell, Cloud Build, Database Migration Service, Cloud SQL connectors, Unix sockets, or on-premises environments to connect to Cloud SQL instances with Private Service Connect enabled.
  • When testing connectivity to a Cloud SQL instance with Private Service Connect enabled, you can't set the following items:
    • The instance's private IP address or DNS name as the destination directly
    • The instance as the source
    • The IP address of the Private Service Connect endpoint as the source
    • The instance as the destination directly
    • You can't use the Connectivity Tests diagnostics tool to check connectivity between network endpoints.
  • IP-based allowlisting via Authorized Networks isn't supported.

Troubleshooting

This section contains information about issues associated with Cloud SQL instances with Private Service Connect enabled along with steps for troubleshooting the issues.

Issue Troubleshooting
The service attachment of the instance doesn't accept the Private Service Connect endpoint.

  1. Use the gcloud compute forwarding-rules command to check the endpoint's status.

            gcloud compute forwarding-rules ENDPOINT_NAME \
        --project=PROJECT_ID \
        --region=REGION_NAME \
        | grep pscConnectionStatus

    Make the following replacements:

    • ENDPOINT_NAME with the name of the endpoint
    • PROJECT_ID with the ID of the Google Cloud project that contains the endpoint
    • REGION_NAME with the name of the region for the endpoint

  2. Verify that the status of the endpoint is ACCEPTED. If the status is PENDING, then the Google Cloud project that contains the endpoint isn't allowlisted by the instance. You need to make sure that the network project in which the endpoint is created is allowlisted by the instance. For more information, see Update a Cloud SQL instance.

What's next