Conectar-se a uma instância usando o Private Service Connect

Nesta página, descrevemos como usar o Private Service Connect para se conectar a uma instância do Cloud SQL.

Use o Private Service Connect para se conectar a uma instância primária do Cloud SQL ou a qualquer uma das réplicas de leitura de várias redes de nuvem privada virtual (VPC) que pertencem a diferentes grupos, equipes, projetos ou organizações.

Antes de começar

O suporte para usar o Private Service Connect com uma instância do Cloud SQL está disponível para a versão 416.0.0 e posteriores do gcloud CLI.

Papéis do usuário

A tabela a seguir contém informações sobre os papéis necessários para usar o Private Service Connect com uma instância do Cloud SQL:

Papel Descrição
compute.networkAdmin

Concede controle total sobre a rede VPC que inicia uma conexão com uma instância do Cloud SQL. É possível criar e gerenciar endereços IP, regras de firewall e endpoints do Private Service Connect.

Se você usar o Private Service Connect para se conectar a uma instância do Cloud SQL de várias redes VPC, cada rede terá o próprio administrador.
dns.admin Concede controle total sobre os recursos do Cloud DNS, incluindo zonas e registros DNS.
cloudsql.admin Concede controle total sobre uma instância do Cloud SQL e sobre o ciclo de vida dela.
cloudsql.instanceUser Concede acesso à instância do Cloud SQL. Se você se conecta pelo cliente do proxy do Cloud SQL Auth, é necessário ter o papel de cliente do Cloud SQL. Se a conexão for direta, não serão necessários papéis e permissões do Identity and Access Management (IAM).

Criar uma instância do Cloud SQL

Você pode criar uma instância e habilitar o Private Service Connect usandogcloud CLI, o Terraform ou a API.

gcloud

Para criar uma instância e ativar o Private Service Connect para ela, use o comando gcloud sql instances create:

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

Faça as seguintes substituições:

  • INSTANCE_NAME: o nome da instância.
  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância.
  • REGION_NAME: o nome da região da instância.

  • ALLOWED_PROJECTS: uma lista de IDs ou números de projetos permitidos, separados por vírgulas. Se um projeto não estiver na lista, não será possível usá-lo para criar uma instância e ativar o Private Service Connect para ele.

  • AVAILABILITY_TYPE: ativa a alta disponibilidade para a promovida. Para esse parâmetro, especifique um dos seguintes valores:
    • REGIONAL: ativa a alta disponibilidade e é recomendado para instâncias de produção. A instância faz o failover para outra zona na sua região selecionada.
    • ZONAL: não fornece capacidade de failover. Esse é o valor padrão.

    Para mais informações sobre como configurar e remover a alta disponibilidade de instâncias, consulte Configurar uma instância para alta disponibilidade e Desativar a alta disponibilidade de uma instância.

  • MACHINE_TYPE: o tipo de máquina da instância.
  • DATABASE_VERSION: a versão do banco de dados para a instância (por exemplo, MYSQL_8_0).

Terraform

Para criar uma instância com o Private Service Connect ativado, use o google_sql_database_instancerecurso do Terraform.

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 = []
      }
      ipv4_enabled = false
    }
  }
  deletion_protection = false # Set to "true" to prevent destruction of the resource
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

    Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

  1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

    Copie o exemplo de código no main.tf recém-criado.

    Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas: 
    terraform plan

    Faça as correções necessárias na configuração.

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância.
  • INSTANCE_NAME: o nome da instância.
  • REGION_NAME: o nome da região da instância.
  • AVAILABILITY_TYPE: ativa a alta disponibilidade para a promovida. Para esse parâmetro, especifique um dos seguintes valores:
    • REGIONAL: ativa a alta disponibilidade e é recomendado para instâncias de produção. A instância faz o failover para outra zona na sua região selecionada.
    • ZONAL: não fornece capacidade de failover. Esse é o valor padrão.

    Para mais informações sobre como configurar e remover a alta disponibilidade de instâncias, consulte Configurar uma instância para alta disponibilidade e Desativar a alta disponibilidade de uma instância.

  • ALLOWED_PROJECTS: uma lista de IDs ou números de projetos permitidos, separados por vírgulas. Se um projeto não estiver na lista, não será possível usá-lo para criar uma instância e ativar o Private Service Connect para ele.

  • MACHINE_TYPE: o tipo de máquina da instância.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Acessar o anexo de serviço

Depois de criar uma instância do Cloud SQL com o Private Service Connect ativado, acesse o URI do anexo de serviço e use-o para criar o endpoint do Private Service Connect.

gcloud

Para acessar informações resumidas sobre uma instância com o Private Service Connect ativado, como o campo pscServiceAttachmentLink, que mostra o URI que aponta para o anexo de serviço da instância, use o comando gcloud sql instances describe:

gcloud sql instances describe INSTANCE_NAME \
--project=PROJECT_ID

Faça as seguintes substituições:

  • INSTANCE_NAME: o nome da instância do Cloud SQL a que os endpoints do Private Service Connect em redes VPC podem se conectar
  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância

O exemplo a seguir é uma demonstração de saída desse comando:

gcloud sql instances describe myinstance \
--project=12345

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

Terraform

Para conseguir o URI do anexo de serviço, use o google_compute_addressrecurso do Terraform.

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
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

    Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

  1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

    Copie o exemplo de código no main.tf recém-criado.

    Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas: 
    terraform plan

    Faça as correções necessárias na configuração.

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da instância

Método HTTP e URL: 

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

O campo pscServiceAttachmentLink exibe o URI que aponta para o anexo de serviço da instância.

Criar um endpoint do Private Service Connect

É possível reservar um endereço IP interno para o endpoint do Private Service Connect e criar um endpoint com esse endereço. Para criar o endpoint, você precisa do URI do anexo de serviço e dos projetos com permissão para a instância.

gcloud

  1. Para reservar um endereço IP interno para o endpoint do Private Service Connect, use o comando
    gcloud compute addresses create:

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

    Faça as seguintes substituições:

    • ADDRESS_NAME: o nome do endereço IP interno.
    • PROJECT_ID: o ID ou número do projeto do Google Cloud para o endpoint.
    • REGION_NAME: o nome da região do endpoint.
    • SUBNET_NAME: o nome da sub-rede do endereço IP.
    • INTERNAL_IP_ADDRESS: o endereço IP a ser reservado. Esse endereço IP precisa estar dentro do intervalo de IP principal da sub-rede. O endereço IP pode ser um endereço RFC 1918 ou uma sub-rede com intervalos não RFC.

  2. Para verificar se o endereço IP está reservado, use o comando gcloud compute addresses list:

    gcloud compute addresses list ADDRESS_NAME \
--project=PROJECT_ID

    Na resposta, verifique se o endereço IP tem um status RESERVED.

  3. Para criar o endpoint do Private Service Connect e apontá-lo para o anexo do serviço do Cloud SQL, use o comando gcloud compute forwarding-rules create:

    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

    Faça as seguintes substituições:

    • ENDPOINT_NAME: o nome do endpoint.
    • NETWORK_NAME: o nome da rede VPC do endpoint.
    • SERVICE_ATTACHMENT_URI: o URI do anexo de serviço

  4. Para verificar se o anexo de serviço aceita o endpoint, use o comando
    gcloud compute forwarding-rules describe:

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

    Na resposta, verifique se um status ACCEPTED aparece para o campo pscConnectionStatus. O endpoint pode se conectar ao anexo de serviço.

Terraform

Para criar um endpoint do Private Service Connect, use o google_sql_database_instancerecurso do Terraform.

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
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

    Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

  1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

    Copie o exemplo de código no main.tf recém-criado.

    Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas: 
    terraform plan

    Faça as correções necessárias na configuração.

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

REST

  1. Reserve um endereço IP interno para o endpoint do Private Service Connect.

  2. Verifique se o endereço IP está reservado.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém o endpoint do Private Service Connect
    • REGION_NAME: o nome da região.
    • ADDRESS_NAME: o nome do endereço IP

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

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

    Na resposta, verifique se o endereço IP tem um status RESERVED.

  3. Crie o endpoint do Private Service Connect e aponte-o para o anexo de serviço do Cloud SQL.

  4. Verifique se o anexo de serviço aceita o endpoint.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém o endpoint do Private Service Connect
    • REGION_NAME: o nome da região.
    • ENDPOINT_NAME: o nome do endpoint.

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

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

    Na resposta, verifique se um status ACCEPTED aparece para o campo pscConnectionStatus. O endpoint pode se conectar ao anexo de serviço.

Conexão com uma instância do Cloud SQL

É possível se conectar a uma instância do Cloud SQL com o Private Service Connect ativado usando um endereço IP interno, um registro DNS, o proxy de autenticação do Cloud SQL, os conectores de linguagem do Cloud SQL ou outros aplicativos do Google Cloud.

Configurar uma zona gerenciada de DNS e um registro DNS

O Cloud SQL não cria registros DNS automaticamente. Em vez disso, a resposta da API de consulta da instância fornece um nome DNS sugerido. Recomendamos que você crie o registro DNS em uma zona de DNS particular na rede VPC correspondente. Isso proporciona uma maneira consistente de usar o proxy do Cloud SQL Auth para se conectar de diferentes redes.

gcloud

  1. Para ver informações resumidas sobre uma instância do Cloud SQL, incluindo o nome DNS da instância, use o comando gcloud sql instances describe:

    gcloud sql instances describe INSTANCE_NAME \
--project=PROJECT_ID

    Faça as seguintes substituições:

    • INSTANCE_NAME: o nome da instância do Cloud SQL
    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância

    Na resposta, verifique se o nome DNS é exibido. Esse nome tem o seguinte padrão: INSTANCE_UID.PROJECT_DNS_LABEL.REGION_NAME.sql.goog.. Por exemplo, 1a23b4cd5e67.1a2b345c6d27.us-central1.sql.goog..

  2. Para criar uma zona de DNS particular, use o comando gcloud dns managed-zones create. Essa zona está associada à rede VPC usada para se conectar à instância do Cloud SQL por meio do endpoint do Private Service Connect.

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

    Faça as seguintes substituições:

    • ZONE_NAME: o nome da zona de DNS.
    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a zona
    • DESCRIPTION: uma descrição da zona (por exemplo, uma zona DNS para a instância do Cloud SQL
    • DNS_NAME: o nome do sufixo DNS da zona, como REGION_NAME.sql.goog. (em que REGION_NAME é o nome da região da zona)
    • NETWORK_NAME: o nome da rede VPC.

  3. Depois de criar o endpoint do Private Service Connect, use o comando gcloud dns record-sets create para criar um registro DNS na zona:

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

    Faça as seguintes substituições:

    • DNS_RECORD: o nome do registro DNS. Esse registro é definido como o nome de DNS que você extraiu da instância do Cloud SQL anteriormente neste procedimento (por exemplo, 1a23b4cd5e67.1a2b345c6d27.us-central1.sql.goog.).
    • RRSET_TYPE: o tipo de registro de recurso do conjunto de registros DNS (por exemplo, A).
    • RR_DATA: o endereço IP alocado para o endpoint do Private Service Connect (por exemplo, 198.51.100.5). Também é possível inserir diversos valores, como rrdata1 rrdata2 rrdata3 (por exemplo, 10.1.2.3 10.2.3.4 10.3.4.5).

REST

  1. Conferir o nome do DNS de uma instância do Cloud SQL.

    2. Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
    • INSTANCE_NAME: o nome da instância

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

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

    O campo dnsName exibe o nome DNS da instância do Cloud SQL. os nomes DNS sempre terminam com um ponto (.).

  2. Crie uma zona de DNS particular. Essa zona está associada à rede VPC usada para se conectar à instância do Cloud SQL por meio do endpoint do Private Service Connect.

    3. Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a zona DNS
    • ZONE_NAME: o nome da zona
    • DESCRIPTION: uma descrição da zona (por exemplo, uma zona DNS para a instância do Cloud SQL
    • DNS_NAME: o nome do sufixo DNS da zona, como REGION_NAME.sql.goog. (em que REGION_NAME é o nome da região da zona)
    • NETWORK_NAME: o nome da rede VPC.

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    {
  "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. Depois de criar o endpoint do Private Service Connect, crie um registro DNS na zona.

    4. Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a zona de DNS.
    • ZONE_NAME: o nome da zona.
    • DNS_RECORD: o nome do registro DNS. Esse registro é definido como o nome de DNS que você extraiu da instância do Cloud SQL anteriormente neste procedimento (por exemplo, 1a23b4cd5e67.1a2b345c6d27.us-central1.sql.goog.).
    • RRSET_TYPE: o tipo do conjunto de registros (por exemplo, A).
    • TTL: o tempo de vida (TTL) do conjunto de registros em número de segundos (por exemplo, 300).
    • RR_DATA: o endereço IP alocado para o endpoint do Private Service Connect (por exemplo, 198.51.100.5). Também é possível inserir diversos valores, como rrdata1 rrdata2 rrdata3 (por exemplo, 10.1.2.3 10.2.3.4 10.3.4.5).

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

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

Conectar-se diretamente usando um registro DNS

Antes de se conectar a uma instância do Cloud SQL usando um registro DNS, faça o seguinte:

  1. Crie um endpoint do Private Service Connect.
  2. Confirme se o anexo de serviço da instância aceita o endpoint. Para verificar se o status do endpoint é ACCEPTED, confira o status.
  3. Configure uma zona gerenciada de DNS e um registro DNS.

Depois de atender a essas condições, use o registro DNS para se conectar à instância por qualquer rede VPC em que você criou o endpoint.

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

Faça as seguintes substituições:

  • DNS_RECORD: o registro DNS do endpoint
  • USERNAME: o nome do usuário que está se conectando à instância

Conectar diretamente por um endereço IP interno

Antes de se conectar a uma instância do Cloud SQL com o Private Service Connect ativado, faça o seguinte:

  1. Crie um endpoint do Private Service Connect.
  2. Confirme se o anexo de serviço da instância aceita o endpoint. Para verificar se o status do endpoint é ACCEPTED, confira o status.

Depois de atender a essas condições, use o endereço IP do endpoint para acessar a instância por qualquer rede VPC em que você criou o endpoint.

  1. Recupere o endereço IP interno do endpoint do Private Service Connect.

    gcloud

    Para recuperar o endereço IP, use o comando gcloud compute addresses describe:

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

    Faça as seguintes substituições:

    • ADDRESS_NAME: o nome do endereço IP do endpoint
    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém o endpoint
    • REGION_NAME: o nome da região do endpoint

    Na resposta, verifique se um endereço IP aparece para o campo address. Esse é o endereço IP interno.

    REST

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém o endpoint
    • REGION_NAME: o nome da região do endpoint
    • ADDRESS_NAME: o nome do endereço IP do endpoint

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

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

    O endereço IP interno é o valor associado ao campo address.

  2. Para se conectar à instância do Cloud SQL, use o endereço IP interno.

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

    Faça as seguintes substituições:

    • IP_ADDRESS: o endereço IP do endpoint
    • USERNAME: o nome do usuário que está se conectando à instância

Conectar usando o proxy do Cloud SQL Auth

O proxy de autenticação do Cloud SQL é um conector que fornece acesso seguro a uma instância com o Private Service Connect ativado sem a necessidade de redes autorizadas ou configuração de SSL.

Para permitir conexões de clientes do proxy do Cloud SQL Auth, configure um registro DNS que corresponda ao nome DNS recomendado fornecido para a instância. O registro DNS é um mapeamento entre um recurso de DNS e um nome de domínio.

Fazer o download e instalar o proxy de autenticação do Cloud SQL

Para se conectar a instâncias com o Private Service Connect ativado, faça o download e instale o binário do proxy do Cloud SQL Auth. O binário para download depende do sistema operacional e se ele usa um kernel de 32 ou 64 bits. Os modelos de hardware mais recentes usam kernel de 64 bits.

Se você não tiver certeza se a máquina está executando um kernel de 32 ou 64 bits, use o comando uname -a para Linux ou macOS. Para o Windows, consulte a documentação do Windows.

Iniciar o proxy de autenticação do Cloud SQL

O proxy do Cloud SQL Auth é compatível com conexões a instâncias com o Private Service Connect ativado. Para mais informações, consulte Iniciar o proxy de autenticação do Cloud SQL.

  1. Exibir informações resumidas sobre uma instância do Cloud SQL, incluindo o nome de conexão da instância.

    gcloud

    Para conferir informações resumidas sobre uma instância do Cloud SQL, use o comando
    gcloud sql instances describe.

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

    Faça as seguintes substituições:

    • INSTANCE_NAME: o nome da instância do Cloud SQL
    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância

    Esse nome de conexão está no formato PROJECT_ID:REGION_NAME:INSTANCE_NAME.

    REST

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
    • INSTANCE_NAME: o nome da instância

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

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

    Esse nome de conexão está no formato PROJECT_ID:REGION_NAME:INSTANCE_NAME.

  2. Copie o nome da conexão da instância.

  3. Inicie o proxy do Cloud SQL Auth:

    ./cloud-sql-proxy INSTANCE_CONNECTION_NAME --psc

    Substitua INSTANCE_CONNECTION_NAME pelo nome da conexão da instância copiado no passo anterior.

Conectar usando os conectores do Cloud SQL Language

Os conectores de linguagem do Cloud SQL são bibliotecas que fornecem acesso seguro a uma instância do Cloud SQL com o Private Service Connect ativado sem necessidade de redes autorizadas ou configuração de SSL.

Para permitir conexões com os conectores de linguagem do Cloud SQL, configure um registro DNS que corresponda ao nome DNS recomendado fornecido para a instância. O registro DNS é um mapeamento entre um recurso de DNS e um nome de domínio.

Os conectores de idioma do Cloud SQL são compatíveis com conexões do Private Service Connect pelo tipo de IP PSC nas respectivas bibliotecas.

Conectar-se pelo App Engine Standard, Cloud Run ou funções do Cloud Run

Para se conectar a instâncias do Cloud SQL com o Private Service Connect ativado, use o ambiente padrão do App Engine, o Cloud Run ou funções do Cloud Run.

Nesses ambientes sem servidor compatíveis, há suporte tanto para os conectores de linguagem do Cloud SQL quanto para as conexões TCP diretas por meio de um endereço IP e de um número de porta. Para conexões TCP diretas, esse é o endereço IP que você reserva ao criar o endpoint do Private Service Connect. É possível especificar o endereço IP como o endereço do host do banco de dados.

Se você criar um registro DNS para o endpoint, poderá especificar esse registro para o host.

Conectar a partir do BigQuery

Para acessar dados no Cloud SQL e fazer consultas nesses dados por uma conexão IP interna, use o parâmetro
--enable-google-private-path. Esse parâmetro só será válido se:

  • Use o parâmetro --no-assign-ip.
  • Use o parâmetro --network para especificar o nome da rede VPC que você quer usar para criar uma conexão interna.

Testar a conectividade

Para testar a conectividade de entrada de uma instância do Cloud SQL com o Private Service Connect ativado, defina o endereço IP do endpoint do Private Service Connect como o endereço IP de destino.

gcloud

Para criar um teste de conectividade para uma instância do Cloud SQL com o Private Service Connect ativado, use o comando gcloud network-management connectivity-tests create:

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

Faça as seguintes substituições:

  • CONNECTIVITY_TEST_NAME: o nome do teste de conectividade.
  • SOURCE_INSTANCE: o URI da instância do Compute Engine em que o endereço IP de origem está localizado (por exemplo, projects/myproject/zones/myzone/instances/myinstance).
  • DESTINATION_CLOUD_SQL_INSTANCE: o URL da instância do Cloud SQL (por exemplo, projects/myproject/instances/myinstance).
  • DESTINATION_NETWORK: o URI da rede VPC em que o endereço IP de destino está (por exemplo, projects/myproject/global/networks/mynetwork).
  • DESTINATION_PORT pelo número da porta reservada para a instância. Para instâncias do Cloud SQL para MySQL, o número da porta é 3306.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância.
  • CONNECTIVITY_TEST_NAME: o nome do teste de conectividade.
  • SOURCE_IP_ADDRESS: o endereço IP da instância de origem do Compute Engine.
  • SOURCE_INSTANCE: o URI da instância do Compute Engine em que o endereço IP de origem está localizado (por exemplo, projects/myproject/zones/myzone/instances/myinstance).
  • SOURCE_NETWORK: o URI da rede VPC em que o endereço IP de origem está localizado (por exemplo, projects/myproject/global/networks/mynetwork).
  • DESTINATION_IP_ADDRESS: o endereço IP da instância de destino do Cloud SQL.
  • DESTINATION_PORT pelo número da porta reservada para a instância. Para instâncias do Cloud SQL para MySQL, o número da porta é 3306.
  • DESTINATION_NETWORK: o URI da rede VPC em que o endereço IP de destino está (por exemplo, projects/myproject/global/networks/mynetwork).

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Limitações

  • É possível configurar até 20 endpoints do Private Service Connect que se conectam ao anexo de serviço de uma instância do Cloud SQL com o Private Service Connect ativado.
  • Não é possível usar backends para instâncias com o Private Service Connect ativado.
  • As sinalizações a seguir são invalidadas ou afetadas:
    • --no-assign-ip: usa essa flag porque as instâncias do Cloud SQL com o Private Service Connect ativado não têm suporte para usar outros tipos de conectividade, como conexões IP externas
    • --authorized-networks: não é possível usar esta flag para adicionar redes autorizadas.
    • --network: não é possível usar esta flag porque ela está associada ao acesso a serviços privados.
    • --allocated-ip-range-name: não é possível usar esta flag porque os nomes de intervalos de IP permitidos não são compatíveis.
  • Não é possível criar uma réplica externa de uma instância com o Private Service Connect ativado.
  • Não é possível ativar ou desativar o Private Service Connect em uma instância.
  • Não é possível configurar uma instância que tenha o Private Service Connect ativado para usar o Acesso a serviços privados ou conexões IP externas.
    • Não é possível ativar conexões de IP externo em uma instância com o Private Service Connect ativado.
    • Não é possível ativar o acesso a serviços privados ou adicionar redes autorizadas à instância.
    • Não é possível alterar o tipo de conectividade da instância.
    • Não é possível usar o comando gcloud sql connect, o Cloud Shell, o Cloud Build ou o Database Migration Service para se conectar a instâncias do Cloud SQL com o Private Service Connect ativado.
    • Ao testar a conectividade com uma instância do Cloud SQL com o Private Service Connect ativado, não é possível definir os seguintes itens:
      • O endereço IP interno da instância ou o nome DNS como o destino diretamente
      • A instância como a origem
      • O endereço IP do endpoint do Private Service Connect como a origem
    • Não há suporte para a lista de permissões baseada em IP usando redes autorizadas.
    • Se o projeto de rede tiver instâncias que usam a arquitetura de rede antiga do Cloud SQL, não será possível criar uma instância do Private Service Connect. O Cloud SQL fornece ferramentas para ajudar você a fazer upgrade das suas instâncias da arquitetura de rede antiga para a nova. Para saber mais ou verificar a arquitetura de rede das instâncias do Cloud SQL no projeto e realizar os upgrades necessários, consulte Fazer upgrade de uma instância para a nova arquitetura de rede.

    Resolver problemas

    Esta seção contém informações sobre problemas associados a instâncias do Cloud SQL com o Private Service Connect ativado, além de etapas para solucionar os problemas.
    Problema Solução de problemas
    O anexo de serviço da instância não aceita o endpoint do Private Service Connect.
    1. Verifique o status do endpoint.

      gcloud

      Para verificar o status, use o comando
      gcloud compute forwarding-rules describe.

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

      Faça as seguintes substituições:

      • ENDPOINT_NAME: o nome do endpoint.
      • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém o endpoint
      • REGION_NAME: o nome da região do endpoint

      REST

      Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

      • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém o endpoint do Private Service Connect
      • REGION_NAME: o nome da região.
      • ENDPOINT_NAME: o nome do endpoint.

      Método HTTP e URL: 

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

      Para enviar a solicitação, expanda uma destas opções:

      Você receberá uma resposta JSON semelhante a esta:

      {
  "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. Verifique se o status do endpoint é ACCEPTED. Se o status for PENDING, a instância não está permitindo o projeto do Google Cloud que contém o endpoint. Verifique se o projeto de rede em que o endpoint foi criado é permitido. Para mais informações, consulte Editar uma instância com o Private Service Connect ativado.

    A seguir