Configurar o DNS no Private Service Connect

Nesta página, descrevemos como configurar o DNS no Private Service Connect.

Visão geral

O DNS é a maneira recomendada de se conectar a instâncias que têm 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 e os conectores de linguagem exigem nomes DNS para se conectar a essas instâncias.

As instâncias do Cloud SQL com o Private Service Connect ativado podem ter dois tipos de nomes DNS:

  • Um nome DNS por instância. Esse recurso está disponível para instâncias em todas as edições do Cloud SQL. A instância principal e cada instância de réplica têm nomes de DNS por instância diferentes.

  • Um nome de DNS de endpoint de gravação global. Isso está disponível para instâncias na edição Cloud SQL Enterprise Plus, para ajudar na recuperação avançada de desastres (ADR). Um endpoint de gravação é um nome 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 de réplica, esse endpoint de gravação redireciona as conexões de entrada para a nova instância principal automaticamente. 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 alternância de réplica para recuperação de interrupção regional ou um simulado de recuperação de desastres.

Automação de DNS no Private Service Connect

Para criar um nome DNS por instância, use o recurso de automação de DNS do Cloud SQL para configurar os registros e o nome. Quando você ativa a automação de DNS, o Cloud SQL provisiona e gerencia automaticamente os registros DNS para o nome de DNS por instância nas redes VPC consumidoras autorizadas.

Com a automação de DNS ativada em uma instância do Cloud SQL Enterprise Plus, também é possível ativar um nome DNS de endpoint de gravação global que sempre é resolvido automaticamente para o endereço IP da instância principal atual.

Se quiser, você pode configurar manualmente um registro DNS por instância (consulte Configurar o DNS manualmente), mas recomendamos usar a automação de DNS. A configuração manual de DNS é uma opção legada.

Pré-requisitos para ativar a automação de DNS

  • Para usar a automação de DNS ou um nome DNS de endpoint de gravação global, ative a API Cloud DNS.
  • A automação de DNS só pode ser ativada quando o Private Service Connect está ativado (use o parâmetro --enable-private-service-connect).
  • A automação de DNS só pode ser ativada quando há pelo menos uma conexão automática do Private Service Connect especificada (use --psc-auto-connections=network).
  • Um nome de DNS de endpoint de gravação global só pode ser ativado para uma instância da edição Enterprise Plus do Cloud SQL que tenha a automação de DNS ativada.

Configuração de automação de DNS

É possível ativar a automação de DNS e o nome DNS do endpoint de gravação global ao criar uma instância com o Private Service Connect ativado, conforme mostrado em Criar uma instância do Cloud SQL.

Também é possível ativar ou desativar a automação de DNS para instâncias atuais. Quando você faz isso, o Cloud SQL provisiona ou limpa automaticamente os registros DNS associados nas respectivas redes.

gcloud

gcloud sql instances patch INSTANCE_NAME \
  --enable-psc-auto-dns=DNS_ENABLEMENT \
  --enable-psc-write-endpoint-dns=GLOBAL_DNS_ENABLEMENT \

REST

O método HTTP e o URL seriam assim:

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

O corpo da solicitação JSON teria uma forma como esta:

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

Faça as seguintes substituições:

  • DNS_ENABLEMENT: true ou false dependendo se você quer ativar ou desativar a automação de DNS.
  • GLOBAL_DNS_ENABLEMENT: true ou false dependendo se você quer ativar ou desativar um nome DNS de endpoint de gravação global. Se true, então enable-psc-auto-dns também vai precisar ser true.

Ver nomes DNS

É possível encontrar o nome DNS por instância e o nome DNS do endpoint de gravação global do projeto usando o comando describe.

gcloud

Nome DNS por instância

Para encontrar o nome de DNS por instância criado com a automação de DNS, use o comando gcloud sql instances describe desta forma:

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

A saída será semelhante a esta (em que DNS_NAME será o nome DNS por instância):

INSTANCE,CLOUD_SQL_AUTOMATION,DNS_NAME

O nome de DNS vai terminar com o nome da região da instância seguido por .sql-psc-goog, assim:
INSTANCE,CLOUD_SQL_AUTOMATION,d73a167a8c3a.2naantchj3tsc.us-central1.sql-psc.goog.
Para retornar apenas o nome DNS sem decoração, adicione | cut -d, -f3 ao final do comando.

O nome de DNS do endpoint de gravação global

Da mesma forma, use o comando describe para encontrar o nome DNS do endpoint de gravação global do cluster de replicação:

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

A saída será semelhante a esta (em que GLOBAL_DNS_NAME será o nome DNS global do endpoint de gravação do cluster de replicação):

CLUSTER,CLOUD_SQL_AUTOMATION,GLOBAL_DNS_NAME

O nome DNS do endpoint de gravação global termina com .global.sql-psc-goog, assim:
CLUSTER,CLOUD_SQL_AUTOMATION,d73a167a8c3a.2naantchj3tsc.global.sql-psc.goog. Para retornar apenas o nome DNS sem decoração, adicione | cut -d, -f3 ao final do comando.

REST

O método HTTP e o URL seriam assim:

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

O nome DNS por instância e o nome DNS do endpoint de gravação global seriam retornados no campo dnsNames da resposta, assim:

{
  "dnsNames": [
    {
      "connectionType": "PRIVATE_SERVICE_CONNECT",
      "dnsScope": "INSTANCE",
      "name": "31f5395197d0.3e0v7ztul56ph.us-central1.sql.goog.",
      "recordManager": "CUSTOMER"
    },
    {
      "connectionType": "PRIVATE_SERVICE_CONNECT",
      "dnsScope": "INSTANCE",
      "name": "31f5395197d0.3e0v7ztul56ph.us-central1.sql-psc.goog",
      "recordManager": "CLOUD_SQL_AUTOMATION"
    },
    {
      "connectionType": "PRIVATE_SERVICE_CONNECT",
      "dnsScope": "CLUSTER",
      "name": "3lbvojtu2fo6q.3e0v7ztul56ph.global.sql-psc.goog",
      "recordManager": "CLOUD_SQL_AUTOMATION"
    }
  ],
}

É possível usar o nome DNS do endpoint de gravação global ou o nome DNS por instância para se conectar à instância. Consulte Conectar usando um registro DNS.

Campos de status da automação de DNS

É possível determinar o status do DNS para sua instância e cluster de replicação nestes dois campos de saída:

  • instanceAutoDnsStatus: mostra o status do DNS por instância.
  • writeEndpointAutoDnsStatus: mostra o status do DNS do endpoint de gravação global.

Ambos os campos podem ter os seguintes valores:

  • AUTO_DNS_STATUS_UNSPECIFIED
  • AUTO_DNS_OK
  • AUTO_DNS_FAILED
  • AUTO_DNS_UNKNOWN

Esses campos aparecem no campo de saída pscAutoConnections:

    "pscAutoConnections": [
      {
        "consumerNetwork": "projects/my-psc-project/global/networks/psc-dns-net2",
        "consumerNetworkStatus": "VALID",
        "consumerProject": "my-psc-project",
        "instanceAutoDnsStatus": "AUTO_DNS_OK",
        "ipAddress": "10.0.2.4",
        "status": "ACTIVE",
        "writeEndpointAutoDnsStatus": "AUTO_DNS_OK"
      }
    ]

Solução de problemas de automação de DNS

Se a API Cloud DNS não estiver ativada, se a política de conexão do Private Service Connect estiver faltando ou se houver erros de back-end durante a criação do registro DNS, a automação de DNS poderá não criar um registro DNS por instância ou um nome DNS de endpoint de gravação global.

Há duas flags que podem ser usadas com a API update/patch ou a CLI gcloud se você encontrar uma situação em que a automação de DNS não foi provisionada corretamente:

  • --reconcile-psc-networking (boolean): quando definido, o Cloud SQL tenta restaurar as partes da automação de DNS que não estão funcionando. Essa flag não causa inatividade.
  • --reconcile-psc-networking-force (boolean): semelhante a reconcile-psc-networking, mas, se definido, o Cloud SQL tenta restaurar completamente toda a automação de DNS ao custo de um breve tempo de inatividade nas partes de automação de DNS do PSC que estão funcionando. Isso pode ajudar em alguns casos em que reconcile-psc-networking não ajuda.

Atribuir nomes DNS personalizados

É possível configurar nomes DNS personalizados para suas instâncias do Cloud SQL do Private Service Connect. Basta criar um registro CNAME com o nome DNS da instância do Private Service Connect como valor. Por exemplo, se você quiser configurar seus aplicativos usando o nome DNS do banco de dados sample-db.mycompany.example.com para se referir à instância do banco de dados com o nome DNS do Private Service Connect abcdef123456.987654321fedcb.us-central1.sql-psc.goog, primeiro configure a instância com um nome DNS personalizado e crie um registro DNS CNAME usando o provedor de DNS:

NOME TIPO TTL VALOR
sample-db.mycompany.example.com CNAME 600 abcdef123456.987654321fedcb.us-central1.sql-psc.goog

Configurar o DNS manualmente

Recomendamos usar a automação de DNS, porque a configuração manual é uma opção legada. Também é possível configurar manualmente um registro DNS por instância para a instância. Um nome DNS oferece uma maneira consistente de usar o proxy de autenticação ou conectores de linguagem para se conectar de diferentes redes. A resposta da API de pesquisa de instâncias fornece um nome DNS sugerido que pode ser usado para criar o registro DNS em uma zona de DNS particular na rede VPC correspondente.

gcloud

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

            gcloud sql instances describe INSTANCE_NAME \
          --project=PROJECT_ID

    Faça estas 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

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

    Se você quiser usar um nome DNS personalizado para se conectar a uma instância do Cloud SQL em vez do nome DNS predefinido nesta seção, configure a configuração de nome alternativo do assunto (SAN) personalizada ao criar a instância. O nome DNS personalizado inserido na configuração SAN personalizada é adicionado ao campo SAN do certificado do servidor da instância. Isso permite usar o nome DNS personalizado com validação segura do nome de host.

    Para mais informações sobre como configurar a SAN personalizada, consulte Criar instâncias.

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

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

    Faça as seguintes substituições:

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

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

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

    Faça as seguintes substituições:

    • DNS_RECORD: o nome do registro DNS. Esse registro é definido como o nome DNS que você extraiu da instância do Cloud SQL anteriormente neste procedimento (por exemplo,
      1a23b4cd5e67.1a2b345c6d27.us-central1.sql.goog.).
    • RRSET_TYPE: o tipo de registro de recurso do conjunto de registros DNS. Se o endereço IP interno reservado para o endpoint do Private Service Connect for um endereço IPv4, especifique A para esse parâmetro. Caso contrário, se o endereço IP do endpoint for um endereço IPv6, especifique AAAA.
    • RR_DATA: o endereço IP alocado para o endpoint do Private Service Connect (por exemplo, 198.51.100.5). Também é possível inserir vários valores, como rrdata1 rrdata2 rrdata3 (por exemplo,
      10.1.2.3 10.2.3.4 10.3. 4.5).

REST

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

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

    • PROJECT_ID: o ID ou número do projeto do 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:

    Você receberá uma resposta JSON semelhante a esta:

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

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

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

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

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

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

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

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

    Você receberá uma resposta JSON semelhante a esta:

    {
  "name": "ZONE_NAME",
  "dnsName": "DNS_NAME",
  "description": "DESCRIPTION",
  "id": "ID",
  "nameServers": [
    "ns-gcp-private.googledomains.com."
  ],
  "creationTime": "2024-05-10T17:05:34.607Z",
  "visibility": "private",
  "privateVisibilityConfig": {
    "networks": [
      {
        "networkUrl": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/NETWORK_NAME",
        "kind": "dns#managedZonePrivateVisibilityConfigNetwork"
      }
    ],
    "gkeClusters": [],
    "kind": "dns#managedZonePrivateVisibilityConfig"
  },
  "cloudLoggingConfig": {
    "kind": "dns#managedZoneCloudLoggingConfig"
  },
  "kind": "dns#managedZone"
}
  3. Depois de criar o endpoint do Private Service Connect, crie um registro DNS na zona.

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

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

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

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

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

    Você receberá uma resposta JSON semelhante a esta:

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