Acessar APIs regionais do Google por endpoints

Neste documento, explicamos como usar endpoints do Private Service Connect para se conectar a endpoints regionais de APIs do Google compatíveis.

Para mais informações sobre outras configurações do Private Service Connect, consulte Private Service Connect.

Papéis

Para receber as permissões necessárias para criar um endpoint regional do Private Service Connect, peça ao administrador para conceder a você os seguintes papéis do IAM na rede VPC:

Papel Administrador de rede do Compute (roles/compute.networkAdmin)
Papel Administrador do DNS (roles/dns.admin)

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 usando papéis personalizados ou outros papéis predefinidos.

Antes de começar

Instale a CLI do Google Cloud. Após a instalação, inicialize a CLI do Google Cloud executando o seguinte comando:
```
$ gcloud init
```
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Observação: se você já instalou a gcloud CLI, execute o comando gcloud components update para verificar se você tem a versão mais recente.
Enable the Compute Engine, Network Connectivity Center, and Cloud DNS APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs
Além disso, ative a API do serviço de destino que você quer acessar pelo endpoint do Private Service Connect. Por exemplo, se você quiser acessar spanner.me-central2.rep.googleapis.com, ative a API Cloud Spanner. O Private Service Connect não ativa APIs automaticamente.
Verifique se as regras de firewall de saída permitem o tráfego para o endpoint. A configuração padrão de firewall das redes VPC permite esse tráfego porque contém uma regra de saída de permissão implícita. Você não deve criar uma regra de saída de prioridade mais alta que bloqueie o tráfego.

Criar um endpoint regional do Private Service Connect

É possível criar um endpoint regional do Private Service Connect para enviar solicitações a um endpoint regional de uma API de destino do Google.

Confira a lista de endpoints regionais compatíveis neste link.

Console

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

Acessar Private Service Connect
Clique em Conectar endpoint.
Em Destino, selecione API do Google.
Na lista Escopo, selecione Regional.
Na lista Região, selecione a região que você quer usar.
Na lista Serviço de destino, selecione o serviço que você quer acessar.
Em Nome do endpoint, digite um nome para o endpoint.
Em Rede, selecione uma rede.
Em Sub-rede, selecione uma sub-rede.
Em Endereço IP, faça uma destas opções para configurar um endereço IP:
- Selecione Alocação automática para alocar e reservar automaticamente um novo endereço IP.
- Selecione um endereço IP reservado na lista.
- Clique em Criar endereço IP para reservar um novo endereço.
Opcional: para disponibilizar o endpoint em todas as regiões da rede VPC, selecione Ativar o acesso global.
Clique em Adicionar endpoint.

gcloud

Use o comando gcloud network-connectivity regional-endpoints create:

gcloud network-connectivity regional-endpoints create ENDPOINT_NAME \
    --region=REGION \
    --address=ADDRESS \
    --network=projects/PROJECT_ID/global/networks/NETWORK_NAME \
    --subnetwork=projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
    --target-google-api=REP_DNS_NAME

Se quiser disponibilizar o endpoint para recursos em outras regiões, adicione a flag --enable-global-access.

Substitua:

ENDPOINT_NAME: um nome para o endpoint.
REGION: a região em que você quer criar o endpoint.
ADDRESS: o endereço IPv4 ou IPv6 que você quer usar para o endpoint. Se esse valor for omitido, um endereço IPv4 da sub-rede será alocado. Use um dos seguintes formatos:
- Endereço IPv4, por exemplo, 10.0.0.2.
- URI de recurso de endereço IPv4 ou IPv6, por exemplo, projects/PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME.
PROJECT_ID: o projeto em que você está criando o endpoint.
NETWORK_NAME: o nome da rede VPC do endpoint.
SUBNET_NAME: a sub-rede a que você está conectando o endpoint.
REP_DNS_NAME: o nome do host do endpoint do serviço regional a que você está se conectando. Por exemplo, spanner.me-central2.rep.googleapis.com.

API

Use o método projects.locations.regionalEndpoints.create.

Método HTTP e URL:

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints?regionalEndpointId=ENDPOINT_NAME

{
  "accessType": "REGIONAL",
  "address": "ADDRESS",
  "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
  "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME",
  "targetGoogleApi": "REP_DNS_NAME"
}

Substitua:

PROJECT_ID: o ID do projeto do endpoint.
REGION: a região em que você quer criar o endpoint.
ENDPOINT_NAME: um nome para o endpoint.
ADDRESS: o endereço IPv4 ou IPv6 que você quer usar para o endpoint. Se esse valor for omitido, um endereço IPv4 da sub-rede será alocado. Use um dos formatos a seguir:
- Endereço IPv4, por exemplo, 10.0.0.2.
- URI de recurso de endereço IPv4 ou IPv6, por exemplo, projects/PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME.
NETWORK_NAME: o nome da rede VPC do endpoint.
SUBNET_NAME: o nome da sub-rede a que você quer conectar o endpoint.
REP_DNS_NAME: o nome do host do endpoint de serviço regional a que você quer se conectar. Por exemplo, spanner.me-central2.rep.googleapis.com.

Listar endpoints

É possível listar todos os endpoints configurados.

Console

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

Acessar Private Service Connect
Clique na guia Endpoints conectados.

Todos os endpoints são exibidos, incluindo aqueles com destinos regionais.

gcloud

Use o comando gcloud network-connectivity regional-endpoints list:

gcloud network-connectivity regional-endpoints list \
    --region=REGION

Substitua REGION pela região dos endpoints que você quer listar.

API

Use o método projects.locations.regionalEndpoints.list.

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints

Substitua:

PROJECT_ID: o ID do projeto do endpoint.
REGION: a região dos endpoints que você quer listar.

Verificar se o endpoint está funcionando

Crie uma instância de máquina virtual (VM) na rede VPC e na região em que o endpoint 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).

Para verificar um endpoint IPv4, faça o seguinte:

curl --connect-to REP_DNS_NAME:443:ADDRESS:443 \
'https://REP_DNS_NAME/PATH'

Para verificar um endpoint IPv6, faça o seguinte:

curl -6 --connect-to REP_DNS_NAME:443:[ADDRESS]:443 \
'https://REP_DNS_NAME/PATH'

Substitua:

REP_DNS_NAME: o nome DNS público do endpoint regional de destino. Por exemplo, spanner.me-central2.rep.googleapis.com.
ADDRESS: o endereço IP do endpoint.
PATH: o caminho para um recurso que é disponibilizado por este serviço. Por exemplo, muitos serviços oferecem um documento de descoberta com o caminho $discovery/rest?version=v1.

O exemplo de solicitação a seguir testa se um endpoint com o endereço IP 192.168.1.100 pode solicitar o documento de descoberta da API Cloud Spanner do endpoint regional em me-central2.

curl --connect-to spanner.me-central2.rep.googleapis.com:443:192.168.1.100:443 \
'https://spanner.me-central2.rep.googleapis.com/$discovery/rest?version=v1'

Criar uma entrada de DNS particular para o endpoint

É necessário criar entradas de DNS particulares para que os clientes possam encaminhar solicitações ao endpoint do Private Service Connect.

Recomendamos criar uma zona particular que use o mesmo nome do host do endpoint regional de destino: SERVICE.REGION.rep.DOMAIN e criar um registro apex nessa zona.

Por exemplo, se o endpoint do Private Service Connect tiver spanner.me-central2.rep.googleapis.com como destino, crie uma zona particular para spanner.me-central2.rep.googleapis.com que contenha um registro apex para spanner.me-central2.rep.googleapis.com. Criar registros no do domínio significa que você pode acessar o nome do host público de outros endpoints regionais, como logging.me-central2.rep.googleapis.com.

Nas seções a seguir, descrevemos como usar o Cloud DNS para criar uma zona particular e um registro DNS de apex.

Criar uma zona particular

Console

No console do Google Cloud , acesse a página Criar zona de DNS.

Acessar a página Criar zona de DNS
Em Tipo de zona, selecione Particular.
Em Nome da zona, digite um nome. Por exemplo, se o endpoint do Private Service Connect apontar para spanner.me-central2.rep.googleapis.com, digite spanner-me-central2-rep-googleapis-com.
Em Nome DNS, especifique o nome do host do endpoint regional de destino seguido por um ponto final. Por exemplo, spanner.me-central2.rep.googleapis.com..
Opcional: adicione uma descrição.
Em Opções, selecione Padrão (privado).
Selecione as redes VPC em que você quer que a zona privada fique visível. Somente as redes VPC selecionadas estão autorizadas a consultar registros na zona.
Clique em Criar.

gcloud

Execute o comando dns managed-zones create:

gcloud dns managed-zones create ZONE_NAME \
    --dns-name=REP_DNS_NAME. \
    --networks=VPC_NETWORK_LIST \
    --visibility=private \
    --description="Private zone for REP_DNS_NAME"

Substitua:

ZONE_NAME: um nome para a zona. Por exemplo, spanner-me-central2-rep-googleapis.com.
DESCRIPTION: uma descrição para a zona
REP_DNS_NAME: o sufixo DNS da zona. Use o nome do host do endpoint regional de destino. Por exemplo, spanner.me-central2.rep.googleapis.com.
VPC_NETWORK_LIST: uma lista de VPCs que estão autorizadas a consultar a zona, separadas por vírgulas.

API

Envie uma solicitação POST usando o método managedZones.create:

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "name": "ZONE_NAME",
  "dnsName": "REP_DNS_NAME.",
  "description": "DESCRIPTION",
  "visibility": "private",
  "privateVisibilityConfig": {
    "kind": "dns#managedZonePrivateVisibilityConfig",
    "networks": [
      {
        "kind": "dns#managedZonePrivateVisibilityConfigNetwork",
        "networkUrl": "NETWORK_1_URL"
      },
      {
        "kind": "dns#managedZonePrivateVisibilityConfigNetwork",
        "networkUrl": "NETWORK_2_URL"
      }
    ]
  }
}

Substitua:

PROJECT_ID: o ID do projeto da zona DNS.
ZONE_NAME: o nome da zona particular que você criou para esse endpoint regional.
REP_DNS_NAME: o FQDN do registro que você está criando. Use o nome do host do endpoint regional de destino. Por exemplo, spanner.me-central2.rep.googleapis.com.
DESCRIPTION: uma descrição para a zona de DNS.
NETWORK_1_URL e NETWORK_2_URL: os URLs completos das redes VPC autorizadas a consultar a zona. Por exemplo, https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/NETWORK_NAME.

Adicionar um registro DNS à zona

Console

No console do Google Cloud , acesse a página Zonas do Cloud DNS.

Acessar Zonas do Cloud DNS
Clique no nome da zona gerenciada a que você quer adicionar o registro.
Na página Detalhes da zona, clique em Adicionar padrão.
Na página Criar conjunto de registros, deixe o campo Nome do DNS em branco. Se você deixar o campo em branco, um registro de recurso será criado na raiz do domínio.
Em Tipo de registro de recurso, selecione A.
No campo Endereço IPv4, digite ou selecione o endereço IP do endpoint do Private Service Connect.
Clique em Criar.

gcloud

Para adicionar um conjunto de registros de recursos, use o comando gcloud dns record-sets create:

gcloud dns record-sets create REP_DNS_NAME \
    --rrdatas=ADDRESS \
    --type=RECORD_TYPE \
    --ttl=TTL \
    --zone=ZONE_NAME

Substitua:

REP_DNS_NAME: o FQDN do registro que você está criando. Use o nome do host do endpoint regional de destino. Por exemplo, spanner.me-central2.rep.googleapis.com.
ADDRESS: o endereço IP do endpoint do Private Service Connect.
RECORD_TYPE: o tipo de registro DNS, como A para registros IPv4 ou AAAA para registros IPv6.
TTL: o TTL (em segundos) do armazenamento em cache do conjunto de registros de recurso. Por exemplo, 300
ZONE_NAME: o nome da zona particular que você criou para esse endpoint regional.

API

Para adicionar um conjunto de registros de recursos, use o método resourceRecordSets.create:

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "name": "REP_DNS_NAME.",
  "type": "RECORD_TYPE",
  "ttl": TTL,
  "rrdatas": [ "ADDRESS" ]
}

Substitua:

PROJECT_ID: o ID do projeto da zona DNS.
ZONE_NAME: o nome da zona particular que você criou para esse endpoint regional.
REP_DNS_NAME: o FQDN do registro que você está criando. Use o nome do host do endpoint regional de destino. Por exemplo, spanner.me-central2.rep.googleapis.com.
RECORD_TYPE: o tipo de registro DNS, como A para registros IPv4 ou AAAA para registros IPv6.
TTL: o TTL (em segundos) do armazenamento em cache do conjunto de registros de recurso. Por exemplo, 300
ADDRESS: o endereço IP do endpoint do Private Service Connect.

Configurar clientes para usar o nome do endpoint particular

Configure os clientes para usar os nomes DNS particulares em vez dos nomes DNS públicos. 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 as etapas de configuração de 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.
Java: é possível configurar setEndpoint na classe de configurações do cliente.
gcloud: é possível configurar api_endpoint_overrides na gcloud CLI.

Acessar informações detalhadas sobre um endpoint

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

gcloud

Use o comando gcloud network-connectivity regional-endpoints describe:

gcloud network-connectivity regional-endpoints describe \
    ENDPOINT_NAME --region=REGION

Substitua:

ENDPOINT_NAME: o nome do endpoint.
REGION: a região do endpoint.

API

Use o comando projects.locations.regionalEndpoints.get.

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints/ENDPOINT_NAME

Substitua:

PROJECT_ID: o ID do projeto do endpoint.
REGION: a região dos endpoints que você quer listar.
ENDPOINT_NAME: o nome do endpoint.

Atualizar a configuração de acesso global

Não é possível atualizar um endpoint do Private Service Connect que tenha um destino de endpoint regional. Se você precisar mudar a configuração de acesso global do endpoint, exclua o endpoint e crie um endpoint com a configuração de acesso global necessária.

Excluir um endpoint

É possível excluir um endpoint.

gcloud

Use o comando gcloud network-connectivity regional-endpoints delete:

gcloud network-connectivity regional-endpoints delete \
    ENDPOINT_NAME --region=REGION

Substitua:

ENDPOINT_NAME: o nome do endpoint.
REGION: a região do endpoint.

API

Use o comando projects.location.regionalEndpoints.delete.

DELETE https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints/ENDPOINT_NAME

Substitua:

PROJECT_ID: o ID do projeto do endpoint.
REGION: a região do endpoint.
ENDPOINT_NAME: o nome do endpoint.

Acessar endpoints em redes híbridas

Os clientes em redes conectadas ao Google Cloud com anexos da VLAN para túneis do Cloud Interconnect ou do Cloud VPN podem alcançar endpoints do Private Service Connect.

O anexo da VLAN ou o túnel do Cloud VPN precisa terminar na mesma rede VPC (ou rede VPC compartilhada) que o endpoint. Os clientes em redes VPC com peering não podem acessar os endpoints.
O tráfego de cliente de anexos da VLAN ou túneis do Cloud VPN poderá acessar endpoints em outra região se o acesso global estiver configurado.
O Dataplane v1 e o Dataplane v2 têm suporte para os anexos da VLAN. Saiba mais sobre as versões do Dataplane em Dataplane v2.

É preciso configurar os sistemas na outra rede para que eles possam fazer consultas nas suas zonas DNS particulares.

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

Crie uma política de servidor de entrada na rede VPC a que a outra rede se conecta.
Identifique os pontos de entrada do encaminhador de entrada na região em que o anexo da VLAN ou o túnel do Cloud VPN está localizado, na rede VPC a que sua outra rede se conecta.
Configure sistemas e servidores de nomes DNS na outra rede para encaminhar os nomes DNS do endpoint a um ponto de entrada do encaminhador de entrada na mesma região do anexo da VLAN ou do túnel do Cloud VPN que se conecta à rede VPC.