Opzioni di avvio di Extensible Service Proxy

Extensible Service Proxy (ESP) è una Proxy basato su NGINX che consente Cloud Endpoints per fornire funzionalità di gestione delle API. Configura ESP specificando le opzioni quando avvii il container Docker ESP. Quando il contenitore ESP si avvia, viene eseguito uno script chiamato start_esp, che scrive il file di configurazione di NGINX utilizzando le opzioni specificate e avvia ESP.

Specifica le opzioni di avvio di 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, specificherai la fase di avvio opzioni nel file manifest di 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 Descrizione
-s SERVICE_NAME --service SERVICE_NAME Imposta il nome del servizio Endpoints.
-R ROLLOUT_STRATEGY --rollout_strategy ROLLOUT_STRATEGY

Disponibile in ESP 1.7.0 e versioni successive. Specifica una delle seguenti opzioni: managed o fixed. L'opzione --rollout_strategy=managed configura ESP in modo che utilizzi la configurazione del servizio di cui è stato eseguito il deployment più recente. Quando specificare questa opzione, fino a 5 minuti dopo il deployment di un nuovo servizio configurazione, ESP rileva la modifica e inizia automaticamente a utilizzarla. Ti consigliamo di specificare questa opzione anziché un ID configurazione specifico da utilizzare per ESP. Non è necessario specificare l'opzione --version quando imposti --rollout_strategy su managed.
-v CONFIG_ID --version CONFIG_ID Imposta l'ID configurazione del servizio che deve essere utilizzato da ESP. Consulta: Recupero del nome del servizio e l'ID configurazione per le informazioni necessarie per impostare questa opzione. Se specifichi --rollout_strategy=fixed o non includi l'opzione --rollout_strategy, devi includere i campi --version e specifica un ID configurazione. In questo caso, ogni volta che esegui il deployment di una nuova configurazione di Endpoints, riavvia 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 del server di backend dell'applicazione HTTP/1.x. Il valore predefinito per l'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, specifica il nome del container e la porta, ad esempio:
--backend=my-api-container:8000
Per specificare che il backend accetta il traffico gRPC, aggiungi il prefisso grpc://. Ad esempio:
--backend=grpc://127.0.0.1:8000
Se il server di backend è in esecuzione su Compute Engine in un contenitore e accetta traffico gRPC, puoi specificare il nome del contenitore e la porta, ad esempio:
--backend=grpc://my-api-container:8000
-N STATUS_PORT --status_port STATUS_PORT Imposta la porta di stato (valore predefinito: 8090).
nessuno --disable_cloud_trace_auto_sampling Per impostazione predefinita, ESP campiona una richiesta ogni 1000 o 1 richiesta richiesta ogni 10 secondi sia abilitata con Cloud Trace. Imposta questo flag per disattivare questo campionamento automatico. Cloud Trace può comunque essere attivato dalle intestazioni HTTP della richiesta con il contesto della traccia, indipendentemente dal valore di questo flag. Consulta: Tracciamento dell'API per ulteriori informazioni.
-n NGINX_CONFIG --nginx_config NGINX_CONFIG Imposta la posizione del file di configurazione NGINX personalizzato. Se specifichi questa opzione, ESP recupera il file di configurazione specificato avvia immediatamente NGINX con il file di configurazione personalizzato fornito. Per saperne di più, consulta Utilizzare una configurazione nginx personalizzata per GKE informazioni.
-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. Devi specificare questa opzione solo quando ESP viene in esecuzione su piattaforme diverse da Google Cloud, come desktop locale, Kubernetes o un altro cloud provider. Per ulteriori informazioni, vedi Creare un account di servizio.
-z HEALTHZ_PATH --healthz HEALTHZ_PATH Definisci un endpoint di controllo di integrità sulle stesse porte del backend dell'applicazione. Ad esempio, -z healthz fa in modo che l'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 di 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 l'una dall'altra. Se non specifichi alcuna opzione di porta, l'ESP accetta le connessioni HTTP/1.x sulla porta 8080. Per le connessioni HTTPS, ESP si aspetta che i secret TLS si trovino in /etc/nginx/ssl/nginx.crt e /etc/nginx/ssl/nginx.key.

Esempi di chiamate dalla riga di comando

I seguenti esempi mostrano come utilizzare alcuni degli argomenti della riga di comando:

Per avviare ESP in modo che gestisca le richieste in arrivo sulla porta HTTP/1.x 80 e la porta HTTPS 443 e invia 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 di controllo dei servizi:

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 contenitore Docker di ESP. L'esempio precedente mappa la directory $HOME/Downloads sul computer locale alla directory esp nel contenitore. Quando salvi il file della chiave privata per l'account di servizio, in genere viene scaricato nella directory Downloads. Se vuoi, puoi copiare il file della chiave privata in un'altra directory. Per saperne di più, consulta Gestire i dati in Docker.

Aggiunta del supporto CORS a ESP

Fai riferimento a Assistenza CORS per una descrizione delle opzioni di supporto CORS disponibili. In questa sezione viene descritto l'utilizzo dei flag di avvio ESP per supportare CORS.

Per attivare il supporto CORS in ESP, includi l'opzione --cors_preset e impostarlo su basic o cors_with_regex. Quando 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 alle richieste semplici che preflight HTTP OPTIONS richieste.
  • Memorizza nella cache il risultato della richiesta OPTIONS preflight per un massimo di 20 giorni (1728000 secondi).

  • Imposta le intestazioni di 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 sostituire il valore predefinito di Access-Control-Allow-Origin, specifica una delle seguenti opzioni:

Opzione Descrizione
--cors_allow_origin Da utilizzare con --cors_preset=basic per impostare Access-Control-Allow-Origin su un'origine specifica.
Esempio:
--cors_preset=basic
--cors_allow_origin=http://example.com
--cors_allow_origin_regex Utilizza con --cors_preset=cors_with_regex. Ti consente di utilizzare una un'espressione regolare per impostare Access-Control-Allow-Origin.
Esempio:
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

L'espressione regolare nell'esempio precedente consente un'origine con http o https e qualsiasi sottodominio di example.com.

Dopo aver impostato --cors_preset=basic o --cors_preset=cors_with_regex per l'attivazione CORS, puoi eseguire l'override dei valori predefiniti delle altre intestazioni delle risposte specificando una o più delle seguenti opzioni:

Opzione Descrizione
--cors_allow_methods Set Access-Control-Allow-Methods ai metodi HTTP specificati. Specifica i metodi HTTP come stringa con ogni Metodo HTTP separato da una virgola.
Esempio:
--cors_preset=basic
--cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers Set Access-Control-Allow-Headers alle intestazioni HTTP specificate. Specifica le intestazioni HTTP come stringa con ogni intestazione HTTP separata da una virgola.
Esempio:
--cors_preset=basic
--cors_allow_headers=Origin,Content-Type,Accept
--cors_allow_credentials Include: 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_allow_credentials
--cors_expose_headers Imposta Access-Control-Expose-Headers sulle intestazioni specificate. Specifica quali intestazioni possono essere esposte nell'ambito della risposta come stringa con ogni intestazione separata da una virgola.
Esempio:
--cors_preset=basic
--cors_expose_headers=Content-Length

Se le opzioni di avvio CORS di ESP non soddisfano le esigenze della tua applicazione, puoi creare un file nginx.conf personalizzato con il supporto CORS richiesto dalla tua applicazione. Per ulteriori informazioni, vedi Creazione di un nginx.conf personalizzato per supportare CORS.

Passaggi successivi

Scopri di più su: