可擴充服務 Proxy 啟動選項

可擴充服務 Proxy (ESP) 是一種採用 NGINX 技術的 Proxy，可讓 Cloud Endpoints 提供 API 管理功能。您可以透過在啟動 ESP Docker 容器時指定選項來設定 ESP。ESP 容器啟動時，會執行名為 start_esp 的指令碼，該指令碼會使用您指定的選項寫入 NGINX 設定檔並啟動 ESP。

您可以在 docker run 指令中指定 ESP 啟動選項，例如：

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

如要將 ESP 部署到 Kubernetes，您可以在部署資訊清單檔案的 args 欄位中指定啟動選項，例如：

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"
  ]

下表說明 ESP 的啟動選項。

簡短選項 長選項 說明
-s SERVICE_NAME --service SERVICE_NAME 設定 Endpoints 服務的名稱。
-R ROLLOUT_STRATEGY --rollout_strategy ROLLOUT_STRATEGY

ESP 1.7.0 以上版本均適用。指定 managed 或 fixed。--rollout_strategy=managed 選項可將 ESP 設為使用最新部署的服務設定。指定此選項時，在您部署新服務設定後 5 分鐘內，ESP 會偵測到變更並自動開始使用新設定。建議您指定此選項而非讓 ESP 使用特定的設定 ID。 將 --rollout_strategy 設為 managed 時，您不需要指定 --version 選項。
-v CONFIG_ID --version CONFIG_ID 設定 ESP 將使用的服務設定 ID。請參閱「取得服務名稱和設定 ID」，瞭解設定此選項所需的資訊。指定 --rollout_strategy=fixed 或未加入 --rollout_strategy 選項時，您必須加入 --version 選項並指定設定 ID。在這種情況下，每次部署新的 Endpoints 設定時，都必須使用新的設定 ID 重新啟動 ESP。
-p HTTP1_PORT --http_port HTTP1_PORT 設定 ESP 的 HTTP/1.x 連線公開通訊埠。1
-P HTTP2_PORT --http2_port HTTP2_PORT 設定 ESP 的 HTTP/2 連線公開通訊埠。1
-S SSL_PORT --ssl_port SSL_PORT 設定 ESP 的 HTTPS 連線公開通訊埠。1
-a BACKEND --backend BACKEND 設定 HTTP/1.x 應用程式後端伺服器位址。後端位址的預設值為 http://127.0.0.1:8081。
您可以指定通訊協定的前置字串，例如：
--backend=https://127.0.0.1:8000
如果您未指定通訊協定的前置字串，則預設為 http。
如果您的後端伺服器執行於容器中的 Compute Engine，您可以指定容器名稱和連接埠，例如：
--backend=my-api-container:8000
如要指定後端接受 gRPC 流量，請加上前置字串 grpc://。例如：
--backend=grpc://127.0.0.1:8000
如果您的後端伺服器執行於容器中的 Compute Engine，且接受 gRPC 流量，您可以指定容器名稱和連接埠，例如：
--backend=grpc://my-api-container:8000
-N STATUS_PORT --status_port STATUS_PORT 設定狀態連接埠 (預設：8090)。
無 --disable_cloud_trace_auto_sampling 根據預設，ESP 會透過 Cloud Trace 採樣每 1, 000 個要求中的 1 個，或每 10 秒 1 個要求。設定此標記即可停用這類自動採樣功能。無論此標記值為何，您仍可透過含有追蹤內容的 HTTP 要求標頭啟用 Cloud Trace。詳情請參閱「追蹤您的 API」。
-n NGINX_CONFIG --nginx_config NGINX_CONFIG 設定自訂 NGINX 設定檔的位置。若指定此選項，ESP 會擷取指定的設定檔，然後立即使用所提供的自訂設定檔啟動 NGINX。詳情請參閱「使用 GKE 的自訂 nginx 設定」。
-k SERVICE_ACCOUNT_KEY --service_account_key SERVICE_ACCOUNT_KEY 設定服務帳戶認證 JSON 檔。如果提供服務帳戶，ESP 會使用該帳戶產生存取權杖，以呼叫 Service Infrastructure API。您只需要在 ESP 在 Google Cloud以外的平台上執行時指定此選項，例如在本機電腦、Kubernetes 或其他雲端服務供應商上執行。詳情請參閱「 建立服務帳戶」一文。
-z HEALTHZ_PATH --healthz HEALTHZ_PATH 會在應用程式後端所處連接埠上，定義健康狀態檢查端點。例如，若設為 -z healthz，ESP 會傳回程式碼 200，代表地點 /healthz，而不會將要求轉發至後端。預設：未使用。
無 --dns DNS_RESOLVER 指定 DNS 解析器。舉例來說，--dns 169.254.169.254 會使用 GCP 中繼資料伺服器做為 DNS 解析器。如未指定，則預設為 8.8.8.8。

1連接埠並非必要項目，且彼此不能重複。如果您未指定任何通訊埠選項，ESP 會接受使用通訊埠 8080 進行的 HTTP/1.x 連線。對於 HTTPS 連線，ESP 會預期 TLS 密鑰位於 /etc/nginx/ssl/nginx.crt 和 /etc/nginx/ssl/nginx.key。

指令列叫用範例

下列範例示範如何使用其中某些指令列引數：

如要啟動 ESP 以處理使用 HTTP/1.x 通訊埠 80 和 HTTPS 通訊埠 443 傳入的要求，並將要求傳送到位於 127.0.0.1:8000 的 API 後端：

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

如要使用自訂的 NGINX 設定啟動 ESP，請使用服務帳戶認證檔來擷取服務設定，然後連線到 Service Control：

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

請注意，您必須使用 Docker 標記 --volume 或 --mount 裝載 JSON 檔案，此檔案包含服務帳戶私密金鑰，以及相當於 ESP Docker 容器中磁碟區的自訂 NGINX 設定檔。以上範例將本機電腦的 $HOME/Downloads 目錄對應至容器中的 esp 目錄。您儲存服務帳戶的私密金鑰檔案時，通常會將金鑰下載至 Downloads 目錄中。如有必要，您可以將私密金鑰檔案複製到另一個目錄。) 詳情請參閱「在 Docker 中管理資料」。

新增 CORS 支援到 ESP

如要瞭解可用的 CORS 支援選項，請參閱「支援 CORS」。本節說明如何使用 ESP 啟動標記支援 CORS。

要在 ESP 中啟用 CORS 支援，請納入 --cors_preset 選項，並將該選項設為 basic 或 cors_with_regex。當您納入 --cors_preset=basic 或 --cors_preset=cors_with_regex 時，ESP 會：

  • 假設所有位置路徑都具有相同的 CORS 政策。
  • 回應簡單要求和預檢 HTTP OPTIONS 要求。
  • 快取最多 20 天 (1728000 秒) 的預檢 OPTIONS 要求的結果。

  • 將回應標頭設為下列值：

    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

如要覆寫 Access-Control-Allow-Origin 的預設值，請指定下列其中一個選項：

選項 說明
--cors_allow_origin 與 --cors_preset=basic 搭配使用，可將 Access-Control-Allow-Origin 設為特定來源。
範例：
--cors_preset=basic
--cors_allow_origin=http://example.com
--cors_allow_origin_regex 請使用 --cors_preset=cors_with_regex 的帳戶操作。可讓您使用規則運算式設定 Access-Control-Allow-Origin。
範例：
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

前面範例中的規則運算式允許含有 http 或 https 及任何 example.com 子網域的來源。

設定 --cors_preset=basic 或 --cors_preset=cors_with_regex 啟用 CORS 後，您可以透過指定下列一或多個選項，覆寫其他回應標頭的預設值：

選項 說明
--cors_allow_methods 將 Access-Control-Allow-Methods 設為指定的 HTTP 方法。將 HTTP 方法指定為字串，並用逗號分隔每個 HTTP 方法。
範例：
--cors_preset=basic
--cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers 將 Access-Control-Allow-Headers 設為指定的 HTTP 標頭。將 HTTP 標頭指定為字串，並用逗號分隔每個 HTTP 標頭。
範例：
--cors_preset=basic
--cors_allow_headers=Origin,Content-Type,Accept
--cors_allow_credentials 在回應中加入 Access-Control-Allow-Credentials 標頭，並在其中加入 true 值。根據預設，回應中不會包含 Access-Control-Allow-Credentials 標頭。
範例：
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers 將 Access-Control-Expose-Headers 設為指定的標頭。指定哪些標頭可以做為字串公開成回應的一部分，並用逗號分隔每個標頭。
範例：
--cors_preset=basic
--cors_expose_headers=Content-Length

如果 ESP CORS 啟動選項不符合您應用程式的需求，您可以使用應用程式需要的 CORS 支援來建立自訂的 nginx.conf 檔案。詳情請參閱「建立自訂 nginx.conf 以支援 CORS」。

後續步驟

瞭解下列內容：