Acessar APIs globais do Google por back-ends

Nesta página, descrevemos como acessar APIs globais do Google usando back-ends do Private Service Connect baseados em balanceadores de carga de aplicativo internos entre regiões.

Essa configuração permite visar uma ou mais APIs globais do Google individuais e aplicar a visibilidade e o controle que os back-ends do Private Service Connect oferecem.

É possível configurar nomes dos hosts personalizados, no local da sua nuvem privada virtual (VPC) e das redes locais conectadas, que roteiam o tráfego para as APIs globais do Google escolhidas.
É possível acessar os back-ends de qualquer região, e o back-end pode balancear o tráfego para grupos de endpoints de rede (NEGs) do Private Service Connect localizados em qualquer região.
É possível enviar tráfego para os back-ends de redes VPC pareadas.

Para ver uma lista das APIs globais do Google disponíveis, consulte Destinos de APIs globais do Google.

Antes de começar

Para receber as permissões necessárias para configurar um back-end e acessar as APIs globais do Google, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto do Google Cloud:
- Administrador do Compute (roles/compute.admin)
- Proprietário do Gerenciador de certificados (roles/certificatemanager.owner)
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.
Ative a API Compute Engine no projeto.
Ative a API Certificate Manager no seu projeto.
Crie uma chave privada e um certificado assinado de uma autoridade certificadora (AC). Siga as instruções na Etapa 1: criar uma chave privada e um certificado. A chave privada e o certificado são necessários para criar um certificado SSL autogerenciado com o Gerenciador de certificados.
Crie um recurso de certificado para um balanceador de carga de aplicativo interno entre regiões usando a chave privada e o certificado assinado que você criou. Ao fazer upload do certificado, defina o escopo como all-regions. Para mais informações, consulte Fazer upload de um certificado autogerenciado para o Gerenciador de certificados. O recurso de certificado é necessário para configurar o proxy HTTPS de destino para o balanceador de carga.
Crie uma sub-rede somente proxy se você ainda não tiver uma. É necessário haver uma única sub-rede somente proxy na região e rede VPC em que você pretende criar a regra de encaminhamento do balanceador de carga de aplicativo interno entre regiões. Essa sub-rede é usada por todos os balanceadores de carga de aplicativo internos nessa rede e região.

Criar um NEG do Private Service Connect

Para cada API global do Google que você quer acessar, crie um NEG do Private Service Connect. Os NEGs do Private Service Connect são regionais, mesmo quando são usados para se conectar a APIs globais do Google.

Um NEG do Private Service Connect não pode ser atualizado depois de criado.

Console

No console do Google Cloud, acesse a página Criar um grupo de endpoints de rede.

Acessar "Criar um grupo de endpoints de rede"
Na página Criar grupo de endpoints de rede, insira um Nome para o grupo de endpoints de rede.
Em Tipo de grupo de endpoints de rede, selecione NEG do Private Service Connect (regional).
Em Destino, selecione APIs globais do Google.
Selecione a Região do grupo de endpoints da rede.
Selecione o Serviço de destino para o grupo de endpoints de rede.
Clique em Criar.

gcloud

Use o comando network-endpoint-groups create.

gcloud compute network-endpoint-groups create NEG_NAME \
    --network-endpoint-type=private-service-connect \
    --psc-target-service=TARGET_SERVICE \
    --region=REGION

Substitua:

NEG_NAME: um nome para o grupo de endpoints da rede.
TARGET_SERVICE: o destino da API global do Google a que você quer se conectar, por exemplo, pubsub.googleapis.com. Consulte a lista de destinos permitidos de APIs globais do Google.
REGION: a região em que o grupo de endpoints da rede será criado.

API

Faça uma solicitação POST ao método regionNetworkEndpointGroups.insert.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/networkEndpointGroups
{
  "name": "NEG_NAME",
  "networkEndpointType": "PRIVATE_SERVICE_CONNECT",
  "pscTargetService": "TARGET_SERVICE"
}

Substitua:

PROJECT_ID: o ID do projeto do grupo de endpoints de rede.
REGION: a região em que o grupo de endpoints da rede será criado.
NEG_NAME: um nome para o grupo de endpoints da rede.
TARGET_SERVICE: o destino da API global do Google a que você quer se conectar, por exemplo, pubsub.googleapis.com. Consulte a lista de destinos permitidos de APIs globais do Google.

Configurar o balanceador de carga

Para acessar as APIs globais do Google, configure um balanceador de carga de aplicativo interno entre regiões.

Console

Iniciar a configuração

No console do Google Cloud, acesse a página Balanceamento de carga.

Acessar o "Balanceamento de carga"
Clique em Criar balanceador de carga.
Em Tipo de balanceador de carga, selecione Balanceador de carga de aplicativo (HTTP/HTTPS) e clique em Próxima.
Em Voltado ao público ou interno, selecione Interno e clique em Próxima.
Em Implantação entre regiões ou região única, selecione Melhor para cargas de trabalho entre regiões e clique em Próxima.
Clique em Configurar.

Configuração básica

Digite um Nome para o balanceador de carga.
Selecione uma Rede para o balanceador de carga.

A rede precisa conter uma sub-rede somente proxy na região em que você está criando o balanceador de carga.

Configuração de front-end

Clique em Configuração de front-end.
Insira um Nome para a regra de encaminhamento do balanceador de carga.
No campo Protocolo, selecione HTTPS (inclui HTTP/2 e HTTP/3).
Selecione a Região da sub-rede do balanceador de carga.
Selecione uma Sub-rede para o balanceador de carga.
Clique em Endereço IP e siga um destes procedimentos:
- Para atribuir automaticamente um endereço IP temporário, selecione Temporário (automático).
- Para escolher um endereço IP temporário, selecione Temporário (personalizado) e insira um Endereço IP temporário personalizado do intervalo de endereços IP da sub-rede do balanceador de carga.
- Para reservar e usar um endereço IP interno estático, clique em Criar endereço IP e siga estas etapas:
  1. Insira um Nome para o endereço IP.
  2. Clique em Endereço IP estático e siga um destes procedimentos:
    - Para atribuir automaticamente um endereço IP estático, selecione Atribuir automaticamente.
    - Para configurar um endereço IP específico, selecione Deixe-me escolher e insira um Endereço IP personalizado do intervalo de endereços IP da sub-rede do balanceador de carga.
  3. Clique em Reservar.
Certifique-se de que o campo Porta esteja definido como 443, para permitir tráfego HTTPS.
Clique na lista Certificado e selecione seu certificado autogerenciado.
Clique em Concluído.

Configuração de back-end

Clique em Configuração de back-end.
Crie um serviço de back-end global para cada API global do Google que você quer acessar. Para criar um serviço de back-end global, faça isto:
1. No menu Criar ou selecionar serviços de back-end, selecione Criar um serviço de back-end.
2. Digite um Nome para o serviço de back-end.
3. Defina o Tipo de back-end como Grupo de endpoints de rede do Private Service Connect.
4. Defina o Tipo de destino do Private Service Connect como API global do Google.
5. Selecione HTTPS para o protocolo.
6. Na seção Back-ends, clique no menu Novo back-end e selecione um grupo de endpoints de rede do Private Service Connect.
  
  Se você precisar criar um novo grupo de endpoints de rede do Private Service Connect, clique em Criar NEG do PSC.
7. Clique em Concluído.
8. Clique em Criar.
Verifique se cada serviço de back-end que você quer adicionar está selecionado no menu Criar ou selecionar serviços de back-end e clique em OK.

Regras de roteamento

O conjunto de regras para encaminhar solicitações HTTPS de entrada para serviços de back-end específicos é chamado de mapa de URL. Para saber mais sobre mapas de URL, consulte Visão geral de mapas de URL.

Se você estiver configurando apenas um serviço de back-end para o balanceador de carga, a regra de roteamento padrão será suficiente e será possível pular para Revisar e finalizar.

Se você estiver configurando vários serviços de back-end, crie uma correspondência de caminhos para cada um deles. Cada regra de host pode referir-se apenas a uma correspondência de caminhos, mas duas ou mais regras podem referir-se à mesma correspondência.

Se você tiver mais de um serviço de back-end, clique em Regras de roteamento.
Selecione Regra de host e caminho simples.
Para cada back-end, faça o seguinte:
1. Clique em Adicionar regra de host e caminho.
2. Em Host, insira o nome do host que será usado para enviar solicitações a esse serviço, por exemplo, pubsub.example.com.
3. Em Caminhos, digite o caminho, por exemplo, /*.
4. Em Back-ends, selecione o serviço de back-end.

Analisar e finalizar

Clique em Analisar e finalizar para revisar a configuração.
Clique em Criar.

gcloud

Para cada API global do Google que você quer acessar, faça isto:
1. Para criar um serviço de back-end, use o comando gcloud compute backend-services create.
```
gcloud compute backend-services create BACKEND_SERVICE_NAME \
    --load-balancing-scheme=INTERNAL_MANAGED \
    --protocol=HTTPS \
    --global
```
  Substitua BACKEND_SERVICE_NAME pelo nome do serviço de back-end.
2. Para adicionar um NEG ao serviço de back-end correspondente, use o comando gcloud compute backend-services add-backend.
```
gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
    --network-endpoint-group=NEG_NAME \
    --network-endpoint-group-region=REGION \
    --global
```
  Substitua:
  - NEG_NAME: o nome do NEG do Private Service Connect.
  - REGION: a região do NEG do Private Service Connect.
Para criar um mapa de URL global para o balanceador de carga, use o comando gcloud compute url-maps create.

Um mapa de URL precisa referir-se a um serviço de back-end padrão. Se você estiver configurando o balanceador de carga com um serviço de back-end, defina esse serviço como o padrão. Se estiver configurando o balanceador de carga para usar vários serviços de back-end, escolha um deles para ser o padrão de mapa de URL.
```
gcloud compute url-maps create URL_MAP_NAME \
    --default-service=DEFAULT_BACKEND_SERVICE_NAME
```
Substitua:
- URL_MAP_NAME: um nome para o mapa de URL.
- DEFAULT_BACKEND_SERVICE_NAME: o nome do serviço de back-end padrão do balanceador de carga. O padrão é usado quando nenhuma regra de host corresponde ao nome do host solicitado.
Opcional: se você estiver configurando o balanceador de carga para usar vários serviços de back-end, conclua esta etapa. Se o mapa de URL referir-se apenas a um serviço de back-end, ignore esta etapa.

Para adicionar outros serviços de back-end ao mapa de URL, use o comando gcloud compute url-maps add-path-matcher.

Para cada serviço de back-end, adicione uma correspondência de caminhos e uma ou mais regras de host. É necessário criar uma correspondência de caminhos para cada serviço de back-end. Cada regra de host pode referir-se apenas a uma correspondência de caminhos, mas duas ou mais regras podem referir-se à mesma correspondência.
```
gcloud compute url-maps add-path-matcher URL_MAP_NAME \
    --path-matcher-name=PATH_MATCHER \
    --default-service=BACKEND_SERVICE_NAME \
    --new-hosts=HOSTNAMES
```
Substitua:
- PATH_MATCHER: um nome para a correspondência de caminho.
- BACKEND_SERVICE_NAME: o nome do serviço de back-end.
- HOSTNAMES: um ou mais nomes dos hosts para enviar solicitações ao serviço de back-end. Por exemplo, pubsub.example.com. É possível incluir vários nomes dos hosts em uma lista separada por vírgulas.
Para criar um proxy HTTPS de destino, use o comando gcloud compute target-https-proxies create.
```
gcloud compute target-https-proxies create PROXY_NAME \
    --url-map=URL_MAP_NAME \
    --certificate-manager-certificates=CERTIFICATE_NAME
```
Substitua:
- PROXY_NAME: um nome para o proxy HTTPS de destino.
- URL_MAP_NAME: o nome do mapa de URL.
- CERTIFICATE_NAME: o nome do recurso de certificado.
Para criar uma regra de encaminhamento global para o balanceador de carga, use o comando gcloud compute forwarding-rules create.
```
gcloud compute forwarding-rules create RULE_NAME \
    --load-balancing-scheme=INTERNAL_MANAGED \
    --network=NETWORK \
    --address=IP_ADDRESS \
    --ports=443 \
    --target-https-proxy=PROXY_NAME \
    --subnet=SUBNET \
    --subnet-region=SUBNET_REGION \
    --global
```
Substitua:
- RULE_NAME: o nome da regra de encaminhamento.
- NETWORK: a rede VPC da regra de encaminhamento. Essa rede precisa conter uma sub-rede somente proxy na região em que você está criando o balanceador de carga.
- IP_ADDRESS: o endereço IP interno da regra de encaminhamento, que precisa estar no intervalo de endereços IP da sub-rede da regra de encaminhamento. Para usar um endereço IP temporário específico, insira o endereço IP, por exemplo, 10.0.0.5. Para usar um endereço IP interno estático, insira o nome do endereço IP. Para permitir que o Google Cloud selecione um endereço IP temporário, omita essa flag.
- SUBNET: a sub-rede da regra de encaminhamento.
- SUBNET_REGION: a região da sub-rede da regra de encaminhamento.

API

Para cada API global do Google que você quer acessar, faça isto:
1. Para criar um serviço de back-end global, faça uma solicitação POST ao método backendServices.insert.
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices
{
  "loadBalancingScheme": "INTERNAL_MANAGED",
  "name": "BACKEND_SERVICE_NAME",
  "protocol": "HTTPS"
}
```
  Substitua:
  - PROJECT_ID: o ID do projeto.
  - BACKEND_SERVICE_NAME: o nome do serviço de back-end.
2. Para adicionar um NEG ao serviço de back-end correspondente, faça uma solicitação PATCH para o método backendServices.patch.
```
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME
{
  "backends": [
    {
      "group": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/networkEndpointGroups/NEG_NAME"
    }
  ]
}
```
  Substitua:
  - REGION: a região do NEG.
  - NEG_NAME: o nome do grupo de endpoints de rede a ser adicionado.
Para criar um mapa de URL global para o balanceador de carga, faça uma solicitação POST para o método urlMaps.insert.

Um mapa de URL precisa referir-se a um serviço de back-end padrão. Se você estiver configurando o balanceador de carga com um serviço de back-end, defina esse serviço como o padrão. Se estiver configurando o balanceador de carga para usar vários serviços de back-end, escolha um deles para ser o padrão de mapa de URL.
```
 POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps
 {
   "defaultService": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/DEFAULT_BACKEND_SERVICE_NAME",
   "name": "URL_MAP_NAME"
 }
 
```
Substitua:
- DEFAULT_BACKEND_SERVICE_NAME: o nome padrão do balanceador de carga. O padrão é usado quando nenhuma regra de host corresponde ao nome do host solicitado.
- URL_MAP_NAME: um nome para o mapa de URL.
Se você estiver configurando o balanceador de carga para usar vários serviços de back-end, conclua esta etapa. Se o mapa de URL referir-se apenas a um serviço de back-end, ignore esta etapa.

Para adicionar outros serviços de back-end ao mapa de URL, faça uma solicitação PATCH para o método urlMaps.patch.

Para cada serviço de back-end, adicione uma correspondência de caminhos e uma ou mais regras de host. É necessário criar uma correspondência de caminhos para cada serviço de back-end. Cada regra de host pode referir-se apenas a uma correspondência de caminhos, mas duas ou mais regras podem referir-se à mesma correspondência.

É possível adicionar várias correspondências de caminhos e regras de host fazendo uma única solicitação de API.
```
 PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/URL_MAP_NAME
 {
   "pathMatchers": [
     {
       "name": "PATH_MATCHER_NAME_1",
       "defaultService": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME_1"
     },
     {
       "name": "PATH_MATCHER_NAME_2",
       "defaultService": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME_2"
     }
   ],
   "hostRules": [
     {
       "hosts": ["HOSTNAME_1"],
       "pathMatcher": "PATH_MATCHER_NAME_1"
     },
     {
       "hosts": ["HOSTNAME_2"],
       "pathMatcher": "PATH_MATCHER_NAME_2"
     }
   ]
 }
 
```
Substitua:
- PATH_MATCHER_NAME_1: um nome para a primeira correspondência de caminhos.
- BACKEND_SERVICE_NAME_1: o nome do primeiro serviço de back-end.
- PATH_MATCHER_NAME_2: um nome para a segunda correspondência de caminhos.
- BACKEND_SERVICE_NAME_2: o nome do segundo serviço de back-end.
- HOSTNAME_1: o nome do host ao qual enviar solicitações para o primeiro serviço, por exemplo, pubsub.example.com.
- HOSTNAME_2: o nome do host ao qual enviar solicitações para o segundo serviço.

Para criar um proxy HTTPS de destino, faça uma solicitação POST ao método targetHttpsProxies.insert.

 POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/targetHttpsProxies
 {
   "name": "PROXY_NAME",
   "sslCertificates": [
     "https://certificatemanager.googleapis.com/v1/projects/PROJECT_ID/locations/global/certificates/CERTIFICATE_NAME"
   ],
   "urlMap": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/URL_MAP_NAME"
 }

Substitua:

PROJECT_ID: o ID do projeto.
PROXY_NAME: um nome para o proxy HTTPS de destino.
CERTIFICATE_NAME: o nome do recurso de certificado.
URL_MAP_NAME: o nome do mapa de URL.

Para criar uma regra de encaminhamento global para o balanceador de carga, faça uma solicitação POST ao método globalForwardingRules.insert. A rede da regra de encaminhamento precisa conter uma sub-rede somente proxy na sub-rede da região da regra de encaminhamento.
```
 POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/forwardingRules
 {
   "IPAddress": "IP_ADDRESS",
   "loadBalancingScheme": "INTERNAL_MANAGED",
   "name": "FORWARDING_RULE_NAME",
   "network": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/NETWORK_NAME",
   "portRange": "443",
   "subnetwork": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/SUBNET_REGION/subnetworks/SUBNET_NAME",
   "target": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/targetHttpsProxies/PROXY_NAME"
 }
 
```
Substitua:
- IP_ADDRESS: o endereço IP interno da regra de encaminhamento, que precisa estar no intervalo de endereços IP da sub-rede da regra de encaminhamento. Para usar um endereço IP temporário específico, insira o endereço IP, por exemplo, 10.0.0.5. Para usar um endereço IP interno estático, informe o nome do endereço IP. Para permitir que o Google Cloud selecione um endereço IP temporário, omita esse campo.
- FORWARDING_RULE_NAME: o nome da regra de encaminhamento.
- NETWORK_NAME: o nome da rede VPC da regra de encaminhamento. Essa rede precisa conter uma sub-rede somente proxy na região em que você está criando o balanceador de carga.
- SUBNET_REGION: a região da sub-rede da regra de encaminhamento.
- SUBNET_NAME: o nome da sub-rede da regra de encaminhamento.

Verificar a configuração

Para testar a conexão do seu back-end com as APIs globais do Google, faça isto:

Se você não tiver um, crie uma instância de máquina virtual (VM) na rede VPC em que você configurou o back-end.
Verifique se você não criou regras ou políticas de firewall que substituem a regra implícita de IPv4 que permite saída.
Conecte-se à VM.
Na VM, use curl para verificar se é possível consultar cada API. Esse comando define o cabeçalho Host e ignora a resolução de DNS especificando um endereço IP definido pelo usuário.

É possível pular a validação do certificado usando a sinalização -k. Talvez seja necessário pular a validação se você usou um certificado autoassinado para configurar o proxy HTTPS de destino ou se a VM não tem o certificado da autoridade certificadora que assinou o certificado.
```
curl -iv --resolve HOSTNAME:443:IP_ADDRESS \
   'https://HOSTNAME/RESOURCE_URI'
```
Substitua:
- HOSTNAME: o nome do host configurado no mapa de URL, por exemplo, pubsub.example.com.
- IP_ADDRESS: o endereço IP da regra de encaminhamento do balanceador de carga.
- RESOURCE_URI: o restante do URI do recurso que você quer usar para verificação. Por exemplo, se o balanceador de carga estiver encaminhando solicitações para um endpoint regional do Pub/Sub, use $discovery/rest?version=v1.

Configurar registros DNS

Configure registros DNS para cada host adicionado ao mapa de URL, apontando para o endereço IP da regra de encaminhamento. Se você estiver usando o Cloud DNS para gerenciar DNS, consulte Adicionar, modificar e excluir registros. Caso contrário, configure os registros DNS no servidor DNS.

Por exemplo, digamos que você tenha criado as seguintes configurações:

Um NEG do Private Service Connect que usa o serviço de destino pubsub.googleapis.com.
Um balanceador de carga de aplicativo interno entre regiões que usa esse NEG do Private Service Connect como back-end.
Um mapa de URL que define uma regra de host para pubsub.example.com.

Para que essa configuração funcione corretamente, crie um registro DNS que aponte pubsub.example.com para o endereço IP da regra de encaminhamento.

Com essa configuração, todas as solicitações enviadas para pubsub.example.com são enviadas ao balanceador de carga, que encaminha a solicitação para pubsub.googleapis.com.

Configurar clientes para enviar solicitações ao back-end

Para enviar solicitações pelo back-end no lugar dos endpoints de serviço público, configure os clientes para enviar solicitações ao nome do host definido no mapa de URL do balanceador de carga, por exemplo, pubsub.example.com. Consulte a documentação do seu cliente ou da biblioteca de cliente para mais informações sobre como configurá-lo para usar endpoints personalizados. As páginas a seguir incluem etapas de configuração para alguns clientes comuns:

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.