esegui il deployment del backend dell'API

OpenAPI   |  gRPC

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

Anche se i passaggi di deployment variano a seconda della piattaforma che ospita l'API, c'è sempre un passaggio in cui devi fornire a ESP il nome del servizio e un'opzione che configura ESP per utilizzare l'ultima configurazione del servizio Cloud Endpoints di cui è stato eseguito il deployment. Con queste informazioni, ESP può ottenere la configurazione degli endpoint dell'API, che consente a ESP di delegare le richieste e le risposte in modo che gli endpoint possano gestire l'API.

Nota: Extensible Service Proxy V2 (ESPv2) può essere eseguito anche su GKE e Kubernetes. ESPv2 non supporta l'ambiente flessibile di App Engine.

Prerequisiti

Per iniziare, si parte dal presupposto che tu abbia:

• Hai creato un progetto Google Cloud.
• Configurato Endpoints.
• È stato eseguito il deployment della configurazione di Endpoints.

Preparazione per il deployment

App Engine

Con l'aggiunta di un piccolo passaggio di configurazione (descritto nei passaggi seguenti), eseguire il deployment dell'API in modo che sia gestita da Endpoints equivale 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 su come configurare i file app.yaml per ogni servizio.

Per eseguire il deployment dell'API in App Engine, puoi utilizzare il comando gcloud app deploy. Questo comando crea automaticamente un'immagine container utilizzando il servizio Container Builder, quindi ne esegue il deployment 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 necessari.

Compute Engine

Affinché Endpoints possa gestire l'API, devi installare e configurare l'ESP e il codice del server di backend per l'API. Devi installare Docker sulla tua istanza VM di Compute Engine in modo da poter eseguire l'immagine Docker ESP liberamente disponibile in Container Registry.

Prima del deployment:

Di seguito sono descritti a livello generale i passaggi da seguire prima di poter eseguire il deployment dell'API e dell'ESP in Compute Engine. In generale, esegui tutti i passaggi come faresti normalmente per eseguire il codice del tuo 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. Vedi Installare Docker.
3. Crea un container Docker per il codice del tuo server di backend. Consulta la documentazione di Cloud Build.
4. Esegui il push del container in Container Registry o in un altro registro.
5. Assicurati di riuscire a:
   • Connettiti all'istanza VM.
   • Esegui l'immagine Docker per avviare il server di backend sull'istanza VM. Consulta la sezione Riferimento per le esecuzioni di Docker.
   • Invia richieste all'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 servizio: 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 maggiori informazioni, consulta 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 all'applicazione containerizzata. Di seguito sono descritti a livello generale i passaggi da seguire prima di poter eseguire il deployment dell'API con ESP su GKE. In generale, devi eseguire tutti i passaggi normalmente utilizzati per eseguire il codice del tuo server di backend su GKE.

1. Esegui il deployment della tua 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 registro.
   3. Creare un cluster di container.
   4. Eseguire il deployment dell'app nel cluster.
   5. Esporre la tua app su internet.
2. Assicurati di riuscire a:
   • Avvia il server dell'API.
   • Invia richieste all'API.

Deployment dell'API e dell'ESP

App Engine

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

1. Recupera il nome del servizio della tua API. Questo è il nome che hai specificato nel campo host 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

   NodeJS

   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 l'ESP per utilizzare l'ultima configurazione del servizio di cui è stato eseguito il deployment. Quando specifichi questa opzione, fino a cinque minuti dopo il deployment di una nuova configurazione del servizio, ESP rileva la modifica e inizia automaticamente a utilizzarla. Ti consigliamo di specificare questa opzione anziché un ID di configurazione specifico per ESP.

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

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

   gcloud app deploy
   

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

Se devi configurare ESP per utilizzare un ID di configurazione specifico:

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

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

Per rimuovere l'ID configurazione specifico:

1. Rimuovi l'opzione config_id dal app.yamlfile.
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 caso contrario, l'errore gcloud app deploy non va a buon fine e viene restituito il seguente errore:

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

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

Compute Engine

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

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

   gcloud compute ssh INSTANCE_NAME

2. Crea la tua rete di container denominata esp_net:

   sudo docker network create --driver bridge esp_net

3. Esegui un'istanza dell'immagine del codice del tuo server di backend e connettila alla rete di 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 tuo container.
   • Sostituisci YOUR_PROJECT_ID con l'ID del progetto Google Cloud che hai utilizzato quando hai eseguito il push dell'immagine.
   • Sostituisci YOUR_IMAGE con il nome della tua immagine.
4. Recupera il nome servizio dell'API. Questo è il nome che hai specificato nel campo host 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 tuo servizio.
   • Sostituisci YOUR_API_CONTAINER_NAME con il nome del container dell'API.

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

Se devi configurare ESP per utilizzare un ID di 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 l'ESP in modo che utilizzi 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 inizia con la configurazione specificata in --version, ma poi viene eseguito in modalità gestita e recupera l'ultima configurazione.

Ti consigliamo di non mantenere ESP configurato per utilizzare un ID configurazione specifico per molto tempo perché se esegui il deployment di una configurazione del servizio aggiornata, devi riavviare 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 ESP.

Consulta le opzioni di avvio di ESP per l'elenco completo delle opzioni che puoi specificare quando avvii l'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 documento OpenAPI).
2. Apri il file manifest di deployment (indicato come 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 l'ultima configurazione del servizio di cui è stato eseguito il deployment. Quando specifichi questa opzione, fino a cinque minuti dopo il deployment di una nuova configurazione del servizio, ESP rileva la modifica e inizia automaticamente a utilizzarla. Ti consigliamo di specificare questa opzione anziché un ID di configurazione specifico 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 di configurazione specifico:

1. Nel file manifest del tuo deployment, aggiungi l'opzione --version e impostala su un ID di configurazione specifico.
2. Rimuovi --rollout_strategy=managed o imposta --rollout_strategy su fixed. L'opzione fixed configura l'ESP in modo che utilizzi 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 inizia con la configurazione specificata in --version, ma poi viene eseguito in modalità gestita e ottiene la configurazione più recente.

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

Per rimuovere l'ID configurazione specifico:

1. Nel file manifest del deployment, rimuovi l'opzione --version.
2. Aggiungi il --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 quando avvii l'ESP.

monitora l'attività dell'API

Dopo aver eseguito il deployment di ESP e del backend dell'API, puoi utilizzare strumenti come curl o Postman per inviare richieste alla tua API. Se non ricevi una risposta corretta, consulta Risoluzione degli errori di risposta.

Dopo aver inviato alcune richieste, puoi:

• Visualizza i grafici di attività per la tua API su Endpoint > Servizi.
  

  Vai alla pagina Endpoints Services

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

• 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 dell'ambiente flessibile di App Engine.
• Risoluzione dei problemi di Endpoints su Compute Engine.
• Risoluzione dei problemi relativi agli endpoint in Google Kubernetes Engine.