Questa pagina spiega come configurare ed eseguire un'istanza di Extensible Service Proxy (ESP) su un computer locale, su un altro provider cloud, come Amazon Web Services (AWS), o su un cluster Kubernetes 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 dell'ESP sullo stesso host o su host diversi. L'hosting di un'istanza locale di ESP ti consente di:
- Prova ESP prima di eseguirlo in 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 in una VM. Per ulteriori informazioni, consulta Installare Docker.
Hai eseguito il deployment di un'API localmente o su un host raggiungibile dall'host su 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 e eseguire il deployment del codice campione nella sezione Facoltativo: utilizzo di un'API di esempio. Se hai già configurato e disegnato l'API, vai a Creare un account di servizio.
(Facoltativo) Utilizzo di un'API di esempio
Questa sezione illustra la procedura per configurare ed eseguire il deployment della versione Python dell'esempio di getting-started
per Endpoints localmente. Esegui i passaggi descritti in questa sezione solo se non hai un'API per il testing con l'ESP.
L'esempio getting-started
di Cloud Endpoints è disponibile in altre lingue.
Consulta la pagina Samples per la posizione su GitHub dell'esempio getting-started
nella lingua che preferisci. Segui le istruzioni nel file README.md
dell'esempio per l'esecuzione locale, quindi segui le istruzioni in questa sezione per configurare Endpoints e per eseguire il deployment della configurazione di Endpoints.
Ottenere il software necessario
Se non hai ancora configurato un ambiente di sviluppo Python, consulta la sezione Configurazione di un ambiente di sviluppo Python per indicazioni. Assicurati di avere 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 di esempio:
cd python-docs-samples/endpoints/getting-started
Configura endpoint
Nella directory codice campione, apri il file di configurazione
openapi.yaml
.Nel campo
host
, sostituisciYOUR-PROJECT-ID
con il tuo ID progetto Google Cloud.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
Gestione dei servizi
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 che si apre, seleziona un account.
Imposta il progetto predefinito sul tuo ID progetto:
gcloud config set project YOUR-PROJECT-ID
Sostituisci
YOUR-PROJECT-ID
con l'ID del progetto Google Cloud specificato nel fileopenapi.yaml
.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 configura il servizio in base al
file di configurazione OpenAPI.
Durante la creazione e la configurazione del servizio, Service Management visualizza informazioni sul terminale. Puoi ignorare tranquillamente gli avvisi relativi ai 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
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 usa
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 le hai inviato 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 Infrastruttura di servizi. Per chiamare questi servizi, ESP ed ESPv2 devono utilizzare token di accesso. Quando esegui il deployment di ESP o ESPv2 in ambienti Google Cloud, come GKE, Compute Engine o l'ambiente flessibile di App Engine, ESP ed ESPv2 ottengono i token di accesso per te tramite il servizio di metadati di Google Cloud.
Quando esegui il deployment di ESP o ESPv2 in un ambiente non Google Cloud, come il tuo computer locale, un cluster Kubernetes on-premise o un altro fornitore cloud, devi fornire un file JSON dell'account di servizio contenente una chiave privata. ESP ed ESPv2 utilizzano l'account di servizio per generare token di accesso per chiamare i servizi di cui ha bisogno per gestire la tua API.
Puoi utilizzare la console Google Cloud o Google Cloud CLI per creare l'account di servizio e il file della chiave privata:
Console
- Nella console Google Cloud, apri la 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 dell'account di servizio.
- Fai clic su Crea.
- Fai clic su Continua.
- Fai clic su Fine.
- Fai clic sull'indirizzo email dell'account di servizio appena creato.
- Fai clic su Chiavi.
- Fai clic su Aggiungi chiave, quindi 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 account di servizio. Puoi spostare e rinominare il file come preferisci.
Fai clic su Chiudi.
gcloud
Inserisci quanto segue per visualizzare gli ID progetto per i tuoi progetti Google Cloud:
gcloud projects list
Sostituisci PROJECT_ID nel seguente comando per impostare il progetto predefinito su quello in cui si trova l'API:
gcloud config set project PROJECT_ID
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 quello che si trova nel progetto Google Cloud 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 seguente comando 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 l'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 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 per l'accesso di questo account di servizio alle risorse.
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 Responsabile controllo servizi per accedervi.
Il ruolo IAM si trova nella configurazione del servizio 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 endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
è l'account di servizio associato.
Cloud Trace
ESP ed ESPv2 chiamano il servizio
Cloud Trace per
esportare la traccia in un progetto. Questo progetto è chiamato progetto di monitoraggio. In ESP, il progetto di monitoraggio e il progetto proprietario della configurazione del servizio endpoint sono gli stessi. In ESPv2, il progetto di monitoraggio può essere specificato tramite il flag --tracing_project_id
e per impostazione predefinita corrisponde al progetto di implementazione.
ESP ed ESPv2 richiedono il ruolo Agente Cloud Trace per abilitare Cloud Trace.
Utilizza il seguente comando gcloud per aggiungere il ruolo all'account di servizio 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 monitoraggio
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
è l'account di servizio associato.
Per ulteriori informazioni, consulta
Che cosa sono i ruoli e le autorizzazioni?
Per ulteriori informazioni sui comandi, consulta
gcloud iam service-accounts
.
Eseguire ESP in un contenitore
Questa sezione descrive come eseguire il deployment del contenitore ESP. La procedura da utilizzare dipende da dove viene eseguito il deployment del contenitore ESP:
- Eseguire ESP in un contenitore Docker in locale o su un'altra piattaforma
- Eseguire ESP in un contenitore su un cluster Kubernetes
Esecuzione di ESP in un container Docker in locale o su un'altra piattaforma
Rinomina il file JSON contenente 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 valore di--service_account_key
nel seguente comandodocker run
.Nel seguente comando
docker run
, sostituisciYOUR_SERVICE_NAME
con il nome del 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 la mappatura esplicita delle porte dall'host al contenitore, sostituendo --net="host"
con --publish 8082:8082
. Devi anche sostituire localhost
con il nome DNS speciale solo per macOS docker.for.mac.localhost
. Per ulteriori informazioni, consulta la sezione Casi d'uso e soluzioni alternative della 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 contenitore in modalità disconnessa, quindi viene eseguito in background. |
--name="esp"
|
Questa opzione Docker fornisce un nome di facile accesso per il contenitore.
Ad esempio, per visualizzare i log del contenitore, 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 localmente su macOS. |
--publish=8082:8082
|
Per macOS, se vuoi eseguire ESP localmente, utilizza questa opzione Docker invece di --net="host" per eseguire la mappatura esplicita delle porte dall'host al container.
|
--volume= $HOME/Downloads:/esp
|
Questa opzione Docker mappa la directory $HOME/Downloads locale alla directory /esp nel contenitore. Questa mappatura viene utilizzata dall'opzione ESP --service_account_key . |
Esegui ESP in un contenitore 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 consentire la gestione dell'API da parte di Endpoints, esegui il deployment del
contenuto ESP
nello stesso pod Kubernetes del
contenuto dell'API. L'insieme di pod che eseguono ESP e la tua API sono agrupati 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 del client sulla porta del proxy.
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 nel passaggio successivo.Esegui il seguente comando per creare un secret di Kubernetes e montarlo 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
Nel file di configurazione di Kubernetes, aggiungi quanto segue, sostituendo
YOUR_APP_NAME
con il nome dell'API eYOUR_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 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 all'API e assicurati che passino per l'ESP. Puoi visualizzare i log dell'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 contenitore ESP per ricevere richieste sulla porta 8082
. Se invii una richiesta direttamente al server all'indirizzo
http://localhost:8080
, le richieste bypassano 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 per l'ESP e non invii una chiave API, l'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:
Crea una chiave API nella pagina Credenziali API.
Fai clic su Crea credenziali e poi seleziona Chiave API.
Copia la chiave e incollala nella seguente istruzione della variabile di ambiente:
export KEY=AIza...
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 di esito positivo:
{ "message": "hello world" }
Pulizia
Arresta e rimuovi il container Docker esp
utilizzando lo strumento docker
:
sudo docker stop esp
sudo docker rm esp