Configure o Private Service Connect

MySQL   |  PostgreSQL   |  SQL Server

Neste documento, descrevemos como configurar o Private Service Connect para as conexões de rede particular das instâncias do Cloud SQL.

Depois de configurar o Private Service Connect e os endpoints dele, você e os clientes de aplicativos poderão 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. Também é possível configurar nomes DNS globais ou por instância para conexões de clientes baseadas em nomes DNS, o que é útil para casos de uso de failover e recuperação de desastres.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Service Networking, Network Connectivity, Cloud DNS APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Make sure that you have the following role or roles on the project: Compute Network Admin, Cloud SQL Admin, Cloud DNS Admin, Cloud SQL Instance User

Check for the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

Grant the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.
3. Click Grant access.

4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

5. Click Select a role, then search for the role.
6. To grant additional roles, click Add another role and add each additional role.
7. Click Save.

Instale a CLI gcloud.

Observação:se você já instalou a CLI gcloud, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Service Networking, Network Connectivity, Cloud DNS APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Make sure that you have the following role or roles on the project: Compute Network Admin, Cloud SQL Admin, Cloud DNS Admin, Cloud SQL Instance User

Check for the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

Grant the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.
3. Click Grant access.

4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

5. Click Select a role, then search for the role.
6. To grant additional roles, click Add another role and add each additional role.
7. Click Save.

Instale a CLI gcloud.

Observação:se você já instalou a CLI gcloud, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Papéis necessários para o Private Service Connect

A tabela a seguir contém informações sobre os papéis necessários para configurar e se conectar a um 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, políticas de conexão de serviço 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).

Para configurar uma política de conexão de serviço automaticamente ao criar sua instância do Cloud SQL, você precisa de mais papéis e da capacidade de atribuir os papéis ao agente de serviço do Cloud SQL. Para mais informações, consulte Criar uma política de conexão de serviço.

Criar um endpoint do Private Service Connect

Os endpoints do Private Service Connect são endereços IP internos em uma rede VPC do consumidor, que os clientes nessa rede podem acessar diretamente. Os clientes podem usar esses endpoints para se conectar a instâncias do Cloud SQL.

É possível criar um endpoint do Private Service Connect automaticamente no Cloud SQL na sua VPC ou criar o endpoint manualmente.

Criar o endpoint automaticamente

Observação: se a política de conexão de serviço e a instância do Cloud SQL estiverem em projetos diferentes, configure a política com um escopo de instância de serviço personalizado. Esse escopo define a hierarquia de recursos como os IDs dos projetos, pastas ou organizações em que a instância está localizada para garantir que a política possa descobrir e se conectar a ela.

Para que o Cloud SQL crie o endpoint do Private Service Connect automaticamente, faça o seguinte:

1. Crie uma política de conexão de serviço na rede VPC. Com essa política, é possível provisionar endpoints do Private Service Connect automaticamente.

   Observação: é possível criar uma política de conexão de serviço automaticamente ao criar a instância do Cloud SQL. No entanto, essa opção exige mais permissões administrativas.

2. Crie uma instância do Cloud SQL com o Private Service Connect ativado e configure a instância para criar endpoints do Private Service Connect automaticamente.

3. Recupere o endpoint da instância. Isso permite que você use o endpoint para se conectar à instância.

Criar uma política de conexão de serviço

É possível criar uma política de conexão de serviço usando o Google Cloud console, a CLI gcloud ou a API.

Console

1. No console do Google Cloud , acesse a página Private Service Connect.

   Acessar a página "Private Service Connect"

2. Clique na guia Políticas de conexão.

3. Clique em Criar política de conexão.

4. Digite um nome para a conexão.

5. Especifique a classe de serviço fazendo o seguinte:

   1. Em Source service class, selecione Google services.
   2. No menu Classe de serviço, selecione google-cloud-sql porque o Cloud SQL é o serviço gerenciado para a política de conexão.

6. Na seção Escopo de endpoints de destino, selecione uma Rede e uma Região a que essa política se aplica.

7. Opcional: se a política de conexão de serviço e a instância do Cloud SQL estiverem em projetos, pastas ou organizações diferentes, configure o Escopo da instância de serviço personalizada:

   1. Mude a chave Escopo da instância de serviço personalizada para a posição ativado.
   2. No campo Escopos, insira os IDs dos projetos, pastas ou organizações em que a instância está localizada.

8. Na seção Política, selecione uma ou mais sub-redes no menu Sub-redes. As sub-redes são usadas para alocar endereços IP para endpoints.

9. Opcional: especifique um Limite de conexão para a política. O limite determina quantos endpoints podem ser criados usando essa política de conexão. Se você não especificar um limite de conexão, não haverá limite.

10. Clique em Criar política.

gcloud

Para criar uma política de conexão de serviço, use o comando service-connection-policies create.

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

Substitua:

• POLICY_NAME: o nome da política de conexão de serviço.
• NETWORK: a rede a que esta política se aplica.
• PROJECT_ID: o ID do projeto ou o número do projeto da rede VPC. Para redes VPC compartilhadas, implante políticas de conexão de serviço no projeto host porque elas não são compatíveis com projetos de serviço.
• REGION: a região em que a política será aplicada. A mesma política precisa existir para todas as regiões em que você queira automatizar a conectividade do serviço.
• SERVICE_CLASS: o identificador de recurso fornecido pelo produtor da classe de serviço. Para o Cloud SQL, a classe de serviço é google-cloud-sql.
• SUBNETS: uma ou mais sub-redes de consumidor regulares usadas para alocar endereços IP para endpoints do Private Service Connect. Esses endereços IP são alocados automaticamente e retornados ao pool da sub-rede à medida que as instâncias de serviço gerenciado são criadas e excluídas. As sub-redes precisam estar na mesma região que a política de conexão do serviço. Se várias políticas de conexão compartilharem a mesma região, será possível reutilizar a mesma sub-rede nessas políticas. É possível inserir várias sub-redes em uma lista separada por vírgulas.
• LIMIT: o número máximo de endpoints que você pode criar usando essa política. Se você não especificar um limite, não haverá nenhum.
• DESCRIPTION: uma descrição opcional do política de conexão de serviço.

• PRODUCER_INSTANCE_LOCATION: especifique se uma hierarquia personalizada de locais para uma instância do Cloud SQL será autorizada. Se a instância estiver em um projeto, pasta ou organização diferente da política, defina esse valor como custom-resource-hierarchy-levels.

• RESOURCE_HIERARCHY_LEVEL: uma lista de projetos, pastas ou organizações em que a instância está localizada. A lista está em um destes formatos:

  • projects/PROJECT_ID
  • folders/FOLDER_ID
  • organizations/ORGANIZATION_ID.

Por exemplo, o comando a seguir cria uma política de conexão de serviço para a classe de serviço
google-cloud-sql que aloca endereços IP da sub-rede managed-services. É possível criar até 10 endpoints do Private Service Connect usando esta política. Os endpoints precisam ser criados em projetos que estejam na mesma organização da instância de serviço gerenciado. A instância do Cloud SQL está localizada no projeto myproject.

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

REST

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

• PROJECT_ID: ID do projeto.
• REGION: a região da política de conexão de serviço.
• POLICY_NAME: o nome da política de conexão de serviço.
• DESCRIPTION: uma descrição opcional da política de conexão de serviço.
• NETWORK: a rede da política de conexão de serviço.
• LIMIT: o número máximo de endpoints que podem ser criados usando essa política. Se você não especificar um limite, não haverá nenhum.
• SUBNETS: uma ou mais sub-redes de consumidor regulares usadas para alocar endereços IP para endpoints do Private Service Connect. Esses endereços IP são alocados automaticamente e retornados ao pool da sub-rede à medida que as instâncias de serviço gerenciado são criadas e excluídas. As sub-redes precisam estar na mesma região que a política de conexão do serviço. Se várias políticas de conexão compartilharem a mesma região, será possível reutilizar a mesma sub-rede nessas políticas. É possível inserir várias sub-redes em uma lista separada por vírgulas.
• SERVICE_CLASS: o identificador de recurso fornecido pelo produtor da classe de serviço.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

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

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

Você receberá uma resposta JSON semelhante a esta:

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

Criar uma política de conexão de serviço automaticamente

É possível criar uma política de conexão de serviço automaticamente ao criar a instância do Cloud SQL. No entanto, essa opção exige mais permissões administrativas.

Console

Se você estiver usando o console do Google Cloud , crie a instância do Cloud SQL com o Private Service Connect ativado. O console Google Cloud verifica e configura automaticamente as funções necessárias. Talvez seja necessário ativar a API Network Connectivity se ela ainda não estiver ativada para seu projeto.

gcloud ou REST

Se você estiver usando a CLI gcloud ou a API Cloud SQL Admin, será necessário conceder outros papéis ao agente de serviço do Cloud SQL antes de criar a instância.

1. Se um agente de serviço do Cloud SQL específico do projeto ainda não existir no projeto que vai hospedar a instância do Cloud SQL, crie um.

   Para criar o agente de serviço, execute o seguinte comando:

   gcloud beta services identity create \
     --service=sqladmin.googleapis.com \
     --project=INSTANCE_PROJECT
   

   Substitua:

   • INSTANCE_PROJECT: o projeto em que você planeja criar a instância do Cloud SQL.

   O comando cria um agente de serviço com o formato [e-mail].

2. Conceda as permissões do IAM necessárias ao agente de serviço do Cloud SQL atribuindo os seguintes papéis a ele:

   • Administrador de rede do consumidor de automação de serviços (roles/networkconnectivity.consumerNetworkAdmin)
   • Leitor da rede do Compute (roles/compute.networkViewer)

   Para adicionar os papéis ao agente de serviço do Cloud SQL, execute os seguintes comandos:

   gcloud projects add-iam-policy-binding CONSUMER_PROJECT \
     --member='serviceAccount:CLOUD_SQL_SERVICE_AGENT' \
     --role='roles/networkconnectivity.consumerNetworkAdmin'
   
   gcloud projects add-iam-policy-binding CONSUMER_PROJECT \
     --member='serviceAccount:CLOUD_SQL_SERVICE_AGENT' \
     --role='roles/compute.networkViewer'
   

   Substitua:

   • CONSUMER_PROJECT: o projeto em que o endpoint do Private Service Connect será criado. Se você estiver usando uma rede VPC compartilhada, pode ser o projeto host ou o projeto de serviço.
   • CLOUD_SQL_SERVICE_AGENT: o endereço de e-mail da conta do agente de serviço do Cloud SQL que você criou.

Criar uma instância do Cloud SQL

É possível criar uma instância com o Private Service Connect ativado e configurar a criação automática de endpoints usando o console Google Cloud , a CLI gcloud ou a API.

Observação: depois de criar a instância, um endpoint do Private Service Connect será criado automaticamente nas redes VPC especificadas. No entanto, o endpoint pode não ser criado por motivos como a rede especificada não existir, não haver uma política de conexão de serviço válida ou não haver endereços IP disponíveis. Se isso acontecer, o endpoint não será criado. Também é possível criar endpoints do Private Service Connect manualmente.

Console

1. No console Google Cloud , acesse a página Instâncias do Cloud SQL.

   Acesse "Instâncias do Cloud SQL"

2. Na seção Personalizar sua instância, expanda a seção Conexões.
3. Marque a caixa de seleção IP privado.
4. Na seção Escolha um método de conexão particular, marque a caixa de seleção Private Service Connect (PSC).
5. Na seção Configuração de endpoint, clique em Adicionar um endpoint.
6. Na seção Configuração do endpoint, faça o seguinte:
   1. No card Novo endpoint, selecione o projeto em que você quer configurar o endpoint no menu Projeto.
   2. Selecione uma rede para o endpoint no menu Rede.
   3. Se a API Network Connectivity ainda não estiver ativada, clique em Ativar.
7. Clique em Confirmar configuração de rede. Se uma política de conexão de serviço for detectada para a rede selecionada, uma mensagem de sucesso será exibida. Se nenhuma política de conexão de serviço for detectada, mas as permissões tiverem sido concedidas, o Google Cloud criará uma política de conexão de serviço para você.
8. Opcional: conclua outras opções de configuração da instância.
9. Clique em Criar instância.

gcloud

Para criar uma instância com o Private Service Connect ativado, use o comando gcloud sql instances create:

gcloud sql instances create INSTANCE_NAME \
  --project=PROJECT_ID \
  --region=REGION_NAME \
  --cpu=NUMBER_OF_vCPUs \
  --memory=MEMORY_SIZE \
  --root-password=ROOT_PASSWORD \
  --availability-type=AVAILABILITY_TYPE \
  --database-version=DATABASE_VERSION \
  --no-assign-ip \
  --enable-private-service-connect \
  --allowed-psc-projects=ALLOWED_PROJECTS \
  --psc-auto-connections=network=CONSUMER_NETWORK,project=CONSUMER_PROJECT \
  --enable-psc-auto-dns \
  --enable-psc-write-endpoint-dns

Opcional. Para criar ou atualizar uma política de conexão de serviço automaticamente ao criar a instância do Cloud SQL, adicione o parâmetro --enable-psc-auto-connection-policy ao comando. Você precisa configurar permissões adicionais para usar esse parâmetro. Para mais informações, consulte Criar uma política de conexão de serviço automaticamente.

Substitua:

• INSTANCE_NAME: o nome da instância.
• PROJECT_ID: o ID ou número do projeto do projeto Google Cloud que contém a instância.
• REGION_NAME: o nome da região da instância.
• NUMBER_OF_vCPUs: o número de núcleos da instância.
• MEMORY_SIZE: a quantidade de memória para a instância.
• ROOT_PASSWORD: a senha do usuário do Cloud SQL root.

• AVAILABILITY_TYPE: ativa a alta disponibilidade para a instância. 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.

• DATABASE_VERSION: a versão do banco de dados para a instância (por exemplo, SQLSERVER_2019_STANDARD).

• ALLOWED_PROJECTS: uma lista separada por vírgulas de IDs ou números de projetos permitidos de onde os endpoints do Private Service Connect podem se conectar a instâncias do Cloud SQL.

  Se um projeto não estiver na lista, não será possível criar endpoints do Private Service Connect nele para se conectar à instância.

• CONSUMER_NETWORK: o caminho para a rede VPC de onde os endpoints do Private Service Connect precisam ser criados. Por exemplo, projects/my-host-project/global/networks/default.

• CONSUMER_PROJECT: o projeto em que o endpoint do Private Service Connect é criado. Se você estiver usando uma rede VPC compartilhada, pode ser o projeto host ou o projeto de serviço.

  Todos os projetos especificados nos parâmetros de conexão automática são adicionados automaticamente aos projetos permitidos. Se quiser criar endpoints do Private Service Connect manualmente em alguns projetos, adicione esses projetos à sua lista de projetos permitidos.

Use estes parâmetros para ativar e configurar o Private Service Connect:

• --enable-private-service-connect: ativa o Private Service Connect.
• --allowed-psc-projects=ALLOWED_PROJECTS: especifica uma lista separada por vírgulas de IDs ou números de projetos permitidos. São os projetos em que os endpoints do Private Service Connect podem se conectar às instâncias do Cloud SQL.
• --psc-auto-connections=network=CONSUMER_NETWORK,project=CONSUMER_PROJECT: especifica o caminho para a rede VPC em que os endpoints do Private Service Connect precisam ser criados.

• --enable-psc-auto-dns: indica se a automação de DNS do Private Service Connect deve ser ativada para esta instância. O padrão é desativado para novas instâncias quando o Private Service Connect é ativado usando --enable-private-service-connect.

  Quando a automação de DNS está ativada, o Cloud SQL provisiona um registro DNS por instância em todas as redes configuradas com conexões automáticas do Private Service Connect.

• --enable-psc-write-endpoint-dns: indica se a automação de DNS do endpoint de gravação do Private Service Connect está ativada para esta instância. Esse recurso só é compatível com instâncias do Enterprise Plus em que --enable-psc-auto-dns também está definido. Ele fica desativado por padrão quando uma nova instância é criada.

  Quando a automação de DNS do endpoint de gravação está ativada, o Cloud SQL provisiona um registro DNS global para atuar como um endpoint de gravação para o cluster de replicação em todas as redes configuradas com conexões automáticas do Private Service Connect. Esse registro DNS global sempre aponta para a instância principal atual do cluster de replicação, o que permite o failover de aplicativos sem interrupções sem exigir atualizações de string de conexão do lado do cliente em caso de uma operação de failover ou alternância de réplica.

REST

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

• INSTANCE_NAME: o nome da instância do Cloud SQL.
• PROJECT_ID: o ID ou número do projeto do projeto Google Cloud que contém a instância.
• REGION_NAME: o nome da região da instância.
• DATABASE_VERSION: a versão do banco de dados para a instância (por exemplo, SQLSERVER_2019_STANDARD).
• ROOT_PASSWORD: a senha do usuário do Cloud SQL root.
• AVAILABILITY_TYPE: o tipo de disponibilidade zonal da instância. Use esse parâmetro para ativar ou desativar a alta disponibilidade da instância especificando 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 região selecionada.
  • ZONAL: não oferece 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 separada por vírgulas de IDs ou números de projetos permitidos de onde os endpoints do Private Service Connect podem se conectar a instâncias do Cloud SQL.

  Se um projeto não estiver na lista, não será possível criar endpoints do Private Service Connect nele para se conectar à instância.

• CONSUMER_PROJECT: o projeto em que o endpoint do Private Service Connect é criado. Se você estiver usando uma rede VPC compartilhada, pode ser o projeto host ou o projeto de serviço.

  Todos os projetos especificados nos parâmetros de conexão automática são adicionados aos projetos permitidos automaticamente. Se quiser criar endpoints do Private Service Connect manualmente em alguns projetos, adicione esses projetos à sua lista de projetos permitidos.

• PARENT_PROJECT: o projeto que contém a rede CONSUMER_NETWORK. Se você não especificar um projeto diferente em CONSUMER_PROJECT, os endpoints serão criados automaticamente em PARENT_PROJECT .

• CONSUMER_PROJECT: opcional. Especifique isso apenas se CONSUMER_NETWORK for uma rede VPC compartilhada e você quiser permitir a criação automática de endpoints do Private Service Connect em um projeto de serviço.

  Todos os projetos especificados nos parâmetros de conexão automática são adicionados automaticamente aos projetos permitidos. Se quiser criar endpoints do Private Service Connect manualmente em outros projetos, adicione-os à lista de projetos permitidos.

• CONSUMER_NETWORK: a rede VPC em que você quer permitir a criação automática de endpoints do Private Service Connect. Por exemplo:
  projects/my-host-project/global/networks/default.
• MACHINE_TYPE: um valor de string enumerado que representa o tipo de máquina da instância. Por exemplo: code>db-custom-NUMBER_OF_vCPUs-MEMORY_SIZE, em que NUMBER_OF_vCPUs e MEMORY_SIZE são o número de núcleos e a quantidade de memória que você quer para a 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": "SQLSERVER_2019_STANDARD",
  "rootPassword": "ROOT_PASSWORD",
  "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,
        "pscAutoConnectionPolicyEnabled": true,
        "pscAutoDnsEnabled": true,
        "pscWriteEndpointDnsEnabled": true
      }
    },
    "kind": "sql#settings",
    "pricingPlan": "PER_USE",
    "replicationType": "SYNCHRONOUS",
    "tier": "MACHINE_TYPE"
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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

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": "[e-mail]",
  "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"
}

Estes são os campos que você usa para ativar a automação de DNS e um nome DNS global de endpoint de gravação:

• psc_auto_dns_enabled: indica se a automação de DNS do Private Service Connect está ativada para esta instância. O padrão é desativado para novas instâncias quando o Private Service Connect é ativado usando --enable-private-service-connect.

  Quando a automação de DNS está ativada, o Cloud SQL provisiona um registro DNS universal em todas as redes configuradas com conexões automáticas do Private Service Connect.

• psc_write_endpoint_dns_enabled: indica se a automação de DNS do endpoint de gravação do Private Service Connect está ativada para esta instância. Esse recurso só é compatível com instâncias do Enterprise Plus em que --enable-psc-auto-dns também está definido. Ele fica desativado por padrão quando uma nova instância é criada.

  Com a automação de DNS do endpoint de gravação ativada, o Cloud SQL provisiona um registro DNS global para atuar como um endpoint de gravação em todas as redes configuradas com conexões automáticas do Private Service Connect. Esse registro DNS global sempre aponta para a instância principal atual do cluster de replicação, o que permite o failover de aplicativos sem interrupções sem exigir atualizações de string de conexão do lado do cliente em caso de operação de failover ou alternância de réplica.

Para criar uma política de conexão de serviço automaticamente ao criar a instância, ative o seguinte campo:

• psc_auto_connection_policy_enabled: indica se é necessário permitir que Google Cloud crie ou atualize uma política de conexão de serviço ao criar a instância do Cloud SQL. Você precisa configurar outras permissões para usar essa opção. Para mais informações, consulte Criar uma política de conexão de serviço automaticamente.

Terraform

Para criar a instância, use um recurso do Terraform com um campo psc_config:

resource "google_sql_database_instance" "INSTANCE_NAME"
{
  name = "INSTANCE_NAME"
  database_version = "DATABASE_VERSION"
  settings
  {
    tier = "MACHINE_TYPE"
    ip_configuration
    {
      psc_config
      {
        psc_enabled = true
        psc_auto_dns_enabled = true
        psc_write_endpoint_dns_enabled = true
        allowed_consumer_projects = ["ALLOWED_PROJECTS"]
        psc_auto_connections
        {
          consumer_network = "CONSUMER_NETWORK"
          consumer_service_project_id = "CONSUMER_PROJECT"
        }
      }
      ipv4_enabled = false
    }
  }
}

Substitua:

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

• ALLOWED_PROJECTS: uma lista separada por vírgulas de IDs ou números de projetos permitidos de onde os endpoints do Private Service Connect podem se conectar a instâncias do Cloud SQL.

  Se um projeto não estiver na lista, não será possível criar endpoints do Private Service Connect nele para se conectar à instância.

• CONSUMER_NETWORK: o caminho para a rede VPC de onde os endpoints do Private Service Connect precisam ser criados. Por exemplo, projects/my-host-project/global/networks/default.

• CONSUMER_PROJECT: o projeto em que o endpoint do Private Service Connect é criado. Se você estiver usando uma rede VPC compartilhada, pode ser o projeto host ou o projeto de serviço.

Use estes campos para ativar a automação de DNS e um nome DNS de endpoint de gravação global:

• psc_auto_dns_enabled: indica se a automação de DNS do Private Service Connect está ativada para esta instância. O padrão é desativado para novas instâncias quando o Private Service Connect é ativado usando --enable-private-service-connect.

  Quando a automação de DNS está ativada, o Cloud SQL provisiona um registro DNS universal em todas as redes configuradas com conexões automáticas do Private Service Connect.

• psc_write_endpoint_dns_enabled: indica se a automação de DNS do endpoint de gravação do Private Service Connect está ativada para esta instância. Esse recurso só é compatível com instâncias do Enterprise Plus em que --enable-psc-auto-dns também está definido. Ele fica desativado por padrão quando uma nova instância é criada.

  Com a automação de DNS do endpoint de gravação ativada, o Cloud SQL provisiona um registro DNS global para atuar como um endpoint de gravação em todas as redes configuradas com conexões automáticas do Private Service Connect. Esse registro DNS global sempre aponta para a instância principal atual do cluster de replicação, o que permite o failover de aplicativos sem interrupções sem exigir atualizações de string de conexão do lado do cliente em caso de operação de failover ou alternância de réplica.

Para ativar o Private Service Connect e criar uma política de conexão de serviço automaticamente, use o seguinte campo:

• psc_auto_connection_policy_enabled: indica se é necessário permitir que Google Cloud crie ou atualize uma política de conexão de serviço ao criar a instância do Cloud SQL. Você precisa configurar outras permissões para usar essa opção. Para mais informações, consulte Criar uma política de conexão de serviço automaticamente.

Aplique as alterações

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

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto Google Cloud padrão 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 Google Cloud projeto para conferir os resultados. No console do Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu projeto Google Cloud .

Excluir as alterações

Para excluir as mudanças, faça o seguinte:

1. Para desativar a proteção contra exclusão, no arquivo de configuração do Terraform, defina o argumento deletion_protection como false.

   deletion_protection =  "false"

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

   terraform apply

3. Remova os recursos aplicados anteriormente com a configuração do Terraform executando o seguinte comando e inserindo yes no prompt:

   terraform destroy

Recuperar o endpoint

Ao recuperar o endereço IP interno, que é o endpoint do Private Service Connect de uma instância, é possível usar esse endpoint para se conectar à instância.

gcloud

Para conferir informações sobre uma instância, incluindo o endereço IP que é o endpoint do Private Service Connect para ela, use o comando gcloud sql instances describe:

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

Faça as seguintes substituições:

• INSTANCE_NAME: o nome da instância do Cloud SQL. Se o Private Service Connect estiver ativado nessa instância, os endpoints do Private Service Connect nas redes VPC poderão se conectar a ela.
• PROJECT_ID: o ID ou número do projeto do Google Cloud projeto que contém a instância.

Na resposta, observe o valor que aparece ao lado do campo pscConfig:pscAutoConnections:ipAddress. Esse valor é o endereço IP interno que também é o endpoint do Private Service Connect para a instância.

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 projeto que contém a instância.
• INSTANCE_NAME: o nome da instância do Cloud SQL. Se o Private Service Connect estiver ativado nessa instância, os endpoints do Private Service Connect nas redes VPC poderão se conectar a ela.

Método HTTP e URL:

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

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Execute o seguinte comando:

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

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Execute o seguinte comando:

$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

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#instance",
  "state": "RUNNABLE",
  "databaseVersion": "SQLSERVER_2019_STANDARD",
  "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
    },
}

Os campos a seguir existem para instâncias que têm o Private Service Connect ativado:

• allowedConsumerProjects: uma lista dos projetos permitidos para a instância. Você pode criar endpoints do Private Service Connect de qualquer rede VPC nesses projetos para o anexo de serviço da instância.
• pscAutoConnections: a rede VPC permitida, o status da política de conexão de serviço e o status do endereço IP que é o endpoint da instância.
• pscEnabled: se uma instância tem o Private Service Connect ativado para ela.

Para ver como criar a solicitação da API REST subjacente desta tarefa, consulte a página instances:get.

Observação: para acessar o endpoint de gravação da sua instância do Cloud SQL, use o método instances:get. Esse endpoint é o valor associado ao parâmetro WriteEndpoint.

Criar o endpoint manualmente

Para criar o endpoint do Private Service Connect manualmente, faça o seguinte:

1. Crie uma instância do Cloud SQL com o Private Service Connect ativado para a instância.

2. Acesse o URI do anexo de serviço. Use esse URI para criar o endpoint do Private Service Connect.

3. Reserve um endereço IP interno para o endpoint do Private Service Connect e crie um endpoint com esse endereço.

Criar uma instância do Cloud SQL

Você pode criar uma instância com o Private Service Connect ativado usando a CLI gcloud, o Terraform ou a API.

Observação : agora é possível criar uma instância que oferece suporte ao acesso a serviços particulares e ao Private Service Connect. Com o Private Service Connect, é possível se conectar a uma instância principal ou a qualquer uma das réplicas de leitura dela de várias redes VPC. Para mais informações, consulte Configurar o acesso a serviços particulares e o Private Service Connect.

gcloud

Para criar uma instância com o Private Service Connect ativado, 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 \
--database-version=DATABASE_VERSION
--cpu=NUMBER_OF_vCPUs \
--memory=MEMORY_SIZE \
--root-password=ROOT_PASSWORD

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 projeto que contém a instância.
• REGION_NAME: o nome da região da instância.

• ALLOWED_PROJECTS: uma lista separada por vírgulas de IDs ou números de projetos permitidos de onde os endpoints do Private Service Connect podem se conectar a instâncias do Cloud SQL.

  Se um projeto não estiver na lista, não será possível criar endpoints do Private Service Connect nele para se conectar à instância.

• AVAILABILITY_TYPE: ativar 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 existente para alta disponibilidade e Desativar a alta disponibilidade de uma instância.

• DATABASE_VERSION: a versão do banco de dados para a instância (por exemplo, SQLSERVER_2019_STANDARD).
• NUMBER_OF_vCPUs: o número de núcleos da instância.
• MEMORY_SIZE: a quantidade de memória para a instância.
• ROOT_PASSWORD: a senha do usuário do Cloud SQL root.

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             = "sqlserver-instance"
  region           = "us-central1"
  database_version = "SQLSERVER_2019_ENTERPRISE"
  root_password    = "INSERT-PASSWORD-HERE"
  settings {
    tier              = "db-custom-2-7680"
    availability_type = "REGIONAL"
    backup_configuration {
      enabled    = true
      start_time = "20:55"
    }
    ip_configuration {
      psc_config {
        psc_enabled               = true
        allowed_consumer_projects = [] # Add consumer project IDs here.
      }
      ipv4_enabled = false
    }
  }
}

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

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto Google Cloud padrão 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 Google Cloud projeto para conferir os resultados. No console do Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu projeto Google Cloud .

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 projeto que contém a instância.
• INSTANCE_NAME: o nome da instância.
• REGION_NAME: o nome da região da instância.
• ROOT_PASSWORD: a senha do usuário do Cloud SQL root.
• AVAILABILITY_TYPE: ativa a alta disponibilidade para a instância. 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 separada por vírgulas de IDs ou números de projetos permitidos de onde os endpoints do Private Service Connect podem se conectar a instâncias do Cloud SQL.

  Se um projeto não estiver na lista, não será possível criar endpoints do Private Service Connect nele para se conectar à instância.

• MACHINE_TYPE: um valor de string enumerado que representa o tipo de máquina da instância. Por exemplo: db-custom-NUMBER_OF_vCPUs-MEMORY_SIZE, em que NUMBER_OF_vCPUs e MEMORY_SIZE são o número de núcleos e a quantidade de memória que você quer para a 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": "SQLSERVER_2019_STANDARD",
  "rootPassword": "ROOT_PASSWORD",
  "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"
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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

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": "[e-mail]",
  "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

Observação: o URI do anexo de serviço é usado para criar o endpoint do Private Service Connect.

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

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 projeto Google Cloud que contém a instância
• INSTANCE_NAME: 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:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Execute o seguinte comando:

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)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Execute o seguinte comando:

$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

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_URI \
   --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 projeto Google Cloud para o endpoint.
   • REGION_NAME: o nome da região do endpoint.
   • SUBNET_URI: o nome da sub-rede do endereço IP. O formato é: projects/SUBNET_PROJECT_ID/regions/REGION_NAME/subnetworks/SUBNET_NAME. Se a sub-rede estiver em uma rede VPC compartilhada, recomendamos que o SUBNET_PROJECT_ID seja o projeto host.
   • 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. Se você não quiser especificar o endereço IP porque quer que Google Cloud reserve um endereço IP disponível na sub-rede, omita essa flag.
   Observação : se a rede VPC e a sub-rede forem compatíveis com endereços IP IPv4 e IPv6 internos, será possível reservar um endereço IPv6 para o endpoint adicionando a seguinte linha de código:

   --ip-version=IPV6

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

   Faça as seguintes substituições:

   • ENDPOINT_NAME: o nome do endpoint.
   • NETWORK_URI: o URI da rede VPC do endpoint. O formato é: projects/NETWORK_PROJECT_ID/global/networks/NETWORK_NAME. Se você quiser usar uma rede VPC compartilhada, especifique o projeto host como o NETWORK_PROJECT_ID.
   • SERVICE_ATTACHMENT_URI: o URI do anexo de serviço
   Com o parâmetro opcional --allow-psc-global-access, os clientes de todas as regiões podem acessar essa regra de encaminhamento.

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.

Use o exemplo a seguir para criar um endpoint do Private Service Connect IPv4.

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.44" # 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 o exemplo a seguir para criar um endpoint do Private Service Connect IPv6.

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
}

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

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto Google Cloud padrão 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 Google Cloud projeto para conferir os resultados. No console do Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu projeto Google Cloud .

REST

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

   Observação : não é possível usar a API para reservar um endereço IP interno para o endpoint. Para reservar esse endereço, use o comando gcloud compute addresses create.

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 projeto 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:

   curl (Linux, macOS ou Cloud Shell)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   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)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   $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

   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.

   Observação : não é possível usar a API para criar o endpoint do Private Service Connect. Para criar esse endpoint, use o comando gcloud compute forwarding-rules create.

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 projeto 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:

   curl (Linux, macOS ou Cloud Shell)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   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)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   $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

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

Conectar usando um registro DNS

O DNS é a maneira recomendada de se conectar a instâncias com o Private Service Connect ativado. Um nome DNS permite que redes diferentes se conectem à mesma instância, em que os endpoints do Private Service Connect em cada rede podem ter endereços IP diferentes. Além disso, o proxy de autenticação do Cloud SQL exige nomes DNS para se conectar a essas instâncias. Para informações sobre como configurar o DNS, consulte Configurar o DNS para o Private Service Connect.

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.

sqlcmd -S DNS_RECORD -d DATABASE_NAME -U USERNAME

Faça as seguintes substituições:

• DNS_RECORD: o registro DNS do endpoint
• DATABASE_NAME: o nome do banco de dados do Cloud SQL para SQL Server contido na instância
• 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 usando o nome do endereço IP do endpoint.

   Observação : use os comandos desta seção para recuperar os endereços IP internos de todos os endpoints criados de forma manual e automática. Para recuperar os endereços IP internos dos endpoints criados automaticamente, consulte Recuperar o endpoint.

   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 projeto 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 projeto 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:

   curl (Linux, macOS ou Cloud Shell)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   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)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   $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

   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. Como alternativa, recupere o endereço IP interno do endpoint do Private Service Connect usando o anexo de serviço da instância do Cloud SQL.

   gcloud

   Para recuperar o endereço IP, use o comando gcloud compute forwarding-rules list:

   gcloud compute forwarding-rules list \
   --filter="TARGET:REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_NAME" \
   --project=PROJECT_ID

   Faça as seguintes substituições:

   • REGION_NAME: o nome da região do endpoint
   • PROJECT_ID: o ID ou número do projeto do Google Cloud projeto que contém o endpoint
   • SERVICE_ATTACHMENT_NAME: o nome do anexo de serviço da instância do Cloud SQL

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

   Confira um exemplo de resposta:

   NAME	REGION	IP_ADDRESS	TARGET
   myInstance	us-central1	10.10.10.10	us-central1/serviceAttachments/a-123456789e0a-psc-service-attachment-abc123d4e5f67gh8

   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 projeto que contém o endpoint
   • REGION_NAME: o nome da região do endpoint
   • SERVICE_ATTACHMENT_PROJECT_ID: o ID ou número do projeto Google Cloud que contém o anexo de serviço
   • SERVICE_ATTACHMENT_NAME: o nome do anexo de serviço da instância do Cloud SQL

   Método HTTP e URL:

   GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules?target="https://www.googleapis.com/compute/v1/projects/SERVICE_ATTACHMENT_PROJECT_ID/regions/REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_NAME"

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

   curl (Linux, macOS ou Cloud Shell)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules?target="https://www.googleapis.com/compute/v1/projects/SERVICE_ATTACHMENT_PROJECT_ID/regions/REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_NAME""

   PowerShell (Windows)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   $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?target="https://www.googleapis.com/compute/v1/projects/SERVICE_ATTACHMENT_PROJECT_ID/regions/REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_NAME"" | Select-Object -Expand Content

   Você receberá uma resposta JSON semelhante a esta:

   {
     "kind": "compute#forwardingRuleList",
     "id": "projects/PROJECT_ID/regions/REGION_NAME/forwardingRules",
     "items": [
       {
         "kind": "compute#forwardingRule",
         "id": "FORWARDING_RULE_ID",
         "creationTimestamp": "2023-10-31T13:04:37.168-07:00",
         "name": "FORWARDING_RULE_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/SERVICE_ATTACHMENT_PROJECT_ID/regions/REGION_NAME/serviceAttachments/SERVICE_ATTACHMENT_NAME",
         "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules/FORWARDING_RULE_NAME",
         "network": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME",
         "serviceDirectoryRegistrations": [
           {
             "namespace": "goog-psc-default"
           }
         ],
         "networkTier": "PREMIUM",
         "labelFingerprint": "LABEL_FINGERPRINT_ID",
         "fingerprint": "FINGERPRINT_ID",
         "pscConnectionId": "PSC_CONNECTION_ID",
         "pscConnectionStatus": "CLOSED",
         "allowPscGlobalAccess": true
       }
     ],
     "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION_NAME/forwardingRules"
   }
   

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

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

   sqlcmd -S IP_ADDRESS -d DATABASE_NAME -U USERNAME

   Faça as seguintes substituições:

   • IP_ADDRESS: o endereço IP do endpoint
   • DATABASE_NAME: o nome do banco de dados do Cloud SQL para SQL Server contido na instância
   • 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.

Configure o proxy de autenticação do Cloud SQL usando o nome DNS do Private Service Connect da sua instância. Um nome DNS identifica um registro DNS que mapeia um recurso DNS para um nome de domínio. Para mais informações sobre como ativar o DNS no seu projeto, consulte Configurar o DNS no Private Service Connect. Para localizar nomes DNS atuais da sua instância, consulte Encontrar nomes DNS.

Também é possível configurar o proxy de autenticação do Cloud SQL para usar o nome DNS do endpoint de gravação do Private Service Connect de um cluster de failover avançado, se você tiver um ativado. Por exemplo, se o nome do endpoint de gravação DNS do Private Service Connect para seu cluster for abcdef123456.987654321fedcb.global.sql-psc.goog, inicie o proxy de autenticação assim:

./cloud-sql-proxy abcdef123456.987654321fedcb.global.sql-psc.goog

Se você estiver se conectando pelo Private Service Connect, será necessário usar o proxy de autenticação do Cloud SQL versão v2.5.0 ou mais recente.

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 de autenticação do Cloud SQL. 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 de autenticação do Cloud SQL é 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 projeto Google Cloud que contém a instância

   O nome da 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 projeto Google Cloud que contém a instância
   • INSTANCE_NAME: 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:

   curl (Linux, macOS ou Cloud Shell)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   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)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   $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

   Você receberá uma resposta JSON semelhante a esta:

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

   O nome da 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 que você copiou na etapa anterior.

   Observação : use a flag psc para iniciar o proxy de autenticação do Cloud SQL e se conectar a instâncias com o Private Service Connect ativado.

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.

Configure o proxy de autenticação do Cloud SQL usando o nome DNS do Private Service Connect da sua instância e o nome DNS do endpoint de gravação do Private Service Connect de um cluster de failover avançado, se você tiver um ativado. Um nome DNS identifica um registro DNS que mapeia um recurso DNS para um nome de domínio. Para mais informações sobre como ativar o DNS no seu projeto, consulte Configurar o DNS no Private Service Connect. Para localizar nomes DNS atuais da sua instância, consulte Encontrar nomes DNS.

Os conectores de linguagem do Cloud SQL são compatíveis com conexões do Private Service Connect pelo tipo de IP PSC nas respectivas bibliotecas. A documentação de cada conector está na documentação pública do GitHub para recuperação de desastres (DR) avançada:

• Conector Python do Cloud SQL (v1.3.0 ou mais recente)
• Conector do Cloud SQL para Go (v1.4.0 ou mais recente)
• Conector Java do Cloud SQL (v1.13.0 ou mais recente)
• Conector do Cloud SQL para Node.js (v0.5.0 ou mais recente)

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 ou o 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 por 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.

Configurar a conectividade de saída para sua instância do Cloud SQL

É possível configurar sua instância do Cloud SQL com o Private Service Connect ativado para ter conectividade de saída com sua rede usando uma interface do Private Service Connect e um anexo de rede. Para mais informações sobre como funciona a conectividade de saída do Private Service Connect e as limitações dela, consulte Visão geral da conectividade de saída do Private Service Connect.

Para usar a conectividade de saída com sua instância do Cloud SQL, você precisa:

1. Crie ou atualize um anexo de rede. Esse anexo de rede é usado pela instância do Cloud SQL para se conectar à interface do Private Service Connect da sua rede.

   1. O anexo de rede precisa estar na mesma região da instância do Cloud SQL e configurado para aceitar conexões automaticamente usando uma lista de interfaces do Private Service Connect.

      Observação: se uma instância do Cloud SQL estiver configurada para alta disponibilidade, ela vai precisar de dois endereços IP: um para a instância principal e outro para a instância em espera.

   2. Receba o ID do projeto de locatário do Cloud SQL. Use o comando gcloud sql instances describe para recuperar detalhes sobre a instância. Você pode encontrar o ID do projeto do locatário no URL do anexo de serviço mostrado na saída:

        ADMIN_PROJECT=PROJECT_ID
        INSTANCE_NAME=INSTANCE_NAME
      
        TENANT_PROJECT_ID=$(gcloud --project=$ADMIN_PROJECT sql instances describe $INSTANCE_NAME | grep pscServiceAttachmentLink | cut -f 2 -d "/")
      

      Substitua:

      • PROJECT_ID: o ID do projeto Google Cloud que você está usando.
      • INSTANCE_NAME: o nome da instância do Cloud SQL habilitada para o Private Service Connect que você quer configurar para conectividade de saída.

      Salve o valor do ID do projeto de locatário para incluir mais tarde na lista de IDs de projetos aceitos. Isso é necessário quando você cria ou atualiza um anexo de rede no seu projeto Google Cloud .

2. Identifique a rede que você quer receber conexões de saída do Cloud SQL e verifique se ela tem uma interface do Private Service Connect.

3. Ative as conexões de saída com a instância do Cloud SQL usando a vinculação de rede.

Você também pode desativar a conectividade de saída a qualquer momento quando não precisar mais de conexões de saída para sua instância.

Para mais informações sobre a conectividade de saída do Private Service Connect, consulte Conexões de saída do Private Service Connect.

Ativar conexões de saída para sua instância do Cloud SQL

Para ativar a conectividade de saída da sua instância do Cloud SQL, primeiro crie ou atualize um anexo de rede no seu projeto Google Cloud .

Observação: a ativação da conectividade de saída do Private Service Connect exige tempo de inatividade. Essa operação leva cerca de 8 minutos para ser concluída, com um tempo de inatividade aproximado de 3 minutos.

gcloud

Para ativar a conectividade de saída, execute o seguinte comando:

gcloud beta sql instances patch INSTANCE_NAME \
  --psc-network-attachment-uri=NETWORK_ATTACHMENT_URI \
  --project=PROJECT_ID

Substitua:

• INSTANCE_NAME: o nome da instância do Cloud SQL habilitada para o Private Service Connect que você quer configurar para conectividade de saída.
• NETWORK_ATTACHMENT_URI: o URI do anexo de rede no projeto Google Cloud que você quer usar para se conectar à interface do Private Service Connect da sua rede.
• PROJECT_ID: o ID do projeto do Google Cloud que você está usando.

Para confirmar se a conectividade de saída do Private Service Connect foi ativada, execute gcloud sql instances describe. Se você vir psc-network-attachment-uri na saída, a conectividade de saída do Private Service Connect foi ativada com sucesso.

REST v1

Para ativar a conectividade de saída, execute o seguinte comando:

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

• PROJECT_ID: ID do projeto.
• NETWORK_ATTACHMENT_URI: o URI do anexo de rede no seu projeto.
• INSTANCE_ID: o nome da sua instância do Cloud SQL.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "settings": {
    "ipConfiguration": {
      "pscConfig: {
        "networkAttachmentUri": "NETWORK_ATTACHMENT_URI"
        "kind": "sql#settings"
      }
    },
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": USER,
  "insertTime": "2025-05-13T20:44:23.064Z",
  "operationType": "UPDATE",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID","
}

REST v1beta4

Para ativar a conectividade de saída, execute o seguinte comando:

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

• PROJECT_ID: ID do projeto.
• NETWORK_ATTACHMENT_URI: o URI do anexo de rede no seu projeto.
• INSTANCE_ID: o nome da sua instância do Cloud SQL.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "settings": {
    "ipConfiguration": {
      "pscConfig: {
        "networkAttachmentUri": "NETWORK_ATTACHMENT_URI"
      }
    },
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": USER,
  "insertTime": "2025-05-13T20:44:23.064Z",
  "operationType": "UPDATE",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID","
}

Para informações sobre a solução de problemas relacionados à conectividade de saída do Private Service Connect, consulte Solução de problemas do Private Service Connect.

Desativar conexões de saída para sua instância do Cloud SQL

Observação: desativar a conectividade de saída do Private Service Connect requer tempo de inatividade. Essa operação leva cerca de 8 minutos para ser concluída, com um tempo de inatividade aproximado de 3 minutos.

gcloud

Para desativar a conectividade de saída, execute o seguinte comando:

gcloud beta sql instances patch INSTANCE_NAME \
  --clear-psc-network-attachment-uri \
  --project=PROJECT_ID

Substitua:

• INSTANCE_NAME: o nome da instância do Cloud SQL habilitada para o Private Service Connect que você quer configurar para conectividade de saída.
• PROJECT_ID: o ID do projeto do Google Cloud que você está usando.

REST v1

Para desativar a conectividade de saída, execute o seguinte comando:

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

• PROJECT_ID: ID do projeto.
• NETWORK_ATTACHMENT_URI: o URI do anexo de rede no seu projeto. Para desativar, defina como null.
• INSTANCE_ID: o nome da sua instância do Cloud SQL.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "settings": {
    "ipConfiguration": {
      "pscConfig: {
        "networkAttachmentUri": null,
        "kind": "sql#settings"
      }
    },
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": USER,
  "insertTime": "2025-05-13T20:44:23.064Z",
  "operationType": "UPDATE",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID","
}

REST v1beta4

Para desativar a conectividade de saída, execute o seguinte comando:

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

• PROJECT_ID: ID do projeto.
• NETWORK_ATTACHMENT_URI: o URI do anexo de rede no seu projeto. Para desativar, defina como null.
• INSTANCE_ID: o nome da sua instância do Cloud SQL.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "settings": {
    "ipConfiguration": {
      "pscConfig: {
        "networkAttachmentUri": null,
        "kind": "sql#settings"
      }
    },
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": USER,
  "insertTime": "2025-05-13T20:44:23.064Z",
  "operationType": "UPDATE",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID","
}

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 SQL Server, o número da porta é 1433.

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 projeto 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 SQL Server, o número da porta é 1433.
• 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:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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

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
}

Observação : além de testar a conectividade, é possível restringir a conectividade dos consumidores de serviço em uma rede VPC aos endpoints do Private Service Connect. Para fazer isso, use o comando gcloud compute firewall-rules create para criar uma regra de firewall de saída de rede. Essa regra se aplica ao endereço IP de um endpoint. Para a regra, defina como origem todas as VMs na rede VPC e especifique uma tag ou conta de serviço.

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.

  Se você precisar se conectar de mais redes VPC, use a propagação de endpoint do Private Service Connect pelo NCC. Para mais informações, consulte Propagação de endpoints do Private Service Connect.

• É possível ter até 64.512 conexões simultâneas com o Private Service Connect em uma instância do Cloud SQL.

• 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 essa flag porque ela está associada ao acesso a serviços particulares.
  • --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 configurar uma instância que tenha o Private Service Connect ativado para usar o acesso a serviços particulares ou conexões IP externo.

  • 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 particulares 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, o Database Migration Service ou o Datastream 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.

  • A lista de permissões baseada em IP aplicada pelo Acesso baseado no contexto não é compatível.

  • Para instâncias do Cloud SQL com o Private Service Connect ativado, o Serviço Gerenciado para Microsoft Active Directory (também chamado de Microsoft AD gerenciado) não é compatível.

  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.	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 projeto 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 projeto 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: curl (Linux, macOS ou Cloud Shell) Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list. Execute o seguinte comando: 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) Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list. Execute o seguinte comando: $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 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 } Verifique se o status do endpoint é ACCEPTED. Se o status for PENDING, a instância não estará permitindo o projeto 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.
  ERROR: (gcloud.compute.forwarding-rules.create) Could not fetch resource: The resource 'projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME' was not found	Essa mensagem de erro pode ocorrer ao reservar um endereço IP interno estático para o endpoint do Private Service Connect. Verifique se a sub-rede especificada existe no projeto indicado pelo URI. Se você quiser criar um endpoint em um projeto de serviço, mas usar uma sub-rede de uma rede VPC compartilhada, especifique a sub-rede pelo URI e use o ID do projeto host no URI. Para mais informações, consulte Criar o endpoint manualmente.
  ERROR: (gcloud.compute.forwarding-rules.create) Could not fetch resource: - The resource 'projects/PROJECT_ID/global/networks/NETWORK_NAME' was not found	Essa mensagem de erro pode ocorrer quando você cria um endpoint do Private Service Connect manualmente. Verifique se a rede especificada existe no projeto indicado pelo URI. Se você quiser criar um endpoint em um projeto de serviço, mas usar uma rede VPC compartilhada, especifique a rede pelo URI e use o ID do projeto host no URI. Para mais informações, consulte Criar o endpoint manualmente.
  Invalid consumer network status for PSC auto connection.	A rede do consumidor não está configurada corretamente ou não está configurada, e, portanto, nenhum endpoint está disponível para conexão. Para se conectar ao endpoint, verifique o status dele e corrija o erro antes de tentar se conectar novamente. Para verificar o status de um endpoint, consulte Recuperar o endpoint. O status do endpoint pode ser um dos seguintes: CONNECTION_POLICY_MISSING: não há uma política de conexão de serviço correspondente na rede do consumidor. As políticas de conexão de serviço são configuradas por rede e por região. Para reconfigurar a rede, consulte Atualizar uma política de conexão de serviço. CONSUMER_INSTANCE_PROJECT_NOT_ALLOWLISTED: há uma política de conexão de serviço correspondente, mas o campo Escopo da instância de serviço na política não está configurado para permitir a conexão com essa instância do Cloud SQL. Atualize a política para configurar o valor do campo Escopo da instância de serviço (--producer-instance-location) com o projeto, a pasta ou a organização em que a instância do Cloud SQL está localizada. Para reconfigurar a política de conexão de serviço, consulte Atualizar uma política de conexão de serviço. POLICY_LIMIT_REACHED: a política de conexão de serviço atingiu o limite de endpoints. Para resolver isso, aumente o limite de endpoints atualizando a política de conexão de serviço.
  No permission to create a service connection policy.	Você não tem as permissões necessárias para criar uma política de conexão de serviço. Para criar uma política de conexão de serviço, você precisa da função Compute Network Admin IAM. Para mais informações, consulte Papéis e permissões.
  O anexo de rede não pode aceitar conexões da interface do Private Service Connect ao usar a conectividade de saída do Private Service Connect.	Se a rede externa não puder aceitar conexões da interface do Private Service Connect, as políticas de conexão no anexo de rede talvez não estejam configuradas corretamente. Os anexos de rede precisam ser configurados para aceitar todas as conexões automaticamente ou manualmente com uma lista de conexões aceitas. Para mais informações, consulte Políticas de conexão. Use o comando a seguir para verificar as conexões aceitas na sua vinculação de rede: gcloud compute network-attachments describe default --region=REGION_ID Se a interface do Private Service Connect não estiver na lista de aceitas, atualize o anexo de rede. Para mais informações, consulte Gerenciar anexos de rede.

  A seguir

  • Saiba mais sobre IP privado.
  • Saiba mais sobre o Private Service Connect.
  • Saiba mais sobre como criar uma réplica de leitura de uma instância com o Private Service Connect ativado.
  • Saiba mais sobre como clonar uma instância com o Private Service Connect ativado.
  • Saiba mais sobre como ver informações resumidas sobre instâncias com o Private Service Connect ativado.
  • Saiba mais sobre como configurar e remover a alta disponibilidade de uma instância com o Private Service Connect ativado.
  • Saiba mais sobre como editar e excluir uma instância com o Private Service Connect ativado.