Configura Cloud Endpoints OpenAPI per Knative Serving con ESPv2

Questa pagina mostra come configurare Cloud Endpoints per Knative serving. Endpoints utilizza Extensible Service Proxy V2 (ESPv2) come gateway API. Per fornire la gestione delle API per Knative serving, esegui il deployment del container ESPv2 precompilato in Knative serving in esecuzione su un cluster GKE.

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 segnala la telemetria.

Per una panoramica di Endpoints, vedi Informazioni su Endpoints e Architettura di Endpoints.

Elenco attività

Utilizza il seguente elenco di attività mentre segui il tutorial. Tutte le attività sono necessarie per completare questo tutorial.

  1. Crea un Google Cloud progetto e, se non hai eseguito il deployment del tuo Knative Serving, esegui il deployment di un servizio di esempio. Vedi Prima di iniziare.

  2. Crea un cluster GKE con Knative Serving abilitato.

  3. Esegui il deployment di un servizio Knative serving di esempio.

  4. Crea un documento OpenAPI che descriva la tua API Endpoints e configura le route al tuo servizio Knative. Consulta Configurazione di Endpoints.

  5. Esegui il deployment del documento OpenAPI per creare un servizio gestito. Vedi Deployment della configurazione di Endpoints.

  6. Crea una nuova immagine Docker ESPv2 con la configurazione del servizio Endpoints. Consulta la sezione Creazione di una nuova immagine ESPv2.

  7. Esegui il deployment della nuova immagine ESPv2 Knative serving. Consulta Deployment dell'immagine Cloud Run di ESPv2.

  8. Crea una mappatura di dominio al servizio Knative serving ESPv2.

  9. Testa la configurazione inviando una richiesta all'API.

  10. Monitorare l'attività sui tuoi servizi. Consulta Monitorare l'attività dell'API.

  11. Pulisci.

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.

I nuovi Google Cloud utenti potrebbero avere diritto a una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per ulteriori informazioni, vedi Pulizia.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Prendi nota dell'ID progetto perché ti servirà in seguito. Nel resto della pagina, questo ID progetto è indicato come ESP_PROJECT_ID.
  7. Scarica e installa Google Cloud SDK.
  8. Installa cURL se vuoi inviare una richiesta al servizio di esempio di cui è stato eseguito il deployment.

    9. Configurazione della riga di comando gcloud

    Per configurare l'interfaccia alla gcloud CLI per Knative Serving per Anthos:

    1. Assicurati che Google Cloud SDK sia autorizzato 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 Knative Serving.

    2. Aggiorna i componenti gcloud installati: 

      gcloud components update

    3. Imposta la piattaforma su gke e imposta l'impostazione del progetto predefinita per gcloud su quella appena creata: 

      gcloud config set run/platform gke 
gcloud config set project ESP_PROJECT_ID

      Sostituisci ESP_PROJECT_ID con l'ID progetto del progetto che hai creato.

    4. Imposta la zona desiderata per il nuovo cluster. Puoi utilizzare qualsiasi zona in cui è supportato GKE, ad esempio: 

      gcloud config set compute/zone ZONE

      Sostituisci ZONE con la tua zona. Ad esempio, usa us-central1-a. Puoi utilizzare qualsiasi zona supportata da GKE.

    5. Abilita le seguenti API per il progetto, necessarie per creare un cluster, creare e pubblicare un container in Artifact Registry: 

      gcloud services enable container.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

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 \ 
  --enable-stackdriver-kubernetes

    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 container di esempio Knative Serving

Per eseguire il deployment del container di esempio "hello" di Knative serving nel cluster appena creato:

  1. Vai a Cloud Run

  2. Fai clic su Crea servizio.

  3. Seleziona Knative serving come piattaforma di sviluppo.

  4. Nel menu a discesa dei cluster disponibili, seleziona il cluster che hai appena creato.

  5. Utilizza il nome hello come Nome servizio. Puoi utilizzare un altro nome, ma in questo caso assicurati di utilizzarlo in seguito. Queste istruzioni presuppongono che tu utilizzi hello.

  6. Seleziona Interna in Connettività in modo che il servizio non sia accessibile esternamente.

  7. Fai clic su Avanti per continuare con la seconda pagina del modulo di creazione del servizio.

  8. Specifica gcr.io/cloudrun/hello come URL immagine container.

  9. Fai clic su Crea per eseguire il deployment dell'immagine in Knative Serving e attendi il completamento del deployment.

    Al termine, viene visualizzata la schermata Revisioni. Tieni presente che l'URL del servizio di cui è stato eseguito il deployment è:

    http://hello.default.svc.cluster.local

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

  10. Per verificare che il servizio funzioni correttamente utilizzando cURL, configura un tunnel dal desktop al cluster. Per visualizzare queste istruzioni, fai clic sull'icona a destra dell'URL nella schermata Revisioni:

    Schermata Revisioni.

  11. Si apre un riquadro che mostra i due comandi che utilizzi per accedere al servizio interno. Devi eseguire questi comandi in due finestre del terminale separate perché il primo comando configura il port forwarding utilizzato dal secondo comando.

    Quando esegui il comando cURL, dovresti visualizzare l'output del servizio nel formato: 

    <!doctype html>
<html lang=en> 
<head> 
<meta charset=utf-8> 
<meta name="viewport" content="width=device-width, initial-scale=1"> 
<title>Congratulations | Cloud Run</title> 
...

Configurazione di Endpoints

Devi disporre di un documento OpenAPI basato sulla specifica OpenAPI v2.0 che descriva la superficie del tuo servizio di backend e qualsiasi requisito di autenticazione. Devi anche aggiungere un campo specifico di Google che contenga l'URL di ogni servizio, in modo che ESPv2 disponga delle informazioni necessarie per richiamare un servizio. Se non hai familiarità con OpenAPI, consulta la panoramica di OpenAPI per saperne di più.

Informazioni sull'impostazione del campo host della specifica OpenAPI

Nel campo host della specifica OpenAPI, specifica il nome del servizio Endpoints utilizzato per accedere al servizio Knative. 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: 

hello-api.endpoints.ESP_PROJECT_ID.cloud.goog

Creazione della specifica OpenAPI

  1. Crea un file di testo denominato openapi-run-anthos.yaml.

  2. Il servizio di backend Knative serving è definito nella parte superiore del file openapi-run-anthos.yaml, in una definizione x-google-backend. Ad esempio: 

    swagger: '2.0' 
info:
  title: Cloud Endpoints + Cloud Run
  description: Sample API on Cloud Endpoints with a Cloud Run backend
  version: 1.0.0 
host: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
x-google-endpoints:
- name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
  target: "INGRESS-IP"
schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: http://hello.default.svc.cluster.local
  disable_auth: true
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string

    Il rientro è importante per il formato YAML. Ad esempio, il campo host deve trovarsi allo stesso livello di info.

  3. Nel campo host, specifica il nome di dominio dell'API Endpoints utilizzata per accedere al servizio Knative, nel formato: 

    API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

    Ad esempio: 

    hello-api.endpoints.ESP_PROJECT_ID.cloud.goog

  4. L'estensione x-google-endpoints registra una voce DNS per il tuo servizio Endpoints sul dominio cloud.goog, nel formato: 

    x-google-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 nella Google 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.

  5. Nel campo address della sezione x-google-backend, specifica il nome DNS interno del servizio "hello" di Knative Serving di backend e disattiva l'autenticazione a questo servizio. Ciò è necessario perché la chiamata da ESPv2 al servizio Knative Serving viene effettuata come chiamata interna dall'interno del cluster e pertanto l'autenticazione non è necessaria.

  6. Prendi nota del valore della proprietà title nel file openapi-run-anthos.yaml: 

    title: Cloud Endpoints + Cloud Run

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

  8. Salva il documento OpenAPI.

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

  2. Carica la configurazione e crea un servizio gestito. 

    gcloud endpoints services deploy openapi-run-anthos.yaml \ 
  --project ESP_PROJECT_ID

    Viene creato un nuovo servizio Endpoints con il nome specificato nel campo host del file openapi-run-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 [hello-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 openapi-run-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

Come minimo, Endpoints ed ESP richiedono l'abilitazione dei seguenti servizi Google:
Nome Titolo
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control

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:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
  --platform gke \ 
  --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:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ 
  --platform gke \ 
  --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.

Il servizio ESPv2 viene implementato come servizio esterno, il che significa che puoi accedervi utilizzando un comando cURL nel formato:

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS

dove IP_ADDRESS è l'indirizzo IP del servizio istio-ingress per il tuo cluster.

Per visualizzare questo comando cURL, fai clic sull'icona IMMAGINE a destra dell'URL ESPv2 nella schermata Revisioni del servizio di pubblicazione ESPv2 Knative di cui è stato eseguito il deployment.

Ora puoi effettuare chiamate API al tuo servizio Endpoints tramite il servizio ESPv2. Ad esempio, per effettuare una richiesta a un servizio Endpoints con un percorso /hello, puoi effettuare una richiesta nel formato:

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS/hello

Tuttavia, specificare un'intestazione host in ogni richiesta al servizio Endpoints non è facile da usare. Nella sezione successiva, configurerai una mappa dei domini per semplificare la chiamata al servizio Endpoint tramite ESPv2.

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": 

    hello-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

Utilizza cURL per inviare una richiesta HTTP alla tua API:

curl -X GET "http://hello-api.endpoints.ESP_PROJECT_ID.cloud.goog/hello"

Se non hai ricevuto una risposta corretta, consulta Risoluzione dei problemi relativi agli errori di risposta.

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 Cloud Domains 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 Cloud Domains, utilizza Cloud DNS o un server DNS a tua scelta. L'utilizzo di un dominio di Cloud Domains è l'opzione più semplice.

  3. Nella specifica OpenAPI di Endpoints:

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

    2. Rimuovi il tag x-google-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

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 delle istanze API per informazioni sull'interruzione dei servizi utilizzati in questo tutorial.

Passaggi successivi