Conectar-se a uma instância usando um endpoint de gravação

Visão geral

Nesta página, mostramos como usar um endpoint de gravação para se conectar de clientes na sua rede de nuvem privada virtual (VPC) a uma instância do Cloud SQL usando o acesso a serviços particulares (PSA).

Um endpoint de gravação é um nome de serviço de nome de domínio (DNS) global que se refere automaticamente ao endereço IP da instância principal atual. No caso de uma operação de failover ou alternância da réplica, esse endpoint de gravação redireciona automaticamente as conexões de entrada para a nova instância principal. É possível usar o endpoint de gravação em uma string de conexão SQL com a instância do Cloud SQL em vez de um endereço IP. Ao usar um endpoint de gravação, você evita ter que fazer mudanças na conexão do aplicativo quando realiza uma operação de failover ou switchover de réplica para recuperação de interrupção regional ou simulação de recuperação de desastres.

Cada instância qualificada do Cloud SQL tem um único endpoint de gravação integrado cujo nome, criação e atualização são gerenciados pelo Cloud SQL. O exemplo a seguir ilustra o formato:

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
  

O endpoint de gravação sempre termina com o sufixo .global.sql-psa.goog.. Não é possível modificar o nome ou o formato desse endpoint de gravação gerenciado pelo Cloud SQL.

É possível usar o endpoint de gravação para todas as operações de gravação na instância principal, incluindo inserções, atualizações, exclusões e mudanças de DDL. Também é possível usar o endpoint de gravação para operações de leitura, como consultas. O endereço IP privado apontado pelo endpoint de gravação é mudado automaticamente pelo Cloud SQL quando você realiza uma operação de failover ou alternância de réplica para promover uma instância de réplica como a nova instância principal.

Gerar o endpoint de gravação

Se você criar uma instância do Cloud SQL, o Cloud SQL vai criar automaticamente o endpoint de gravação quando os seguintes pré-requisitos forem atendidos:

  • As seguintes APIs precisam estar ativadas no projeto Google Cloud em que sua instância do Cloud SQL está localizada:

    Se a API Cloud DNS não for ativada no projeto, a zona de DNS de peering não será criada, o que vai tornar os nomes DNS inutilizáveis.

    Depois que a zona de DNS de peering é criada, é importante que ela não seja modificada de forma alguma. Qualquer modificação, incluindo a exclusão, vai tornar o DNS inutilizável para a conexão do banco de dados.

  • A instância do Cloud SQL precisa ser da edição Enterprise Plus.
  • A instância do Cloud SQL precisa ser configurada para usar um IP particular com o acesso a serviços particulares (PSA) ativado.
  • O recurso exige instâncias na nova arquitetura de rede. Na maioria dos casos, as novas instâncias são criadas com a nova arquitetura. Para verificar isso, confira a arquitetura de rede da sua instância.

Quando você faz upgrade de uma instância do Cloud SQL Enterprise para uma do Cloud SQL Enterprise Plus, o Cloud SQL gera automaticamente o endpoint de gravação se os pré-requisitos listados anteriormente forem atendidos. Se a instância estiver na arquitetura de rede antiga, primeiro faça upgrade para a nova arquitetura para receber o endpoint de gravação.

Se você já tiver uma instância do Cloud SQL edição Enterprise Plus sem o endpoint de gravação e quiser que o Cloud SQL gere um endpoint de gravação automaticamente, crie uma réplica ativada para recuperação avançada de desastres.

Ver o endpoint de gravação

gcloud

Para encontrar o endpoint de gravação, use o seguinte comando da CLI gcloud:

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Faça as seguintes substituições:

INSTANCE_NAME: o nome da instância do Cloud SQL.

Os endpoints de gravação sempre terminam com o sufixo .global.sql-psa.goog., semelhante ao exemplo a seguir:

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
  

Se você não encontrar o endpoint de gravação de uma instância qualificada, consulte Solução de problemas.

Conectar-se a uma instância do Cloud SQL usando um endpoint de gravação

psql

Para conectar um cliente psql a uma instância do Cloud SQL usando o endpoint de gravação, execute o seguinte comando:

    psql -U DATABASE_NAME -h WRITE_ENDPOINT
  

Faça as seguintes substituições:

  • DATABASE_NAME: o nome do banco de dados. Por exemplo, postgres.
  • WRITE_ENDPOINT: o nome DNS ou o endpoint de gravação. Esse valor alfanumérico sempre termina com o sufixo .global.sql-psa.goog.. Por exemplo, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..

Conectar clientes de banco de dados a instâncias de banco de dados usando um endpoint de gravação em uma conexão SSL/TLS

psql

Para conectar clientes de banco de dados a instâncias usando um endpoint de gravação em uma conexão SSL/TLS, execute o seguinte comando:

  psql "sslmode=SSL_MODE \
    sslrootcert=SSL_ROOT_SERVER \
    sslcert=SSL_CERT \
    sslkey=SSL_KEY \
    host=WRITE_ENDPOINT \
    port=PORT user=USERNAME \
    dbname=DATABASE_NAME"
  

Faça as seguintes substituições:

  • SSL_MODE: o modo SSL usado. Por exemplo, verify-full.
  • SSL_ROOT_SERVER: o nome do servidor raiz SSL. Por exemplo, server-ca.pem.
  • SSL_CERT: o nome do certificado SSL usado pelo cliente. Por exemplo, client-cert.pem.
  • SSL_KEY: o nome da chave SSL usada pelo cliente. Por exemplo, client-key.pem.
  • WRITE_ENDPOINT: o nome DNS ou o endpoint de gravação. Esse valor alfanumérico sempre termina com o sufixo .global.sql-psa.goog.. Por exemplo, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
  • PORT: o número da porta usada. Por exemplo, 5432.
  • USERNAME: o nome de usuário. Por exemplo, postgres.
  • DATABASE_NAME: o nome do banco de dados. Por exemplo, postgres.

Limitações

  • Os endpoints de gravação não estão disponíveis para criações de instâncias do Cloud SQL Enterprise.
  • Os endpoints de gravação não estão disponíveis para instâncias somente com IP público ou somente com Private Service Connect.
  • Os endpoints de gravação não estão disponíveis para uso com o proxy do Cloud SQL Auth ou conectores de linguagem.

Solução de problemas

As seções a seguir descrevem a arquitetura dos endpoints de gravação e abordam problemas comuns de solução de problemas.

Arquitetura de um endpoint de gravação

Quando você cria uma instância qualificada, um endpoint de gravação é gerado por padrão.

Para criar um endpoint de gravação, o Cloud SQL realiza a seguinte configuração:

  • Cria uma zona DNS particular na rede VPC do produtor de serviços do Cloud SQL.
  • Cria uma zona de DNS de peering na rede VPC do cliente.
  • Cria um registro DNS na zona DNS particular da rede do produtor de serviços.

O diagrama a seguir ilustra como esse processo funciona:

Diagrama mostrando como o peering de VPC oferece suporte ao peering de zona DNS entre projetos.
Figura 1. Diagrama que mostra como o peering de VPC oferece suporte ao peering de zona de DNS entre uma rede de produtor de serviços e uma rede de clientes.

Problemas de resolução de DNS

Se a resolução de DNS não estiver funcionando, verifique cada um dos seguintes itens:

  1. Verifique se todos os pré-requisitos foram atendidos.
  2. Verifique se os clientes em que a resolução é esperada estão localizados na mesma rede a que a instância do Cloud SQL está anexada. Para verificar isso, use o comando gcloud compute instances list:
    gcloud compute instances list \
       --format="table( name, zone.basename(), networkInterfaces[].network )" \
       --project=PROJECT_NAME

    Substitua PROJECT_NAME pelo nome do projeto em que a rede de consumidor de DNS está localizada.

  3. Verifique se a zona de peering existe. Para fazer isso, use o comando gcloud dns managed-zones list:
    gcloud dns managed-zones list \
        --project=PROJECT_NAME

    Substitua PROJECT_NAME pelo nome do projeto em que a rede de consumidor de DNS está localizada.

  4. Se a zona de peering não existir, use o comando gcloud beta sql instances patch para corrigir o problema:
    gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking

    Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL.

A nova instância não tem um endpoint de gravação

Se uma instância recém-criada não tiver um endpoint de gravação, verifique cada um dos seguintes itens:

  1. Verifique se todos os pré-requisitos foram atendidos.
  2. Verifique se não há uma zona de peering de DNS restante com o nome DNS sql-psa.goog..

    Uma zona de DNS de peering é uma zona de DNS restante se a rede associada a ela não tiver um peering de VPC com o ID do projeto de peering da zona de DNS de peering.

    Se houver uma zona de DNS de peering restante com o sufixo sql-psa.goog., exclua-a.

    Para verificar se há zonas de DNS de peering restantes, use o comando gcloud dns managed-zones list:

    gcloud dns managed-zones list \
       --project=PROJECT_NAME

    Substitua PROJECT_NAME pelo nome do projeto em que a rede de consumidor de DNS está localizada.

    Se houver uma zona de DNS com o sufixo sql-psa.goog., exclua-a depois de verificar se a zona de peering de DNS é uma zona de DNS restante.

    Para excluir uma zona de DNS, use o comando gcloud dns managed-zones delete:

    gcloud dns managed-zones delete ZONE_NAME

    Substitua ZONE_NAME pelo nome da zona de DNS associada aos endpoints de gravação. Os valores são alfanuméricos e usam o seguinte formato: cloud-sql-psa-dns-1234567890.

  3. É possível corrigir um endpoint de gravação ausente para uma instância qualificada usando o comando gcloud beta sql instances patch:
    gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking

    Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL.

A seguir