Configurazione di Cloud Endpoints OpenAPI per Cloud Run for Anthos con ESPv2
Questa pagina mostra come configurare Cloud Endpoints per Cloud Run for Anthos. Endpoints utilizza Extensible Service Proxy V2 (ESPv2) come gateway API. Per fornire la gestione delle API per Cloud Run for Anthos, devi eseguire il deployment del container ESPv2 predefinito su Cloud Run for Anthos in esecuzione su un cluster GKE.
Con questa configurazione, ESPv2 intercetta tutte le richieste ai tuoi servizi ed esegue gli eventuali controlli necessari (come l'autenticazione) prima di richiamare il servizio. Quando il servizio risponde, ESPv2 raccoglie e segnala i dati di telemetria.
Per una panoramica di Endpoints, vedi Informazioni su Endpoints ed Architettura degli endpoint.
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 for Anthos, esegui il deployment di un servizio di esempio. Vedi Prima di iniziare.
Crea un cluster GKE con Cloud Run for Anthos abilitato.
Esegui il deployment di un servizio Cloud Run for Anthos di esempio.
Crea un documento OpenAPI che descriva l'API Endpoints e configura le route al tuo servizio Cloud Run for Anthos. Consulta Configurazione di Endpoints.
Esegui il deployment del documento OpenAPI per creare un servizio gestito. Vedi Eseguire il deployment della configurazione di Endpoints.
Crea una nuova immagine Docker ESPv2 con la configurazione del tuo servizio Endpoints. Consulta la sezione Creazione di una nuova immagine ESPv2.
Esegui il deployment della nuova immagine ESPv2 Cloud Run for Anthos. Vedi Deployment dell'immagine Cloud Run ESPv2.
Crea una mappatura di dominio al servizio ESPv2 Cloud Run for Anthos.
Testa la configurazione inviando una richiesta all'API.
Monitora l'attività relativa ai tuoi servizi. Consulta la sezione Attività dell'API di monitoraggio.
Costi
In questo documento vengono utilizzati 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
- Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
- Prendi nota dell'ID progetto perché sarà necessario in seguito. Nel resto della pagina, questo ID progetto è indicato come ESP_PROJECT_ID.
- Scarica e installa Google Cloud SDK.
- Installa cURL se vuoi inviare una richiesta al servizio di esempio di cui è stato eseguito il deployment.
Configurazione della riga di comando gcloud
Per configurare gcloud CLI per Cloud Run for Anthos for Anthos:
Assicurati che Google Cloud SDK 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 di Editor o Proprietario nel progetto Google Cloud che hai creato per eseguire il deployment di ESPv2 in Cloud Run for Anthos.
Aggiorna i componenti
gcloud
installati:gcloud components update
Imposta la piattaforma su
gke
e configura l'impostazione di progetto predefinita pergcloud
sulla piattaforma che hai appena creato:gcloud config set run/platform gke
gcloud config set project ESP_PROJECT_ID
Sostituisci ESP_PROJECT_ID con l'ID del progetto che hai creato.
Imposta la zona desiderata per il nuovo cluster. Puoi utilizzare qualsiasi zona in cui GKE è supportato, ad esempio:
gcloud config set compute/zone ZONE
Sostituisci ZONE con la tua zona. Ad esempio, utilizza
us-central1-a
. Puoi utilizzare qualsiasi zona supportata da GKE.Abilita per il progetto le seguenti API, necessarie per creare un cluster, generare e pubblicare un container in Google Container Registry:
gcloud services enable container.googleapis.com containerregistry.googleapis.com cloudbuild.googleapis.com
Creazione di un cluster GKE con Cloud Run for Anthos abilitato
Per creare un cluster e abilitarlo per Cloud Run for Anthos su Google Cloud:
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 preferisci per il cluster.
Sebbene queste istruzioni non abilitino la scalabilità automatica dei cluster per ridimensionare i cluster per la domanda, Cloud Run for Anthos su Google Cloud scala automaticamente le istanze all'interno del cluster.
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
dell'output. Ad esempio,1.15.11-gke.1
o1.14.10-gke.27
. Prendi nota della versione del cluster per utilizzarla più avanti in questo documento.Configura le impostazioni predefinite di
gcloud
per utilizzare la nuova località del cluster e del cluster, per evitare di doverla specificare quando utilizzi gcloud CLI:gcloud config set run/cluster CLUSTER_NAME
gcloud config set run/cluster_location ZONE
Utilizza questo comando per visualizzare i dettagli del nuovo cluster:
gcloud container clusters describe CLUSTER_NAME
Utilizza il seguente comando per recuperare le credenziali per il cluster:
gcloud container clusters get-credentials CLUSTER_NAME
Deployment di un container Cloud Run for Anthos di esempio
Per eseguire il deployment del container di esempio Cloud Run for Anthos "hello" nel cluster che hai appena creato:
Fai clic su Crea servizio.
Seleziona Cloud Run for Anthos come piattaforma di sviluppo.
Nel menu a discesa dei cluster disponibili, seleziona il cluster appena creato.
Utilizza il nome hello come Nome servizio. Puoi utilizzare un altro nome, ma in tal caso assicurati di utilizzarlo in seguito. Queste istruzioni presuppongono l'utilizzo di hello.
Seleziona Interna in Connettività in modo che il servizio non sia accessibile dall'esterno.
Fai clic su Avanti per passare alla seconda pagina del modulo di creazione del servizio.
Specifica
gcr.io/cloudrun/hello
come URL immagine container.Fai clic su Crea per eseguire il deployment dell'immagine in Cloud Run for Anthos 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.
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:
Si apre un riquadro con i due comandi che utilizzi per accedere al servizio interno. Devi eseguire questi comandi in due finestre del terminale separate, poiché il primo comando configura il port forwarding utilizzato dal secondo comando.
Quando esegui il comando cURL, l'output del servizio dovrebbe essere visualizzato 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 gli eventuali requisiti di autenticazione. Devi anche aggiungere un campo specifico di Google che contenga l'URL di ciascun servizio in modo che ESPv2 abbia le informazioni necessarie per richiamare un servizio. Se non hai mai utilizzato OpenAPI, consulta la panoramica di OpenAPI per ulteriori informazioni.
Informazioni sull'impostazione del campo host della specifica OpenAPI
Nel campo host
della specifica OpenAPI, devi specificare il nome del servizio Endpoints utilizzato per accedere al servizio Cloud Run for Anthos. Il nome del servizio Endpoints è sotto forma di nome di dominio:
API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
Poiché il nome del servizio Endpoints corrisponde a un nome di dominio, il nome deve seguire queste regole:
- Deve contenere solo lettere minuscole, numeri, punti o trattini.
- Non deve iniziare con un trattino.
- Non deve contenere un trattino basso.
Ad esempio:
hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
Creazione della specifica OpenAPI
Crea un file di testo denominato
openapi-run-anthos.yaml
.Il servizio di backend Cloud Run for Anthos viene definito nella parte superiore del file
openapi-run-anthos.yaml
, in una definizione dix-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 essere allo stesso livello diinfo
.Nel campo
host
, 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:
hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
L'estensione
x-google-endpoints
registra una voce DNS per il servizio Endpoints sul dominiocloud.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:Vai alla pagina Google Kubernetes Engine nella console Google Cloud:
Fai clic su Servizi e Ingress nel pannello di navigazione a sinistra per visualizzare un elenco di servizi.
Se la versione del tuo cluster è
1.15.3-gke.19
o successiva,1.14.3-gke.12
o successiva o1.13.10-gke.8
o successiva, scorri verso il basso fino al servizioistio-ingress
. Per tutte le altre versioni del cluster, scorri verso il basso fino al servizioistio-ingressgateway
.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.
Nel campo
address
della sezionex-google-backend
, specifica il nome DNS interno del servizio "hello" di Cloud Run for Anthos e disabilita l'autenticazione per questo servizio. Questo è necessario perché la chiamata da ESPv2 al servizio Cloud Run for Anthos viene effettuata come chiamata interna dall'interno del cluster, quindi l'autenticazione non è necessaria.Prendi nota del valore della proprietà
title
nel fileopenapi-run-anthos.yaml
:title: Cloud Endpoints + Cloud Run
Il valore della proprietà
title
diventa il nome del servizio Endpoints dopo il deployment della configurazione.Salva il documento OpenAPI.
Per informazioni sui campi del documento OpenAPI richiesti da Endpoints, vedi 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:
Assicurati di essere nella directory che contiene il documento OpenAPI.
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 fileopenapi-run-anthos.yaml
. Il servizio Endpoints viene configurato in base al documento OpenAPI.Durante la creazione e la configurazione del servizio Endpoints, Service Management invia informazioni al terminale. Al completamento 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 di 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 è costituito da un indicatore data 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 del deployment nella pagina Endpoint > Servizi della console Google Cloud.Se viene visualizzato un messaggio di errore, vedi Risoluzione dei problemi relativi al 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 |
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 seguente comando per confermare che i servizi richiesti siano abilitati:
gcloud services list
Se i servizi richiesti non sono elencati, abilitali:
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 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 è mostrato sotto la 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 maggiori informazioni sui comandi gcloud
, consulta la pagina relativa ai
servizi gcloud
.
Creazione di una nuova immagine ESPv2 Cloud Run for Anthos
Crea la configurazione del servizio Endpoints in una nuova immagine Docker ESPv2. Dopo aver creato questa immagine, puoi eseguirne il deployment nel cluster.
Per creare la configurazione del servizio in una nuova immagine Docker ESPv2:
Scarica questo script sulla macchina locale in cui è installato gcloud CLI ed eseguilo come:
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 Container Registry del tuo progetto. Lo script utilizza automaticamente l'ultima release 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-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID
Deployment dell'immagine Cloud Run for Anthos di ESPv2
Esegui il deployment dell'immagine del servizio ESPv2 Cloud Run for Anthos nel tuo cluster:
Esegui il deployment del servizio ESPv2 Cloud Run for Anthos 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
.Se vuoi configurare Endpoints in modo da utilizzare opzioni di avvio di ESPv2 aggiuntive, ad esempio l'abilitazione 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, incluso l'elenco delle opzioni disponibili e le informazioni su come specificare più opzioni, vedi Flag di Extensible Service Proxy V2.
Il deployment del servizio ESPv2 è stato eseguito 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 IMAGE a destra dell'URL ESPv2 nella schermata Revisioni del servizio ESPv2 Cloud Run for Anthos di cui è stato eseguito il deployment.
Ora puoi effettuare chiamate API al 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
su ogni richiesta al servizio Endpoints non è facile da usare. Nella sezione successiva, configurerai una mappa di dominio per semplificare l'esecuzione di una chiamata al tuo servizio Endpoint tramite ESPv2.
Creazione di una mappatura di dominio al servizio ESPv2 Cloud Run for Anthos
Per poter omettere l'intestazione host
quando effettui una richiesta, aggiungi una mappatura di dominio per il servizio ESPv2:
Seleziona Gestisci domini personalizzati.
Seleziona Aggiungi mappatura.
Dal menu a discesa, seleziona Aggiungi mappatura del dominio del servizio.
Nel campo Select a service to Map to (Seleziona un servizio a cui mappare) della finestra popup Add mapping (Aggiungi mappatura), seleziona il servizio ESPv2.
Nel campo Inserisci nome di dominio, specifica il nome di dominio che vuoi utilizzare per accedere al servizio Cloud Run for Anthos 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
Fai clic su Continua. Viene visualizzato un riepilogo della mappatura.
Seleziona Fine per salvare la mappatura.
invia richieste all'API
Utilizza cURL per inviare una richiesta HTTP all'API:
curl -X GET "http://hello-api.endpoints.ESP_PROJECT_ID.cloud.goog/hello"
Se non hai ricevuto una risposta corretta, consulta la sezione 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 Cloud Run for Anthos su Google Cloud. Pertanto, in questo esempio, quando accedi all'API Endpoints tramite ESPv2, la chiamata viene effettuata utilizzando HTTP.
Puoi configurare ESPv2 per supportare le richieste utilizzando 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:
Possedere un dominio. Se non hai un dominio, puoi ottenerne uno da Cloud Domains o da un altro fornitore di dominio.
Crea una mappatura di dominio per il tuo 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.
Nella specifica OpenAPI di Endpoints:
Imposta il campo
host
in modo che faccia riferimento al tuo dominio anziché su*.cloud.goog
.Rimuovi il tag
x-google-endpoints
e le sue due proprietà secondarie.
Per istruzioni e tutorial completi, vedi Attivare i certificati HTTPS e TLS automatici.
monitora l'attività dell'API
Visualizza i grafici di attività per la tua API nella pagina Endpoint > Servizio nella console Google Cloud.
Visualizzare i grafici di attività di Endpoints
Potrebbero essere necessari alcuni minuti prima che la richiesta venga riportata nei grafici.
Esamina i log delle richieste per l'API nella pagina Esplora log. Visualizza i log delle richieste di Endpoints
Creazione di un portale per gli sviluppatori per l'API
Puoi utilizzare il portale Cloud Endpoints per creare un portale per 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:
Consulta Eliminazione di un'API e istanze API per informazioni sull'interruzione dei servizi utilizzati da questo tutorial.