esegui il deployment del backend dell'API

OpenAPI   |  gRPC

Questa pagina spiega come eseguire il deployment del codice di backend dell'API e dell'Extensible Service Proxy (ESP) su Google Kubernetes Engine, Compute Engine e nell'ambiente flessibile di App Engine.

Sebbene i passaggi di deployment variano a seconda della piattaforma che ospita l'API, esiste sempre un passaggio in cui fornisci all'ESP il nome del servizio e un'opzione che configura l'ESP in modo da utilizzare la configurazione del servizio Cloud Endpoints di cui è stato eseguito il deployment più di recente. Con queste informazioni, l'ESP può ottenere la configurazione degli endpoint della tua API, che consente all'ESP di eseguire il proxy delle richieste e delle risposte in modo che gli endpoint possano gestire la tua API.

Nota: Extensible Service Proxy V2 (ESPv2) può essere implementato anche su GKE e Kubernetes. ESPv2 non supporta App Engine Flexible.

Prerequisiti

Per iniziare, questa pagina presuppone che tu abbia:

• Hai creato un progetto Google Cloud.
• Configurato Endpoints.
• Esegui il deployment della configurazione di Endpoints.

Preparazione al deployment

App Engine

Con l'aggiunta di un piccolo passaggio di configurazione (descritto nei passaggi seguenti), il deployment dell'API in modo che sia gestita da Endpoints è uguale al deployment di qualsiasi applicazione nell'ambiente flessibile di App Engine. Segui la documentazione di App Engine per:

• Organizza i file di configurazione.
• Crea il file di configurazione app.yaml
• Se la tua applicazione è basata su microservizi, consulta la documentazione relativa al deployment di più applicazioni di servizio per informazioni sulla configurazione dei file app.yaml per ogni servizio.

Esegui il deployment dell'API in App Engine utilizzando il comando gcloud app deploy. Questo comando crea automaticamente un'immagine container utilizzando il servizio Container Builder e poi esegue il deployment dell'immagine nell'ambiente flessibile di App Engine.

Prima del deployment:

• Il proprietario del progetto Google Cloud deve creare l'applicazione App Engine.
• Assicurati che il tuo account utente includa i privilegi richiesti.

Compute Engine

Affinché Endpoints possa gestire la tua API, devi installare e configurare ESP, nonché il codice del server di backend per la tua API. Devi installare Docker sull'istanza VM di Compute Engine per poter eseguire l'immagine Docker ESP disponibile gratuitamente in Artifact Registry.

Prima del deployment:

Di seguito sono descritti a grandi linee i passaggi da seguire prima di poter eseguire il deployment dell'API e dell'ESP su Compute Engine. In generale, esegui tutti i passaggi che normalmente esegui per eseguire il codice del server di backend su Compute Engine.

1. Crea, configura e avvia l'istanza VM. Consulta la documentazione di Compute Engine.
2. Installa Docker Enterprise Edition (EE) o Docker Community Edition (CE) sulla tua istanza VM. Consulta Installa Docker.
3. Crea un container Docker per il codice del server di backend. Consulta la documentazione di Cloud Build.
4. Esegui il push del container in Artifact Registry o in un altro registry.
5. Assicurati di poter:
   • Connettiti all'istanza VM.
   • Esegui l'immagine Docker per avviare il server di backend sull'istanza VM. Consulta la documentazione di riferimento di docker run.
   • Invia richieste alla tua API.

GKE

Quando crei un cluster nella console Google Cloud, per impostazione predefinita gli ambiti OAuth concessi all'account di servizio del cluster includono gli ambiti richiesti da Endpoints:

• Service Control: abilitato
• Gestione servizi: sola lettura

Quando crei un cluster utilizzando il comando gcloud container clusters create o un file di configurazione di terze parti, assicurati di specificare i seguenti ambiti:

• "https://www.googleapis.com/auth/servicecontrol"
• "https://www.googleapis.com/auth/service.management.readonly"

Per ulteriori informazioni, consulta Che cosa sono gli ambiti di accesso?

Prima del deployment:

Con l'aggiunta di una piccola sezione al file manifest di deployment, puoi eseguire l'immagine Docker ESP sui tuoi cluster di container insieme alla tua applicazione containerizzata. Di seguito sono descritti a grandi linee i passaggi da seguire prima di poter eseguire il deployment dell'API con ESP in GKE. In generale, esegui tutti i passaggi che normalmente faresti per eseguire il codice del server di backend su GKE.

1. Esegui il deployment dell'applicazione containerizzata nei cluster di container. I passaggi generali descritti nella documentazione di GKE sono:
   1. Pacchettizza la tua app in un'immagine Docker.
   2. Carica l'immagine in un registry.
   3. Crea un cluster di container.
   4. Esegui il deployment dell'app nel cluster.
   5. Esporre l'app a internet.
2. Assicurati di poter:
   • Avvia il server dell'API.
   • Invia richieste alla tua API.

Eseguire il deployment dell'API e di ESP

App Engine

Per eseguire il deployment dell'API e di ESP in App Engine:

1. Recupera il nome del servizio della tua API. Si tratta del nome specificato nel host campo del documento OpenAPI.
2. Modifica il file app.yaml e aggiungi una sezione denominata endpoints_api_service contenente il nome del servizio. Puoi utilizzare il file app.yaml del tutorial come modello:
   Java

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Python

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Vai

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   PHP

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
     # previously run the deploy command, you can list your existing configuration
     # ids using the 'configs list' command as follows:
     #
     #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
     #
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Ruby

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Node.js

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Sostituisci ENDPOINTS-SERVICE-NAME con il nome del servizio dell'API. Ad esempio:

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     

   L'opzione rollout_strategy: managed configura ESP in modo da utilizzare la configurazione del servizio di cui è stato eseguito il deployment più recente. Quando specifichi questa opzione, fino a 5 minuti dopo aver eseguito il deployment di una nuova configurazione del servizio, ESP rileva la modifica e inizia a utilizzarla automaticamente. Ti consigliamo di specificare questa opzione anziché un ID configurazione specifico da utilizzare per ESP.

   Se la tua applicazione è basata su microservizi, devi includere la sezione endpoints_api_service in ogni file app.yaml.

3. Salva il file (o i file) app.yaml.
4. Esegui il deployment del codice di backend e di ESP in App Engine:

   gcloud app deploy

Poiché hai aggiunto la sezione endpoints_api_service al app.yaml file, il comando gcloud app deploy esegue il deployment e configura ESP in un contenitore separato rispetto al tuo ambiente flessibile App Engine. Tutto il traffico delle richieste viene instradato tramite ESP, che funge da proxy per le richieste e le risposte verso e dal contenitore che esegue il codice del server di backend.

Se devi configurare ESP per utilizzare un ID configurazione specifico:

1. Nella sezione endpoints_api_service del file app.yaml, aggiungi il campo config_id e impostalo su un ID configurazione specifico.
2. Rimuovi rollout_strategy: managed o imposta rollout_strategy su fixed. L'opzione fixed configura ESP in modo da utilizzare la configurazione del servizio specificata in config_id.
3. Esegui nuovamente il deployment dell'API e dell'ESP: gcloud app deploy

Ti consigliamo di non mantenere l'ESP configurato per l'utilizzo di un ID configurazione specifico per molto tempo, perché se esegui il deployment di una configurazione del servizio aggiornata, devi riavviare l'ESP per utilizzare la nuova configurazione.

Per rimuovere l'ID configurazione specifico:

1. Rimuovi l'opzione config_id dal file app.yaml.
2. Aggiungi l'opzione rollout_strategy: managed.
3. Esegui il comando gcloud app deploy

Quando utilizzi l'opzione rollout_strategy: managed, non includere config_id: YOUR_SERVICE_CONFIG_ID nel file app.yaml. In questo caso, gcloud app deploy non va a buon fine con il seguente errore:

config_id is forbidden when rollout_strategy is set to "managed".

Quando esegui il deployment dell'API nell'ambiente flessibile di App Engine per la prima volta, potrebbe verificarsi un ritardo durante la configurazione della macchina virtuale (VM) e dell'altra infrastruttura. Per ulteriori informazioni, consulta Garantire il buon esito del deployment nella documentazione di App Engine.

Compute Engine

Per eseguire il deployment dell'API con ESP in Compute Engine con Docker:

1. Connettiti all'istanza VM. Sostituisci INSTANCE_NAME con il nome dell'istanza VM.

   gcloud compute ssh INSTANCE_NAME

2. Crea la tua rete di contenitori denominata esp_net:

   sudo docker network create --driver bridge esp_net

3. Esegui un'istanza dell'immagine del codice del server di backend e connettila alla rete del container esp_net:

   sudo docker run \
       --detach \
       --name=YOUR_API_CONTAINER_NAME \
       --net=esp_net \
       gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0

   • Sostituisci YOUR_API_CONTAINER_NAME con il nome del contenitore.
   • Sostituisci YOUR_PROJECT_ID con l'ID del progetto Google Cloud che hai utilizzato per eseguire il push dell'immagine.
   • Sostituisci YOUR_IMAGE con il nome dell'immagine.
4. Recupera il nome del servizio della tua API. Si tratta del nome specificato nel host campo del documento OpenAPI.
5. Esegui un'istanza dell'immagine Docker ESP:

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --backend=YOUR_API_CONTAINER_NAME:8080

   • Sostituisci SERVICE_NAME con il nome del servizio.
   • Sostituisci YOUR_API_CONTAINER_NAME con il nome del contenitore dell'API.

   L'opzione --rollout_strategy=managed configura ESP in modo da utilizzare la configurazione del servizio di cui è stato eseguito il deployment più recente. Quando specifichi questa opzione, fino a 5 minuti dopo aver eseguito il deployment di una nuova configurazione del servizio, ESP rileva la modifica e inizia a utilizzarla automaticamente. Ti consigliamo di specificare questa opzione anziché un ID configurazione specifico da utilizzare per ESP.

Se devi configurare ESP per utilizzare un ID configurazione specifico:

1. Includi l'opzione --version e impostala su un ID configurazione specifico.
2. Rimuovi l'opzione --rollout_strategy=managed o imposta --rollout_strategy su fixed. L'opzione fixed configura ESP in modo da utilizzare la configurazione del servizio specificata in --version.
3. Esegui di nuovo il comando docker run.

Se specifichi sia --rollout_strategy=managed sia l'opzione --version, ESP si avvia con la configurazione specificata in --version, ma poi viene eseguito in modalità gestita e ottiene la configurazione più recente.

Ti consigliamo di non mantenere l'ESP configurato per l'utilizzo di un ID configurazione specifico per molto tempo, perché se esegui il deployment di una configurazione del servizio aggiornata, devi riavviare l'ESP per utilizzare la nuova configurazione.

Per rimuovere l'ID configurazione specifico:

1. Nei flag ESP per docker run, rimuovi l'opzione --version.
2. Aggiungi l'opzione --rollout_strategy=managed.
3. Esegui il comando docker run per riavviare l'ESP.

Consulta le opzioni di avvio di ESP per l'elenco completo delle opzioni che puoi specificare all'avvio di ESP.

GKE

Per eseguire il deployment di ESP in GKE:

1. Recupera il nome del servizio della tua API (il nome specificato nel campo host del tuo documento OpenAPI).
2. Apri il file manifest del deployment (chiamato file deployment.yaml) e aggiungi quanto segue alla sezione dei container:

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed"
     ]

   Sostituisci SERVICE_NAME con il nome del servizio dell'API.

   L'opzione --rollout_strategy=managed" configura ESP in modo che utilizzi la configurazione del servizio di cui è stato eseguito il deployment più recente. Quando specifichi questa opzione, fino a 5 minuti dopo aver eseguito il deployment di una nuova configurazione del servizio, ESP rileva la modifica e inizia a utilizzarla automaticamente. Ti consigliamo di specificare questa opzione anziché un ID configurazione specifico da utilizzare per ESP.

3. Avvia il servizio Kubernetes utilizzando il comando kubectl create:

   kubectl create -f deployment.yaml

Se devi configurare ESP per utilizzare un ID configurazione specifico:

1. Nel file manifest di deployment, aggiungi l'opzione --version e impostala su un ID configurazione specifico.
2. Rimuovi --rollout_strategy=managed o imposta --rollout_strategy su fixed. L'opzione fixed configura ESP in modo da utilizzare la configurazione del servizio specificata in --version.
3. Avvia il servizio Kubernetes: kubectl create -f deployment.yaml

Se specifichi sia --rollout_strategy=managed sia l'opzione --version, ESP si avvia con la configurazione specificata in --version, ma poi viene eseguito in modalità gestita e ottiene la configurazione più recente.

Ti consigliamo di non mantenere l'ESP configurato per l'utilizzo di un ID configurazione specifico per molto tempo, perché se esegui il deployment di una configurazione del servizio aggiornata, devi riavviare l'ESP per utilizzare la nuova configurazione.

Per rimuovere l'ID configurazione specifico:

1. Nel file manifest di Deployment, rimuovi l'opzione --version.
2. Aggiungi --rollout_strategy=managed.
3. Avvia il servizio Kubernetes: kubectl create -f deployment.yaml

Consulta le opzioni di avvio di ESP per l'elenco completo delle opzioni che puoi specificare all'avvio di ESP.

monitora l'attività dell'API

Dopo aver eseguito il deployment dell'ESP e del backend dell'API, puoi utilizzare strumenti come curl o Postman per inviare richieste all'API. Se non ricevi una risposta positiva, consulta la sezione Risolvere i problemi relativi alle risposte.

Dopo aver inviato alcune richieste, puoi:

• Visualizza i grafici delle attività per la tua API in 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 Cloud Logging.
  

  Vai alla pagina Esplora log

Passaggi successivi

• Risoluzione dei problemi di deployment nell'ambiente flessibile di App Engine.
• Risolvere i problemi relativi a Endpoints su Compute Engine.
• Risoluzione dei problemi relativi agli endpoint in Google Kubernetes Engine.