Connect to an instance using Private Service Connect

gcloud

You can enable DNS Automation for instances that also have these parameters set:

• --enable-private-service-connect
• --allowed-psc-projects=...
• --psc-auto-connections=...

Use the gcloud CLI beta sql instances create command to enable the feature.

These are the parameters that you use to enable DNS automation and a Global Cluster Write Endpoint:

• --enable-psc-auto-dns
  Indicates whether Private Service Connect DNS automation is enabled for this instance. Defaults to disabled for new instances when Private Service Connect is enabled using --enable-private-service-connect.

  When DNS automation is enabled, Cloud SQL provisions a universal DNS record across all networks configured with Private Service Connect auto-connections.

• --enable-psc-write-endpoint-dns
  Indicates whether Private Service Connect write endpoint DNS automation is enabled for this instance. This feature is only supported for Enterprise Plus instances in which --enable-psc-auto-dns is also set, and it defaults to disabled when a new instance is created.

  With write endpoint DNS automation enabled, Cloud SQL provisions a Global Cluster Write Endpoint across all networks that are configured with Private Service Connect auto-connections. This universal global DNS record always points to the cluster's primary instance, which enables seamless application failover without requiring any client-side connection-string updates.

REST

The HTTP method and URL: would look like this:

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

The JSON request body would take a form like this:

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

gcloud

gcloud beta sql instances patch INSTANCE_NAME \
  --enable-psc-auto-dns \
  --enable-psc-write-endpoint-dns \

Use --enable-psc-auto-dns to enable the per instance DNS automation, and --no-enable-psc-auto-dns to disable it.

Use --enable-psc-write-endpoint-dns to enable write endpoint DNS automation, and --no-enable-psc-write-endpoint-dns to disable it.

REST

The HTTP method and URL: would look like this:

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

The JSON request body would take a form like this:

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

Replace DESIRED_STATE with true to enable the feature, or with false to disable it.

gcloud

The automated DNS names are only visible in the output of gcloud CLI CLI or the API to describe the instance.

To find the per-instance DNS name created using DNS automation, use the following gcloud CLI command:

      gcloud beta sql instances describe INSTANCE_NAME \
        --project=PROJECT_ID  \
        --flatten="dnsNames[]" \
        --format="csv[no-heading](dnsNames.dnsScope, dnsNames.recordManager, dnsNames.name)" \
        | grep "INSTANCE,CLOUD_SQL_AUTOMATION"
    

Replace INSTANCE_NAME with the name of the Cloud SQL instance for which you are looking for the DNS name.

gcloud

The automated DNS names are only visible in the output of gcloud CLI CLI or the API to describe the instance.

To find the global write endpoint DNS name created using DNS automation, use the following gcloud CLI command:

      gcloud beta sql instances describe INSTANCE_NAME \
        --project=INSTANCE_NAME  \
        --flatten="dnsNames[]" \
        --format="csv[no-heading](dnsNames.dnsScope, dnsNames.recordManager, dnsNames.name)" \
        | grep "CLUSTER,CLOUD_SQL_AUTOMATION"
    

Replace INSTANCE_NAME with the name of a Cloud SQL instance in your cluster.

gcloud

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

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

Make the following replacements:

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

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

REST

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

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

HTTP method and URL:

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

To send your request, expand one of these options:

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

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

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

You should receive a JSON response similar to the following:

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

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

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

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

gcloud

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

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

Make the following replacements:

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

• ALLOWED_PROJECTS: a comma-separated list of allowed project IDs or numbers from where Private Service Connect endpoints can connect to Cloud SQL instances.

  If a project isn't contained in this list, then you can't create Private Service Connect endpoints in the project to connect to the instance.

• AVAILABILITY_TYPE: enable high availability for the instance. For this parameter, specify one of the following values:
  • REGIONAL: enables high availability and is recommended for production instances. The instance fails over to another zone within your selected region.
  • ZONAL: provides no failover capability. This is the default value.

  For more information about setting and removing high availability for instances, see Configure an existing instance for high availability and Deactivate high availability for an instance.

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

Terraform

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

resource "google_sql_database_instance" "default" {
  name             = "mysql-instance"
  region           = "us-central1"
  database_version = "MYSQL_8_0"
  settings {
    tier              = "db-f1-micro"
    availability_type = "REGIONAL"
    backup_configuration {
      enabled            = true
      binary_log_enabled = true
    }
    ip_configuration {
      psc_config {
        psc_enabled               = true
        allowed_consumer_projects = [] # Add consumer project IDs here.
      }
      ipv4_enabled = false
    }
  }
}

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: enables high availability for the instance. For this parameter, specify one of the following values:
  • REGIONAL: enables high availability and is recommended for production instances. The instance fails over to another zone within your selected region.
  • ZONAL: provides no failover capability. This is the default value.

  For more information about setting and removing high availability for instances, see Configure an existing instance for high availability and Deactivate high availability for an instance.

• ALLOWED_PROJECTS: a comma-separated list of allowed project IDs or numbers from where Private Service Connect endpoints can connect to Cloud SQL instances.

  If a project isn't contained in this list, then you can't create Private Service Connect endpoints in the project to connect to the instance.

• MACHINE_TYPE: the machine type for the instance.

HTTP method and URL:

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

Request JSON body:

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

To send your request, expand one of these options:

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

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

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

You should receive a JSON response similar to the following:

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

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

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:

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

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

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

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.

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_URI \
   --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_URI: the subnet name for the IP address. The format is: projects/SUBNET_PROJECT_ID/regions/REGION_NAME/subnetworks/SUBNET_NAME. If the subnet is in a Shared VPC network, then we recommend that the SUBNET_PROJECT_ID is the host project.
   • 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. If you don't want to specify the IP address because you want Google Cloud to reserve an available IP address in the subnet, then omit this flag.

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_URI \
   --target-service-attachment=SERVICE_ATTACHMENT_URI \
   --allow-psc-global-access

   Make the following replacements:

   • ENDPOINT_NAME: the name of the endpoint
   • NETWORK_URI: the URI of the VPC network for the endpoint. The format is: projects/NETWORK_PROJECT_ID/global/networks/NETWORK_NAME. If you want to use a Shared VPC network, then specify the host project as the NETWORK_PROJECT_ID.
   • 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.

Use the following sample to create an IPv4 Private Service Connect endpoint.

resource "google_compute_address" "default" {
  name         = "psc-compute-address-${google_sql_database_instance.default.name}"
  region       = "us-central1"
  address_type = "INTERNAL"
  subnetwork   = "default"     # Replace value with the name of the subnet here.
  address      = "10.128.0.43" # 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
  allow_psc_global_access = true
}

Use the following sample to create an IPv6 Private Service Connect endpoint.

resource "google_compute_network" "ipv6_default" {
  name                     = "net-ipv6"
  auto_create_subnetworks  = false
  enable_ula_internal_ipv6 = true
}

resource "google_compute_subnetwork" "ipv6_default" {
  name             = "subnet-internal-ipv6"
  ip_cidr_range    = "10.0.0.0/16"
  region           = "us-central1"
  stack_type       = "IPV4_IPV6"
  ipv6_access_type = "INTERNAL"
  network          = google_compute_network.ipv6_default.id
}

resource "google_compute_address" "ipv6_default" {
  name         = "psc-compute-ipv6-address-${google_sql_database_instance.default.name}"
  region       = "us-central1"
  address_type = "INTERNAL"
  subnetwork   = google_compute_subnetwork.ipv6_default.name
  ip_version   = "IPV6"
}

resource "google_compute_forwarding_rule" "ipv6_ilb_example" {
  name   = "ipv6-psc-forwarding-rule-${google_sql_database_instance.default.name}"
  region = "us-central1"

  load_balancing_scheme   = ""
  target                  = data.google_sql_database_instance.default.psc_service_attachment_link
  network                 = google_compute_network.ipv6_default.name
  subnetwork              = google_compute_subnetwork.ipv6_default.name
  ip_address              = google_compute_address.ipv6_default.id
  allow_psc_global_access = true
}

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:

   curl (Linux, macOS, or Cloud Shell)

   Execute the following command:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/addresses/ADDRESS_NAME"

   PowerShell (Windows)

   Execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/addresses/ADDRESS_NAME" | Select-Object -Expand Content

   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:

   curl (Linux, macOS, or Cloud Shell)

   Execute the following command:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules/ENDPOINT_NAME"

   PowerShell (Windows)

   Execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules/ENDPOINT_NAME" | Select-Object -Expand Content

   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.

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

   If you want to use a custom DNS name to connect to a Cloud SQL instance instead of using the predefined DNS name in this section, then configure the custom subject alternative name (SAN) setting while creating the instance. The custom DNS name that you insert into the custom SAN setting is added to the SAN field of the server certificate of the instance. This lets you use the custom DNS name with hostname validation securely.

   For more information about configuring the custom SAN setting, see Create instances.

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. If the internal IP address that you reserved for the Private Service Connect endpoint is IPv4, then specify A for this parameter. Otherwise, if the IP address for the endpoint is IPv6, then specify AAAA.
   • 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.

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:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

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

PowerShell (Windows)

Execute the following command:

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

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

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.

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:

curl (Linux, macOS, or Cloud Shell)

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

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

PowerShell (Windows)

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

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

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

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.

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 resource record type of the DNS record set. If the internal IP address that you reserved for the Private Service Connect endpoint is IPv4, then specify A for this parameter. Otherwise, if the IP address for the endpoint is IPv6, then specify AAAA.
• 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:

curl (Linux, macOS, or Cloud Shell)

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

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

PowerShell (Windows)

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

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

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

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"
}

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 MySQL instances, the port number is 3306.

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 MySQL instances, the port number is 3306.
• 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:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://networkmanagement.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/connectivityTests?testId=CONNECTIVITY_TEST_NAME"

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://networkmanagement.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/connectivityTests?testId=CONNECTIVITY_TEST_NAME" | Select-Object -Expand Content

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
}