Configura gRPC di Cloud Endpoints 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 container ESPv2 predefinito in Cloud Run. Potrai quindi contribuire a proteggere i tuoi servizi utilizzando Cloud Run IAM in modo che ESPv2 possa richiamarli.
Con questa configurazione, ESPv2 intercetta tutte le richieste ai tuoi servizi ed esegue tutti i controlli necessari (come l'autenticazione) prima di chiamare il servizio. Quando il servizio risponde, ESPv2 raccoglie e segnala la telemetria, come mostrato nella figura seguente. Puoi visualizzare le metriche relative al tuo servizio nella pagina Endpoint > Servizi nella console Google Cloud.
Per una panoramica di Cloud Endpoints, consulta Informazioni su Endpoints ed architettura degli endpoint.
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à
Utilizza il seguente elenco di attività mentre esegui il tutorial. Per completare questo tutorial sono necessarie tutte le attività.
- Crea un progetto Google Cloud e, se non hai eseguito il deployment di Cloud Run, esegui il deployment di un servizio gRPC di backend di esempio. Vedi Prima di iniziare.
- Prenota un nome host di Cloud Run per il servizio ESPv2. Vedi Prenotare un nome host di Cloud Run.
- Crea un documento di configurazione API gRPC che descriva l'API e configura le route per Cloud Run. Vedi Configurazione di Endpoints.
- Esegui il deployment del documento di configurazione dell'API gRPC per creare un servizio gestito. Vedi Deployment della configurazione di Endpoints.
- Crea una nuova immagine Docker ESPv2 con la configurazione del servizio Endpoints. Consulta la sezione Creazione di una nuova immagine ESPv2.
- Eseguire il deployment del container ESPv2 in Cloud Run. Concedi quindi a ESPv2 l'autorizzazione Identity and Access Management (IAM) per richiamare il servizio. Vedi Deployment del container ESPv2.
- Richiamare un servizio. Vedi Invio di una richiesta all'API.
- Monitora l'attività relativa ai tuoi servizi. Consulta Monitoraggio dell'attività dell'API.
- Evita che al tuo account Google Cloud vengano addebitati costi. Vedi Pulizia.
Costi
In questo documento, utilizzi i seguenti componenti fatturabili di Google Cloud:
Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.
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 effettuare la configurazione:
Nella console Google Cloud, vai alla pagina Gestisci risorse e crea un progetto.
Verifica che la fatturazione sia attivata per il tuo progetto.
Prendi nota dell'ID progetto perché ti servirà in un secondo momento. Nel resto di questa pagina, questo ID progetto è indicato come ESP_PROJECT_ID.
Prendi nota del numero di progetto perché è necessario in seguito. Nel resto di questa pagina, questo numero di progetto è indicato come ESP_PROJECT_NUMBER.
Scarica e installa Google Cloud CLI.
Segui i passaggi nella guida rapida di gRPC per Python per installare gli strumenti gRPC e gRPC.
Esegui il deployment del servizio di backend gRPC Cloud Run python-grpc-bookstore-server di esempio da utilizzare con 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 nella guida rapida con
gcr.io/endpointsv2/python-grpc-bookstore-server:2
Nota della regione e dell'ID progetto in cui viene eseguito il deployment del servizio. 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 è indicato come BACKEND_SERVICE_NAME. Il suo nome host Cloud Run è denominato BACKEND_HOST_NAME.
Prenotazione di un nome host di Cloud Run
Devi prenotare un nome host Cloud Run per il servizio ESPv2 per configure la configurazione del documento OpenAPI o del servizio gRPC. Per prenotare un nome host, eseguirai il deployment di un container di esempio in Cloud Run. In un secondo momento, deploy del container ESPv2 sullo stesso servizio Cloud Run.
-
Assicurati che gcloud CLI sia autorizzato ad accedere ai tuoi dati e servizi.
- Accedi.
gcloud auth login
- Nella nuova scheda del browser che si apre, scegli un account con il ruolo Editor o Proprietario nel progetto Google Cloud che hai creato per eseguire il deployment di ESPv2 in Cloud Run.
- Accedi.
-
Imposta la regione.
gcloud config set run/region us-central1
-
Esegui il deployment dell'immagine di esempio
gcr.io/cloudrun/hello
in Cloud Run. Sostituisci CLOUD_RUN_SERVICE_NAME con il nome che vuoi utilizzare per il servizio.gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/cloudrun/hello" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
Una volta completato correttamente, il comando visualizza un messaggio simile al seguente:
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
è CLOUD_RUN_SERVICE_URL egateway-12345-uc.a.run.app
è CLOUD_RUN_HOSTNAME. - Annota CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME.
In seguito eseguirai il deployment di ESPv2 sul servizio Cloud Run CLOUD_RUN_SERVICE_NAME.
CLOUD_RUN_HOSTNAME specifichi nel campo
host
del documento OpenAPI.
Configurazione di Endpoints
L'esempio di bookstore-grpc
contiene i file che devi copiare localmente e configurare.
- Crea un file descrittore autonomo di un protobuf dal file
.proto
del servizio:- Salva una copia di
bookstore.proto
dal repository di esempio alla directory di lavoro corrente. Questo file definisce l'API del servizio Bookstore. - Crea la seguente directory nella directory di lavoro:
mkdir generated_pb2
- Crea il file del descrittore
api_descriptor.pb
utilizzando il compilatore dei buffer di protocolloprotoc
. Esegui questo comando nella directory in cui hai salvatobookstore.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 attuale. Nel tuo ambiente di build 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 salvatobookstore.proto
.
- Salva una copia di
-
Crea un file di testo denominato
api_config.yaml
nell'attuale directory di lavoro (la stessa directory contenentebookstore.proto
). Per praticità, questa pagina si riferisce al documento di configurazione dell'API gRPC in base al nome del file, ma puoi assegnare un altro nome, se preferisci. Aggiungi i seguenti contenuti al 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
Il rientro è importante per il formato yaml. Ad esempio, il camponame
deve essere allo stesso livello ditype
. Nel campo
name
, specifica CLOUD_RUN_HOSTNAME, la porzione del nome host dell'URL riservato in precedenza nella sezione Prenotazione di un nome host Cloud Run. Non includere l'identificatore di protocollo, ad esempiohttps://
ogrpcs://
.Nel campo
address
della sezionebackend.rules
, sostituisci BACKEND_HOST_NAME con il servizio effettivo di Libreria gRPC Cloud Run creato in Prima di iniziare.Osserva il valore della proprietà
title
nel fileapi_config.yaml
:title: Cloud Endpoints + Cloud Run gRPC
Il valore della proprietà
title
diventa il nome del servizio Endpoints dopo il deployment della configurazione.- Salva il documento di configurazione dell'API gRPC.
Per ulteriori informazioni, consulta Configurazione di Endpoints.
Eseguire il deployment della configurazione di Endpoints
Per eseguire il deployment della configurazione di Endpoints, utilizza il comando gcloud endpoints services deploy
. Questo comando utilizza Service Management per creare un servizio gestito.
- Assicurati di essere nella directory in cui si trovano i file
api_descriptor.pb
eapi_config.yaml
. - Verifica che il progetto predefinito utilizzato attualmente dallo strumento a riga di comando
gcloud
sia il progetto Google Cloud in cui vuoi eseguire il deployment della configurazione degli endpoint. Convalida l'ID progetto restituito dal comando seguente per assicurarti che il servizio non venga creato nel progetto sbagliato.gcloud config list project
Se devi modificare il progetto predefinito, esegui il comando seguente:
gcloud config set project YOUR_PROJECT_ID
- Esegui il deployment del file
proto descriptor
e del file di configurazione utilizzando Google Cloud CLI:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
Durante la creazione e la configurazione del servizio, Service Management genera informazioni nel terminale. Al termine del deployment, viene visualizzato un messaggio simile al seguente:
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID è l'ID univoco della configurazione del servizio Endpoints 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 di configurazione del servizio ebookstore.endpoints.example-project.cloud.goog
è il nome del servizio. L'ID di configurazione del servizio è costituito da un timestamp con un numero di revisione. Se esegui nuovamente il deployment della configurazione Endpoint, lo stesso giorno, il numero di revisione viene aumentato nell'ID configurazione del servizio.
Controllo dei servizi richiesti in corso...
Come minimo, Endpoints ed ESP richiedono che siano abilitati i seguenti servizi Google: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 abilita i servizi richiesti nelle seguenti circostanze:
Se hai utilizzato un'applicazione di terze parti come Terraform e non includi questi servizi.
Hai eseguito il deployment della configurazione di Endpoints in un progetto Google Cloud esistente in cui questi servizi sono stati disabilitati esplicitamente.
Utilizza il comando seguente per confermare che i servizi richiesti siano abilitati:
gcloud services list
Se i servizi richiesti non sono elencati, attivali:
gcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com
Abilita anche il servizio Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
Per determinare i 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 è visualizzato nella colonna Nome servizio.
Per OpenAPI, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel campo
host
della specifica OpenAPI. Per gRPC, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel camponame
della configurazione degli endpoint gRPC.
Per ulteriori informazioni sui comandi gcloud
, consulta la pagina relativa ai servizi gcloud
.
Se viene visualizzato un messaggio di errore, consulta Risoluzione dei problemi di deployment della configurazione di Endpoints.
Per ulteriori informazioni, consulta Deployment della configurazione di Endpoints.
Creazione di una nuova immagine ESPv2
Crea la configurazione del servizio Endpoints in una nuova immagine Docker ESPv2. In seguito eseguirai il deployment di questa immagine sul servizio Cloud Run riservato.
Per creare la configurazione del servizio in una nuova immagine Docker ESPv2:
Scarica questo script sulla macchina locale in cui è installato gcloud CLI.
Esegui lo script con il seguente 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 hai prenotato sopra in Prenotare un nome host di 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
-
Lo script utilizza il comando
gcloud
per scaricare la configurazione del servizio, creare la configurazione del servizio in una nuova immagine ESPv2 e caricare la nuova immagine nel registro dei container del progetto. Lo script utilizza automaticamente la release più recente di ESPv2, indicata con 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
Esegui il deployment del servizio Cloud Run ESPv2 con la nuova immagine che hai creato sopra. Sostituisci CLOUD_RUN_SERVICE_NAME con lo stesso nome del servizio Cloud Run che hai utilizzato quando hai prenotato in origine il nome host riportato 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
Se vuoi configurare Endpoints in modo che utilizzi ulteriori opzioni di avvio ESPv2, ad esempio l'abilitazione 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
, inclusi l'elenco delle opzioni disponibili e le informazioni su come specificare più opzioni, consulta la sezione Flag per Extensible Service Proxy V2.- Concedi l'autorizzazione ESPv2 per richiamare i servizi Cloud Run.
Esegui questo comando per ciascun servizio. Nel seguente comando:
- Sostituisci BACKEND_SERVICE_NAME con il nome del servizio Cloud Run richiamato. Se utilizzi il servizio creato eseguendo il deployment di "gcr.io/endpointsv2/python-grpc-bookstore-server:2", usa
python-grpc-bookstore-server
come valore. - Sostituisci ESP_PROJECT_NUMBER con il numero del progetto che hai creato per ESPv2. Un modo per trovarlo è andare alla pagina IAM nella console Google Cloud e cercare l'Account di servizio di computing predefinito, che è l'account di servizio utilizzato nel 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
- Sostituisci BACKEND_SERVICE_NAME con il nome del servizio Cloud Run richiamato. Se utilizzi il servizio creato eseguendo il deployment di "gcr.io/endpointsv2/python-grpc-bookstore-server:2", usa
Per ulteriori informazioni, consulta Gestione dell'accesso utilizzando IAM.
Invia richieste all'API
Per inviare richieste all'API di esempio, puoi utilizzare un client gRPC di esempio scritto in Python.
Clona il repository Git in cui è ospitato il codice client gRPC:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Cambia la directory di lavoro:
cd python-docs-samples/endpoints/bookstore-grpc/
Installa le dipendenze:
pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt
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 ESPv2 Cloud Run 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
Consulta i grafici delle attività per la tua API nella pagina Endpoint > Servizi.
Vai alla pagina Servizi endpoint
Potrebbero essere necessari alcuni istanti perché la richiesta venga riportata nei grafici.
Esamina i log delle richieste per la tua API nella pagina Esplora log.
Se non ricevi una risposta corretta, consulta la sezione Risoluzione dei problemi relativi agli errori di risposta.
Hai appena eseguito il deployment e il test di un'API in Endpoints.
Monitora l'attività dell'API
Visualizza i grafici delle attività per la tua API nella pagina Endpoint > Servizio nella console Google Cloud.
Visualizzare i grafici delle attività di Endpoints
Potrebbero essere necessari alcuni istanti prima che la richiesta venga riportata nei grafici.
Esamina i log delle richieste per la tua API nella pagina Esplora log.
Creazione di un portale per gli sviluppatori per l'API
Puoi utilizzare il portale Cloud Endpoints per creare un portale per gli 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 relativi alle risorse utilizzate in questa pagina, segui questi passaggi.
Consulta Eliminazione di un'API e istanze API per informazioni sull'interruzione dei servizi utilizzati da questo tutorial.