Acessar APIs do Google por endpoints

Neste documento, explicamos como usar os endpoints do Private Service Connect para se conectar às APIs do Google. Em vez de enviar solicitações de API para os endereços IP disponíveis publicamente para endpoints de serviço, como storage.googleapis.com, envie as solicitações para o endereço IP interno de um endpoint.

Também é possível usar o Private Service Connect para acessar serviços em outra rede VPC e para publicar serviços.

Papéis

Os papéis do IAM a seguir fornecem as permissões necessárias para executar as tarefas neste guia.

Tarefa Papéis
Crie um endpoint Todas as seguintes funções:
Administrador de rede do Compute (roles/compute.networkAdmin ),
Editor do Diretório de serviços (roles/servicedirectory.editor ), e
Administrador do DNS (roles/dns.admin .
Configurar o Acesso privado do Google (opcional) Administrador de rede do Compute (roles/compute.networkAdmin)

Antes de começar

  • Para mais informações, incluindo configurações e limitações de DNS, leia Sobre a conexão com APIs do Google usando endpoints.

  • O Private Service Connect não ativa automaticamente nenhuma API. É necessário ativar as APIs do Google separadamente na página de APIs e serviços do Console do Google Cloud.

  • Você precisa ativar a API Compute Engine no projeto.

  • Você precisa ativar a API Service Directory no seu projeto.

  • Você precisa ativar a API Cloud DNS no seu projeto.

  • Escolha um endereço IP para o endpoint. Para informações sobre quais endereços IP podem ser usados, consulte Requisitos de endereço IP.

  • As regras de firewall de saída precisam permitir tráfego para o endpoint. A configuração padrão de firewall para uma rede VPC permite esse tráfego porque contém uma regra de saída de permissão implícita. Verifique se você não criou uma regra de saída de prioridade mais alta que bloqueia o tráfego.

  • As instâncias de máquina virtual (VM, na sigla em inglês) sem um endereço IP externo atribuído precisam usar uma sub-rede com o Acesso privado do Google ativado para acessar as APIs e os serviços do Google usando um endpoint.

    Uma VM com um endereço IP externo pode acessar APIs e serviços do Google usando endpoints, mesmo que o Acesso privado do Google esteja desativado para a sub-rede. A conectividade com o endpoint permanece na rede do Google.

  • Se a rede VPC não contiver endpoints, verifique se há uma zona particular do Cloud DNS para p.googleapis.com. Se a zona existir, exclua-a antes de criar o endpoint. Se você não a excluir, a criação da zona DNS do Diretório de serviços usada para o Private Service Connect falhará. Para mais informações, consulte Solução de problemas.

  • Os endpoints não podem ser acessados em redes VPC com peering.

Ativar o Acesso privado do Google para uma sub-rede

As VMs sem um endereço IP externo atribuído precisam estar conectadas a uma sub-rede com o Acesso privado do Google ativado para acessar as APIs e os serviços do Google usando um endpoint.

Se a VM tiver mais de uma interface, conecte a interface configurada com uma rota padrão (geralmente nic0).

O endereço IP de origem dos pacotes enviados da VM corresponde ao endereço IPv4 interno principal da interface da VM ou a um endereço IPv4 interno de um intervalo de IPs de alias.

Para ativar o Acesso privado do Google em uma sub-rede, siga estas etapas.

Console

  1. No Console do Google Cloud, acesse a página Redes VPC.

    Acessar redes VPC

  2. Clique no nome da rede que contém a sub-rede para a qual você precisa ativar o Acesso privado do Google.

  3. Clique no nome da sub-rede. A página Detalhes da sub-rede é exibida.

  4. Clique em Editar.

  5. Na seção Acesso privado do Google, selecione Ativado.

  6. Clique em Salvar.

gcloud

  1. Determine o nome e a região da sub-rede. Para listar as sub-redes de uma rede específica, use o seguinte comando:

    gcloud compute networks subnets list --filter=NETWORK_NAME

  2. Execute o seguinte comando para ativar o Acesso privado do Google:

    gcloud compute networks subnets update SUBNET_NAME \
--region=REGION \
--enable-private-ip-google-access

  3. Execute o comando a seguir para verificar se o Acesso privado do Google está ativado:

    gcloud compute networks subnets describe SUBNET_NAME \
--region=REGION \
--format="get(privateIpGoogleAccess)"

Substitua:

  • SUBNET_NAME: o nome da sub-rede
  • REGION: a região da sub-rede
  • NETWORK_NAME: o nome da rede VPC que contém a sub-rede

Terraform

Use o recurso do Terraform para ativar o Acesso privado do Google em uma sub-rede.

resource "google_compute_network" "network" {
  project                 = var.project # Replace this with your project ID in quotes
  name                    = "tf-test"
  auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "vpc_subnetwork" {
  project                  = google_compute_network.network.project
  name                     = "test-subnetwork"
  ip_cidr_range            = "10.2.0.0/16"
  region                   = "us-central1"
  network                  = google_compute_network.network.id
  private_ip_google_access = true
}

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

Crie um endpoint

Depois de escolher um endereço IP que atenda aos requisitos, você poderá criar um endpoint.

Um endpoint se conecta às APIs e aos serviços do Google usando uma regra de encaminhamento global. Cada regra de encaminhamento é contabilizada na cota de rede VPC para a Private Service Connect.

Não é possível atualizar um endpoint para APIs e serviços do Google depois que ele é criado. Se você precisar atualizar um endpoint para APIs e serviços do Google, exclua o endpoint e crie um novo.

Console

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

    Acessar a página "Private Service Connect"

  2. Clique na guia Endpoints conectados.

  3. Clique em Conectar endpoint.

  4. Em Destino, selecione o pacote de API de destino que você quer usar:

    • Todas as APIs do Google
    • VPC-SC

  5. Em Nome da conexão, insira um nome para o endpoint.

  6. Selecione uma Rede para o endpoint.

  7. Selecione um Endereço IP para o endpoint.

    O endereço IP precisa atender a estes requisitos.

    Se você precisar de um novo endereço IP, crie um:

    1. Clique em Criar endereço IP.
    2. Digite um Nome e uma Descrição para o endereço IP.
    3. Digite o endereço IP que você quer usar e clique em Salvar.

  8. Se uma região do diretório de serviços ainda não estiver configurada para essa rede VPC, selecione a região que você quer usar.

    Todos os endpoints usados para acessar serviços e APIs do Google em uma determinada rede VPC usam a mesma região do diretório de serviços.

  9. Se um namespace do Diretório de serviços ainda não estiver configurado para esta rede VPC, configure o namespace que você quer usar:

    • Para usar um namespace atribuído automaticamente, clique no menu suspenso Namespace e selecione o namespace atribuído automaticamente.

    • Para selecionar um namespace usado em outra rede, clique no menu suspenso Namespace e selecione um namespace na lista. A lista exibe todos os namespaces no projeto. É preciso selecionar um namespace usado apenas para endpoints usados para acessar as APIs do Google.

    • Para criar um novo namespace, clique no menu suspenso Namespace e em Criar namespace. Digite o namespace e clique em Criar.

    Todos os endpoints que você usa para acessar as APIs e os serviços do Google em uma determinada rede VPC usam o mesmo namespace do diretório de serviços.

  10. Clique em Adicionar endpoint.

gcloud

  1. Reserve um endereço IP interno global para atribuir ao endpoint.

    gcloud compute addresses create ADDRESS_NAME \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=ENDPOINT_IP \
  --network=NETWORK_NAME

    Substitua:

    • ADDRESS_NAME: o nome a ser atribuído ao endereço IP reservado.

    • ENDPOINT_IP: o endereço IP a ser reservado para o endpoint.

      O endereço IP precisa atender a estes requisitos.

    • NETWORK_NAME: o nome da rede VPC do endpoint.

  2. Crie uma regra de encaminhamento para conectar o endpoint aos serviços e APIs do Google.

    gcloud compute forwarding-rules create ENDPOINT_NAME \
  --global \
  --network=NETWORK_NAME \
  --address=ADDRESS_NAME \
  --target-google-apis-bundle=API_BUNDLE \
  [ --service-directory-registration=REGION_NAMESPACE_URI ]

    Substitua:

    • ENDPOINT_NAME: o nome a ser atribuído ao endpoint. O nome precisa ser uma string de 1 a 20 caracteres, contendo apenas letras minúsculas e números. O nome precisa começar com uma letra.

    • NETWORK_NAME: o nome da rede VPC do endpoint.

    • ADDRESS_NAME: o nome do endereço reservado na rede associada.

    • API_BUNDLE: o pacote de APIs a ser disponibilizado usando o endpoint. Veja a lista de APIs compatíveis.

      • Use all-apis para conceder acesso a todas as APIs compatíveis.

      • Use vpc-sc para restringir o acesso às APIs do Google compatíveis com o VPC Service Controls.

    • REGION_NAMESPACE_URI: o URI do namespace ou região do serviço de diretório que você quer usar. Esse URI precisa fazer referência ao mesmo projeto em que você está criando o endpoint.

      • É possível definir uma região apenas com projects/PROJECT_NAME/locations/REGION.

      • Defina uma região e um namespace com projects/PROJECT_NAME/locations/REGION/namespaces/NAMESPACE.

      Se você omitir --service-directory-registration completamente ou definir uma região sem um namespace, ocorrerá o seguinte:

      • Se uma região ou um namespace já estiver configurado para essa rede VPC, esses padrões serão usados.

      • Se uma região não estiver configurada, ela será definida como us-central1. Se um namespace não for configurado, um namespace gerado pelo sistema será atribuído.

API

  1. Reserve um endereço IP interno global para atribuir ao endpoint.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/addresses

{
"name": ADDRESS_NAME,
"address": ENDPOINT_IP,
"addressType": "INTERNAL",
"purpose": PRIVATE_SERVICE_CONNECT,
"network": NETWORK_URL
}

    Substitua:

    • PROJECT_ID: o ID do projeto.

    • ADDRESS_NAME: o nome a ser atribuído ao endereço IP reservado.

    • ENDPOINT_IP: o endereço IP a ser reservado para o endpoint.

      O endereço IP precisa atender a estes requisitos.

    • NETWORK_URL: a rede VPC do endpoint. Use o método network.list ou gcloud compute networks list --uri para encontrar os URLs das suas redes.

  2. Crie uma regra de encaminhamento para conectar o endpoint aos serviços e APIs do Google.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/forwardingRules
{
 "IPAddress": ADDRESS_URL,
 "network": NETWORK_URL,
 "name": ENDPOINT_NAME,
 "target": API_BUNDLE,
 "serviceDirectoryRegistrations : [
   {
     "service_directory_region": REGION,
     "namespace": "NAMESPACE"

   }
 ],
}

    Substitua:

    • PROJECT_ID: o ID do projeto.

    • ENDPOINT_NAME: o nome a ser atribuído ao endpoint. O nome precisa ser uma string de 1 a 20 caracteres, contendo apenas letras minúsculas e números. O nome precisa começar com uma letra.

    • NETWORK_URL: a rede VPC do endpoint. Use o método network.list ou gcloud compute networks list --uri para encontrar os URLs das suas redes.

    • ADDRESS_URL: o URL do endereço reservado na rede associada. Use o método globalAddresses.list ou gcloud compute addresses list --uri para encontrar os URLs dos endereços reservados.

    • API_BUNDLE: o pacote de APIs a ser disponibilizado usando o endpoint. Veja a lista de APIs compatíveis.

      • Use all-apis para conceder acesso a todas as APIs compatíveis.

      • Use vpc-sc para restringir o acesso às APIs do Google compatíveis com o VPC Service Controls.

    • REGION: a região do Diretório de serviços que você quer usar. Por exemplo, us-central1. Se você omitir REGION e uma região já estiver configurada para essa rede VPC, essa região será usada. Se uma região não estiver configurada, a região será definida como us-central1.

    • NAMESPACE: o nome do namespace do Diretório de serviços que você quer usar. Se você omitir NAMESPACE e um namespace já estiver configurado para essa rede VPC, esse namespace será usado. Se um namespace não for configurado, um namespace gerado pelo sistema será atribuído.

Terraform

Use os seguintes recursos do Terraform para criar um endpoint:

resource "google_compute_global_address" "default" {
  project      = google_compute_network.network.project
  name         = "global-psconnect-ip"
  address_type = "INTERNAL"
  purpose      = "PRIVATE_SERVICE_CONNECT"
  network      = google_compute_network.network.id
  address      = "10.3.0.5"
}
 
resource "google_compute_global_forwarding_rule" "default" {
  project               = google_compute_network.network.project
  name                  = "globalrule"
  target                = "all-apis"
  network               = google_compute_network.network.id
  ip_address            = google_compute_global_address.default.id
  load_balancing_scheme = ""
}

Verifique se o endpoint está funcionando

Crie uma instância de VM na rede VPC em que o Private Service Connect está configurado. Execute o comando a seguir na VM para verificar se o endpoint do Private Service Connect está funcionando. Os endpoints não respondem a solicitações de ping (ICMP).

curl -v ENDPOINT_IP/generate_204

Substitua ENDPOINT_IP pelo endereço IP do endpoint.

Se o endpoint estiver funcionando, você verá um código de resposta HTTP 204.

Listar endpoints

É possível listar todos os endpoints configurados.

Console

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

    Acessar a página "Private Service Connect"

  2. Clique na guia Endpoints conectados.

    Os endpoints serão exibidos.

gcloud

gcloud compute forwarding-rules list  \
--filter target="(all-apis OR vpc-sc)" --global

O resultado será assim:

NAME  REGION  IP_ADDRESS  IP_PROTOCOL  TARGET
RULE          IP          TCP          all-apis

Receber informações sobre um endpoint

É possível ver todos os detalhes de configuração de um endpoint.

Console

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

    Acessar a página "Private Service Connect"

  2. Clique na guia Endpoints conectados.

    Os endpoints são exibidos.

  3. Clique no endpoint com os detalhes que você quer ver.

gcloud 

gcloud compute forwarding-rules describe \
    ENDPOINT_NAME --global

Rotular um endpoint

É possível gerenciar rótulos para endpoints. Consulte Como rotular recursos para mais informações.

Excluir um endpoint

É possível excluir um endpoint.

Console

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

    Acessar a página "Private Service Connect"

  2. Clique na guia Endpoints conectados.

  3. Selecione o endpoint que você quer excluir e clique em Excluir.

gcloud 

    gcloud compute forwarding-rules delete \
        ENDPOINT_NAME --global

Substitua ENDPOINT_NAME pelo nome do endpoint que você quer excluir.

Usar um endpoint

Para usar um endpoint, envie solicitações para um nome de host DNS que seja resolvido para o endereço IP do endpoint.

  • É possível usar os nomes de DNS p.googleapis.com criados automaticamente se for possível configurar os clientes para usar um endpoint personalizado e se os registros de DNS p.googleapis.com forem criados para as APIs e os serviços que você quer usar. Para mais informações, consulte Usar nomes DNS p.googleapis.com.

    Por exemplo, se o nome do endpoint for xyz, os registros DNS serão criados para storage-xyz.p.googleapis.com, compute-xyz.p.googleapis.com e outras APIs usadas com frequência no pacote de APIs.

  • É possível criar registros DNS usando os nomes DNS padrão se você estiver usando um cliente que não tenha sido configurado para usar um endpoint personalizado ou se não houver um registro DNS p.googleapis.com para o serviço que você quer usar. Para mais informações, consulte Criar registros DNS usando nomes DNS padrão.

    Por exemplo, crie registros DNS para storage.googleapis.com e compute.googleapis.com.

Usar nomes DNS p.googleapis.com

Quando você cria um endpoint, o Diretório de serviços cria registros DNS para APIs e serviços usados com frequência que estão disponíveis no endpoint. Os registros DNS são criados apenas para APIs e serviços que têm nomes DNS padrão que terminam com googleapis.com e apenas para um subconjunto dessas APIs e serviços.

Os registros DNS são criados em uma zona particular p.googleapis.com. Os registros apontam para o endereço IP do endpoint e usam este formato: SERVICE-ENDPOINT.p.googleapis.com

Por exemplo, se o nome do endpoint for xyz, os registros DNS serão criados para storage-xyz.p.googleapis.com, compute-xyz.p.googleapis.com e outras APIs compatíveis.

Os clientes que podem ser configurados para usar um endpoint personalizado podem usar os nomes de DNS p.googleapis.com para enviar solicitações a um endpoint.

Consulte a documentação do seu cliente ou da biblioteca de cliente para mais informações sobre como configurá-lo para usar endpoints personalizados. Por exemplo:

  • Python: é possível configurar api_endpoint em Opções de cliente.

  • Go: é possível configurar WithEndpoint em ClientOptions.

  • .NET: é possível configurar Endpoint na classe de builder do cliente.

  • gcloud: é possível configurar api_endpoint_overrides na gcloud CLI.

Criar registros DNS usando nomes DNS padrão

Você precisa criar registros DNS para direcionar os nomes DNS padrão de APIs e serviços para seu endpoint nestas circunstâncias:

  • Seu cliente ou aplicativo não pode ser configurado para usar um nome DNS p.googleapis.com.

  • Você precisa acessar um serviço compatível, mas não há um nome DNS p.googleapis.com criado automaticamente para esse serviço.

Para criar registros DNS que apontem para o endpoint do Private Service Connect, siga estas instruções:

  1. Crie uma zona de DNS para o domínio que você precisa usar, por exemplo, googleapis.com ou gcr.io. Considere criar uma zona particular do Cloud DNS para essa finalidade.

  2. Nesta zona do DNS:

    1. Crie um registro A para o próprio nome de domínio (zona). Por exemplo, googleapis.com ou gcr.io Aponte esse registro A para o endereço IP do endpoint. Se você estiver usando o Cloud DNS, consulte Como adicionar um registro.

    2. Crie um registro CNAME para todos os possíveis nomes de host do domínio usando um asterisco e um ponto seguido pelo nome do domínio (zona). Por exemplo, *.googleapis.com ou *.gcr.io. Aponte este registro CNAME para o registro A na mesma zona. Por exemplo, direcione *.googleapis.com para googleapis.com ou direcione*.gcr.io para gcr.io.

Acesse o endpoint de hosts locais

Se sua rede local estiver conectada a uma rede VPC, será possível usar o Private Service Connect para acessar APIs e serviços do Google de hosts locais usando o endereço IP interno do endpoint.

  • Sua rede local precisa estar conectada a uma rede VPC usando túneis do Cloud VPN ou anexos da VLAN para o Cloud Interconnect.

  • O endpoint precisa estar na rede VPC conectada à sua rede local.

  • A rede local precisa ter rotas apropriadas para o endpoint. Configure uma Divulgação de rota personalizada do Cloud Router para anunciar rotas para o endpoint na sessão do BGP que gerencia rotas para o túnel do Cloud VPN ou para o anexo do Cloud Interconnect (VLAN).

    • Se a rede local usa roteamento de vários caminhos de custo igual (ECMP, na sigla em inglês) para distribuir tráfego para os endpoints do Private Service Connect, garanta que todos os pacotes de uma única conexão TCP sejam encaminhados pelo mesmo túnel do Cloud VPN ou anexo da VLAN. Se os pacotes de uma conexão TCP estabelecida forem encaminhados por vários caminhos, poderá haver redefinições de TCP intermitentes (RSTs, na sigla em inglês). Para evitar redefinições, configure os roteadores de peering locais para manter destinos consistentes do próximo salto.

  • Configure sistemas locais para que eles possam fazer consultas às suas zonas de DNS particulares.

    Se você implementou as zonas DNS particulares usando o Cloud DNS, siga estas etapas:

Solução de problemas

As seções a seguir contêm informações sobre como resolver problemas com os endpoints do Private Service Connect usados para acessar as APIs do Google.

Falha na criação da zona de DNS privado

Quando você cria um endpoint, uma zona DNS do diretório de serviços é criada. A criação da zona pode falhar por estes motivos:

  • Você não ativou a API do Cloud DNS no projeto.

  • Você não tem as permissões necessárias para criar uma zona de DNS do Diretório de serviços.

  • Há uma zona DNS com o mesmo nome de zona nessa rede VPC.

  • Já existe uma zona DNS para p.googleapis.com nessa rede VPC.

Pode haver zonas conflitantes devido a uma falha na exclusão anterior.

Para criar a zona DNS do Diretório de serviços, faça o seguinte:

  1. Verifique se a API do Cloud DNS está ativada no projeto.

  2. Verifique se você tem as permissões necessárias para criar a zona DNS do Diretório de serviços:

    • dns.managedZones.create
    • servicedirectory.namespaces.associatePrivateZone

  3. Exclua a zona do DNS.

  4. Crie uma zona DNS do Diretório de serviços apoiada pelo namespace do Diretório de serviços associado ao seu endpoint.

    Use os seguintes valores ao criar a zona:

    • Nome da zona: use o mesmo nome de zona que o sistema usou durante a tentativa de criação com falha. A mensagem de erro mostra o nome da zona que foi usada.

    • Nome do DNS: p.googleapis.com. (inclua o ponto final).

    • Namespace do diretório de serviços: encontre o namespace do diretório de serviços para o endpoint de conexão de serviço privado que você criou e use esse namespace ao criar o serviço Zona de DNS do diretório.

    O namespace do Diretório de serviços tem o seguinte formato: goog-psc-NETWORK_NAME-NETWORK_ID.

Falha ao excluir a zona DNS particular

Quando você exclui o último endpoint em uma rede VPC, a configuração do Diretório de serviços associada, incluindo a zona de DNS, é excluída.

Essa exclusão pode falhar por estes motivos:

  • Você não tem as permissões necessárias para excluir a zona DNS.

  • A zona contém entradas DNS definidas pelo usuário que não foram criadas pelo diretório de serviços.

Para resolver esse problema, faça o seguinte:

  1. Verifique se você tem a permissão dns.managedZones.delete. Para mais informações, consulte Controle de acesso na documentação do Cloud DNS.

  2. Exclua a zona do DNS.