Configurare Cloud Endpoints gRPC per Cloud Run con ESPv2

Questa pagina mostra come configurare Cloud Endpoints per Cloud Run con un backend gRPC. Endpoints utilizza Extensible Service Proxy V2 (ESPv2) come gateway API. Per fornire la gestione delle API per Cloud Run, esegui il deployment del modello il container ESPv2 in Cloud Run. A questo punto, contribuisci a proteggere i tuoi servizi utilizzando Cloud Run IAM in modo che ESPv2 possa invocarli.

Con questa configurazione, ESPv2 intercetta tutte le richieste ai tuoi servizi ed esegue controlli necessari (come l'autenticazione) prima di richiamare il servizio. Quando il servizio risponde, ESPv2 raccoglie e segnala la telemetria, come mostrato nella figura seguente. Puoi visualizzare le metriche del tuo servizio nella pagina Endpoints > Servizi nella console Google Cloud.

Architettura di Endpoints

Per una panoramica di Cloud Endpoints, consulta Informazioni su Endpoints e Architettura di Endpoints.

Migrazione a ESPv2

Le versioni precedenti di Cloud Endpoints non supportavano gRPC su Cloud Run con ESP. Per utilizzare questa funzionalità, esegui la migrazione a Extensible Service Proxy V2.

Elenco attività

Durante il tutorial, utilizza il seguente elenco di attività. Tutte per completare questo tutorial.

  1. Crea un progetto Google Cloud e, se non hai ancora eseguito il deployment di Cloud Run, esegui il deployment di un servizio gRPC di backend di esempio. Vedi Prima di iniziare.
  2. Prenota un nome host Cloud Run per il servizio ESPv2. Consulta Prenotare un nome host Cloud Run.
  3. Crea un documento di configurazione dell'API gRPC che descriva l'API e configura le route per Cloud Run. Consulta Configurazione di Endpoints.
  4. Esegui il deployment del documento di configurazione dell'API gRPC per creare un servizio gestito. Consulta Eseguire il deployment della configurazione di Endpoints.
  5. crea una nuova immagine Docker ESPv2 con i tuoi endpoint la configurazione del servizio. Consulta Creazione di una nuova immagine ESPv2.
  6. Eseguire il deployment del container ESPv2 su Cloud Run. Quindi concedi a ESPv2 Identity and Access Management (IAM) per richiamare il tuo servizio. Vedi Deployment del container ESPv2.
  7. Richiama un servizio. Consulta Invio di una richiesta all'API.
  8. Monitora l'attività relativa ai tuoi servizi. Consulta Monitoraggio dell'attività dell'API.
  9. Evita che al tuo account Google Cloud vengano addebitati costi. Consulta Pulizia.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Una volta completate le attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la pagina Pulizia.

Prima di iniziare

Per eseguire la configurazione:

  1. Nella console Google Cloud, vai alla pagina Gestisci risorse e creo un progetto.

    Vai alla pagina Gestisci risorse

  2. Verifica che la fatturazione sia attivata per il tuo progetto.

    Scopri come attivare la fatturazione

  3. Prendi nota dell'ID progetto perché sarà necessario in seguito. Per il resto questo ID progetto è noto come ESP_PROJECT_ID.

  4. Prendi nota delle numero progetto perché è necessario più tardi. Nel resto della pagina, questo numero di progetto è denominata ESP_PROJECT_NUMBER.

  5. Scarica e installa Google Cloud CLI.

    Scarica l'interfaccia a riga di comando gcloud

  6. Segui i passaggi nella Guida rapida di gRPC Python per installare gRPC e gli strumenti gRPC.

  7. Esegui il deployment del backend di esempio python-grpc-bookstore-server Servizio Cloud Run gRPC da utilizzare in questo tutorial. Il servizio gRPC utilizza la seguente immagine container:

    gcr.io/endpointsv2/python-grpc-bookstore-server:2

    Segui i passaggi descritti in Guida rapida: deployment di un container di esempio predefinito per eseguire il deployment del servizio. Assicurati di sostituire l'immagine container specificata in questa guida rapida con gcr.io/endpointsv2/python-grpc-bookstore-server:2

    Nota della regione e dell'ID progetto in cui il servizio viene eseguito il deployment. Nel resto di questa pagina, questo ID progetto è indicato come BACKEND_PROJECT_ID. Il nome del servizio Cloud Run di cui è stato eseguito il deployment è denominata BACKEND_SERVICE_NAME. Il suo nome host Cloud Run è denominata BACKEND_HOST_NAME.

Prenotazione di un nome host Cloud Run

Devi prenotare un nome host Cloud Run per ESPv2 per poter configurare dalla configurazione del documento OpenAPI o del servizio gRPC. Per prenotare un nome host, esegui il deployment di un container di esempio in Cloud Run. Successivamente, eseguirai il deployment del contenitore ESPv2 sullo stesso servizio Cloud Run.

  1. Assicurati che gcloud CLI sia autorizzato ad accedere ai tuoi dati i servizi di machine learning.
    1. Accedi. 
      gcloud auth login
    2. Nella nuova scheda del browser che si apre, scegli un account con l'Editor. o Proprietario nel progetto Google Cloud per cui hai creato eseguendo il deployment di ESPv2 in Cloud Run.
  2. Imposta la regione. 
    gcloud config set run/region us-central1
  3. Esegui il deployment dell'immagine di esempio gcr.io/cloudrun/hello in Cloud Run. Sostituisci CLOUD_RUN_SERVICE_NAME con il nome che vuoi usare per il servizio. 
    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESP_PROJECT_ID

    Al completamento, il comando visualizza un messaggio simile al seguenti:

    Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

    Ad esempio, se imposti CLOUD_RUN_SERVICE_NAME su gateway:

    Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

    In questo esempio, https://gateway-12345-uc.a.run.app è l'elemento CLOUD_RUN_SERVICE_URL e gateway-12345-uc.a.run.app è CLOUD_RUN_HOSTNAME.

  4. Prendi nota di CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME. Successivamente, esegui il deployment di ESPv2 nel servizio CLOUD_RUN_SERVICE_NAME Cloud Run. Devi specificare CLOUD_RUN_HOSTNAME nel campo host del documento OpenAPI.

Configurazione di Endpoints

La bookstore-grpc contiene i file che devi copiare localmente e configurare.

  1. Crea un file descrittore protobuf autonomo dal file .proto del servizio:
    1. Salva una copia di bookstore.proto dal repository di esempio alla directory di lavoro attuale. Questo file definisce l'API del servizio Libreria.
    2. Crea la seguente directory nella tua directory di lavoro: mkdir generated_pb2
    3. Crea il file descrittore api_descriptor.pb utilizzando il compilatore di buffer di protocollo protoc. Esegui questo comando nella directory in cui hai salvato bookstore.proto: 
      python3 -m grpc_tools.protoc \
    --include_imports \
    --include_source_info \
    --proto_path=. \
    --descriptor_set_out=api_descriptor.pb \
    --python_out=generated_pb2 \
    --grpc_python_out=generated_pb2 \
    bookstore.proto

      Nel comando precedente, --proto_path è impostato sulla directory di lavoro corrente. Nell'ambiente di compilazione gRPC, se utilizzi una directory diversa per i file di input .proto, modifica --proto_path in modo che il compilatore cerchi nella directory in cui hai salvato bookstore.proto.

  2. Crea un file di testo denominato api_config.yaml nella tua directory di lavoro attuale (la stessa directory che contiene bookstore.proto). Per comodità, in questa pagina il documento di configurazione dell'API gRPC viene indicato con questo nome, ma puoi chiamarlo in un altro modo se preferisci. Aggiungi quanto segue i contenuti del file: 
    # The configuration schema is defined by the service.proto file.
# https://github.com/googleapis/googleapis/blob/master/google/api/service.proto

type: google.api.Service
config_version: 3
name: CLOUD_RUN_HOSTNAME
title: Cloud Endpoints + Cloud Run gRPC
apis:
  - name: endpoints.examples.bookstore.Bookstore
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true
backend:
  rules:
    - selector: "*"
      address: grpcs://BACKEND_HOST_NAME
    L'indentazione è importante per il formato YAML. Ad esempio, name deve essere allo stesso livello di type.

  3. Nel campo name, specifica CLOUD_RUN_HOSTNAME, la parte del nome host dell'URL riservato sopra in Prenotare un nome host Cloud Run. Non includere l'identificatore del protocollo, ad esempio https:// o grpcs://.

  4. Nel campo address della sezione backend.rules, sostituisci BACKEND_HOST_NAME con il servizio Cloud Run gRPC Bookstore effettivo creato in Prima di iniziare.

  5. Prendi nota del valore della proprietà title nel file api_config.yaml:

    title: Cloud Endpoints + Cloud Run gRPC

    Il valore della proprietà title diventa il nome del servizio Endpoints dopo il deployment della configurazione.

  6. Salva il documento di configurazione dell'API gRPC.

Consulta Configurazione di Endpoints per ulteriori informazioni.

esegui il deployment della configurazione di Endpoints

Per eseguire il deployment della configurazione di Endpoints, utilizza gcloud endpoints services deploy . Questo comando utilizza Gestione del servizio per creare un servizio gestito.

  1. Assicurati di trovarti nella directory in cui si trovano i file api_descriptor.pb e api_config.yaml.
  2. Conferma che il progetto predefinito a riga di comando gcloud attualmente in uso è il progetto Google Cloud che vuoi eseguire il deployment della configurazione di Endpoints. Convalida l'ID progetto restituito dal seguente comando per assicurarti che il servizio non venga creato nel progetto sbagliato. 
    gcloud config list project

    Se devi modificare il progetto predefinito, esegui questo comando:

    gcloud config set project YOUR_PROJECT_ID
  3. Esegui il deployment del file proto descriptor e del file di configurazione utilizzando l'interfaccia a riga di comando Google Cloud: 
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml

    Durante la creazione e la configurazione del servizio, Service Management genera le informazioni al terminale. Al termine del deployment, verrà visualizzato un messaggio simile a viene visualizzato quanto segue:

    Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

    CONFIG_ID è la configurazione univoca del servizio Endpoints ID creato dal deployment. Ad esempio:

    Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

    Nell'esempio precedente, 2017-02-13r0 è l'ID configurazione del servizio e bookstore.endpoints.example-project.cloud.goog è il nome del servizio. L'ID configurazione del servizio è costituito da una data seguita da un numero di revisione. Se esegui il deployment della configurazione di Endpoints sempre nello stesso giorno, il numero di revisione viene incrementato o l'ID configurazione.

Controllo dei servizi richiesti in corso...

Come minimo, Endpoints ed ESP richiedono seguenti servizi Google da attivare:
Nome Titolo
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control
endpoints.googleapis.com Google Cloud Endpoints

Nella maggior parte dei casi, il comando gcloud endpoints services deploy abilita questi servizi richiesti. Tuttavia, il comando gcloud viene completato correttamente, ma non attiva i servizi richiesti nelle seguenti circostanze:

  • Se hai utilizzato un'applicazione di terze parti, come Terraform, includono questi servizi.

  • Hai eseguito il deployment della configurazione di Endpoints in una Progetto Google Cloud in cui questi servizi sono stati disattivati esplicitamente.

Utilizza il comando seguente per confermare che i servizi richiesti siano abilitati:

gcloud services list

Se non vedi elencati i servizi richiesti, abilitali:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Abilita anche il servizio Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Per determinare il ENDPOINTS_SERVICE_NAME puoi:

  • Dopo aver eseguito il deployment della configurazione di Endpoints, vai alla pagina Endpoint nella console Cloud. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è riportato nella colonna Nome servizio.

  • Per OpenAPI, ENDPOINTS_SERVICE_NAME è quello che hai specificato nel campo host della specifica OpenAPI. Per gRPC, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel campo name della configurazione degli endpoint gRPC.

Per ulteriori informazioni sui comandi gcloud, consulta gcloud servizi.

Se ricevi un messaggio di errore, consulta Risoluzione dei problemi di deployment della configurazione di Endpoints.

Consulta Deployment della configurazione di Endpoints per ulteriori informazioni.

Creazione di una nuova immagine ESPv2

Crea la configurazione del servizio Endpoints in un nuovo ESPv2 Docker. Successivamente eseguirai il deployment di questa immagine dal servizio Cloud Run.

Per creare la configurazione del servizio in una nuova immagine Docker ESPv2:

  1. Scarica questo script alla macchina locale in cui è installato gcloud CLI.

  2. Esegui lo script con questo comando: 

    chmod +x gcloud_build_image

./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESP_PROJECT_ID

    Per CLOUD_RUN_HOSTNAME, specifica il nome host dell'URL che che hai prenotato sopra in Prenotare un nome host Cloud Run. Non includere l'identificatore di protocollo, https://.

    Ad esempio:

    chmod +x gcloud_build_image

./gcloud_build_image -s gateway-12345-uc.a.run.app \
    -c 2019-02-01r0 -p your-project-id

  3. Lo script utilizza il comando gcloud per scaricare la configurazione del servizio, creare in una nuova immagine ESPv2 e poi caricare la nuova immagine al Container Registry del tuo progetto. Lo script utilizza automaticamente la versione più recente di ESPv2, indicata dal carattere ESP_VERSION nel nome dell'immagine di output. L'immagine di output viene caricata in:

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID

    Ad esempio:

    gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

Deployment del container ESPv2

  1. Esegui il deployment del servizio Cloud Run ESPv2 con la nuova immagine creata sopra. Sostituisci CLOUD_RUN_SERVICE_NAME con lo stesso Cloud Run il nome del servizio utilizzato quando hai prenotato in origine il nome host sopra in Prenotazione di un nome host Cloud Run:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESP_PROJECT_ID

  2. Se vuoi configurare Endpoints in modo da utilizzare opzioni di avvio di ESPv2 aggiuntive, ad esempio l'attivazione di CORS, puoi passare gli argomenti nella variabile di ambiente ESPv2_ARGS:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESP_PROJECT_ID

    Per ulteriori informazioni ed esempi sull'impostazione della variabile di ambiente ESPv2_ARGS, tra cui l'elenco delle opzioni disponibili e informazioni su come specificare più opzioni, consulta i Flag di Extensible Service Proxy V2.

  3. Concedi a ESPv2 l'autorizzazione per richiamare i tuoi servizi Cloud Run. Esegui questo comando per ciascun servizio. Nel seguente comando:
    • Sostituisci BACKEND_SERVICE_NAME con il nome del servizio Cloud Run invocato. Se utilizzi il servizio creato eseguendo il deployment di "gcr.io/endpointsv2/python-grpc-bookstore-server:2", quindi usa python-grpc-bookstore-server come valore.
    • Sostituisci ESP_PROJECT_NUMBER con number del progetto per cui hai creato ESPv2. Per scoprirlo, puoi andare all' IAM nella console Google Cloud e trova Account di servizio Compute predefinito, ovvero l'account di servizio utilizzato in il flag "member".
    gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
  --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role "roles/run.invoker" \
  --platform managed \
  --project BACKEND_PROJECT_ID

Per ulteriori informazioni, vedi Gestione dell'accesso tramite IAM.

invia richieste all'API

Per inviare richieste all'API di esempio, puoi utilizzare un client gRPC di esempio scritto in Python.

  1. Clona il repository Git in cui è ospitato il codice client gRPC:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

  2. Cambia la directory di lavoro:

    cd python-docs-samples/endpoints/bookstore-grpc/

  3. Installa le dipendenze:

    pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt

  4. Invia una richiesta all'API di esempio:

    python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true

    Specifica il nome host del servizio Cloud Run ESPv2 in CLOUD_RUN_HOSTNAME, senza l'identificatore di protocollo. Ad esempio:

    python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true

    • Osserva i grafici delle attività dell'API nella Endpoint > Servizi.

      Vai alla pagina Servizi endpoint

      La visualizzazione dei dati relativi alla richiesta nei grafici può richiedere alcuni minuti.

    • Esamina i log delle richieste per la tua API nella pagina Esplora log.

      Vai alla pagina Esplora log

Se non ricevi una risposta positiva, consulta Risoluzione degli errori di risposta.

Hai eseguito il deployment e il test di un'API in Endpoints.

monitora l'attività dell'API

  1. Visualizza i grafici delle attività della tua API nella pagina Endpoints > Servizio nella console Google Cloud.

    Visualizzare i grafici delle attività di Endpoints

    Potrebbero essere necessari alcuni minuti prima che la richiesta venga riportata nei grafici.

  2. Controlla i log delle richieste per l'API nella pagina Esplora log.

    Visualizza i log delle richieste di Endpoints

Creazione di un portale per gli sviluppatori per l'API

Puoi usare il portale Cloud Endpoints per creare un portale per sviluppatori, un sito web che puoi utilizzare per interagire con l'API di esempio. Per saperne di più, vedi Panoramica del portale Cloud Endpoints.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi per le risorse utilizzate in questa pagina, segui questi passaggi.

Consulta Eliminazione di un'API e di istanze API per informazioni sull'interruzione dei servizi utilizzati da questo tutorial.

Passaggi successivi