esegui il deployment del backend dell'API

OpenAPI   |  gRPC

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

Sebbene i passaggi di deployment varino a seconda della piattaforma che ospita l'API, è sempre presente un passaggio in cui fornisci a ESP il nome del servizio e un'opzione che configura ESP per utilizzare la configurazione del servizio Cloud Endpoints di cui è stato eseguito il deployment più recente. Con queste informazioni, ESP può ottenere la configurazione di Endpoints dell'API, che consente a ESP di eseguire il proxy delle richieste e delle risposte in modo che Endpoints possa gestire l'API.

Nota: ESP ed ESPV2 hanno un supporto ambientale diverso. ESP è supportato solo nell'ambiente flessibile di App Engine e non è disponibile nell'ambiente standard di App Engine. Al contrario, ESPv2 può essere sottoposto a deployment su GKE e Kubernetes, ma non supporta App Engine.

Prerequisiti

Come punto di partenza, questa pagina presuppone che tu abbia:

• Creatoun Google Cloud progetto.
• Configurato Endpoints.
• Eseguito il deployment della configurazione di Endpoints.

Prepararsi al deployment

Ambiente flessibile di 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:

• Organizzare i file di configurazione.
• Creare 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 app.yaml file per ogni servizio.

Esegui il deployment dell'API in App Engine utilizzando il gcloud app deploy comando. 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 di eseguire il deployment:

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

Compute Engine

Affinché Endpoints gestisca l'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 di ESP, disponibile senza costi in Artifact Registry.

Prima di eseguire il deployment:

Di seguito sono riportati a livello generale i passaggi da eseguire prima di poter eseguire il deployment dell'API e di ESP in Compute Engine. In generale, esegui tutti i passaggi che normalmente esegui per eseguire il codice del server di backend in 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) su l'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 registro.
5. Assicurati di poter eseguire correttamente le seguenti operazioni:
   • Connettiti all' istanza VM.
   • Esegui l'immagine Docker per avviare il server di backend sull'istanza VM instance. Consulta il riferimento di docker run.
   • Invia richieste all'API.

GKE

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

• Service Control: abilitato
• Service Management: solo lettura

Quando crei un cluster utilizzando il gcloud container clusters create comando 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 di eseguire il deployment:

Aggiungendo una piccola sezione al file manifest di deployment, puoi eseguire l'immagine Docker di ESP sui cluster di container insieme all'applicazione containerizzata. Di seguito sono riportati a livello generale i passaggi da eseguire prima di poter eseguire il deployment dell'API con ESP in GKE. In generale, esegui tutti i passaggi che normalmente esegui per eseguire il codice del server di backend in GKE.

1. Esegui il deployment dell'applicazione containerizzata nei cluster di container. I passaggi generali descritti nella documentazione di GKE sono:
   1. Pacchettizza l'app in un'immagine Docker.
   2. Carica l'immagine in un registro.
   3. Crea un cluster di container.
   4. Esegui il deployment dell'app nel cluster.
   5. Esporre l'app su internet.
2. Assicurati di poter eseguire correttamente le seguenti operazioni:
   • Avvia il server dell'API.
   • Invia richieste all'API.

Eseguire il deployment dell'API e di ESP

Ambiente flessibile di App Engine

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

1. Recupera il nome del servizio dell'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 che contenga il nome del servizio. Puoi utilizzare il app.yaml file 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

   Go

   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.

   Aggiungi le variabili di ambiente e di runtime nel file di configurazione app.yaml.

   Ad esempio:

   runtime: nodejs
   env: flex
   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     

   L'opzione rollout_strategy: managed configura ESP per utilizzare la configurazione del servizio di cui è stato eseguito il deployment più recente. Quando specifichi questa opzione, fino a 5 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 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 backend e di 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 ESP in un container separato nell'ambiente flessibile di App Engine. Tutto il traffico delle richieste viene instradato tramite ESP, che esegue il proxy delle richieste e delle risposte da e verso il container che esegue il codice del 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 ESP per utilizzare la configurazione del servizio specificata in config_id.
3. Esegui di nuovo il deployment dell'API e di ESP: gcloud app deploy

Ti consigliamo di non mantenere ESP configurato per utilizzare un ID di 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 di configurazione specifico:

1. Rimuovi l'opzione config_iddal 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 app.yaml file. In caso contrario, gcloud app deploy non riesce 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 di altre infrastrutture. Per ulteriori informazioni, consulta Garantire il successo 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 una rete di container personalizzata 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 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 container.
   • Sostituisci YOUR_PROJECT_ID con l' Google Cloud ID del progetto che hai utilizzato quando hai eseguito il push dell'immagine.
   • Sostituisci YOUR_IMAGE con il nome dell'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 di 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 container dell'API.

   L'opzione --rollout_strategy=managed configura ESP per utilizzare la configurazione del servizio di cui è stato eseguito il deployment più recente. Quando specifichi questa opzione, fino a 5 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 da utilizzare per ESP.

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

1. Includi l'opzione --version e impostala su un ID di configurazione specifico .
2. Rimuovi l'opzione --rollout_strategy=managed o imposta --rollout_strategy su fixed. L'opzione fixed configura ESP per 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 viene avviato con la configurazione specificata in --version, ma poi viene eseguito in modalità gestita e recupera la configurazione più recente.

Ti consigliamo di non mantenere ESP configurato per utilizzare un ID di 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 di 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.

Per l'elenco completo delle opzioni che puoi specificare all'avvio di ESP , consulta Opzioni di avvio di ESP.

GKE

Per eseguire il deployment di ESP in GKE:

1. Recupera il nome del servizio dell' API (il nome che hai specificato nel campo host del documento OpenAPI).
2. Apri il file manifest di deployment (denominato file deployment.yaml file) 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 per utilizzare la configurazione del servizio di cui è stato eseguito il deployment più recente. Quando specifichi questa opzione, fino a 5 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 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 di configurazione specifico:

1. Nel file manifest di 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'fixed opzione configura ESP per utilizzare la configurazione del servizio che hai specificato in --version.
3. Avvia il servizio Kubernetes: kubectl create -f deployment.yaml

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

Ti consigliamo di non mantenere ESP configurato per utilizzare un ID di 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 di 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

Per l'elenco completo delle opzioni che puoi specificare all'avvio di ESP , consulta Opzioni di avvio di 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 all'API. Se non ricevi una risposta positiva consulta Risoluzione dei problemi relativi agli errori di risposta.

Dopo aver inviato alcune richieste, puoi:

• Visualizzare i grafici delle attività associate alla tua API in Endpoints > Servizi.
  

  Vai alla pagina Servizi Endpoints

  
  La visualizzazione dei dati relativi alle richieste nei grafici può richiedere alcuni minuti.

• Esaminare i log delle richieste per l'API nella pagina Cloud Logging.
  

  Vai alla pagina Esplora log

Passaggi successivi

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