Esecuzione di Extensible Service Proxy localmente 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 cloud provider come Amazon Web Services (AWS) o su un cluster Kubernetes non presente in Google Cloud.

Puoi eseguire ESP su un computer Linux, macOS o macchina virtuale (VM). Microsoft Windows non è supportato. Puoi eseguire il deployment della tua applicazione ed 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:

Se hai bisogno di un'API per il test con ESP, puoi configurare ed eseguire il deployment del codice di esempio nella sezione Facoltativo: utilizzo di un'API di esempio. Se hai già configurato ed eseguito il deployment dell'API, vai a Creare un account di servizio.

Facoltativo: utilizzo di un'API di esempio

Questa sezione illustra come configurare ed eseguire il deployment della versione Python dell'esempio getting-started per endpoint in locale. Esegui i passaggi descritti in 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 la posizione GitHub del campione getting-started nel tuo linguaggio preferito. Segui le istruzioni del file README.md di esempio per l'esecuzione locale, quindi segui le istruzioni in questa sezione per configurare gli endpoint e per eseguire il deployment della configurazione degli endpoint.

Scarica il software richiesto

Se non hai ancora configurato un ambiente di sviluppo Python, consulta le istruzioni per configurare un ambiente di sviluppo Python. Assicurati di avere installato quanto segue:

Recupera il codice campione

  1. Clona il repository delle app di esempio sul tuo computer 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 del codice di esempio, apri il file di configurazione di 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 il tuo ID progetto di Google Cloud.

  3. Salva il file openapi.yaml.

Eseguire il deployment della configurazione di Endpoints

Per eseguire il deployment della configurazione degli endpoint, utilizza il comando gcloud endpoints services deploy. Questo comando utilizza Service Management per creare un servizio gestito.

  1. Aggiorna l'interfaccia a riga di comando gcloud:

    gcloud components update
  2. Assicurati che l'interfaccia a riga di comando gcloud (gcloud) sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud:

    gcloud auth login

    Seleziona un account nella nuova scheda del browser che si apre.

  3. Imposta il progetto predefinito sull'ID progetto:

    gcloud config set project YOUR-PROJECT-ID
    

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

  4. Esegui il deployment della configurazione:

    gcloud endpoints services deploy openapi.yaml

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

Man mano che crea e configura il servizio, Service Management trasmette informazioni al terminale. Puoi ignorare gli avvisi relativi ai percorsi del file openapi.yaml che non richiedono una chiave API. Al completamento, una riga simile alla seguente mostra l'ID di configurazione del servizio e il nome del servizio all'interno delle 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 servizio.

Avvio del server locale

  1. Crea una virtualenv, attivala 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 di terminale e usa curl per inviare una richiesta:

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

    L'API fa eco sul messaggio che lo invii e risponde con quanto segue:

    {
    "message": "hello world"
    }
    

Creazione di un account di servizio

Per fornire la gestione per la tua API, sia ESP sia ESPv2 richiedono i servizi in Service Infrastructure. Per chiamare questi servizi, ESP e ESPv2 devono utilizzare token di accesso. Quando esegui il deployment di ESP o ESPv2 in ambienti Google Cloud, come GKE o Compute Engine, ESP e ESPv2 ricevono i token di accesso per te tramite il servizio di metadati Google Cloud.

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

Puoi utilizzare Google Cloud Console o l'interfaccia a riga di comando di Google Cloud per creare l'account di servizio e il file della chiave privata:

console

  1. In Google Cloud Console, apri la pagina Account di servizio .

    Vai alla pagina Account di servizio

  2. Fai clic su Seleziona un progetto.
  3. Seleziona il progetto in cui è stata creata l'API e fai clic su Apri.
  4. Fai clic su + Crea account di servizio.
  5. Nel campo Nome account di servizio, inserisci il nome del tuo account di servizio.
  6. Fai clic su Crea.
  7. Fai clic su Continua.
  8. Fai clic su Fine.
  9. Fai clic sull'indirizzo email dell'account di servizio appena creato.
  10. Fai clic su Chiavi.
  11. Fai clic su Aggiungi chiave, quindi su Crea nuova chiave.
  12. Fai clic su Crea. Il file di una chiave JSON viene scaricato sul computer.

    Assicurati di archiviare il file della chiave in modo sicuro, perché può essere utilizzato per l'autenticazione come account di servizio. Puoi spostare e rinominare il file come preferisci.

  13. Fai clic su Chiudi.

gcloud

  1. Inserisci quanto segue per visualizzare gli ID progetto per i tuoi progetti Google Cloud:

    gcloud projects list
  2. Sostituisci PROJECT_ID nel comando seguente per impostare il progetto predefinito su quello in cui si trova l'API:

    gcloud config set project PROJECT_ID
  3. Assicurati che l'interfaccia a riga di comando di Google Cloud (gcloud) sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud:

    gcloud auth login

    Se hai più di un account, assicurati di scegliere quello che fa parte del progetto Google Cloud in cui si trova l'API. Se esegui gcloud auth list, l'account selezionato viene mostrato come account attivo per il progetto.

  4. Per creare un account di servizio, esegui il comando seguente e sostituisci SERVICE_ACCOUNT_NAME e My Service Account con il nome e il nome visualizzato che vuoi utilizzare:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
       --display-name "My Service Account"

    Il comando assegna un indirizzo email all'account di servizio nel seguente formato:

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Questo indirizzo email è obbligatorio nei comandi successivi.

  5. Crea un file della chiave dell'account di servizio:

    gcloud iam service-accounts keys create ~/service-account-creds.json \
       --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Aggiungi i ruoli IAM richiesti:

Questa sezione descrive le risorse IAM utilizzate da ESP e ESPv2 e i ruoli IAM richiesti dall'account di servizio collegato per accedere a tali risorse.

Configurazione del servizio endpoint

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

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

Utilizza il seguente comando gcloud per aggiungere il ruolo all'account di servizio associato 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 di endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com è l'account di servizio associato.

Cloud Trace

ESP e ESPv2 chiamano il servizio Cloud Trace per esportare Trace in un progetto. Questo progetto è chiamato progetto di tracciamento. In ESP, il progetto di tracciamento e il progetto che possiede la configurazione del servizio di endpoint sono gli stessi. In ESPv2, il progetto di tracciamento può essere specificato dal flag --tracing_project_id e presenta l'impostazione predefinita per il progetto di deployment.

ESP e ESPv2 richiedono il ruolo Agente Cloud Trace per abilitare Cloud Trace.

Utilizza il seguente comando gcloud per aggiungere il ruolo all'account di servizio associato:

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 è l'account di servizio associato. Per maggiori informazioni, consulta la pagina Cosa sono i ruoli e le autorizzazioni?

Per saperne di più 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 da utilizzare dipende da dove esegui il deployment del container ESP:

Negli esempi seguenti, l'opzione ESP --http_port funziona solo se per il servizio gRPC è configurata la transcodifica HTTP/JSON. Per ulteriori informazioni, consulta la sezione Transcodificare HTTP/JSON in gRPC.

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

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

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

Linux

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 \
    --http2_port=8083 \
    --backend=grpc://localhost:8080 \
    --service_account_key=/esp/service-account-creds.json
  

Mac OS

L'opzione Docker --net="host" non funziona su macOS. Devi invece eseguire una mappatura esplicita delle porte dall'host al container sostituendo --net="host" con --publish 8082:8082. Devi anche sostituire localhost con il nome speciale DNS solo macOS docker.for.mac.localhost. Per ulteriori informazioni, consulta Casi d'uso e soluzioni alternative nella documentazione di Docker.

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 \
  --http2_port=8083 \
  --backend=grpc://docker.for.mac.localhost:8080 \
  --service_account_key=/esp/service-account-creds.json
  

Un'altra piattaforma

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 \
  --http2_port=8083 \
  --backend=grpc://IP_Address:PORT \
  --service_account_key=/esp/service-account-creds.json
  

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

Opzione Descrizione
--detach Questa opzione Docker avvia il container in modalità scollegata, quindi viene eseguita in background.
--name="esp" Questa opzione Docker fornisce un nome di facile accesso per il container. Ad esempio, per visualizzare i log del container, puoi eseguire docker logs esp
--net="host" Questa opzione Docker indica che il container Docker utilizza la stessa configurazione di rete della macchina host, consentendo di effettuare chiamate a localhost sulla macchina host. Questa opzione non funziona per eseguire ESP in locale su macOS.
--publish=8082:8082 Per macOS quando vuoi eseguire ESP in locale, utilizza questa opzione Docker al posto di --net="host" per eseguire un mapping esplicito di porte dall'host al container.
--volume=
$HOME/Downloads:/esp
Questa opzione Docker mappa la tua directory $HOME/Downloads locale alla directory /esp nel container. Questa mappatura è utilizzata dall'opzione --service_account_key ESP.

Eseguire ESP in un container su un cluster Kubernetes

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

Per fare in modo che l'API sia 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, come app: my-api. Il servizio Kubernetes specifica il criterio di accesso per bilanciare il carico delle richieste del client alla porta del proxy.

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

  2. Esegui il comando seguente per creare un secret Kubernetes e montare il secret come volume 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",
              "--http2_port=8083",
              "--backend=grpc://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, consulta le opzioni di avvio ESP.

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

    kubectl apply -f YOUR_CONFIGURATION_FILE

Invio di richieste in corso...

Per verificare che il file dell'account di servizio sia corretto e che le porte siano mappate correttamente, invia alcune richieste all'API e assicurati che le richieste passino attraverso ESP. Per visualizzare i log ESP, esegui questo comando:

sudo docker logs esp

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

Hai configurato il container ESP in modo che riceva le richieste sulla porta 8082. Se invii una richiesta direttamente al server all'indirizzo http://localhost:8080, le richieste bypassano 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 a http://localhost:8082 una richiesta 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 e incollala nella seguente istruzione della variabile di ambiente:

    export KEY=AIza...
    
  4. Inviare una richiesta con la chiave:

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

    La risposta è corretta:

    {
      "message": "hello world"
    }

Pulizia

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

    sudo docker stop esp
    sudo docker rm esp
Se vuoi pulire la configurazione del servizio di cui è stato eseguito il deployment, consulta la sezione Eliminare un'API e istanze API.

Passaggi successivi