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 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, 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 Cloud SQL instance

You can create an instance and enable Private Service Connect for it by using gcloud CLI, Terraform, or the API.

gcloud

To create an instance and enable Private Service Connect for it, 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

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 list of allowed project IDs or numbers, separated by commas. If a project isn't contained in this list, then you can't use it to create an instance and enable Private Service Connect for it.

  • AVAILABILITY_TYPE: enable high availability for the instance. For this parameter, specify one of the following values:
    • REGIONAL: enable high availability and is recommended for production instances. The instance fails over to another zone within your selected region.
    • ZONAL: provide 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, POSTGRES_13).

Terraform

To create an instance with Private Service Connect enabled, use the google_sql_database_instanceTerraform resource.

resource "google_sql_database_instance" "default" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier              = "db-custom-2-7680"
    availability_type = "REGIONAL"
    backup_configuration {
      enabled = true
    }
    ip_configuration {
      psc_config {
        psc_enabled               = true
        allowed_consumer_projects = []
      }
      ipv4_enabled = false
    }
  }
  deletion_protection = false # Set to "true" to prevent destruction of the resource
}

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

Prepare Cloud Shell

  1. Launch Cloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module).

  1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly created main.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory. 
    terraform init

    Optionally, to use the latest Google provider version, include the -upgrade option: 

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations: 
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and entering yes at the prompt: 
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

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: enable high availability for the instance. For this parameter, specify one of the following values:
    • REGIONAL: enable high availability and is recommended for production instances. The instance fails over to another zone within your selected region.
    • ZONAL: provide 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 list of allowed project IDs or numbers, separated by commas. If a project isn't contained in this list, then you can't use it to create an instance and enable Private Service Connect for it.

  • MACHINE_TYPE: the 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": "POSTGRES_13",
  "kind": "sql#instance",
  "settings": {
    "availabilityType": "AVAILABILITY_TYPE",
    "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"
}

Get the service attachment

After creating a Cloud SQL instance with Private Service Connect enabled, get the service attachment URI and use it to create the Private Service Connect endpoint.

gcloud

To view summary information about an instance with Private Service Connect enabled, such as the pscServiceAttachmentLink field which displays the URI that points to the service attachment of the instance, use the gcloud sql instances describe command:

gcloud sql instances describe INSTANCE_NAME \
--project=PROJECT_ID

Make the following replacements:

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

The following example shows a sample output for this command:

gcloud sql instances describe myinstance \
--project=12345

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

Terraform

To get the service attachment URI, use the google_compute_addressTerraform resource.

resource "google_compute_address" "default" {
  name         = "psc-compute-address"
  region       = "us-central1"
  address_type = "INTERNAL"
  subnetwork   = "default"     # Replace value with the name of the subnet here.
  address      = "10.128.0.42" # Replace value with the IP address to reserve.
}

data "google_sql_database_instance" "default" {
  name = resource.google_sql_database_instance.default.name
}

resource "google_compute_forwarding_rule" "default" {
  name                  = "psc-forwarding-rule-${google_sql_database_instance.default.name}"
  region                = "us-central1"
  network               = "default"
  ip_address            = google_compute_address.default.self_link
  load_balancing_scheme = ""
  target                = data.google_sql_database_instance.default.psc_service_attachment_link
}

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

Prepare Cloud Shell

  1. Launch Cloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module).

  1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly created main.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory. 
    terraform init

    Optionally, to use the latest Google provider version, include the -upgrade option: 

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations: 
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and entering yes at the prompt: 
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

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

HTTP method and URL: 

GET https://sqladmin.googleapis.com/sql/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:

{
  ...
  pscServiceAttachmentLink: "projects/PROJECT_ID/regions/REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_NAME"
}

The pscServiceAttachmentLink field displays the URI that points to the service attachment of the instance.

Create a Private Service Connect endpoint

You can reserve an internal IP address for the Private Service Connect endpoint and create an endpoint with that address. To create the endpoint, you need the service attachment URI and the projects that are allowed for the instance.

gcloud

  1. To reserve an internal IP address for the Private Service Connect endpoint, use the
    gcloud compute addresses create command:

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

    Make the following replacements:

    • ADDRESS_NAME: the name of the internal IP address.
    • PROJECT_ID: the ID or project number of the Google Cloud project for the endpoint.
    • REGION_NAME: the region name for the endpoint.
    • SUBNET_NAME: the subnet name for the IP address.
    • INTERNAL_IP_ADDRESS: the IP address to reserve. This IP address must be within the subnet's primary IP range. The IP address can be an RFC 1918 address or a subnet with non-RFC ranges.

  2. To verify that the IP address is reserved, use the gcloud compute addresses list command:

    gcloud compute addresses list ADDRESS_NAME \
--project=PROJECT_ID

    In the response, verify that a RESERVED status appears for the IP address.

  3. To create the Private Service Connect endpoint and point it to the Cloud SQL service attachment, use the gcloud compute forwarding-rules create command:

    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 \
--allow-psc-global-access

    Make the following replacements:

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

  4. To verify that the service attachment accepts the endpoint, use the
    gcloud compute forwarding-rules describe command:

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

    In the response, verify that an ACCEPTED status appears for the pscConnectionStatus field. The endpoint can connect to the service attachment.

Terraform

To create a Private Service Connect endpoint, use the google_sql_database_instanceTerraform resource.

resource "google_compute_address" "default" {
  name         = "psc-compute-address"
  region       = "us-central1"
  address_type = "INTERNAL"
  subnetwork   = "default"     # Replace value with the name of the subnet here.
  address      = "10.128.0.42" # Replace value with the IP address to reserve.
}

data "google_sql_database_instance" "default" {
  name = resource.google_sql_database_instance.default.name
}

resource "google_compute_forwarding_rule" "default" {
  name                  = "psc-forwarding-rule-${google_sql_database_instance.default.name}"
  region                = "us-central1"
  network               = "default"
  ip_address            = google_compute_address.default.self_link
  load_balancing_scheme = ""
  target                = data.google_sql_database_instance.default.psc_service_attachment_link
}

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

Prepare Cloud Shell

  1. Launch Cloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module).

  1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly created main.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory. 
    terraform init

    Optionally, to use the latest Google provider version, include the -upgrade option: 

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations: 
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and entering yes at the prompt: 
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

REST

  1. Reserve an internal IP address for the Private Service Connect endpoint.

  2. Verify that the IP address is reserved.

    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 Private Service Connect endpoint
    • REGION_NAME: the name of the region
    • ADDRESS_NAME: the name of the IP address

    HTTP method and URL: 

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/addresses/ADDRESS_NAME

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "kind": "compute#address",
  "id": "ADDRESS_ID",
  "creationTimestamp": "2024-05-09T11:20:50.114-07:00",
  "name": "ADDRESS_NAME",
  "description": "This is the name of the internal IP address.",
  "address": "IP_ADDRESS",
  "status": "RESERVED",
  "region": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/addresses/ADDRESS_NAME",
  "networkTier": "PREMIUM",
  "labelFingerprint": "LABEL_FINGERPRINT_ID",
  "addressType": "EXTERNAL"
}

    In the response, verify that a RESERVED status appears for the IP address.

  3. Create the Private Service Connect endpoint and point it to the Cloud SQL service attachment.

  4. Verify that the service attachment accepts the endpoint.

    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 Private Service Connect endpoint
    • REGION_NAME: the name of the region
    • ENDPOINT_NAME: the name of the endpoint

    HTTP method and URL: 

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules/ENDPOINT_NAME

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "kind": "compute#forwardingRule",
  "id": "ENDPOINT_ID",
  "creationTimestamp": "2024-05-09T12:03:21.383-07:00",
  "name": "ENDPOINT_NAME",
  "region": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME",
  "IPAddress": "IP_ADDRESS",
  "target": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_NAME",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules/ENDPOINT_NAME",
  "network": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default",
  "serviceDirectoryRegistrations": [
    {
      "namespace": "goog-psc-default"
    }
  ],
  "networkTier": "PREMIUM",
  "labelFingerprint": "LABEL_FINGERPRINT_ID",
  "fingerprint": "FINGERPRINT_ID",
  "pscConnectionId": "CONNECTION_ID",
  "pscConnectionStatus": "ACCEPTED",
  "allowPscGlobalAccess": true
}

    In the response, verify that an ACCEPTED status appears for the pscConnectionStatus field. The endpoint can connect to the service attachment.

Connect to a Cloud SQL instance

You can connect to a Cloud SQL instance with Private Service Connect enabled by using an internal IP address, a DNS record, the Cloud SQL Auth Proxy, the Cloud SQL Language Connectors, or other Google Cloud applications.

Configure a DNS managed zone and a DNS record

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

gcloud

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

    gcloud sql instances describe INSTANCE_NAME \
--project=PROJECT_ID

    Make the following replacements:

    • INSTANCE_NAME: the name of the Cloud SQL instance
    • PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance

    In the response, verify that the DNS name appears. This name has the following pattern: INSTANCE_UID.PROJECT_DNS_LABEL.REGION_NAME.sql.goog.. For example: 1a23b4cd5e67.1a2b345c6d27.us-central1.sql.goog..

  2. To create a private DNS zone, use the gcloud dns managed-zones create command. 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: the name of the DNS zone
    • PROJECT_ID: the ID or project number of the Google Cloud project that contains the zone
    • DESCRIPTION: a description of the zone (for example, a DNS zone for the Cloud SQL instance)
    • DNS_NAME: the name of the DNS suffix for the zone, such as REGION_NAME.sql.goog. (where REGION_NAME is the region name for the zone)
    • NETWORK_NAME: the name of the VPC network

  3. After you create the Private Service Connect endpoint, to create a DNS record in the zone, use the gcloud dns record-sets create command:

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

    Make the following replacements:

    • DNS_RECORD: the name of the DNS record. This record is set to the DNS name that you retrieved from the Cloud SQL instance earlier in this procedure (for example, 1a23b4cd5e67.1a2b345c6d27.us-central1.sql.goog.).
    • RRSET_TYPE: the resource record type of the DNS record set (for example, A).
    • RR_DATA: the IP address allocated for the Private Service Connect 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).

REST

  1. Get the DNS name of a Cloud SQL instance.

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

    HTTP method and URL: 

    GET https://sqladmin.googleapis.com/sql/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:

    {
  ...
  "dnsName": "INSTANCE_ID.PROJECT_DNS_LABEL.REGION_NAME.sql.goog."
}

    The dnsName field displays the DNS name of the Cloud SQL instance. DNS names always end with a period (.).

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

    3. 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 DNS zone
    • ZONE_NAME: the name of the zone
    • DESCRIPTION: a description of the zone (for example, a DNS zone for the Cloud SQL instance)
    • DNS_NAME: the name of the DNS suffix for the zone, such as REGION_NAME.sql.goog. (where REGION_NAME is the region name for the zone)
    • NETWORK_NAME: the name of the VPC network

    HTTP method and URL: 

    POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones

    Request JSON body: 

    {
  "name": "ZONE_NAME",
  "description": "DESCRIPTION",
  "dnsName": "DNS_NAME",
  "visibility": "private",
  "privateVisibilityConfig": {
    "kind": "dns#managedZonePrivateVisibilityConfig",
    "networks": [
      {
        "kind": "dns#managedZonePrivateVisibilityConfigNetwork",
        "networkUrl": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/NETWORK_NAME"
      }
    ]
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "name": "ZONE_NAME",
  "dnsName": "DNS_NAME",
  "description": "DESCRIPTION",
  "id": "ID",
  "nameServers": [
    "ns-gcp-private.googledomains.com."
  ],
  "creationTime": "2024-05-10T17:05:34.607Z",
  "visibility": "private",
  "privateVisibilityConfig": {
    "networks": [
      {
        "networkUrl": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/NETWORK_NAME",
        "kind": "dns#managedZonePrivateVisibilityConfigNetwork"
      }
    ],
    "gkeClusters": [],
    "kind": "dns#managedZonePrivateVisibilityConfig"
  },
  "cloudLoggingConfig": {
    "kind": "dns#managedZoneCloudLoggingConfig"
  },
  "kind": "dns#managedZone"
}
  3. After you create the Private Service Connect endpoint, create a DNS record in the zone.

    4. 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 DNS zone.
    • ZONE_NAME: the name of the zone.
    • DNS_RECORD: the name of the DNS record. This record is set to the DNS name that you retrieved from the Cloud SQL instance earlier in this procedure (for example, 1a23b4cd5e67.1a2b345c6d27.us-central1.sql.goog.).
    • RRSET_TYPE: the type of the record set (for example, A).
    • TTL: the time to live (TTL) for the record set in the number of seconds (for example, 300).
    • RR_DATA: the IP address allocated for the Private Service Connect 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).

    HTTP method and URL: 

    POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/ZONE_NAME

    Request JSON body: 

    {
  "deletions": []
  "additions": [
    {
      "name": "DNS_RECORD",
      "type": "RRSET_TYPE",
      "ttl": TTL,
      "rrdatas": [
        "RR_DATA"
      ]
    }
  ]
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "additions": [
    {
      "name": "DNS_RECORD",
      "type": "RRSET_TYPE",
      "ttl": TTL,
      "rrdatas": [
        "RR_DATA"
      ],
      "signatureRrdatas": [],
      "kind": "dns#resourceRecordSet"
    }
  ],
  "deletions": [],
  "startTime": "2024-05-10T17:29:44.375Z",
  "id": "CHANGE_ID",
  "status": "pending",
  "kind": "dns#change"
}

Connect directly using a DNS record

Before connecting to a Cloud SQL instance using a DNS record, complete the following actions:

  1. Create a Private Service Connect endpoint.
  2. Confirm that the service attachment of the instance accepts the endpoint. To verify that the status of the endpoint is ACCEPTED, check the status.
  3. Configure a DNS managed zone and a DNS record.

After you meet these conditions, use the DNS record to connect to the instance from any VPC network where you created the endpoint.

psql "sslmode=disable dbname=DATABASE_NAME user=USERNAME host=DNS_RECORD"

Make the following replacements:

  • DATABASE_NAME: the name of the Cloud SQL for PostgreSQL database that's contained within the instance
  • USERNAME: the name of the user that's connecting to the instance
  • DNS_RECORD: the endpoint's DNS record

Connect directly through an internal IP address

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

  1. Create a Private Service Connect endpoint.
  2. Confirm that the service attachment of the instance accepts the endpoint. To verify that the status of the endpoint is ACCEPTED, check the status.

After you meet these conditions, use the endpoint's IP address to access the instance from any VPC network where you created the endpoint.

  1. Retrieve the internal IP address of the Private Service Connect endpoint.

    gcloud

    To retrieve the IP address, use the gcloud compute addresses describe command:

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

    Make the following replacements:

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

    In the response, verify that an IP address appears for the address field. This is the internal IP address.

    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 endpoint
    • REGION_NAME: the region name for the endpoint
    • ADDRESS_NAME: the name of the endpoint's IP address

    HTTP method and URL: 

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/addresses/ADDRESS_NAME

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "kind": "compute#address",
  "id": "ADDRESS_ID",
  "creationTimestamp": "2024-05-09T11:20:50.114-07:00",
  "name": "ADDRESS_NAME",
  "description": "This is the name of the internal IP address.",
  "address": "IP_ADDRESS",
  "status": "RESERVED",
  "region": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/addresses/ADDRESS_NAME",
  "networkTier": "PREMIUM",
  "labelFingerprint": "LABEL_FINGERPRINT_ID",
  "addressType": "EXTERNAL"
}

    The internal IP address is the value that's associated with the address field.

  2. To connect to the Cloud SQL instance, use the internal IP address.

    psql "sslmode=disable dbname=DATABASE_NAME user=USERNAME hostaddr=IP_ADDRESS"

    Make the following replacements:

    • DATABASE_NAME: the name of the Cloud SQL for PostgreSQL database that's contained within the instance
    • USERNAME: the name of the user that's connecting to the instance
    • IP_ADDRESS: the endpoint's IP address

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

If you're connecting through Private Service Connect, then Cloud SQL Auth Proxy version v2.5.0 or later is required.

Download and install the Cloud SQL Auth Proxy

To connect to instances with Private Service Connect enabled, you must download and install the binary for the Cloud SQL Auth Proxy. The binary that you download 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.

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.

  1. View summary information about a Cloud SQL instance, including the connection name of the instance.

    gcloud

    To view summary information about a Cloud SQL instance, use the
    gcloud sql instances describe command.

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

    Make the following replacements:

    • INSTANCE_NAME: the name of the Cloud SQL instance
    • PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance

    The connection name is in the format of PROJECT_ID:REGION_NAME:INSTANCE_NAME.

    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

    HTTP method and URL: 

    GET https://sqladmin.googleapis.com/sql/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:

    {
  ...
  "connectionName": "PROJECT_ID:REGION_NAME:INSTANCE_NAME"
}

    The connection name is in the format of PROJECT_ID:REGION_NAME:INSTANCE_NAME.

  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, 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 Run functions

To connect to Cloud SQL instances with Private Service Connect enabled, you can use App Engine Standard, Cloud Run, or Cloud Run functions.

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 you reserve when you create the Private Service Connect endpoint. You can specify the IP address as the address for the database host.

If you create a DNS record for the endpoint, then you can specify this record for the host.

Connect from BigQuery

To access data in Cloud SQL and make queries against this data over an internal IP connection, use the
--enable-google-private-path parameter . 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 an internal connection.

Test connectivity

To test inbound connectivity to a Cloud SQL instance with Private Service Connect enabled, set the IP address of the Private Service Connect endpoint to be the destination IP address.

gcloud

To create a connectivity test for a Cloud SQL instance with Private Service Connect enabled, use the gcloud network-management connectivity-tests create command:

gcloud network-management connectivity-tests create CONNECTIVITY_TEST_NAME \
--source-instance=SOURCE_INSTANCE \
--destination-cloud-sql-instance=DESTINATION_CLOUD_SQL_INSTANCE \
--destination-network=DESTINATION_NETWORK \
--destination-port=DESTINATION_PORT \
--protocol=tcp

Make the following replacements:

  • CONNECTIVITY_TEST_NAME: the name of the connectivity test.
  • SOURCE_INSTANCE: the URI for the Compute Engine instance where the source IP address is located (for example, projects/myproject/zones/myzone/instances/myinstance).
  • DESTINATION_CLOUD_SQL_INSTANCE: the URL for the Cloud SQL instance (for example, projects/myproject/instances/myinstance).
  • DESTINATION_NETWORK: the URI for the VPC network where the destination IP address is located (for example, projects/myproject/global/networks/mynetwork).
  • DESTINATION_PORT: the port number reserved for the instance. For Cloud SQL for PostgreSQL instances, the port number is 5432.

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.
  • CONNECTIVITY_TEST_NAME: the name of the connectivity test.
  • SOURCE_IP_ADDRESS: the IP address of the source Compute Engine instance.
  • SOURCE_INSTANCE: the URI for the Compute Engine instance where the source IP address is located (for example, projects/myproject/zones/myzone/instances/myinstance).
  • SOURCE_NETWORK: the URI for the VPC network where the source IP address is located (for example, projects/myproject/global/networks/mynetwork).
  • DESTINATION_IP_ADDRESS: the IP address of the destination Cloud SQL instance.
  • DESTINATION_PORT: the port number reserved for the instance. For Cloud SQL for PostgreSQL instances, the port number is 5432.
  • DESTINATION_NETWORK: the URI for the VPC network where the destination IP address is located (for example, projects/myproject/global/networks/mynetwork).

HTTP method and URL: 

POST https://networkmanagement.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/connectivityTests?testId=CONNECTIVITY_TEST_NAME

Request JSON body: 

{
  "source": {
    "ipAddress": "SOURCE_IP_ADDRESS",
    "instance": "SOURCE_INSTANCE",
    "network": "SOURCE_NETWORK"
  },
  "destination": {
    "ipAddress": "DESTINATION_IP_ADDRESS",
    "port": DESTINATION_PORT,
    "network": "DESTINATION_NETWORK",
    "projectId": "PROJECT_ID"
  },
  "protocol": "TCP"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/global/operations/operation-OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.networkmanagement.v1.OperationMetadata",
    "createTime": "2024-05-23T16:43:49.313981473Z",
    "target": "projects/PROJECT_ID/locations/global/connectivityTests/CONNECTIVITY_TEST_NAME",
    "verb": "create",
    "cancelRequested": false,
    "apiVersion": "v1"
  },
  "done": false
}

Limitations

  • You can set up to 20 Private Service Connect endpoints that connect to the service attachment of a Cloud SQL instance with Private Service Connect enabled.
  • You can't use Private Service Connect backends for instances that have Private Service Connect enabled.
  • The following flags are invalidated or impacted:
    • --no-assign-ip: use this flag because instances with Private Service Connect enabled aren't supported to use other connectivity types such as external IP connections
    • --authorized-networks: you can't use this flag to add authorized networks
    • --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't activate or deactivate 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 external IP connections.
    • You can't enable external 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't use the gcloud sql connect command, Cloud Shell, Cloud Build, or Datastream to connect to Cloud SQL instances with Private Service Connect enabled.
  • If you perform homogeneous migrations to Cloud SQL, then you can't use Database Migration Service 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 internal 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
  • IP-based allowlisting by using authorized networks isn't supported.
  • The pglogical, pl/proxy, dblink, and postgres_fdw extensions aren't supported.
  • Client IP-based control, logging, and metrics aren't supported for Query and System insights. However, VPN and Interconnect are supported.
  • If your network project contains instances that use the old Cloud SQL network architecture, then you can't create a Private Service Connect instance. Cloud SQL provides tools to help you upgrade your instances from the old network architecture to the new network architecture. For more information or to check the network architecture of the Cloud SQL instances in your project and perform any necessary upgrades, see Upgrade an instance to the new network architecture.

Troubleshoot

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. Check the endpoint's status.

    gcloud

    To check the status, use the
    gcloud compute forwarding-rules describe command.

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

    Make the following replacements:

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

    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 Private Service Connect endpoint
    • REGION_NAME: the name of the region
    • ENDPOINT_NAME: the name of the endpoint

    HTTP method and URL: 

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules/ENDPOINT_NAME

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "kind": "compute#forwardingRule",
  "id": "ENDPOINT_ID",
  "creationTimestamp": "2024-05-09T12:03:21.383-07:00",
  "name": "ENDPOINT_NAME",
  "region": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME",
  "IPAddress": "IP_ADDRESS",
  "target": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_NAME",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules/ENDPOINT_NAME",
  "network": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default",
  "serviceDirectoryRegistrations": [
    {
      "namespace": "goog-psc-default"
    }
  ],
  "networkTier": "PREMIUM",
  "labelFingerprint": "LABEL_FINGERPRINT_ID",
  "fingerprint": "FINGERPRINT_ID",
  "pscConnectionId": "CONNECTION_ID",
  "pscConnectionStatus": "ACCEPTED",
  "allowPscGlobalAccess": true
}
  2. Verify that the status of the endpoint is ACCEPTED. If the status is PENDING, then the instance isn't allowing the Google Cloud project that contains the endpoint. Make sure that the network project in which the endpoint is created is allowed. For more information, see Edit an instance with Private Service Connect enabled.

What's next