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 che non si trova su Google Cloud.
Puoi eseguire ESP su un computer o una macchina virtuale Linux o macOS (VM). Microsoft Windows non è supportato. Puoi eseguire il deployment della tua applicazione ESP sullo stesso host o su host diversi. Ospita una sede locale di ESP 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 metriche e log vengono visualizzati in Endpoint > pagina Servizi come previsto.
Prerequisiti
Per iniziare, questa pagina presuppone che:
Se stai eseguendo il deployment dell'ESP, hai installato Docker in locale o a una VM. Consulta: Installa Docker per ulteriori informazioni.
Hai eseguito il deployment di un'API localmente o su un host raggiungibile all'host in cui esegui ESP.
Avere configurato Cloud Endpoints e ha eseguito il deployment della configurazione per creare un servizio gestito per l'API.
Se hai bisogno di un'API per i test con ESP, puoi configurare Esegui il deployment del codice campione nella sezione (Facoltativo) Utilizzo di un'API di esempio . Se hai già configurato ed eseguito il deployment dell'API, passa a Creazione di un account di servizio.
(Facoltativo) Utilizzo di un'API di esempio
Questa sezione illustra la configurazione e il deployment della versione Python
il
getting-started
per Endpoints
campionare localmente. Segui la procedura descritta in questa sezione solo se non disponi di un'API per
con ESP.
L'esempio getting-started
di Cloud Endpoints è disponibile in altre lingue.
Consulta la pagina Samples per GitHub
posizione del campione getting-started
nella tua lingua preferita. Segui le
istruzioni nel file README.md
di esempio per l'esecuzione in locale:
segui le istruzioni di questa sezione per configurare gli endpoint
ed eseguire il deployment della configurazione di Endpoints.
Ottieni il software richiesto
Se non hai ancora configurato un ambiente di sviluppo Python, consulta Configurazione di un ambiente di sviluppo Python come guida. Marca assicurati di aver installato quanto segue:
recupera il codice campione
Clona il repository dell'app di esempio nella 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
gcloud endpoints services deploy
. Questo comando utilizza
Gestione del servizio
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
Seleziona un account nella nuova scheda del browser che si apre.
Imposta il progetto predefinito sul tuo ID progetto:
gcloud config set project YOUR-PROJECT-ID
Sostituisci
YOUR-PROJECT-ID
con l'ID progetto del al progetto Google Cloud specificato nel fileopenapi.yaml
.Esegui il deployment della configurazione:
gcloud endpoints services deploy openapi.yaml
Service Management utilizza il testo che hai specificato nel campo host
in
il file openapi.yaml
per creare un nuovo servizio Endpoints
il nome echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog
(se non esiste) e poi configura il servizio in base
File di configurazione OpenAPI.
Durante la creazione e la configurazione del servizio, Service Management genera
le informazioni al terminale. Puoi ignorare tranquillamente gli avvisi
sui percorsi nel file openapi.yaml
che non richiedono una chiave API. Attivato
completamento riuscito, una riga simile alla seguente mostra il 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, mentre
echo-api.endpoints.example-project-12345.cloud.goog
è il nome del servizio.
Avvio del server locale in corso...
Crea un
virtualenv
, attivalo e installa l'applicazione delle dipendenze.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 lo invii e risponde con seguenti:
{ "message": "hello world" }
Creazione di un account di servizio
Per fornire la gestione dell'API, sia ESP sia 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 ambienti Google Cloud, come GKE, Compute Engine o l'ambiente flessibile di App Engine ambiente, ESP ed ESPv2 ottengono i token di accesso per te tramite servizio di metadati di Google Cloud.
Quando esegui il deployment di ESP o ESPv2 in un ambiente non Google Cloud, ad esempio come desktop locale, un cluster Kubernetes on-premise o un altro devi fornire un file JSON dell'account di servizio. che contiene una chiave privata. ESP ed ESPv2 utilizzano account di servizio generare token di accesso per chiamare i servizi necessari per gestire l'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 del 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. Sul computer viene scaricato un file della chiave JSON.
Assicurati di archiviare il file della chiave in modo sicuro, perché può essere utilizzato per di autenticarsi con il proprio account di servizio. Puoi spostare e rinominare questo file come desideri.
Fai clic su Chiudi.
gcloud
Inserisci il codice seguente per visualizzare gli ID progetto per il tuo Progetti Google Cloud:
gcloud projects list
Sostituisci PROJECT_ID nel seguente comando per impostare il valore predefinito progetto a quello in cui si trova la tua API:
gcloud config set project PROJECT_ID
Assicurati che Google Cloud CLI (
gcloud
) sia autorizzato ad accedere al tuo di dati e servizi su Google Cloud:gcloud auth login
Se hai più di un account, assicurati di scegliere quello con cui fa parte del progetto Google Cloud in cui si trova l'API. Se esegui
gcloud auth list
, l'account che hai selezionato risulta attivo per il progetto.Per creare un account di servizio, esegui questo 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 di chiavi per l'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'account di servizio collegato per accedere a queste 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, mentre ESP ed ESPv2 necessitano Controller di 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 al servizio 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
Chiamata ESP ed ESPv2
Cloud Trace per
esportare Trace in un progetto. Questo progetto è chiamato tracciamento
progetto. In ESP, il progetto di tracciamento e il progetto proprietario
la configurazione del servizio endpoint
è la stessa. In ESPv2,
il progetto di tracciamento può essere specificato dal flag --tracing_project_id
, e
il valore predefinito del progetto di deployment.
ESP ed ESPv2 richiedono l'agente Cloud Trace per abilitare Cloud Trace.
Utilizza il seguente comando gcloud per aggiungere il ruolo al 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 del progetto di tracciamento
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
è l'account di servizio collegato.
Per ulteriori informazioni, vedi
Cosa sono i ruoli e le autorizzazioni?
Consulta:
gcloud iam service-accounts
per ulteriori informazioni sui comandi.
Esecuzione di ESP in un container
Questa sezione descrive come eseguire il deployment del container ESP. La che utilizzi dipende da dove esegui 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
Rinomina il file JSON che contiene la chiave privata per l'account di servizio in
service-account-creds.json
e copiarlo in$HOME/Downloads/
, se lo fosse scaricati in un'altra directory. In questo modo, il nome completo del percorso per--service_account_key
nel seguente comandodocker run
.Nel seguente comando
docker run
, sostituisciYOUR_SERVICE_NAME
con 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 una mappatura delle porte esplicita dall'host al container
sostituzione di --net="host"
con --publish 8082:8082
. Tu
Inoltre, devi sostituire localhost
con il nome DNS speciale solo per macOS
docker.for.mac.localhost
. Consulta:
Casi d'uso e soluzioni alternative
per ulteriori informazioni
nella documentazione 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 tabella seguente descrive le opzioni Docker utilizzate nei comandi precedenti. Per informazioni sulle opzioni ESP utilizzate nell'esempio, vedi Opzioni di avvio di ESP.
Opzione | Descrizione |
---|---|
--detach
|
Questa opzione Docker avvia il container in modalità scollegata, in modo che venga eseguito sfondo. |
--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 lo stesso configurazione di rete come macchina host, consentendole di effettuare chiamate localhost sul computer host. Questa opzione non funziona ESP in locale su macOS. |
--publish=8082:8082
|
Per macOS quando vuoi eseguire ESP in locale, utilizza questo Docker
in sostituzione
di --net="host" per eseguire una mappatura esplicita delle porte dall'host a
containerizzato.
|
--volume= $HOME/Downloads:/esp
|
Questa opzione Docker mappa la directory $HOME/Downloads locale a
nella directory /esp nel container. Questa mappatura viene utilizzata
--service_account_key Opzione ESP. |
Esegui ESP in un container su un cluster Kubernetes
Questa sezione descrive come eseguire il deployment di ESP in un cluster Kubernetes non su Google Cloud.
Per fare in modo che l'API sia gestita da Endpoints, esegui il deployment
Container ESP
allo stesso pod Kubernetes del tuo
container API. L'insieme di pod che eseguono ESP e la tua API
raggruppate 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 al proxy
una porta.
Rinomina il file JSON che contiene la chiave privata per l'account di servizio in
service-account-creds.json
e copiarlo in$HOME/Downloads/
, se lo fosse scaricati in un'altra directory. In questo modo, il nome completo del percorso nel passaggio successivo.Esegui questo comando per creare un Kubernetes secret e montare il secret come Kubernetes volume.
kubectl create secret generic service-account-creds \ --from-file=$HOME/Downloads/service-account-creds.json
Se l'operazione riesce, 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 della tua API eYOUR_SERVICE_NAME
con 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, vedi Opzioni di avvio di ESP.
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 passano attraverso l'ESP. Puoi visualizzare i log ESP in esecuzione:
sudo docker logs esp
I seguenti esempi inviano richieste all'API di esempio. Se non utilizzi di esempio, consigliamo di eseguire test simili.
Hai configurato il container ESP in modo da ricevere le richieste su
porta 8082
. Se invii una richiesta direttamente al server su
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 a http://localhost:8082
una richiesta che viene inviata
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:
Crea una chiave API nella pagina Credenziali API.
Fai clic su Crea credenziali, quindi seleziona Chiave API.
Copia la chiave, quindi incollala nella seguente 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 corretta:
{ "message": "hello world" }
esegui la pulizia
Arresta e rimuovi il container Docker esp
utilizzando lo strumento docker
:
Se vuoi eseguire la pulizia della configurazione del servizio di cui hai eseguito il deployment, consulta Eliminazione di un'API e di istanze API.sudo docker stop esp
sudo docker rm esp