Guida rapida: configurazione di Cloud Endpoints gRPC per Cloud Run con ESPv2

Configurare gRPC per 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. Quindi, aiuti 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 i controlli necessari (ad esempio l'autenticazione) prima di richiamare il servizio. Quando il servizio risponde, ESPv2 raccoglie e registra la telemetria, come mostrato nella figura che segue. Puoi visualizzare le metriche relative al tuo servizio nella pagina Endpoint > Servizi di Google Cloud Console.

Architettura degli endpoint

Per una panoramica di Cloud Endpoints, consulta le informazioni sugli endpoint e l'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 svolgi il tutorial. Per completare questo tutorial, sono necessarie tutte le attività.

  1. Crea un progetto Google Cloud e, se non hai eseguito il deployment di Cloud Run, esegui il deployment di un servizio gRPC di esempio. Vedi Prima di iniziare.
  2. Prenota un nome host Cloud Run per il servizio ESPv2. Consulta la sezione Prenotare un nome host Cloud Run.
  3. Crea un documento di configurazione dell'API gRPC che descriva l'API e configura le route per il tuo Cloud Run. Vedi Configurazione degli endpoint.
  4. Esegui il deployment del documento di configurazione dell'API gRPC per creare un servizio gestito. Vedi Deployment della configurazione degli endpoint.
  5. Crea una nuova immagine Docker ESPv2 con la configurazione del tuo servizio Endpoints. Vedi Creare una nuova immagine ESPv2.
  6. Esegui il deployment del container ESPv2 su Cloud Run. Quindi, concedi a ESPv2 l'autorizzazione IAM (Gestione di identità e accessi) per richiamare il tuo servizio. Consulta la sezione Deployment del contenitore ESPv2.
  7. Richiamare un servizio. Consulta l'articolo Inviare una richiesta all'API.
  8. Monitora l'attività dei tuoi servizi. Consulta Attività dell'API di monitoraggio.
  9. Evita di ricevere addebiti sul tuo account Google Cloud. Vedi Pulizia.

Costi

Questo tutorial utilizza i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono beneficiare di una prova gratuita.

Al termine di questo tutorial, puoi evitare una fatturazione continua eliminando le risorse che hai creato. Per scoprire di più, vedi Pulizia.

Prima di iniziare

Per iniziare:

  1. In Google Cloud Console, vai alla pagina Gestisci risorse e crea 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é è necessario in seguito. Nel resto di questa pagina, questo ID progetto è denominato ESP_PROJECT_ID.

  4. Prendi nota del numero di progetto perché è necessario in seguito. Nella parte rimanente di questa pagina, questo numero di progetto è indicato come ESP_PROJECT_NUMBER.

  5. Scarica e installa l'interfaccia a riga di comando di Google Cloud.

    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 servizio Cloud Run gRPC di esempio python-grpc-bookstore-server 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 predefinito di esempio 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 per area geografica e ID progetto in cui viene eseguito il deployment del servizio. Nel resto della pagina l'ID progetto è indicato come BACKEND_PROJECT_ID. Il nome del servizio Cloud Run sottoposto a deployment è denominato BACKEND_SERVICE_NAME. Il nome host di Cloud Run è denominato BACKEND_HOST_NAME.

Prenotazione di un nome host Cloud Run

Devi prenotare un nome host Cloud Run per il servizio ESPv2 per configurareil documento OpenAPI o la configurazione del servizio gRPC. Per prenotare un nome host, devi eseguire il deployment di un container di esempio in Cloud Run. Successivamente, eseguirai il deployment del container ESPv2 sullo stesso servizio Cloud Run.

  1. Assicurati che l'interfaccia a riga di comando gcloud 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 l'area geografica.
    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 è 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 eseguirai il deployment di ESPv2 sul servizio Cloud Run CLOUD_RUN_SERVICE_NAME. Devi specificare CLOUD_RUN_HOSTNAME nel campo host del documento OpenAPI.

Configurazione di Endpoints

L'esempio bookstore-grpc contiene i file che devi copiare localmente e configurare.

  1. Create a self-contained protobuf descriptor file from your service .proto file:
    1. Save a copy of bookstore.proto from the example repository to your current working directory. This file defines the Bookstore service's API.
    2. Create the following directory under your working directory: mkdir generated_pb2
    3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved 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
      

      In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.

  2. Create a text file called api_config.yaml in your current working directory (the same directory that contains bookstore.proto). For convenience, this page refers to the gRPC API configuration document by that file name, but you can name it something else if you prefer. Add the following contents to the 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
    
    Indentation is important for yaml format. For example the name field must be at the same level as type.
  3. In the name field, specify CLOUD_RUN_HOSTNAME, the hostname portion of the URL that was reserved above in Reserving a Cloud Run hostname. Don't include the protocol identifier, such as https:// or grpcs://.

  4. In the address field in the backend.rules section, replace BACKEND_HOST_NAME with the actual gRPC Bookstore Cloud Run service created in Before you begin.

  5. Note the value of the title property in the api_config.yaml file:

    title: Cloud Endpoints + Cloud Run gRPC

    The value of the title property becomes the name of the Endpoints service after you deploy the configuration.

  6. Save your gRPC API configuration document.

Per ulteriori informazioni, consulta la sezione Configurare gli endpoint.

Eseguire il deployment della configurazione di Endpoints

Per eseguire il deployment della configurazione degli endpoint, utilizza il comando gcloud endpoints services deploy. Questo comando utilizza Service Management per creare un servizio gestito.

  1. Assicurati di essere 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 Google Cloud in cui vuoi eseguire il deployment della configurazione degli endpoint. 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 comando seguente:

    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 di Google Cloud:
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml
    

    Durante la creazione e la configurazione del servizio, Service Management trasmette informazioni al 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 servizio è costituito da un timestamp, seguito da un numero di revisione. Se esegui nuovamente il deployment della configurazione endpoint lo stesso giorno, il numero di revisione viene incrementato nell'ID configurazione del servizio.

Verifica dei servizi richiesti

Come minimo, endpoint ed ESP richiedono l'attivazione dei 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 obbligatori. 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 endpoint in un progetto Google Cloud esistente in cui questi servizi sono stati disabilitati esplicitamente.

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

gcloud services list

Se i servizi richiesti non sono elencati, attivali:

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

Attiva anche il servizio Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Per determinare il ENDPOINTS_SERVICE_NAME puoi:

  • Dopo aver eseguito il deployment della configurazione Endpoint, vai alla pagina Endpoint in Cloud Console. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è riportato nella colonna Service name (Nome servizio).

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

Per maggiori informazioni sui comandi gcloud, consulta i servizi gcloud.

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

Per ulteriori informazioni, consulta la sezione Eseguire il deployment della configurazione degli endpoint.

Creazione di una nuova immagine ESPv2

Crea la configurazione del servizio Endpoints in una nuova immagine Docker ESPv2. Eseguirai quindi il deployment di questa immagine nel servizio Cloud Run riservato.

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

  1. Scarica questo script sulla tua macchina locale in cui è installato l'interfaccia a riga di comando gcloud.

  2. Esegui lo script con il comando seguente:

    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 in precedenza 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 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 release 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 ESPv2 Cloud Run con la nuova immagine che hai creato in precedenza. Sostituisci CLOUD_RUN_SERVICE_NAME con lo stesso nome di servizio Cloud Run che hai utilizzato quando hai prenotato in origine il nome host in Prenotare 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 ulteriori opzioni di avvio ESPv2, ad esempio abilitando CORS, puoi trasmettere 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 Extensible Service Proxy V2.

  3. Concedi l'autorizzazione ESPv2 a richiamare i servizi Cloud Run. Esegui questo comando per ogni servizio. Con il 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", utilizza python-grpc-bookstore-server come valore.
    • Sostituisci ESP_PROJECT_NUMBER con il numero del progetto creato per ESPv2. Un modo per farlo è andare alla pagina IAM in Google Cloud Console e trovare l'account di servizio Compute predefinito, che è l'account di servizio utilizzato nel flag "membro".
    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, consulta 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
    • Guarda i grafici delle attività per la tua API nella pagina Endpoint > Servizi.

      Vai alla pagina Servizi di endpoint

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

    • Esamina i log delle richieste relativi alla tua API nella pagina Esplora log.

      Vai alla pagina Esplora log

Se la risposta non va a buon fine, consulta la sezione Risoluzione degli errori di risposta.

Hai appena 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 Endpoint > Servizio in Google Cloud Console.

    Visualizzare grafici di attività endpoint

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

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

    Visualizzare i log delle richieste endpoint

Creazione di un portale per 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 ulteriori informazioni, consulta la 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.

Per informazioni sull'arresto dei servizi utilizzati da questo tutorial, consulta la sezione Eliminare un'API e istanze API.

Passaggi successivi