Configura Cloud Endpoints gRPC per Cloud Run con ESPv2

Prenotare un nome host Cloud Run

Devi prenotare un nome host Cloud Run per il servizio ESPv2 per configurare la configurazione del servizio OpenAPI o gRPC. Per prenotare un nome host, devi eseguire il deployment di un container di esempio su Cloud Run. In un secondo momento, eseguirai il deployment del container ESPv2 sullo stesso servizio Cloud Run.

1. Assicurati che gcloud CLI sia autorizzata ad accedere ai tuoi dati e servizi.
   1. Accedi.

      gcloud auth login

   2. 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 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 utilizzare per il servizio.

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
       --image="gcr.io/cloudrun/hello" \
       --allow-unauthenticated \
       --platform managed \
       --project=ESP_PROJECT_ID
   

   Al termine, 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 è il CLOUD_RUN_SERVICE_URL e gateway-12345-uc.a.run.app è il CLOUD_RUN_HOSTNAME.

4. Prendi nota di CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME. In un secondo momento, esegui il deployment di ESPv2 sul servizio Cloud Run CLOUD_RUN_SERVICE_NAME. Specifichi CLOUD_RUN_HOSTNAME nel campo host del documento OpenAPI.

Configurazione di Endpoints

L'esempio bookstore-grpc contiene i file che devi copiare in locale 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 nella tua directory di lavoro corrente. Questo file definisce l'API del servizio Bookstore.
   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 corrente (la stessa directory che contiene bookstore.proto). Per comodità, questa pagina fa riferimento al documento di configurazione dell'API gRPC con questo nome, ma puoi rinominarlo 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
   

   L'indentazione è importante per il formato YAML. Ad esempio, il campo name deve trovarsi allo stesso livello di type.

3. Nel campo name, specifica CLOUD_RUN_HOSTNAME, la parte del nome host dell'URL che è stata prenotata sopra in Prenotazione di 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.

Per ulteriori informazioni, consulta la sezione Configurazione degli endpoint.

esegui 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.

1. Assicurati di trovarti nella directory in cui si trovano i file api_descriptor.pb e api_config.yaml.
2. Verifica che il progetto predefinito attualmente utilizzato dallo strumento a riga di comando gcloud sia il progetto in cui vuoi eseguire il deployment della configurazione di Endpoints. Google Cloud 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 il seguente 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 Google Cloud CLI:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   Durante la creazione e la configurazione del servizio, Service Management visualizza informazioni sul 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 configurazione del servizio e bookstore.endpoints.example-project.cloud.goog è il nome del servizio. L'ID configurazione del servizio è costituito da un timestamp seguito da un numero di revisione. Se esegui nuovamente il deployment della configurazione di Endpoints nello stesso giorno, il numero di revisione viene incrementato nell'ID configurazione del servizio.

Controllo dei servizi richiesti

Nella maggior parte dei casi, il comando gcloud endpoints services deploy attiva 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 progettoGoogle Cloud esistente in cui questi servizi sono stati disattivati in modo esplicito.

Utilizza questo comando per verificare che i servizi richiesti siano abilitati:

gcloud services list

Se non vedi i servizi richiesti elencati, attivali:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.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 Endpoints nella console Cloud. L'elenco dei possibili ENDPOINTS_SERVICE_NAME viene visualizzato nella colonna Nome servizio.

• Per OpenAPI, ENDPOINTS_SERVICE_NAME è ciò che hai specificato nel campo host della specifica OpenAPI. Per gRPC, ENDPOINTS_SERVICE_NAME è ciò che hai specificato nel campo name della configurazione di gRPC Endpoints.

Per ulteriori informazioni sui comandi gcloud, consulta servizi gcloud.

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

Per ulteriori informazioni, consulta Deployment della configurazione di Endpoints.

Creazione di una nuova immagine ESPv2

Incorpora la configurazione del servizio Endpoints in una nuova immagine Docker ESPv2. In un secondo momento, eseguirai il deployment di questa immagine nel servizio Cloud Run riservato.

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

1. Scarica questo script sul tuo computer locale in cui è installata 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 hai prenotato sopra in Prenotazione di 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 la configurazione del servizio in una nuova immagine ESPv2 e caricare la nuova immagine nel registro dei container del progetto. Lo script utilizza automaticamente l'ultima versione di ESPv2, indicata da 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 nome del servizio Cloud Run che hai utilizzato quando hai prenotato originariamente 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 per 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, inclusi l'elenco delle opzioni disponibili e le informazioni su come specificare più opzioni, consulta Flag di Extensible Service Proxy V2.

3. Concedi a ESPv2 l'autorizzazione per richiamare i tuoi servizi Cloud Run. Esegui questo comando per ogni servizio. Nel seguente comando:
   • Sostituisci BACKEND_SERVICE_NAME con il nome del servizio Cloud Run richiamato. Se utilizzi il servizio creato dal deployment di `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, utilizza 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 trovare il service account Compute predefinito, ovvero il 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

Per saperne di più, consulta Gestire l'accesso utilizzando 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

   • Esamina i grafici delle attività della tua API nella pagina Endpoints > 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 riuscita, consulta la sezione Risoluzione dei problemi relativi agli errori di risposta.

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

monitora l'attività dell'API

1. Visualizza i grafici di attività per la tua API nella pagina Endpoints > Servizio nella console Google Cloud .

   Visualizzare i grafici delle attività di Endpoints

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

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

   Visualizzare i log delle richieste di Endpoints