Esta página foi traduzida pela API Cloud Translation.

Acessar APIs regionais do Google por meio de 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 por meio de papéis personalizados ou de 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 CLI gcloud, pode verificar se tem a versão mais recente executando gcloud components update.
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 para o 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 automaticamente nenhuma API.
Verifique se as regras de firewall de saída permitem o 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.

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 para uma API de destino do Google.

Para uma lista de endpoints regionais compatíveis, consulte endpoints de serviço regional.

Console

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

Acessar a página "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, insira um nome para o endpoint.
Em Rede, selecione uma rede.
Em Sub-rede, selecione uma sub-rede.
Em Endereço IP, faça o seguinte 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 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 você quiser disponibilizar o endpoint para recursos em outras regiões, adicione a sinalização --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 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 do 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 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 do 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 do 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 Google Cloud , acesse a página Private Service Connect.

Acessar a página "Private Service Connect"
Clique na guia Endpoints conectados.

Todos os endpoints são exibidos, incluindo os endpoints 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.

Verifique 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 direcionar solicitações ao endpoint do Private Service Connect.

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

Por exemplo, se o endpoint do Private Service Connect tiver um destino de spanner.me-central2.rep.googleapis.com, crie uma zona particular para spanner.me-central2.rep.googleapis.com que contenha um registro de vértice para spanner.me-central2.rep.googleapis.com. Criar registros no ápice 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.

As seções a seguir descrevem como usar o Cloud DNS para criar uma zona particular e um registro DNS de vértice.

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 Private.
Em Nome da zona, insira um nome. Por exemplo, se o endpoint do Private Service Connect apontar para spanner.me-central2.rep.googleapis.com, insira 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 sua zona, por exemplo, spanner-me-central2-rep-googleapis.com.
DESCRIPTION: uma descrição para a zona;
REP_DNS_NAME: o sufixo DNS da sua zona. Use o nome do host do endpoint regional de destino. Por exemplo, spanner.me-central2.rep.googleapis.com.
VPC_NETWORK_LIST: uma lista delimitada por vírgulas de redes VPC que estão autorizadas a consultar a zona.

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

Solicitar corpo JSON:

{
  "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 a página 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, insira 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 que o resolvedor armazena em cache esse conjunto de registros de recursos. 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

Solicitar corpo JSON:

{
  "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 que o resolvedor armazena em cache esse conjunto de registros de recursos. 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 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 CLI gcloud.

Receber informações detalhadas sobre um endpoint

É possível ver 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 novo 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 de 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) como endpoint. Os clientes em redes VPC com peering não podem alcançar os endpoints.
O tráfego de cliente de anexos da VLAN ou túneis do Cloud VPN pode alcançar 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. Para mais informações sobre as versões do Dataplane, consulte Dataplane v2.

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

Se você tiver implementado as zonas de DNS particular usando o Cloud DNS, conclua 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 para o 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.