Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Esecuzione di ESP in locale o su un'altra piattaforma

OpenAPI | gRPC

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, come Amazon Web Services (AWS), o su un cluster Kubernetes che non è 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 di ESP sullo stesso host o su host diversi. L'hosting di un'istanza locale di ESP ti consente di:

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

Prerequisiti

Come punto di partenza, questa pagina presuppone che:

Hai installato Docker, se esegui il deployment del container ESP in locale o su una VM. Per saperne di più, consulta Installa Docker.
Hai eseguito il deployment di un'API in locale 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) Utilizzare un'API di esempio. Se hai già configurato ed eseguito il deployment dell'API, vai a Creare un account di servizio.

(Facoltativo) Utilizzare un'API di esempio

Questa sezione ti guida nella configurazione e nel deployment in locale della versione Python di the getting-started per Endpoints esempio. Esegui i passaggi descritti in questa sezione solo se non hai 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 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.

Scarica il software richiesto

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

Recupera il codice campione

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

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

Passa alla directory che contiene il codice campione:
```
cd python-docs-samples/endpoints/getting-started
```

Configura endpoint

Nella directory del 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"

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

Importante: deve essere lo stesso progetto selezionato in Creazione del service account.
Salva il file openapi.yaml.

Esegui il deployment della configurazione di Endpoints

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

Aggiorna gcloud CLI:
```
gcloud components update
```
Assicurati che gcloud CLI (gcloud) sia autorizzato ad accedere ai tuoi dati e servizi su Google Cloud:
```
gcloud auth login
```
Nella nuova scheda del browser visualizzata, seleziona un account.
Imposta il progetto predefinito sull'ID del tuo progetto:
```
gcloud config set project YOUR-PROJECT-ID
```
Sostituisci YOUR-PROJECT-ID con l'ID progetto del Google Cloud progetto specificato nel file openapi.yaml.

Esegui il deployment della configurazione:

gcloud endpoints services deploy openapi.yaml

Service Management utilizza il testo 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.

Durante la creazione e la configurazione del servizio, Service Management visualizza le informazioni nel terminale. Puoi ignorare tranquillamente gli avvisi sui percorsi presenti 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.

Avvia il server locale

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

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

Avvia il server:
```
python main.py
```

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 ripete il messaggio che le invii e risponde con quanto segue:

{
"message": "hello world"
}

Crea 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 i token di accesso. Quando esegui il deployment di ESP o ESPv2 in Google Cloud ambienti come GKE, Compute Engine o l'ambiente flessibile di App Engine, ESP ed ESPv2 ottengono i token di accesso tramite il Google Cloud servizio di metadati.

Quando esegui il deployment di ESP o ESPv2 in un ambiente non-Google Cloud ambiente, ad esempio il computer locale, un cluster Kubernetes on-premise o un altro provider di servizi cloud, devi fornire un file JSON dell'account di servizio contenente 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 il file dell'account di servizio e della chiave privata, puoi utilizzare la Google Cloud console o Google Cloud CLI:

Console

Nella Google Cloud console, apri la pagina Account di servizio .
Vai alla pagina Account di servizio
Fai clic su Seleziona un progetto.
Seleziona il progetto in cui è stata creata l'API e fai clic su Apri.
Fai clic su + Crea account di servizio.
Nel campo Nome account di servizio, inserisci il nome del tuo account di servizio.
Fai clic su Crea.
Fai clic su Continua.
Fai clic su Fine.
Fai clic sull'indirizzo email del account di servizio appena creato.
Fai clic su Chiavi.
Fai clic su Aggiungi chiave, poi su Crea nuova chiave.
Fai clic su Crea. Un file della chiave JSON viene scaricato sul computer.

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

`gcloud`

Inserisci quanto segue per visualizzare gli ID progetto dei tuoi Google Cloud progetti:
```
gcloud projects list
```
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
```
Importante: devi creare il account di servizio nello stesso progetto in cui si trova l'API.
Assicurati che Google Cloud CLI (gcloud) sia autorizzato ad accedere ai tuoi dati e servizi su Google Cloud:
```
gcloud auth login
```
Se hai più di un account, assicurati di scegliere l'account che si trova nel Google Cloud progetto in cui si trova l'API. Se esegui gcloud auth list, l'account selezionato viene visualizzato come account attivo per il progetto.
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 per il account di servizio nel seguente formato:

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Questo indirizzo email è obbligatorio nei comandi successivi.

Crea un file della chiave del 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 ed ESPv2 e i ruoli IAM richiesti per l'accesso a queste risorse da parte del account di servizio 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 ed ESP ed ESPv2 richiedono il ruolo di controller del servizio per accedervi.

Il ruolo IAM si trova nella configurazione del servizio endpoint, non nel progetto. Un progetto può avere più configurazioni del 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 è il account di servizio collegato.

Cloud Trace

ESP ed 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 proprietario della configurazione del servizio endpoint sono gli stessi. In ESPv2, il progetto di tracciamento può essere specificato dal flag --tracing_project_id e per impostazione predefinita è 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 saperne di più, consulta Che cosa sono ruoli e autorizzazioni?

Per saperne di più sui comandi, consulta gcloud iam service-accounts.

Esegui ESP in un container

Questa sezione descrive come eseguire il deployment del container ESP. La procedura da utilizzare dipende dalla posizione in cui esegui il deployment del container ESP:

Esegui ESP in un container Docker in locale o su un'altra piattaforma
Esegui ESP in un container su un cluster Kubernetes

Esegui ESP in un container Docker in locale o su un'altra piattaforma

Rinomina il file JSON contenente la chiave privata del 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.
Nel seguente comando docker run, 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 \
  --backend=localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

mac OS

L'opzione Docker --net="host" non funziona su macOS. Devi invece eseguire il mapping esplicito delle porte dall'host al container sostituendo --net="host" con --publish 8082:8082. Devi anche sostituire localhost con il nome DNS speciale solo per macOS docker.for.mac.localhost. Per saperne di più, 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 \
  --backend=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 \
  --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, consulta Opzioni di avvio di ESP.

Opzione	Descrizione
`--detach`	Questa opzione Docker avvia il container in modalità detached, quindi viene eseguito 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, consentendogli 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 anziché `--net="host"` per eseguire il mapping esplicito delle porte dall'host al container.
`--volume=` `$HOME/Downloads:/esp`	Questa opzione Docker mappa la directory locale `$HOME/Downloads` alla directory `/esp` nel container. Questo mapping viene utilizzato dall'opzione ESP `--service_account_key`.

Esegui ESP in un container su un cluster Kubernetes

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

Per gestire l'API 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 la policy di accesso per bilanciare il carico delle richieste client alla porta del proxy.

Rinomina il file JSON contenente la chiave privata del 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.
Esegui il comando seguente per creare un secret Kubernetes e montarlo come volume Kubernetes.
```
kubectl create secret generic service-account-creds \
  --from-file=$HOME/Downloads/service-account-creds.json
```
Se l'operazione ha esito positivo, viene visualizzato il seguente messaggio: secret "service-account-creds" created

Nel file di configurazione di Kubernetes, aggiungi quanto segue, sostituendo YOUR_APP_NAME con il nome dell'API e YOUR_SERVICE_NAME con il nome del 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, consulta Opzioni di avvio di ESP.

Esegui 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
```

Invia richieste

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. 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 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