Configura Cloud Endpoints gRPC per Knative Serving con ESPv2

Creazione di un cluster GKE con Knative Serving abilitato

Per creare un cluster e attivarlo per Knative serving su Google Cloud:

1. Crea un nuovo cluster utilizzando il comando:

   gcloud container clusters create CLUSTER_NAME \ 
     --addons=HttpLoadBalancing,CloudRun \ 
     --machine-type=n1-standard-4 \ 
     --num-nodes=3

   Sostituisci CLUSTER_NAME con il nome che vuoi assegnare al cluster.

   Sebbene queste istruzioni non attivino la scalabilità automatica dei cluster per ridimensionare i cluster in base alla domanda, Knative serving su Google Cloud scala automaticamente le istanze all'interno del cluster.

2. Attendi il completamento della creazione del cluster. Durante il processo di creazione, dovresti visualizzare messaggi simili ai seguenti:

   Creating cluster CLUSTER_NAME...done. 
   Created [https://container.googleapis.com/v1/projects/ESP_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME].

   L'output mostra anche la versione del cluster nella colonna NODE_VERSION. Ad esempio, 1.15.11-gke.1 o 1.14.10-gke.27. Prendi nota della versione del cluster per utilizzarla in un secondo momento in questo documento.

3. Imposta i valori predefiniti di gcloud per utilizzare il nuovo cluster e la posizione del cluster, in modo da non doverli specificare quando utilizzi gcloud CLI:

   gcloud config set run/cluster CLUSTER_NAME
   gcloud config set run/cluster_location ZONE

4. Utilizza questo comando per visualizzare i dettagli del nuovo cluster:

   gcloud container clusters describe CLUSTER_NAME

5. Utilizza il seguente comando per recuperare le credenziali per il cluster:

   gcloud container clusters get-credentials CLUSTER_NAME

Deployment di un servizio Cloud Run gRPC di esempio

Per eseguire il deployment del container di esempio "grpc-bookstore" Cloud Run for Anthos nel cluster appena creato:

1. Segui i passaggi descritti nella guida rapida di gRPC Python per installare gRPC e gli strumenti gRPC.

2. Questo esempio di server gRPC contiene un'immagine Docker precompilata per il "servizio grpc-bookstore" Python: gcr.io/endpointsv2/python-grpc-bookstore-server:2. Utilizza questo comando per eseguire il deployment di "grpc-bookstore" nel cluster:

   gcloud run deploy GRPC_SERVICE \
     --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2 \
     --platform=gke \
    --connectivity=internal \
     --use-http2

   Tieni presente che lo specifichi come servizio interno in modo che non sia accessibile esternamente.

   Sostituisci GRPC_SERVICE con il nome che vuoi assegnare al servizio. Ad esempio:

   gcloud run deploy grpc-bookstore \
     --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2 \
     --platform=gke \
     --connectivity=internal \
     --use-http2

   Al termine, viene visualizzato il seguente messaggio:

   Service [grpc-bookstore] revision [grpc-bookstore-00001-nuk] has been deployed and is serving 100 percent of traffic at http://grpc-bookstore.default.svc.cluster.local

   Quando crei un servizio interno, GKE crea un nome DNS (grpc-bookstore.default.svc.cluster.local in questo esempio) che può essere risolto solo per le richieste provenienti dall'interno del cluster stesso, non per le richieste esterne. Non puoi accedere a questo DNS esternamente dal cluster. Per saperne di più, consulta Servizi Cloud Run.

3. Per verificare che il servizio funzioni correttamente, esegui il deployment di un pod con la stessa immagine Docker nel cluster. L'immagine contiene il codice client gRPC per "grpc-bookstore" che puoi utilizzare per testare il servizio interno.

   1. Utilizza il seguente comando kubectl per eseguire il deployment di un pod nello stesso cluster in cui hai eseguito il deployment in precedenza:

      kubectl run grpc --generator=run-pod/v1 \
        --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2

      Questa immagine contiene lo script bookstore_client.py che puoi utilizzare per effettuare richieste client dall'interno del cluster.

      Nota: per le versioni più recenti di kubectl, il comando potrebbe generare il seguente avviso:

      Flag --generator has been deprecated, has no effect and will be removed in the future".

      Puoi ignorare questo avviso.

   2. Ottieni il nome del pod "grpc-bookstore" creato sul cluster quando hai eseguito il deployment dell'immagine Docker nel passaggio precedente:

      kubectl get pods

      Dovresti vedere un output nel formato:

      NAME   READY    STATUS    RESTARTS   AGE
      grpc   1/1      Running   0          23h

      Dove grp è il nome del pod "grpc-bookstore". Prima di continuare, assicurati che lo Stato del pod sia In esecuzione.

   3. Utilizza il seguente comando per effettuare una richiesta client al servizio "grpc-bookstore":

      kubectl exec grpc -ti -- python3 bookstore_client.py \
        --host grpc-bookstore.default.svc.cluster.local --port=80

      Questo comando esegue internamente lo script bookstore_client.py sul cluster per effettuare una richiesta gRPC al servizio "grpc-bookstore" sul nome host grpc-bookstore.default.svc.cluster.local.

      Se tutto funziona correttamente, dovresti visualizzare una risposta nel formato:

      ListShelves: shelves {
        id: 1
        theme: "Fiction"
      }
      shelves {
        id: 2
        theme: "Fantasy"
      }

Configurazione di Endpoints

Devi disporre di una specifica API gRPC che descriva la superficie del tuo servizio di backend e tutti i requisiti di autenticazione.

Informazioni sull'impostazione del campo del nome della specifica API gRPC

Nel campo name della specifica dell'API gRPC, specifica il nome del servizio Endpoints utilizzato per accedere al servizio Cloud Run for Anthos. Il nome del servizio Endpoints è nel formato di un nome di dominio:

API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

Poiché il nome del servizio Endpoints corrisponde a un nome di dominio, deve rispettare le seguenti regole:

• Deve contenere solo lettere minuscole, numeri, punti o trattini.
• Non può iniziare con un trattino.
• Non deve contenere un trattino basso.

Ad esempio:

grpc-boostore-api.endpoints.ESP_PROJECT_ID.cloud.goog

Creazione della specifica API gRPC

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

1. Crea una nuova directory per la specifica dell'API gRPC, ad esempio my-anthos-grpc. Quindi, passa a quella directory.

2. Clona il repository Git in cui è ospitato il codice client gRPC nella nuova directory:

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

3. Cambia la directory di lavoro:

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

   Tieni presente che questa directory contiene il file bookstore.proto. Questo file definisce l'API del servizio Bookstore.

4. Crea un file descrittore protobuf autonomo dal file .proto del servizio:

   1. Crea la directory generated_pb2 nella directory di lavoro.

   2. Crea il file descrittore, api_descriptor.pb, utilizzando il compilatore di buffer di protocollo protoc. Esegui questo comando nella directory contenente 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 attuale. 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 la directory in cui hai salvato bookstore.proto.

5. Modifica il file api_config_anthos.yaml nella directory di lavoro corrente (la stessa directory contenente bookstore.proto) per aggiungere i seguenti contenuti al file:

   type: google.api.Service
   config_version: 3
   #
   # Name of the service configuration.
   #
   name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
   #
   # API title to appear in the user interface (Google Cloud console).
   #
   title: Bookstore gRPC API In Cloud Run Anthors
   apis:
   - name: endpoints.examples.bookstore.Bookstore
   #
   # Create a DNS record to map your service name to IP address
   #
   endpoints:
     - name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
       target: IP_ADDRESS
   #
   # Specify the backend address to route to
   #
   backend:
     rules:
       - selector: "*"
         address: grpc://GRPC_SERVICE.default.svc.cluster.local
         disable_auth: true
   #
   # API usage restrictions.
   #
   usage:
     rules:
     # ListShelves methods can be called without an API Key.
     - selector: endpoints.examples.bookstore.Bookstore.ListShelves
       allow_unregistered_calls: true

   Il rientro è importante per il formato YAML.

6. Nel campo name, specifica il nome di dominio dell'API Endpoints utilizzata per accedere al servizio Cloud Run for Anthos, nel formato:

   API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

   Ad esempio:

   grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog

7. La sezione endpoints registra una voce DNS per il tuo servizio Endpoints sul dominio cloud.goog, nel formato:

   endpoints:
     - name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
       target: IP_ADDRESS

   IP_ADDRESS è l'IP del servizio istio-ingress per il tuo cluster. Per determinare questo indirizzo IP:

   1. Vai alla pagina Google Kubernetes Engine in Cloud Console:

      Vai a Google Kubernetes Engine

   2. Fai clic su Servizi e Ingress nel pannello di navigazione a sinistra per visualizzare un elenco di servizi.

   3. Se la versione del cluster è 1.15.3-gke.19 o successiva, 1.14.3-gke.12 o successiva oppure 1.13.10-gke.8 o successiva, scorri verso il basso fino al servizio istio-ingress. Per tutte le altre versioni del cluster, scorri verso il basso fino al servizio istio-ingressgateway.

   4. Copia l'indirizzo IP esterno mostrato accanto al bilanciatore del carico, senza l'impostazione della porta, se presente. Ad esempio, se l'IP è XX.XXX.XX.XXX:15020, ometti :15020. Ignora gli altri indirizzi IP elencati.

8. Il campo address nella sezione backend specifica il nome DNS interno del servizio Cloud Run "grpc-bookstore" con lo schema proto grpc:// e disattiva l'autenticazione a questo servizio:

   address: grpc://GRPC_SERVICE.default.svc.cluster.local
   disable_auth: true

   Ad esempio:

   address: grpc://grpc-bookstore.default.svc.cluster.local
   disable_auth: true

   Ciò è necessario perché la chiamata da ESPv2 al servizio Cloud Run for Anthos viene effettuata come chiamata interna dal cluster e pertanto l'autenticazione non è necessaria.

9. Prendi nota del valore della proprietà title nel file api_config_authos.yaml:

   title: Bookstore gRPC API In Cloud Run Anthos

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

10. Salva il documento dell'API gRPC.

Per informazioni sui campi nel documento OpenAPI richiesti da Endpoints, consulta Configurazione di Endpoints.

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.

Per eseguire il deployment della configurazione di Endpoints:

1. Assicurati di trovarti nella directory che contiene il documento gRPC.

2. Carica la configurazione e crea un servizio gestito.

   gcloud endpoints services deploy api_descriptor.pb api_config_anthos.yaml \ 
     --project ESP_PROJECT_ID

   Viene creato un nuovo servizio Endpoints con il nome specificato nel campo name del file api_config_anthos.yaml. Il servizio Endpoints è configurato in base al documento OpenAPI.

   Durante la creazione e la configurazione del servizio Endpoints, Service Management visualizza le informazioni nel terminale. Al termine del deployment, viene visualizzato un messaggio simile al seguente:

   Service Configuration [CONFIG_ID] uploaded for service [API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog]

   CONFIG_ID è l'ID univoco della configurazione del servizio Endpoints creato dal deployment. Ad esempio:

   Service Configuration [2019-02-01r0] uploaded for service [grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog] 

   L'ID configurazione del servizio è composto da un timestamp seguito da un numero di revisione. Se esegui di nuovo il deployment di api_config_anthos.yaml nello stesso giorno, il numero di revisione viene incrementato nell'ID configurazione del servizio. Puoi visualizzare la configurazione del servizio e la cronologia dei deployment nella pagina Endpoints > Servizi della console Google Cloud .

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

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.

Creazione di una nuova immagine di pubblicazione di ESPv2 Knative

Incorpora la configurazione del servizio Endpoints in una nuova immagine Docker ESPv2. Dopo aver creato questa immagine, puoi eseguirne il deployment nel cluster.

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

1. Scarica questo script sulla tua macchina locale in cui è installata gcloud CLI ed eseguilo come segue:

   chmod +x gcloud_build_image 
   ./gcloud_build_image -s API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog \ 
   -c CONFIG_ID -p ESP_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 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-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID

Deployment dell'immagine Knative serving ESPv2

Esegui il deployment dell'immagine del servizio Knative serving ESPv2 nel tuo cluster:

1. Esegui il deployment del servizio Knative serving ESPv2 con la nuova immagine:

   gcloud run deploy ESP_V2_SERVICE_NAME \ 
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
     --platform gke \
     --use-http2 \
     --project=ESP_PROJECT_ID

   Per ESP_PROJECT_ID, specifica il nome che vuoi utilizzare per il servizio ESPv2. In questo esempio, imposta ESP_V2_SERVICE_NAME su espv2.

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

   gcloud run deploy ESP_V2_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ 
     --platform gke --use-http2 \
     --project ESP_PROJECT_ID

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

Creazione di una mappatura di dominio al servizio Knative serving ESPv2

Per poter omettere l'intestazione host quando effettui una richiesta, aggiungi una mappatura di dominio per il servizio ESPv2:

1. Vai a Cloud Run

2. Seleziona Gestisci domini personalizzati.

3. Seleziona Aggiungi mappatura.

4. Dal menu a discesa, seleziona Aggiungi mappatura di dominio di servizio.

5. Nel campo Seleziona un servizio a cui eseguire la mappatura del popup Aggiungi mappatura, seleziona il servizio ESPv2.

6. Nel campo Inserisci il nome di dominio, specifica il nome di dominio che vuoi utilizzare per accedere al servizio Knative tramite Endpoints. Ad esempio, specifica:

   API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

   dove API_NAME è il nome dell'API Endpoints. Per questo esempio, puoi utilizzare "hello-api":

   grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog

7. Fai clic su Continua. Viene visualizzato un riepilogo del mapping.

8. Seleziona Fine per salvare la mappatura.

invia richieste all'API

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

1. Assicurati di trovarti nella directory che contiene i documenti gRPC, ad esempio api_config_anthos.yaml.

2. Installa le dipendenze:

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

3. Invia una richiesta all'API di esempio:

   python3 bookstore_client.py --host API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog --port 80

   Ad esempio:

   python3 bookstore_client.py --host grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog --port 80

   Se tutto funziona correttamente, dovresti visualizzare una risposta nel formato:

   ListShelves: shelves {
     id: 1
     theme: "Fiction"
   }
   shelves {
     id: 2
     theme: "Fantasy"
   }

   • Consulta i grafici di 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.

Configurazione dell'API Endpoints per l'utilizzo di HTTPS

Il supporto TLS automatico è disabilitato per impostazione predefinita per Knative serving su Google Cloud. Pertanto, in questo esempio, quando accedi all'API Endpoints tramite ESPv2, effettui la chiamata utilizzando HTTP.

Puoi configurare ESPv2 in modo che supporti le richieste tramite HTTPS. Tieni presente che configuri il supporto HTTPS su ESPv2, il servizio esterno, non su "hello", il servizio di backend interno.

Per supportare HTTPS con ESPv2, devi:

1. Possedere un dominio. Se non hai un dominio, puoi ottenerlo da Google o da un altro fornitore di domini.

2. Crea una mappatura di dominio per il servizio ESPv2 e aggiorna il record DNS di conseguenza seguendo le istruzioni riportate nella pagina di mappatura dei domini.

   Se hai ottenuto il dominio da Google Domains, utilizzalo come server DNS. In caso contrario, utilizza Cloud DNS o un server DNS a tua scelta. L'opzione più semplice è utilizzare un dominio di Google Domains.

3. Nella specifica OpenAPI di Endpoints:

   1. Imposta il campo name in modo che faccia riferimento al tuo dominio anziché a *.cloud.goog.

   2. Rimuovi il tag endpoints e le relative due proprietà secondarie.

Per istruzioni complete e un tutorial, vedi Abilitare HTTPS e i certificati TLS automatici.

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