Accedi alle API di Google tramite endpoint

Questo documento spiega come usare gli endpoint Private Service Connect per connettersi alle API di Google. Anziché inviare richieste API agli indirizzi IP disponibili pubblicamente per gli endpoint di servizio come storage.googleapis.com, puoi inviare le richieste all'indirizzo IP interno di un endpoint.

Puoi utilizzare Private Service Connect anche per accedere ai servizi in un'altra rete VPC e per pubblicare servizi.

Ruoli

I seguenti ruoli IAM forniscono le autorizzazioni necessarie per eseguire le attività descritte in questa guida.

Attività Ruoli
Creazione di un endpoint Tutti i ruoli seguenti:
Amministratore rete Compute (roles/compute.networkAdmin),
Editor Service Directory (roles/servicedirectory.editor) e
Amministratore DNS (roles/dns.admin)
Configurare l'accesso privato Google (facoltativo) Amministratore rete Compute (roles/compute.networkAdmin)

Prima di iniziare

  • Per ulteriori informazioni, tra cui la configurazione e le limitazioni del DNS, consulta Informazioni sulla connessione alle API di Google tramite gli endpoint.

  • Private Service Connect non abilita automaticamente nessuna API. Devi abilitare separatamente le API Google che devi utilizzare dalla pagina API e servizi della console Google Cloud.

  • Devi enable l'API Compute Engine nel tuo progetto.

  • Devi enable l'API Service Directory nel tuo progetto.

  • Devi enable l'API Cloud DNS nel tuo progetto.

  • Devi scegliere un indirizzo IP da utilizzare per l'endpoint. Per informazioni sugli indirizzi IP che puoi utilizzare, consulta i requisiti degli indirizzi IP.

  • Le regole firewall in uscita devono consentire il traffico verso l'endpoint. La configurazione del firewall predefinita per una rete VPC consente questo traffico, perché contiene una regola implicita di autorizzazione in uscita. Verifica di non aver creato una regola in uscita con priorità più elevata che blocchi il traffico.

  • Le istanze di macchine virtuali (VM) senza un indirizzo IP esterno assegnato devono utilizzare una subnet con accesso privato Google abilitato per accedere alle API e ai servizi Google tramite un endpoint.

    Una VM con un indirizzo IP esterno può accedere alle API e ai servizi Google tramite gli endpoint anche se l'accesso privato Google è disabilitato per la rispettiva subnet. La connettività all'endpoint rimane all'interno della rete Google.

  • Se la tua rete VPC non contiene endpoint, controlla se esiste una zona privata di Cloud DNS per p.googleapis.com. Se la zona esiste, eliminala prima di creare l'endpoint. Se non la elimini, la creazione della zona DNS di Service Directory utilizzata per Private Service Connect non va a buon fine. Per ulteriori informazioni, consulta la risoluzione dei problemi.

  • Gli endpoint non sono accessibili dalle reti VPC in peering.

Abilita l'accesso privato Google per una subnet

Le VM a cui non è assegnato un indirizzo IP esterno devono essere connesse a una subnet con accesso privato Google abilitato per accedere alle API e ai servizi Google utilizzando un endpoint.

Se la VM ha più di un'interfaccia, connetti l'interfaccia configurata con una route predefinita (di solito nic0).

L'indirizzo IP di origine dei pacchetti inviati dalla VM deve corrispondere all'indirizzo IPv4 interno principale dell'interfaccia della VM o a un indirizzo IPv4 interno da un intervallo IP alias.

Per abilitare l'accesso privato Google su una subnet, segui questi passaggi.

Console

  1. Nella console Google Cloud, vai alla pagina Reti VPC.

    Vai a Reti VPC

  2. Fai clic sul nome della rete che contiene la subnet per la quale è necessario abilitare l'accesso privato Google.

  3. Fai clic sul nome della subnet. Viene visualizzata la pagina Dettagli subnet.

  4. Fai clic su Modifica.

  5. Nella sezione Accesso privato Google, seleziona On.

  6. Fai clic su Salva.

gcloud

  1. Determina il nome e la regione della subnet. Per elencare le subnet per una rete specifica, usa il comando seguente:

    gcloud compute networks subnets list --filter=NETWORK_NAME

  2. Esegui questo comando per abilitare l'accesso privato Google:

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

  3. Verifica che l'accesso privato Google sia abilitato eseguendo questo comando:

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

Sostituisci quanto segue:

  • SUBNET_NAME: il nome della subnet
  • REGION: la regione della subnet
  • NETWORK_NAME: il nome della rete VPC che contiene la subnet

Terraform

Puoi utilizzare la risorsa Terraform per abilitare l'accesso privato Google su una subnet.

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
}

Per scoprire come applicare o rimuovere una configurazione Terraform, vedi Comandi Terraform di base.

Creazione di un endpoint

Dopo aver scelto un indirizzo IP che soddisfa i requisiti, puoi creare un endpoint.

Un endpoint si connette alle API e ai servizi Google usando una regola di forwarding globale. Ogni regola di forwarding viene inclusa nel calcolo della quota di rete VPC per Private Service Connect.

Non puoi aggiornare un endpoint per le API e i servizi Google dopo la creazione. Se devi aggiornare un endpoint per le API e i servizi Google, eliminalo e creane uno nuovo.

Console

  1. Nella console Google Cloud, vai alla pagina Private Service Connect.

    Vai a Private Service Connect

  2. Fai clic sulla scheda Endpoint connessi.

  3. Fai clic su Connetti endpoint.

  4. In Destinazione, seleziona il pacchetto di API target che vuoi utilizzare:

    • Tutte le API di Google
    • VPC-SC

  5. In Nome endpoint, inserisci un nome per l'endpoint.

  6. Seleziona una Rete per l'endpoint.

  7. Seleziona un Indirizzo IP per l'endpoint.

    L'indirizzo IP deve soddisfare questi requisiti.

    Se hai bisogno di un nuovo indirizzo IP, puoi crearne uno:

    1. Fai clic su Crea indirizzo IP.
    2. Inserisci un Nome e una Descrizione per l'indirizzo IP.
    3. Inserisci l'indirizzo IP che vuoi utilizzare e fai clic su Salva .

  8. Se non è già configurata una regione di Service Directory per questa rete VPC, seleziona la regione che vuoi utilizzare.

    Tutti gli endpoint utilizzati per accedere alle API e ai servizi Google in una determinata rete VPC utilizzano la stessa regione di Service Directory.

  9. Se per questa rete VPC non è già configurato uno spazio dei nomi di Service Directory, configura lo spazio dei nomi che vuoi utilizzare:

    • Per utilizzare uno spazio dei nomi assegnato automaticamente, fai clic sul menu a discesa Spazio dei nomi e seleziona lo spazio dei nomi assegnato automaticamente.

    • Per selezionare uno spazio dei nomi esistente utilizzato in un'altra rete, fai clic sul menu a discesa Spazio dei nomi e seleziona uno spazio dei nomi dall'elenco. L'elenco mostra tutti gli spazi dei nomi nel progetto. Devi selezionare uno spazio dei nomi utilizzato solo per gli endpoint utilizzati per accedere alle API di Google.

    • Per creare un nuovo spazio dei nomi, fai clic sul menu a discesa Spazio dei nomi e poi su Crea spazio dei nomi. Inserisci lo spazio dei nomi e fai clic su Crea.

    Tutti gli endpoint che utilizzi per accedere alle API e ai servizi Google in una determinata rete VPC utilizzano lo stesso spazio dei nomi di Service Directory.

  10. Fai clic su Aggiungi endpoint.

gcloud

  1. Prenota un indirizzo IP interno globale da assegnare all'endpoint.

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

    Sostituisci quanto segue:

    • ADDRESS_NAME: il nome da assegnare all'indirizzo IP prenotato.

    • ENDPOINT_IP: l'indirizzo IP da prenotare per l'endpoint.

      L'indirizzo IP deve soddisfare questi requisiti.

    • NETWORK_NAME: il nome della rete VPC per l'endpoint.

  2. Creare una regola di forwarding per connettere l'endpoint alle API e ai servizi 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 ]

    Sostituisci quanto segue:

    • ENDPOINT_NAME: il nome da assegnare all'endpoint. Il nome deve essere una stringa di 1-20 caratteri, contenente solo lettere minuscole e numeri. Il nome deve iniziare con una lettera.

    • NETWORK_NAME: il nome della rete VPC per l'endpoint.

    • ADDRESS_NAME: il nome dell'indirizzo riservato sulla rete associata.

    • API_BUNDLE: il bundle di API da rendere disponibile utilizzando l'endpoint. Consulta l'elenco delle API supportate.

      • Usa all-apis per concedere l'accesso a tutte le API supportate.

      • Usa vpc-sc per limitare l'accesso alle API di Google che supportano i Controlli di servizio VPC.

    • REGION_NAMESPACE_URI: l'URI della regione o dello spazio dei nomi di Service Directory che vuoi utilizzare. Questo URI deve fare riferimento allo stesso progetto in cui stai creando l'endpoint.

      • Puoi definire una regione solo con projects/PROJECT_NAME/locations/REGION.

      • Puoi definire una regione e uno spazio dei nomi con projects/PROJECT_NAME/locations/REGION/namespaces/NAMESPACE.

      Se ometti completamente --service-directory-registration o imposti una regione senza spazio dei nomi, si verifica quanto segue:

      • Se per questa rete VPC è già configurato una regione o uno spazio dei nomi, vengono usati i valori predefiniti.

      • Se non è configurata una regione, è impostata su us-central1. Se uno spazio dei nomi non è configurato, ne viene assegnato uno generato dal sistema.

API

  1. Prenota un indirizzo IP interno globale da assegnare all'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
}

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.

    • ADDRESS_NAME: il nome da assegnare all'indirizzo IP prenotato.

    • ENDPOINT_IP: l'indirizzo IP da prenotare per l'endpoint.

      L'indirizzo IP deve soddisfare questi requisiti.

    • NETWORK_URL: la rete VPC dell'endpoint. Utilizza il metodo network.list o gcloud compute networks list --uri per trovare gli URL delle tue reti.

  2. Creare una regola di forwarding per connettere l'endpoint alle API e ai servizi 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"

   }
 ],
}

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.

    • ENDPOINT_NAME: il nome da assegnare all'endpoint. Il nome deve essere una stringa di 1-20 caratteri contenente solo lettere minuscole e numeri. Il nome deve iniziare con una lettera.

    • NETWORK_URL: la rete VPC dell'endpoint. Utilizza il metodo network.list o gcloud compute networks list --uri per trovare gli URL delle tue reti.

    • ADDRESS_URL: l'URL dell'indirizzo riservato sulla rete associata. Utilizza il metodo globalAddresses.list o gcloud compute addresses list --uri per trovare gli URL degli indirizzi prenotati.

    • API_BUNDLE: il bundle di API da rendere disponibili utilizzando l'endpoint. Consulta l'elenco delle API supportate.

      • Usa all-apis per concedere l'accesso a tutte le API supportate.

      • Usa vpc-sc per limitare l'accesso alle API di Google che supportano i Controlli di servizio VPC.

    • REGION: la regione di Service Directory che vuoi utilizzare. Ad esempio: us-central1. Se ometti REGION ed è già configurata una regione per questa rete VPC, viene utilizzata quella regione. Se una regione non è configurata, è impostata su us-central1.

    • NAMESPACE: il nome dello spazio dei nomi di Service Directory che vuoi utilizzare. Se ometti NAMESPACE ed è già configurato uno spazio dei nomi per questa rete VPC, verrà utilizzato quello spazio dei nomi. Se uno spazio dei nomi non è configurato, viene assegnato uno spazio dei nomi generato dal sistema.

Terraform

Per creare un endpoint, puoi usare le seguenti risorse Terraform:

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 = ""
}

Verifica che l'endpoint funzioni

Creare un'istanza VM nella rete VPC in cui è configurato Private Service Connect. Esegui questo comando sulla VM per verificare che l'endpoint Private Service Connect funzioni. Gli endpoint non rispondono alle richieste ping (ICMP).

curl -v ENDPOINT_IP/generate_204

Sostituisci ENDPOINT_IP con l'indirizzo IP dell'endpoint.

Se l'endpoint funziona, viene visualizzato un codice di risposta HTTP 204.

Elenco endpoint

Puoi elencare tutti gli endpoint configurati.

Console

  1. Nella console Google Cloud, vai alla pagina Private Service Connect.

    Vai a Private Service Connect

  2. Fai clic sulla scheda Endpoint connessi.

    Vengono visualizzati gli endpoint.

gcloud

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

L'output è simile al seguente:

NAME  REGION  IP_ADDRESS  IP_PROTOCOL  TARGET
RULE          IP          TCP          all-apis

Ottenere informazioni su un endpoint

Puoi vedere tutti i dettagli di configurazione di un endpoint.

Console

  1. Nella console Google Cloud, vai alla pagina Private Service Connect.

    Vai a Private Service Connect

  2. Fai clic sulla scheda Endpoint connessi.

    Vengono visualizzati gli endpoint.

  3. Fai clic sull'endpoint di cui vuoi visualizzare i dettagli.

gcloud 

gcloud compute forwarding-rules describe \
    ENDPOINT_NAME --global

Etichetta un endpoint

Puoi gestire le etichette per gli endpoint. Per ulteriori informazioni, consulta la sezione sulle risorse di etichettatura.

Eliminazione di un endpoint

Puoi eliminare un endpoint.

Console

  1. Nella console Google Cloud, vai alla pagina Private Service Connect.

    Vai a Private Service Connect

  2. Fai clic sulla scheda Endpoint connessi.

  3. Seleziona l'endpoint che vuoi eliminare e fai clic su Elimina.

gcloud 

    gcloud compute forwarding-rules delete \
        ENDPOINT_NAME --global

Sostituisci ENDPOINT_NAME con il nome dell'endpoint che vuoi eliminare.

utilizza un endpoint

Per utilizzare un endpoint, devi inviare richieste a un nome host DNS che si risolve all'indirizzo IP dell'endpoint.

  • Puoi utilizzare i nomi DNS p.googleapis.com creati automaticamente se puoi configurare i tuoi client in modo che utilizzino un endpoint personalizzato e se vengono creati record DNS p.googleapis.com per le API e i servizi che vuoi utilizzare. Per maggiori informazioni, vedi Utilizzare i nomi DNS p.googleapis.com.

    Ad esempio, se il nome dell'endpoint è xyz, vengono creati record DNS per storage-xyz.p.googleapis.com, compute-xyz.p.googleapis.com e altre API comunemente utilizzate nel bundle di API.

  • Puoi creare record DNS utilizzando i nomi DNS predefiniti se utilizzi un client che non è stato configurato per l'utilizzo di un endpoint personalizzato o se non esiste un record DNS p.googleapis.com per il servizio che vuoi utilizzare. Per ulteriori informazioni, consulta Creare record DNS utilizzando nomi DNS predefiniti.

    Ad esempio, crea record DNS per storage.googleapis.com e compute.googleapis.com.

Usa nomi DNS p.googleapis.com

Quando crei un endpoint, Service Directory crea i record DNS per le API e i servizi di uso comune disponibili utilizzando l'endpoint. I record DNS vengono creati solo per le API e i servizi che hanno nomi DNS predefiniti che terminano con googleapis.com e solo per un sottoinsieme di API e servizi.

I record DNS vengono creati in una zona privata p.googleapis.com. I record rimandano all'indirizzo IP dell'endpoint e usano questo formato: SERVICE-ENDPOINT.p.googleapis.com

Ad esempio, se il nome dell'endpoint è xyz, vengono creati record DNS per storage-xyz.p.googleapis.com, compute-xyz.p.googleapis.com e altre API supportate.

I client che possono essere configurati per utilizzare un endpoint personalizzato possono usare i nomi DNS di p.googleapis.com per inviare richieste a un endpoint.

Consulta la documentazione della libreria client o client per informazioni su come configurarla per l'utilizzo di endpoint personalizzati. Ad esempio:

  • Python: puoi configurare api_endpoint in Opzioni client.

  • Vai: puoi configurare WithEndpoint in ClientOptions.

  • .NET: puoi configurare Endpoint nella classe del builder del client.

  • gcloud: puoi configurare api_endpoint_overrides in gcloud CLI.

Crea record DNS utilizzando nomi DNS predefiniti

È necessario creare record DNS per indirizzare i nomi DNS predefiniti per API e servizi all'endpoint in queste circostanze:

  • Impossibile configurare il client o l'applicazione per l'utilizzo di un nome DNS p.googleapis.com.

  • Devi accedere a un servizio supportato, ma non viene creato automaticamente un nome DNS p.googleapis.com per quel servizio.

Per creare record DNS che puntino all'endpoint Private Service Connect, segui queste istruzioni:

  1. Crea una zona DNS per il dominio che devi utilizzare (ad esempio, googleapis.com o gcr.io). Potresti creare una zona privata di Cloud DNS a questo scopo.

  2. In questa zona DNS:

    1. Crea un record A per il nome del dominio (zona), ad esempio googleapis.com o gcr.io. Punta questo record A all'indirizzo IP dell'endpoint. Se utilizzi Cloud DNS, consulta Aggiunta di un record.

    2. Crea un record CNAME per tutti i possibili nomi host del dominio aggiuntivo utilizzando un asterisco e un punto seguiti dal nome del dominio (zona); ad esempio, *.googleapis.com o *.gcr.io. Punta questo record CNAME al record A nella stessa zona. Ad esempio, punta *.googleapis.com a googleapis.com o *.gcr.io a gcr.io.

Accedi all'endpoint da host on-premise

Se la tua rete on-premise è connessa a una rete VPC, puoi utilizzare Private Service Connect per accedere alle API e ai servizi Google da host on-premise utilizzando l'indirizzo IP interno dell'endpoint.

  • La rete on-premise deve essere connessa a una rete VPC tramite tunnel Cloud VPN o collegamenti VLAN per Cloud Interconnect.

  • L'endpoint deve trovarsi nella rete VPC connessa alla rete on-premise.

  • La rete on-premise deve avere route appropriate per l'endpoint. Configura un pubblicità di route personalizzate per il router Cloud per annunciare le route per l'endpoint sulla sessione BGP che gestisce le route per il tunnel Cloud VPN o il collegamento VLAN.

    • Se la tua rete on-premise utilizza il routing ECMP (Equal-cost multi-path) per distribuire il traffico agli endpoint Private Service Connect, devi assicurarti che tutti i pacchetti per una singola connessione TCP vengano instradati tramite lo stesso tunnel Cloud VPN o collegamento VLAN. Se i pacchetti per una connessione TCP stabilita vengono indirizzati su più percorsi, si potrebbero verificare reset TCP (RST) intermittenti. Per evitare le reimpostazioni, configura i router peer on-premise per mantenere destinazioni coerenti dell'hop successivo.

  • Devi configurare i sistemi on-premise in modo che possano eseguire query sulle tue zone DNS private.

    Se hai implementato le zone DNS private utilizzando Cloud DNS, completa questi passaggi:

Risoluzione dei problemi

Le sezioni seguenti contengono informazioni sulla risoluzione dei problemi con gli endpoint Private Service Connect utilizzati per accedere alle API di Google.

Creazione di una zona DNS privata non riuscita

Quando crei un endpoint, viene creata una zona DNS di Service Directory. La creazione di una zona può non riuscire per i seguenti motivi:

  • Non hai abilitato l'API Cloud DNS nel tuo progetto.

  • Non hai le autorizzazioni necessarie per creare una zona DNS di Service Directory.

  • In questa rete VPC esiste una zona DNS con lo stesso nome.

  • Una zona DNS per p.googleapis.com esiste già in questa rete VPC.

Potrebbero esistere zone in conflitto a causa di un'eliminazione precedente non riuscita.

Per creare la zona DNS di Service Directory, segui questi passaggi:

  1. Verifica che l'API Cloud DNS sia abilitata nel tuo progetto.

  2. Verifica di disporre delle autorizzazioni necessarie per creare la zona DNS di Service Directory:

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

  3. Elimina la zona DNS.

  4. Crea una zona DNS di Service Directory supportata dallo spazio dei nomi di Service Directory associato al tuo endpoint.

    Utilizza i seguenti valori quando crei la zona:

    • Nome zona: utilizza lo stesso nome di zona utilizzato dal sistema durante il tentativo di creazione non riuscito. Il messaggio di errore visualizza il nome della zona utilizzato.

    • Nome DNS: p.googleapis.com. (incluso il punto finale).

    • Spazio dei nomi di Service Directory: trova lo spazio dei nomi di Service Directory per l'endpoint Private Service Connect che hai creato e utilizzalo quando crei la zona DNS di Service Directory.

    Lo spazio dei nomi di Service Directory ha il seguente formato: goog-psc-NETWORK_NAME-NETWORK_ID.

L'eliminazione della zona DNS privata non è riuscita

Quando elimini l'ultimo endpoint in una rete VPC, la configurazione di Service Directory associata, inclusa la zona DNS, viene eliminata.

Questa eliminazione può non riuscire per i seguenti motivi:

  • Non hai le autorizzazioni necessarie per eliminare la zona DNS.

  • La zona contiene voci DNS definite dall'utente che non sono state create da Service Directory.

Per risolvere il problema:

  1. Verifica di avere l'autorizzazione dns.managedZones.delete. Per ulteriori informazioni, consulta Controllo dell'accesso nella documentazione di Cloud DNS.

  2. Elimina la zona DNS.