Esecuzione di ESP in locale o su un'altra piattaforma

Questa pagina spiega come configurare ed eseguire un'istanza di Extensible Service Proxy (ESP) su una macchina locale, su un altro provider di servizi cloud, ad esempio Amazon Web Services (AWS) o su un cluster Kubernetes che non si trova su Google Cloud.

Puoi eseguire ESP su un computer o una macchina virtuale (VM) Linux o macOS. Microsoft Windows non è supportato. Puoi eseguire il deployment dell'applicazione e dell'ESP sullo stesso host o su host diversi. L'hosting di un'istanza locale di ESP ti consente di:

• Prova ESP prima di eseguirne il deployment su una piattaforma di produzione.
• Verifica che le impostazioni di sicurezza siano configurate e funzionino correttamente e che le metriche e i log vengano visualizzati nella pagina Endpoint > Servizi come previsto.

Prerequisiti

Come punto di partenza, questa pagina presuppone che:

• Hai installato Docker, se esegui il deployment del container ESP localmente o su una VM. Per saperne di più, consulta Installare Docker.

• Hai eseguito il deployment di un'API localmente o su un host raggiungibile dall'host in cui esegui ESP.

• Hai configurato Cloud Endpoints e eseguito il deployment della configurazione per creare un servizio gestito per la tua API.

Se hai bisogno di un'API per i test con ESP, puoi configurare ed eseguire il deployment del codice campione nella sezione (Facoltativo) Utilizzo di un'API di esempio. Se hai già configurato e implementato la tua API, vai a Creazione di un service account.

(Facoltativo) Utilizzo di un'API di esempio

Questa sezione ti guida nella configurazione e nel deployment della versione Python dell'esempio di getting-started per Endpoints in locale. Esegui i passaggi di questa sezione solo se non disponi di un'API per i test con ESP.

L'esempio getting-started di Cloud Endpoints è disponibile in altre lingue. Consulta la pagina Esempi per trovare la posizione di GitHub dell'esempio getting-started nella tua lingua preferita. Segui le istruzioni nel file README.md dell'esempio per l'esecuzione in locale, quindi segui le istruzioni in questa sezione per configurare Endpoints ed eseguire il deployment della configurazione di Endpoints.

Ottenere il software richiesto

Se non hai ancora configurato un ambiente di sviluppo Python, consulta la sezione Configurazione di un ambiente di sviluppo Python per indicazioni. Assicurati di aver installato quanto segue:

• virtualenv
• Google Cloud CLI
• curl

recupera il codice campione

1. Clona il repository dell'app di esempio sulla tua macchina locale:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

2. Passa alla directory che contiene il codice di esempio:

   cd python-docs-samples/endpoints/getting-started
   

Configura endpoint

1. Nella directory codice campione, apri il file di configurazione openapi.yaml.

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

2. Nel campo host, sostituisci YOUR-PROJECT-ID con l'ID del tuo progetto Google Cloud .

3. Salva il file openapi.yaml.

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.

1. Aggiorna gcloud CLI:

   gcloud components update

2. Assicurati che gcloud CLI (gcloud) sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud:

   gcloud auth login

   Nella nuova scheda del browser che si apre, seleziona un account.

3. Imposta il progetto predefinito sull'ID progetto:

   gcloud config set project YOUR-PROJECT-ID
   

   Sostituisci YOUR-PROJECT-ID con l'ID progetto del progettoGoogle Cloud che hai specificato nel file openapi.yaml.

4. Esegui il deployment della configurazione:

   gcloud endpoints services deploy openapi.yaml

Service Management utilizza il testo specificato nel campo host del file openapi.yaml per creare un nuovo servizio Endpoints con il nome echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog (se non esiste) e poi lo configura in base al file di configurazione OpenAPI.

Durante la creazione e la configurazione del servizio, Service Management visualizza le informazioni nel terminale. Puoi ignorare tranquillamente gli avvisi sui percorsi nel file openapi.yaml che non richiedono una chiave API. Al termine, viene visualizzata una riga simile alla seguente, in cui sono visualizzati l'ID configurazione del servizio e il nome del servizio tra parentesi quadre:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Nell'esempio precedente, 2017-02-13r0 è l'ID configurazione del servizio e echo-api.endpoints.example-project-12345.cloud.goog è il nome del servizio.

Avvio del server locale

1. Crea un virtualenv, attivalo e installa le dipendenze dell'applicazione.

   virtualenv env
   source env/bin/activate
   pip install -r requirements.txt

2. Avvia il server:

   python main.py
   

3. Apri un'altra finestra del terminale e utilizza curl per inviare una richiesta:

   curl --request POST \
     --header "content-type:application/json" \
     --data '{"message":"hello world"}' \
     http://localhost:8080/echo
   

   L'API restituisce il messaggio che invii e risponde con quanto segue:

   {
   "message": "hello world"
   }

Creazione di un account di servizio

Per fornire la gestione della tua API, sia ESP che ESPv2 richiedono i servizi in Service Infrastructure. Per chiamare questi servizi, ESP ed ESPv2 devono utilizzare token di accesso. Quando esegui il deployment di ESP o ESPv2 negli ambienti Google Cloud , ad esempio GKE, Compute Engine o l'ambiente flessibile di App Engine, ESP ed ESPv2 ottengono token di accesso per te tramite il servizio di metadatiGoogle Cloud .

Quando esegui il deployment di ESP o ESPv2 in un ambiente nonGoogle Cloud , ad esempio il tuo computer locale, un cluster Kubernetes on-premise o un altro provider cloud, devi fornire un file JSON dell'account di servizio che contenga una chiave privata. ESP ed ESPv2 utilizzano il service account per generare token di accesso per chiamare i servizi necessari per gestire l'API.

Per creare l'account di servizio e il file della chiave privata, puoi utilizzare la console Google Cloud o Google Cloud CLI:

Aggiungi i ruoli IAM richiesti:

Questa sezione descrive le risorse IAM utilizzate da ESP e ESPv2 e i ruoli IAM richiesti per l'accesso a queste risorse da parte delaccount di serviziot collegato.

Configurazione del servizio endpoint

ESP ed ESPv2 chiamano Service Control che utilizza la configurazione del servizio endpoint. La configurazione del servizio endpoint è una risorsa IAM e ESP ed ESPv2 richiedono il ruolo Service Controller per accedervi.

Il ruolo IAM si trova nella configurazione del servizio endpoint, non nel progetto. Un progetto può avere più configurazioni di servizio endpoint.

Utilizza il seguente comando gcloud per aggiungere il ruolo al service account collegato per la configurazione del servizio endpoint.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Dove
* SERVICE_NAME è il nome del servizio endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com è l'account di servizio collegato.

Cloud Trace

ESP ed ESPv2 chiamano il servizio Cloud Trace per esportare la traccia in un progetto. Questo progetto è chiamato progetto di tracciamento. In ESP, il progetto di tracciamento e il progetto proprietario della configurazione del servizio endpoint sono gli stessi. In ESPv2, il progetto di tracciamento può essere specificato dal flag --tracing_project_id e il valore predefinito è il progetto di deployment.

ESP ed ESPv2 richiedono il ruolo agente Cloud Trace per abilitare Cloud Trace.

Utilizza il seguente comando gcloud per aggiungere il ruolo al service account collegato:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Dove
* TRACING_PROJECT_ID è l'ID progetto di tracciamento
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com è il account di servizio collegato. Per ulteriori informazioni, vedi Che cosa sono ruoli e autorizzazioni?

Per ulteriori informazioni sui comandi, consulta gcloud iam service-accounts.

Esecuzione di ESP in un container

Questa sezione descrive come eseguire il deployment del container ESP. La procedura che utilizzi dipende da dove viene eseguito il deployment del container ESP:

• Esecuzione di ESP in un container Docker in locale o su un'altra piattaforma
• Esecuzione di ESP in un container su un cluster Kubernetes

Esecuzione di ESP in un container Docker in locale o su un'altra piattaforma

1. Rinomina il file JSON che contiene la chiave privata dell'account di servizio in service-account-creds.json e copialo in $HOME/Downloads/ se è stato scaricato in una directory diversa. In questo modo, il percorso completo corrisponde al valore di --service_account_key nel seguente comando docker run.

2. Nel seguente comando docker run, sostituisci YOUR_SERVICE_NAME con il nome del tuo servizio.

sudo docker run \
  --detach \
  --name="esp" \
  --net="host" \
  --volume=$HOME/Downloads:/esp \
  --publish=8082 \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --backend=localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

sudo docker run \
  --detach \
  --name="esp" \
  --publish=8082:8082 \
  --volume=$HOME/Downloads:/esp \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --backend=docker.for.mac.localhost:8080 \
  --service_account_key=/esp/service-account-creds.json
  

sudo docker run \
  --detach \
  --name="esp" \
  --net="host" \
  --volume=$HOME/Downloads:/esp \
  --publish=8082 \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --backend=IP_Address:PORT \
  --service_account_key=/esp/service-account-creds.json
  

La seguente tabella descrive le opzioni Docker utilizzate nei comandi precedenti. Per informazioni sulle opzioni ESP utilizzate nell'esempio, vedi Opzioni di avvio di ESP.

Esegui ESP in un container su un cluster Kubernetes

Questa sezione descrive come eseguire il deployment di ESP in un cluster Kubernetes che non si trova su Google Cloud.

Per fare in modo che la tua API venga gestita da Endpoints, esegui il deployment del container ESP nello stesso pod Kubernetes del container API. L'insieme di pod che eseguono ESP e la tua API sono raggruppati in un servizio Kubernetes utilizzando un selettore di etichette, ad esempio app: my-api. Il servizio Kubernetes specifica il criterio di accesso per bilanciare il carico delle richieste client sulla porta proxy.

1. Rinomina il file JSON che contiene la chiave privata dell'account di servizio in service-account-creds.json e copialo in $HOME/Downloads/ se è stato scaricato in una directory diversa. In questo modo, il percorso completo corrisponde al comando nel passaggio successivo.

2. Esegui il comando seguente per creare un secret di Kubernetes e montarlo come volume di Kubernetes.

   kubectl create secret generic service-account-creds \
     --from-file=$HOME/Downloads/service-account-creds.json
   

   In caso di esito positivo, viene visualizzato il seguente messaggio: secret "service-account-creds" created

3. Nel file di configurazione di Kubernetes, aggiungi quanto segue, sostituendo YOUR_APP_NAME con il nome della tua API e YOUR_SERVICE_NAME con il nome del tuo servizio.

   spec:
   replicas: 1
   template:
     metadata:
       labels:
         app: "YOUR_APP_NAME"
     spec:
       volumes:
         - name: service-account-creds
           secret:
             secretName: service-account-creds
             containers:
         - name: esp
           image: gcr.io/endpoints-release/endpoints-runtime:1
           args: [
             "--http_port=8082",
             "--backend=127.0.0.1:8081",
             "--service=YOUR_SERVICE_NAME",
             "--rollout_strategy=managed",
             "--service_account_key=/etc/nginx/creds/service-account-creds.json"
           ]
           ports:
             - containerPort: 8080
           volumeMounts:
             - mountPath: /etc/nginx/creds
               name: service-account-creds
               readOnly: true
   

   Per informazioni sulle opzioni ESP utilizzate nell'esempio, vedi Opzioni di avvio di ESP.

4. Esegui il deployment di ESP in Kubernetes. Sostituisci YOUR_CONFIGURATION_FILE con il nome del file di configurazione Kubernetes.

   kubectl apply -f YOUR_CONFIGURATION_FILE

Invio di richieste

Per verificare che il file dell'account di servizio sia corretto e che le porte siano mappate correttamente, invia alcune richieste alla tua API e assicurati che le richieste vengano elaborate da ESP. Puoi visualizzare i log ESP eseguendo:

sudo docker logs esp

Gli esempi seguenti inviano richieste all'API di esempio. Se non utilizzi l'API di esempio, ti consigliamo di eseguire test simili.

Hai configurato il container ESP per ricevere richieste sulla porta 8082. Se invii una richiesta direttamente al server all'indirizzo http://localhost:8080, le richieste ignorano l'ESP. Ad esempio:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8080/echo

Risposta:

  {
    "message": "hello world"
  }

Quando invii una richiesta a http://localhost:8082 che passa attraverso ESP e non invii una chiave API, ESP rifiuta la richiesta. Ad esempio:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8082/echo

Risposta:

  {
   "code": 16,
   "message": "Method doesn't allow unregistered callers (callers without
    established identity). Please use API Key or other form of API consumer
    identity to call this API.",
   "details": [
    {
     "@type": "type.googleapis.com/google.rpc.DebugInfo",
     "stackEntries": [],
     "detail": "service_control"
    }
   ]
  }

Per testare l'API con una chiave API:

1. Crea una chiave API nella pagina Credenziali API.
   

   Vai alla pagina Credenziali

2. Fai clic su Crea credenziali, quindi seleziona Chiave API.

3. Copia la chiave, poi incollala nella seguente istruzione della variabile di ambiente:

   export KEY=AIza...
   

4. Invia una richiesta con la chiave:

   curl --request POST \
     --header "content-type:application/json" \
     --data '{"message":"hello world"}' \
     http://localhost:8082/echo?key=$KEY

   Viene visualizzata una risposta corretta:

   {
     "message": "hello world"
   }

Pulizia

Arresta e rimuovi il container Docker esp utilizzando lo strumento docker:

    sudo docker stop esp
    sudo docker rm esp

Passaggi successivi

• Scopri come aggiungere il supporto SSL a ESP