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

Esta página descreve como usar o Private Service Connect para se conectar a uma instância do AlloyDB para PostgreSQL.

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

Funções exigidas

É necessário conceder todos os papéis a seguir a um usuário na sua rede VPC para se conectar a uma instância do AlloyDB.

Papel	Descrição
compute.networkAdmin	Concede controle total sobre a rede VPC que inicia uma conexão com uma instância do AlloyDB. Se você usar o Private Service Connect para se conectar a uma instância do AlloyDB 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.
alloydb.admin	Concede controle total sobre uma instância do AlloyDB e controla a instância durante o ciclo de vida dela.
alloydb.databaseUser (opcional)	Dá acesso à instância do AlloyDB. Se você se conectar pelo cliente do proxy de autenticação do AlloyDB, é necessário ter o papel de cliente do AlloyDB. Se a conexão for direta, não serão necessários papéis e permissões do Identity and Access Management (IAM).

Ativar o Private Service Connect

Ativar o Private Service Connect envolve criar um cluster do AlloyDB com o Private Service Connect configurado e, em seguida, criar uma instância do AlloyDB com uma lista de projetos permitidos.

Criar um cluster principal do AlloyDB

O exemplo a seguir usa o comando gcloud alloydb clusters create com a flag --enable-private-service-connect, que cria um cluster do AlloyDB com o Private Service Connect ativado.

O processo de criação de um cluster permanece o mesmo, exceto pela transmissão da flag --enable-private-service-connect. Para informações detalhadas sobre a criação de um cluster, consulte Criar o cluster e a instância principal.

Para criar o cluster, use o comando gcloud alloydb clusters create.

  gcloud alloydb clusters create CLUSTER_ID \
    --password=PASSWORD \
    --region=REGION_ID \
    --project=PROJECT_ID \
    --enable-private-service-connect

Substitua:

• CLUSTER_ID: o ID do cluster que você está criando. Ele precisa começar com uma letra minúscula e pode conter letras minúsculas, números e hifens.

• PASSWORD: a senha a ser usada para o usuário postgres padrão.

• REGION_ID: a região em que você quer colocar o cluster.

• PROJECT_ID: o ID do projeto em que você quer colocar o cluster.

Esse comando inicia uma operação de longa duração, retornando um ID de operação.

Um cluster secundário criado para um cluster principal ativado pelo Private Service Connect herda automaticamente a configuração do Private Service Connect. Para mais informações, consulte Criar um cluster secundário.

Criar uma instância do AlloyDB

O exemplo a seguir mostra como criar uma instância principal com uma lista de projetos permitidos configurados. O processo de criação de uma instância permanece o mesmo, exceto pela transmissão da lista de projetos permitidos usando a flag --allowed-psc-projects para um cluster principal ativado pelo Private Service Connect.

Para mais informações sobre como criar outros tipos de instância, consulte Criar uma instância de pool de leitura e Criar uma instância secundária.

Para criar a instância principal, use o comando gcloud alloydb instances create.

  gcloud alloydb instances create INSTANCE_ID \
      --instance-type=PRIMARY \
      --cpu-count=CPU_COUNT \
      --availability-type=AVAILABILITY \
      --region=REGION_ID \
      --cluster=CLUSTER_ID \
      --project=PROJECT_ID \
      --allowed-psc-projects=ALLOWED_PROJECT_LIST

Substitua:

• INSTANCE_ID: o ID da instância que você está criando. Ele precisa começar com uma letra minúscula e pode conter letras minúsculas, números e hifens.
• CPU_COUNT: o número de vCPUs que você quer para a instância. Os valores válidos incluem:
  • 2: 2 vCPUs, 16 GB de RAM
  • 4: 4 vCPUs, 32 GB de RAM
  • 8: 8 vCPUs, 64 GB de RAM
  • 16: 16 vCPUs, 128 GB de RAM
  • 32: 32 vCPUs, 256 GB de RAM
  • 64: 64 vCPUs, 512 GB de RAM
  • 96: 96 vCPUs, 768 GB de RAM
  • 128: 128 vCPUs, 864 GB de RAM
• AVAILABILITY: indica se a instância precisa ou não de alta disponibilidade (HA), com nós em várias zonas. Os valores válidos incluem:
  • REGIONAL: cria uma instância de HA com nós ativos e de espera separados e failover automático entre eles. Esse é o valor padrão, adequado para ambientes de produção.
  • ZONAL: cria uma instância básica, contendo apenas um nó e sem failover automatizado.
• REGION_ID: a região em que você quer que a instância seja colocada.
• CLUSTER_ID: o ID do cluster que você criou anteriormente.
• ALLOWED_PROJECT_LIST: a lista separada por vírgulas dos IDs ou números de projeto que você quer permitir o acesso à instância. Por exemplo, my-project-1, 12345,my-project-n.

Acessar o anexo de serviço

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

Use o comando gcloud alloydb instances describe para conferir detalhes sobre uma instância.

gcloud alloydb instances describe INSTANCE_ID \
 --cluster=CLUSTER_ID --region=REGION_ID

Substitua:

• INSTANCE_ID: o ID da instância.
• CLUSTER_ID: o ID do cluster.
• REGION_ID: a região em que o cluster do AlloyDB é implantado.

Um exemplo de resposta para o comando é o seguinte:

  "pscInstanceConfig": {
    "serviceAttachmentLink:": "https://www.googleapis.com/compute/v1/projects/my-project/regions/my-region/serviceAttachments/my-service-attachment-id"
        "allowedConsumerProjects": {
          "45678",
          "12345",
              "67890",
            },
            "pscDnsName": "11111111-1111-1111-1111-111111111111.22222222-2222-2222-2222-222222222222.alloydb-psc.goog."
          }

O parâmetro pscServiceAttachmentLink contém o valor do URL do anexo de serviço.

Criar um endpoint do Private Service Connect

Para criar um endpoint do Private Service Connect, transmita o URL do anexo do serviço com um nome de endpoint exclusivo. Para mais informações sobre como criar um endpoint do Private Service Connect, consulte Criar um endpoint.

Também é possível reservar um endereço IP interno para o endpoint do Private Service Connect usando o comando gcloud compute addresses create e, em seguida, usar o endereço IP reservado ao criar o endpoint.

Conectar-se a uma instância do AlloyDB

É possível se conectar a uma instância do AlloyDB com o Private Service Connect ativado usando uma das seguintes opções:

• um endereço IP interno,
• um registro DNS
• Proxy de autenticação do AlloyDB
• Conectores de linguagem do AlloyDB

Para se conectar usando registros DNS, é necessário criar um registro DNS em uma zona de DNS particular na rede VPC correspondente. Depois de criar um registro DNS, você pode usá-lo para se conectar a uma instância ativada do Private Service Connect diretamente usando um registro DNS, o proxy de autenticação do AlloyDB ou os conectores de linguagem do AlloyDB.

Configurar uma zona gerenciada de DNS e um registro DNS

Para configurar uma zona gerenciada de DNS e um registro DNS na sua rede, siga estas etapas:

1. Para conferir informações resumidas sobre uma instância do AlloyDB, incluindo o nome DNS da instância, use o comando gcloud alloydb instances describe:

   gcloud alloydb instances describe INSTANCE_ID \
   --project=CLUSTER_ID

   Substitua:

   • INSTANCE_ID: o ID da instância.
   • CLUSTER_ID: o ID do cluster.

   Na resposta, verifique se o nome DNS é exibido. O nome do DNS tem o padrão INSTANCE_UID.PROJECT_UID.REGION_NAME.alloydb-psc.goog..

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

   Observação: crie uma zona de DNS separada para cada rede VPC.

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

   Substitua:

   • ZONE_NAME: o nome da zona de DNS.
   • PROJECT_ID: o ID ou o número do projeto Google Cloud que contém a zona.
   • DESCRIPTION: uma descrição da zona (por exemplo, uma zona DNS para a instância do AlloyDB).
   • DNS_NAME: o nome DNS da zona, como INSTANCE_UID.PROJECT_UID.REGION_NAME.alloydb-psc.goog..
   • 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_NAME \
   --project=PROJECT_ID \
   --type=RRSET_TYPE \
   --rrdatas=RR_DATA \
   --zone=ZONE_NAME

   Substitua:

   • DNS_NAME: o nome de DNS que você recuperou anteriormente neste procedimento.
   • RRSET_TYPE: o tipo de registro de recurso do conjunto de registros DNS (por exemplo, A).
   • RR_DATA: o endereço IP alocado para o endpoint do Private Service Connect (por exemplo, 198.51.100.5). Também é possível inserir vários valores, como rrdata1 rrdata2 rrdata3 (por exemplo, 10.1.2.3 10.2.3.4 10.3.4.5).

Conectar-se diretamente usando um registro DNS

Depois de criar um endpoint do Private Service Connect e um registro DNS, você pode se conectar diretamente usando o registro DNS.

1. Para recuperar o registro DNS do endpoint do Private Service Connect, use o comando gcloud compute addresses describe:

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

   Substitua:

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

2. Para se conectar à instância do AlloyDB, use o registro DNS.

   psql user=USERNAME host=DNS_RECORD

   Substitua:

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

Conectar usando o proxy de autenticação do AlloyDB

O proxy de autenticação do AlloyDB é um conector que permite fazer conexões autorizadas e criptografadas com bancos de dados do AlloyDB. O proxy de autenticação do AlloyDB funciona com um cliente local em execução no ambiente local. O aplicativo se comunica com o proxy de autenticação do AlloyDB com o protocolo de banco de dados padrão usado por seu banco de dados.

Quando você define a flag --psc ao iniciar o cliente do proxy de autenticação, o proxy de autenticação do AlloyDB usa o registro DNS criado para se conectar à instância com o Private Service Connect ativado.

Inicie o cliente do proxy de autenticação transmitindo o URI da instância que você extraiu usando o comando gcloud alloydb instances list e defina a flag --psc.

Para mais informações sobre como se conectar a uma instância usando o proxy de autenticação, consulte Conectar usando o proxy de autenticação.

Conectar usando os conectores de linguagem do AlloyDB

Os conectores de linguagem do AlloyDB são bibliotecas que fornecem mTLS automatizado com TLS 1.3 e autorização de Identity and Access Management (IAM) ao se conectar a uma instância do AlloyDB.

Depois que o conector de linguagem determina que a instância oferece suporte ao Private Service Connect, ele usa o registro DNS que você criou para se conectar à instância.

Java

Se você estiver usando o Private Service Connect para se conectar à instância do AlloyDB, inclua o seguinte:

config.addDataSourceProperty("alloydbIpType", "PSC");

Para mais informações sobre como usar o endpoint do Private Service Connect nos conectores de linguagem Java, consulte o repositório do GitHub.

Python (pg8000)

Se você estiver usando o Private Service Connect para se conectar à instância do AlloyDB, inclua o seguinte:

  def getconn() -> pg8000.dbapi.Connection:
      conn: pg8000.dbapi.Connection = connector.connect(
          inst_uri,
          "pg8000",
          user=user,
          password=password,
          db=db,
          # use ip_type to specify PSC
          ip_type=IPTypes.PSC,
      )
      return conn

Para mais informações sobre como usar o endpoint do Private Service Connect nos conectores de linguagem Python, consulte o repositório do GitHub.

Python (asyncpg)

Se você estiver usando o Private Service Connect para se conectar à instância do AlloyDB, inclua o seguinte:

  async def getconn() -> asyncpg.Connection:
    conn: asyncpg.Connection = await connector.connect(
        inst_uri,
        "asyncpg",
        user=user,
        password=password,
        db=db,
        # use ip_type to specify PSC
        ip_type=IPTypes.PSC,
    )
    return conn

Para mais informações sobre como usar o endpoint do Private Service Connect nos conectores de linguagem Python, consulte o repositório do GitHub.

Go (pgx)

Se você estiver usando o Private Service Connect para se conectar à instância do AlloyDB, inclua o seguinte:

d.Dial(ctx, instURI, alloydbconn.WithPSC())

Para mais informações sobre como usar o endpoint do Private Service Connect nos conectores da linguagem Go, consulte o repositório do GitHub.

Go (database/sql)

Se você estiver usando o Private Service Connect para se conectar à instância do AlloyDB, inclua o seguinte:

  cleanup, err := pgxv5.RegisterDriver(
    "alloydb",
    alloydbconn.WithDefaultDialOptions(alloydbconn.WithPSC())
)

Para mais informações sobre como usar o endpoint do Private Service Connect nos conectores da linguagem Go, consulte o repositório do GitHub.

Conectar diretamente por um endereço IP interno

Depois de criar um endpoint do Private Service Connect, você pode se conectar diretamente a uma instância do AlloyDB usando o endereço IP configurado.

1. Para recuperar o endereço IP do endpoint do Private Service Connect, use o comando gcloud compute addresses describe:

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

   Substitua:

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

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

   psql user=USERNAME hostaddr=IP_ADDRESS"

   Substitua:

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

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 AlloyDB com o Private Service Connect ativado.
• Não é possível usar a flag --network ao criar um cluster ativado para o Private Service Connect porque ela está associada ao acesso a serviços privados.
• Não é possível ativar ou desativar o Private Service Connect em uma instância.
• Não é possível configurar uma instância que tenha o Private Service Connect ativado para usar o Acesso a serviços privados.
• As extensões pglogical, dblink e postgres_fdw que exigem conectividade de saída não são compatíveis.