Extensible Service Proxy
(ESP) è un proxy basato su NGINX che consente a Cloud Endpoints di fornire funzionalità di gestione delle API. Puoi configurare l'ESP specificando le opzioni all'avvio del container ESP Docker. All'avvio, il container ESP esegue uno script denominato start_esp
, che scrive il file di configurazione NGINX utilizzando le opzioni specificate e avvia ESP.
Puoi specificare le opzioni di avvio ESP nel comando docker run
, ad esempio:
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --backend=YOUR_API_CONTAINER_NAME:8080
Se esegui il deployment di ESP in Kubernetes, devi specificare le opzioni di avvio nel file manifest del deployment nel campo args
, ad esempio:
containers: - name: esp image: gcr.io/endpoints-release/endpoints-runtime:1 args: [ "--http_port=8081", "--backend=127.0.0.1:8080", "--service=SERVICE_NAME", "--rollout_strategy=managed" ]
La tabella seguente descrive le opzioni di avvio di ESP.
Opzione breve | Opzione lunga | Description |
---|---|---|
-s SERVICE_NAME |
--service SERVICE_NAME |
Imposta il nome del servizio Endpoints. |
-R ROLLOUT_STRATEGY |
--rollout_strategy ROLLOUT_STRATEGY |
Disponibile in ESP versione 1.7.0 e successive. Specifica |
-v CONFIG_ID |
--version CONFIG_ID |
Imposta l'ID di configurazione del servizio che deve essere utilizzato da ESP. Per le informazioni necessarie per impostare questa opzione, consulta Recupero del nome del servizio e dell'ID di configurazione.
Quando specifichi --rollout_strategy=fixed o non includi l'opzione --rollout_strategy , devi includere l'opzione --version e specificare un ID di configurazione. In questo caso, ogni volta che esegui il deployment di una nuova configurazione di Endpoints, devi riavviare ESP con il nuovo ID di configurazione.
|
-p HTTP1_PORT |
--http_port HTTP1_PORT |
Imposta le porte esposte da ESP per le connessioni HTTP/1.x.1 |
-P HTTP2_PORT |
--http2_port HTTP2_PORT |
Imposta le porte esposte da ESP per le connessioni HTTP/2.1 |
-S SSL_PORT |
--ssl_port SSL_PORT |
Imposta le porte esposte da ESP per le connessioni HTTPS.1 |
-a BACKEND |
--backend BACKEND |
Imposta l'indirizzo per il server di backend dell'applicazione HTTP/1.x. Il valore predefinito dell'indirizzo di backend è http://127.0.0.1:8081 .Puoi specificare un prefisso di protocollo, ad esempio: --backend=https://127.0.0.1:8000 Se non specifichi un prefisso di protocollo, il valore predefinito è http .Se il tuo server di backend è in esecuzione su Compute Engine in un container, puoi specificare il nome del container e la porta, ad esempio: --backend=my-api-container:8000 |
-N STATUS_PORT |
--status_port STATUS_PORT |
Consente di impostare la porta dello stato (impostazione predefinita: 8090 ).
|
nessuno | --disable_cloud_trace_auto_sampling |
Per impostazione predefinita, ESP campiona 1 richiesta ogni 1000 o 1 richiesta ogni 10 secondi è abilitata con Cloud Trace. Imposta questo flag per disabilitare il campionamento automatico. Cloud Trace può comunque essere abilitato dalle intestazioni HTTP delle richieste con contesto di traccia, indipendentemente da questo valore del flag. Per ulteriori informazioni, consulta Tracciamento dell'API. |
-n NGINX_CONFIG |
--nginx_config NGINX_CONFIG |
Imposta la posizione per il file di configurazione NGINX personalizzato. Se specifichi questa opzione, ESP recupera il file di configurazione specificato e avvia immediatamente NGINX con il file di configurazione personalizzata fornito. Per saperne di più, consulta Utilizzo di una configurazione nginx personalizzata per GKE. |
-k SERVICE_ACCOUNT_KEY |
--service_account_key SERVICE_ACCOUNT_KEY |
Imposta il file JSON delle credenziali dell'account di servizio. Se fornito, ESP utilizza l'account di servizio per generare un token di accesso per chiamare le API Service Infrastructure. L'unica volta che devi specificare questa opzione è quando ESP è in esecuzione su piattaforme diverse da Google Cloud, come il tuo desktop locale, Kubernetes o un altro cloud provider. Per ulteriori informazioni, consulta Creazione di un account di servizio. |
-z HEALTHZ_PATH |
--healthz HEALTHZ_PATH |
Definisci un endpoint per il controllo di integrità sulle stesse porte del backend dell'applicazione. Ad esempio, -z healthz fa sì che ESP restituisca il codice 200 per la località /healthz , anziché inoltrare la richiesta al backend. Valore predefinito: non utilizzato.
|
nessuno | --dns DNS_RESOLVER |
Specifica un resolver DNS. Ad esempio, --dns 169.254.169.254 utilizza il server dei metadati Google Cloud come resolver DNS. Se non specificato, il valore predefinito è 8.8.8.8 .
|
1 Queste porte sono facoltative e devono essere distinte tra loro.
Se non specifichi alcuna opzione di porta, ESP accetta le connessioni HTTP/1.x sulla porta 8080
.
Per le connessioni HTTPS, ESP prevede che i secret TLS si trovino in /etc/nginx/ssl/nginx.crt
e /etc/nginx/ssl/nginx.key
.
Chiamate da riga di comando di esempio
I seguenti esempi mostrano come utilizzare alcuni argomenti della riga di comando:
Per avviare l'ESP a gestire le richieste in arrivo sulla porta HTTP/1.x 80
e sulla porta HTTPS 443
e inviare le richieste al backend dell'API all'indirizzo 127.0.0.1:8000
:
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --http_port=80 \ --ssl_port=443 \ --backend=127.0.0.1:8000
Per avviare ESP con una configurazione NGINX personalizzata utilizzando il file delle credenziali dell'account di servizio per recuperare la configurazione del servizio e connetterti al controllo di servizio:
sudo docker run \ --detach \ --volume=$HOME/Downloads:/esp \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --service_account_key=/esp/serviceaccount.json \ --nginx_config=/esp/nginx.conf
Tieni presente che devi utilizzare i flag Docker --volume
o --mount
per montare il file JSON contenente la chiave privata per l'account di servizio e il file di configurazione NGINX personalizzato come volumi all'interno del container Docker di ESP. L'esempio precedente mappa la directory $HOME/Downloads
sul computer locale alla directory esp
nel container. Quando salvi il file della chiave privata per l'account di servizio, in genere questo viene scaricato nella directory Downloads
. Se vuoi, puoi copiare il file della chiave privata in un'altra directory. Consulta Gestire i dati in Docker per ulteriori informazioni.
Aggiunta del supporto CORS a ESP
Consulta la sezione Assistenza CORS per una descrizione delle opzioni di assistenza disponibili. Questa sezione descrive l'utilizzo dei flag di avvio ESP per supportare CORS.
Per abilitare il supporto CORS in ESP, includi l'opzione --cors_preset
e impostala su basic
o cors_with_regex
. Se includi
--cors_preset=basic
o --cors_preset=cors_with_regex
, ESP:
- Presuppone che tutti i percorsi di località abbiano lo stesso criterio CORS.
- Risponde sia a richieste semplici sia a richieste preflight
HTTP OPTIONS
. - Memorizza nella cache il risultato della richiesta
OPTIONS
preflight per un massimo di 20 giorni (1728000 secondi). Imposta le intestazioni della risposta sui seguenti valori:
Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization Access-Control-Expose-Headers: Content-Length,Content-Range
Per eseguire l'override del valore predefinito di Access-Control-Allow-Origin
, specifica una delle seguenti opzioni:
Opzione | Description |
---|---|
--cors_allow_origin |
Utilizzalo con --cors_preset=basic per impostare
Access-Control-Allow-Origin su un'origine specifica.Esempio:
--cors_preset=basic
|
--cors_allow_origin_regex |
Da utilizzare con --cors_preset=cors_with_regex . Consente di utilizzare un'espressione regolare per impostare Access-Control-Allow-Origin .Esempio:
--cors_preset=cors_with_regex
L'espressione regolare nell'esempio precedente consente un'origine con
|
Dopo aver impostato --cors_preset=basic
o --cors_preset=cors_with_regex
per abilitare CORS, puoi eseguire l'override dei valori predefiniti delle altre intestazioni della risposta specificando una o più delle seguenti opzioni:
Opzione | Description |
---|---|
--cors_allow_methods |
Imposta
Access-Control-Allow-Methods
sui metodi HTTP specificati. Specifica i metodi HTTP come stringa con ciascun metodo HTTP separato da una virgola.Esempio:
--cors_preset=basic
|
--cors_allow_headers |
Imposta Access-Control-Allow-Headers sulle intestazioni HTTP specificate. Specifica le intestazioni HTTP come stringa con ogni intestazione HTTP separata da una virgola.Esempio:
--cors_preset=basic
|
--cors_allow_credentials |
Include l'intestazione Access-Control-Allow-Credentials con il valore true nelle risposte. Per impostazione predefinita, l'intestazione Access-Control-Allow-Credentials non è inclusa nelle risposte.Esempio:
--cors_preset=basic
|
--cors_expose_headers |
Imposta
Access-Control-Expose-Headers
sulle intestazioni specificate. Specifica quali intestazioni possono essere mostrate come parte della risposta sotto forma di stringa, con ogni intestazione separata da una virgola.Esempio:
--cors_preset=basic
|
Se le opzioni di avvio di ESP CORS non soddisfano le esigenze della tua applicazione, puoi creare un file nginx.conf
personalizzato con il supporto CORS richiesto dalla tua applicazione. Per maggiori informazioni, consulta
Creare un elemento nginx.conf
personalizzato per supportare CORS.
Passaggi successivi
Scopri di più su:
- Deployment di ESP e del backend dell'API in Google Cloud
- Esecuzione di ESP in locale o su un'altra piattaforma
- Lo script
start_esp
su GitHub