可擴充服務 Proxy V2 啟動選項

可擴充服務 Proxy V2 (ESPv2) 是一種採用 Envoy 技術的 Proxy，可讓 Cloud Endpoints 提供 API 管理功能。如要設定 ESPv2，您可以在部署 ESPv2 服務時指定設定標記。

設定設定旗標

設定 ESPv2 設定標記的方法會因部署平台而異，請參閱下列各節。

Compute Engine VM

docker run 指令會指定 Compute Engine 的 ESPv2 設定標記。例如：

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

在這個範例中，--service、--rollout_strategy 和 --backend 是 ESPv2 設定旗標。

GKE 和 Kubernetes

您可以在部署資訊清單檔案的 args 欄位中，指定 GKE 和 Kubernetes 的設定標記。例如：

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

在本範例中，--listener_port、--backend、--service 和 --rollout_strategy 是 ESPv2 設定旗標。

適用於無伺服器平台的 Cloud Run

如要為 Cloud Run for Serverless 指定啟動選項，請使用 ESPv2_ARGS 環境變數。您可以使用 --set-env-vars 選項，在 gcloud run deploy 指令中設定變數。

例如：

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

在這個範例中，--enable_debug 是 ESPv2 設定標記。

如要進一步瞭解 gcloud run deploy 指令，請參閱 OpenAPI 專用的 Cloud Functions、OpenAPI 專用的 Cloud Run 或 gRPC 專用的 Cloud Run。

如要在 ESPv2_ARGS 環境變數中設定多個引數，請指定自訂分隔符號，並使用該分隔符號分隔多個引數。請勿使用半形逗號做為分隔符。將自訂分隔符放在 ESPv2_ARGS 環境變數的開頭，並以反鉤號包圍。

以下範例使用 ++ 做為分隔符：

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

如果您設定的旗標含有半形逗號，則必須在 gcloud_build_image 指令碼中設定 ESPv2_ARGS 環境變數。

舉例來說，如要新增標記 --cors_allow_methods=PUT,POST,GET：

  • 下載 gcloud_build_image 指令碼。
  • 編輯 gcloud_build_image，如下所示：
    cat <<EOF > Dockerfile
  FROM BASE_IMAGE

  ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
  COPY service.json \ENDPOINTS_SERVICE_PATH

  ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials

  ENTRYPOINT ["/env_start_proxy.py"]
  EOF
  • 執行 gcloud_build_image 指令碼來建構映像檔。

ESPv2 設定旗標

ESPv2 設定標記可分為下列類別：

如需 ESPv2 標記的其他一般範例和說明文字，請前往 GitHub 存放區。

非無伺服器設定

如要在非無伺服器平台 (例如 GKE、Compute Engine 和 Kubernetes) 中執行 ESPv2，就必須使用這些標記。但如果在 Cloud Run for Serverless 平台中部署，就無法設定。

``

旗標 說明
--service 設定 Endpoints 服務的名稱。
--version 設定 Endpoints 服務的服務設定 ID。
--rollout_strategy 指定服務設定的發布策略：[fixed|managed]。預設值為「固定」。
--listener_port 指出接受下游連線的通訊埠。支援 HTTP/1.x、HTTP/2 和 gRPC 連線。預設值為 8080。
--backend 指定本機後端應用程式伺服器位址。有效的配置包括 http、https、grpc 和 grpcs (如果有)。預設配置為 >http。

記錄

您可以使用這些旗標設定 ESPv2，將其他資訊寫入 Stackdriver 記錄。

旗標 說明
--log_request_headers

記錄指定請求標頭的值，以半形逗號分隔，且不加空格。例如，將此旗標設為：

--log_request_headers=foo,bar

如果要求中含有「foo」和「bar」標頭的值，Endpoints 記錄會包含：

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

記錄指定回應標頭的值，並以半形逗號分隔，且不加空格。例如，將此旗標設為：

--log_response_headers=baz,bing

如果回應中提供「baz」和「bing」標頭的值，端點記錄會包含：

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

將指定 JWT 酬載原始欄位的值記錄下來，並以半形逗號分隔，且不加空格。例如，將此旗標設為：

--log_jwt_payload=sub,project_id,foo.foo_name

如果 JWT 酬載中含有這些值，端點記錄就會包含：

jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value

JWT 酬載中的值必須是基本欄位 (字串、整數)。系統不會記錄 JSON 物件和陣列。
--access_log

如果指定，則是存取記錄項目會寫入的本機檔案路徑。
--access_log_format

用於指定存取記錄格式的字串格式。如果未設定，系統會使用 >預設格式字串。如需格式文法詳細說明，請參閱格式字串參考資料。

追蹤

使用這些標記設定傳送至 Stackdriver 的 ESPv2 追蹤資料。這些旗標只會在啟用追蹤功能時套用。

旗標 說明
--disable_tracing

停用追蹤功能。根據預設，系統會啟用追蹤功能。

啟用後，ESPv2 會每秒對傳送至您 API 的要求進行小量採樣，取得該要求傳送至 Stackdriver Trace 的追蹤記錄。根據預設，系統會對每 1000 個要求中的 1 個進行取樣。使用 --tracing_sample_rate 旗標變更取樣率。
--tracing_project_id

Stackdriver 追蹤的 Google 專案 ID。

追蹤是付費服務，系統會向指定的專案收取追蹤費用。

根據預設，系統會對部署的 ESPv2 服務計費。

系統會在啟動時呼叫 Google Cloud 執行個體中繼資料伺服器，藉此判斷專案 ID。如果 ESPv2 部署在 Google Cloud 外(使用 --non_gcp 標記)，除非明確設定這個標記，否則系統會自動停用追蹤功能。
--tracing_sample_rate

將追蹤取樣率設為 0.0 到 1.0 之間的值。這個值會指定要取樣的要求百分比。

預設值為 0.001，也就是每 1000 個要求中 1 個。
--tracing_incoming_context

這個標記會指定要檢查哪些 HTTP 標頭的追蹤記錄，標記值以半形逗號分隔，且不含空格。請注意，順序很重要：追蹤記錄會從相符的第一個標頭衍生。

可能的值包括 traceparent、x-cloud-trace-context 和 grpc-trace-bin。

如果省略，系統會依序檢查 traceparent 和 x-cloud-trace-context 標頭。

詳情請參閱「追蹤您的 API」。
--tracing_outgoing_context

在傳送至後端服務的要求中設定追蹤記錄內容標頭。

這個標記可指定要設定的 HTTP 標頭，其中標記值以逗號分隔，且不含空格。

可能的值包括 traceparent、x-cloud-trace-context 和 grpc-trace-bin。

如果省略，系統會傳送 traceparent 和 x-cloud-trace-context 標頭。

詳情請參閱「追蹤您的 API」。

健康狀態檢查

使用這些標記設定 ESPv2 的健康狀態檢查。第一個旗標可用於設定健康狀態處理程序，以回應健康狀態檢查呼叫。其他旗標可用於啟用 gRPC 後端的健康狀態檢查。

/tbody>
旗標 說明
-z, --healthz 定義健康狀態檢查端點。例如，-z healthz 會讓 ESPv2 傳回路徑 /healthz 的程式碼 200。
--health_check_grpc_backend 啟用 ESPv2，讓系統定期檢查由標記 --backend 指定的後端 gRPC 健康狀態服務。後端必須使用 gRPC 通訊協定，並實作 gRPC 健康狀態檢查通訊協定。由標記 --healthz 啟用的健康狀態檢查端點，會反映後端健康狀態檢查結果。
--health_check_grpc_backend_service 請在呼叫後端 gRPC 健康狀態檢查通訊協定時指定服務名稱。只有在使用 --health_check_grpc_backend 旗標時，系統才會套用這個旗標的值。這是選用項目，如未設定，預設為空白。空白的服務名稱是用來查詢 gRPC 伺服器的整體健康狀態。
--health_check_grpc_backend_interval 在呼叫後端 gRPC 健康狀態服務時，指定檢查間隔和要求逾時時間。只有在使用 --health_check_grpc_backend 旗標時，系統才會套用這個旗標的值。預設值為 1 秒。接受的格式是一串小數，每個小數可加上選用的分數和單位後置字串，例如「5 秒」、「100 毫秒」或「2 公尺」。 有效的時間單位為「m」(分鐘)、「s」(秒) 和「ms」(毫秒)。

偵錯

請使用這些旗標設定 ESPv2 的偵錯功能。這些標記可用於設定 Envoy 管理員端口，以便擷取設定和統計資料，或在偵錯模式下執行 Envoy，將偵錯層級資訊寫入記錄。

旗標 說明
--status_port、--admin_port 在這個通訊埠上啟用 ESPv2 Envoy 管理員。詳情請參閱 Envoy 管理介面參考資料。管理員端口預設為停用。
--enable_debug 啟用偵錯等級記錄檔並新增偵錯標頭。

非Google Cloud 部署

如果 ESPv2 部署在非 Google Cloud 環境中，可能需要下列旗標。

旗標 說明
--service_account_key

指定服務帳戶金鑰 JSON 檔案，以便存取 Google 服務。如果省略這個選項，Proxy 會聯絡 Google Cloud 中繼資料伺服器，擷取存取權權杖。
--dns_resolver_addresses DNS 解析器的位址。每個地址應採用 IP_ADDR 或 IP_ADDR:PORT 格式，並以分號 (;) 分隔。對於 IP_ADDR，系統會使用預設的 DNS 連接埠 52。例如：--dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000) 如果未設定，ESPv2 會使用 /etc/resolv.conf 中設定的預設解析器
--backend_dns_lookup_family 定義所有後端的 DNS 查詢家族。選項包括「自動」、「僅 v4」、「僅 v6」、「偏好 v4」和「全部」。預設值為 v4preferred。請注意，「auto」是舊版值。將標記設為「auto」會產生與「v6preferred」相同的行為。
--non_gcp 根據預設，Proxy 會嘗試連線至 Google Cloud 中繼資料伺服器，在前幾次要求中取得 VM 位置。如要略過這個步驟，請將此標記設為「true」。

本機測試

ESPv2 可部署在本機工作站上進行測試。詳情請參閱「 在本機或其他平台執行 ESP」。

搭配使用這些標記和非Google Cloud 部署標記，即可在持續整合中輕鬆進行本機部署和測試。

旗標 說明
--service_json_path

指定 ESPv2 的路徑，以便載入端點服務設定。使用這個標記後，ESPv2 會採用「固定」推播策略，並忽略下列標記：

  • --service
  • --version
  • --rollout_strategy

這個標記可防止 ESPv2 使用 Service Management API 配額。
--enable_backend_address_override

您可以使用服務設定中的 --backend 旗標或 backend.rule.address 欄位，指定後端地址。針對 OpenAPI 使用者，請注意 backend.rule.address 欄位是由 x-google-backend 擴充功能中的 address 欄位設定。

每個作業的服務設定 backend.rule.address 通常會指定為無伺服器轉送。根據預設，backend.rule.address 會優先於個別作業的 --backend 標記。

如果您希望 --backend 標記優先，請啟用此標記。如果您是在本機工作站上進行開發，這項功能就很實用。接著，您可以使用相同的實際運作服務設定，但透過 --backend 旗標覆寫後端位址，以便進行本機測試。

注意：系統只會覆寫地址。 backend.rule 的所有其他元件仍會套用 (截止期限、後端驗證、路徑轉譯等)。

用戶端 IP 擷取

使用這些標記設定 ESPv2 的用戶端 IP 擷取功能。

旗標 說明
--envoy_use_remote_address

Envoy HttpConnectionManager 設定，詳情請參閱 Envoy 參考資料。預設值為「關閉」。
--envoy_xff_num_trusted_hops Envoy HttpConnectionManager 設定，詳情請參閱 Envoy 參考資料。預設值為 2。

CORS 支援

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

如要在 ESPv2 中啟用 CORS 支援，請納入 --cors_preset 選項，並將該選項設為下列其中一個標記：

  • --cors_preset=basic
  • --cors_preset=cors_with_regex

當您納入 --cors_preset=basic 或 --cors_preset=cors_with_regex 時，ESPv2 會：

  • 假設所有位置路徑都具有相同的 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-Max-Age: 1728000

如要覆寫 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 子網域的來源。

在 Kubernetes 設定檔中設定此選項時，您需要另外加入一個反斜線字元，以逸出字串中的兩個 \。例如：

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^https?://.+\\.example\\.com$"

在 Cloud Run 的 gcloud_build_image 指令碼中設定這個選項時，請盡量避免使用轉義字元和反斜線，因為這些字元可能無法正確從 Bash 指令碼傳遞至 Proxy。請使用字元類別，而非中繼序列。例如： Original: \d Recommended: [0-9]

設定 --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
--cors_max_age 將 Access-Control-Max-Age 設為指定的時間長度。可接受的格式是一串小數，每個小數都含有選用的小數值和單位後置字串，例如「300m」、「1.5h」或「2h45m」。有效的時間單位為「m」(分鐘) 和「h」(小時)。如未設定，則預設值為「480h」。
範例：
--cors_preset=basic
--cors_max_age=24h

TLS 支援

使用這些旗標設定 ESPv2 以便使用 TLS 連線。

旗標 說明
--ssl_server_cert_path Proxy 的伺服器憑證路徑。設定完成後，ESPv2 只會在 listener_port 上接受 HTTP/1.x 和 HTTP/2 安全連線。需要此路徑中的憑證和金鑰檔案「server.crt」和「server.key」。
--ssl_server_cipher_suites 用於下游連線的加密套件，以半形逗號分隔的清單形式指定。請參閱 加密組合設定。
--ssl_backend_client_cert_path Proxy 的用戶端憑證路徑。設定後，ESPv2 會為 HTTPS 後端啟用 TLS 雙向驗證。需要憑證和金鑰檔案「client.crt」和「client.key」位於這個路徑中。
--ssl_backend_client_root_certs_file ESPv2 用來驗證後端伺服器憑證的根憑證檔案路徑。如果未指定，ESPv2 預設會使用「/etc/ssl/certs/ca-certificates.crt」。
--ssl_backend_client_cipher_suites 要用於 HTTPS 後端的加密組合，以半形逗號分隔的清單指定。請參閱 加密組合設定。
--ssl_minimum_protocol 用戶端連線的最低 TLS 通訊協定版本。請參閱這篇文章
--ssl_maximum_protocol 用戶端連線的 TLS 通訊協定最高版本。請參閱這篇文章
--enable_strict_transport_security 啟用 HSTS (HTTP 嚴格傳輸安全性)。所有回應都會新增「Strict-Transport-Security」回應標頭，其值為「max-age=31536000; includeSubdomains;"。
--generate_self_signed_cert 在啟動時產生自行簽署的憑證和金鑰，然後將其儲存在「/tmp/ssl/endpoints/server.crt」和「/tmp/ssl/endpoints/server.key」。當您只需要隨機的自行簽署憑證來提供 HTTPS 要求時，這項功能就非常實用。產生的憑證會具有「localhost」的通用名稱，有效期為 10 年。

逾時和重試

使用這些標記設定 ESPv2 的遠端 HTTP 呼叫逾時和重試。

旗標 說明
--http_request_timeout_s

針對對外部服務 (後端和 Google 服務控制除外) 提出的要求，設定秒數為單位的逾時時間。包括 Google ServiceManagement、中繼資料伺服器和 Google IAM 伺服器。 必須大於 0 ，如果未設定，預設值為 30 秒。
--service_control_network_fail_open

如果連線至 Google 服務控制項時發生網路錯誤，系統會在這個標記開啟時允許要求。預設值為「開啟」。
--service_control_check_timeout_ms 為服務控制 Check 要求設定逾時時間 (以毫秒為單位)。 必須大於 0，如果未設定，則預設值為 1000。
--service_control_report_timeout_ms 為 Service Control Report 要求設定逾時時間 (以毫秒為單位)。 必須大於 0，如果未設定，則預設值為 1000。
--service_control_quota_timeout_ms 為服務控制配額要求設定逾時時間 (以毫秒為單位)。 必須大於 0 ，如果未設定，則預設值為 1000。
--service_control_check_retries 設定服務控制 Check 要求的重試次數。必須大於或等於 0，如果未設定，預設值為 3
--service_control_report_retries 設定服務控制回報要求的重試次數。 必須大於或等於 0，如果未設定，預設值為 5
--service_control_quota_retries 設定服務控制配額要求的重試次數。必須大於或等於 0，如果未設定，預設值為 1
--backend_retry_ons

ESPv2 在後端重試的條件。您可以使用半形逗號分隔清單，指定一或多個 retryOn 條件。預設為 reset,connect-failure,refused-stream。將此旗標設為空白，即可停用重試。

請參閱下列連結，瞭解接受的條件：

--backend_retry_num 允許的重試次數。必須大於或等於 0，預設值為 1。

gRPC 轉碼

使用這些標記設定 ESPv2，以便將 HTTP/JSON 轉碼為 gRPC。

旗標 說明
--transcoding_always_print_primitive_fields

指定是否要為 grpc-json 轉碼作業列印基本欄位。根據預設，JSON 輸出內容會略過含有預設值的原始欄位。舉例來說，如果 int32 欄位設為 0，系統就會略過該欄位。將此標記設為「true」後，系統會覆寫預設行為，並無視值為何而列印原始欄位。預設值為 false。
--transcoding_always_print_enums_as_ints

指定是否要將列舉項目以 int 型別輸出，以便進行 grpc-json 轉碼。根據預設，系統會將這些運算式轉譯為字串。預設值為 false。
--transcoding_stream_newline_delimited

如果為 True，請使用換行符號分隔回應串流訊息。如果為 false，所有回應串流訊息都會轉碼為 JSON 陣列。
--transcoding_case_insensitive_enum_parsing

在 JSON 中使用時，proto 列舉值通常應大寫。如果 JSON 要求使用非大寫的列舉值，請將這個旗標設為 true。
--transcoding_preserve_proto_field_names

指定是否要保留 Proto 欄位名稱，以便進行 grpc-json 轉碼。根據預設，protobuf 會使用 json_name 選項或小寫駝峰式大小寫，依序產生 JSON 欄位名稱。設定此標記後，系統會保留原始欄位名稱。預設值為 false。
--transcoding_ignore_query_parameters

在 grpc-json 轉碼作業中，要忽略的查詢參數清單 (以半形逗號分隔)，用於轉碼方法對應。根據預設，轉碼器篩選器不會轉碼含有不明/無效查詢參數的請求。
--transcoding_ignore_unknown_query_parameters

指定是否要在 grpc-json 轉碼時，忽略無法對應至對應 protobuf 欄位的查詢參數。如果您無法控制查詢參數，且事先不知道這些參數，請使用此選項。否則，請使用 --transcoding_ignore_query_parameters。預設值為 false。
--transcoding_query_parameters_disable_unescape_plus

根據預設，在 grpc-json 轉碼作業中，查詢參數中的加號 "+" 會解碼為空格 " "。這是為了支援 HTML 2.0。如果不想使用這項功能，請將此標記設為 true 來停用。

要求和回應修改

使用這些標記設定 ESPv2，以便部分修改要求和回應。

旗標 說明
--add_request_header

請先在要求中加入 HTTP 標頭，再將要求傳送至上游後端。如果標頭已在要求中，其值就會換成新的值。

支援 Envoy 自訂變數。

這個引數可重複多次，用於指定多個標頭。例如：
--add_request_header=key1=value1
--add_request_header=key2=value2。
--append_request_header

請先在要求中附加 HTTP 標頭，再將要求傳送至上游後端。 如果標頭已在要求中，系統會附加新值。

支援 Envoy 自訂變數。

這個引數可重複多次，用於指定多個標頭。例如：
--append_request_header=key1=value1
--append_request_header=key2=value2。
--add_response_header

請先在回應中加入 HTTP 標頭，再傳送至下游用戶端。如果標頭已在回應中，系統會將其替換為新標頭。

支援 Envoy 自訂變數。

這個引數可重複多次，用於指定多個標頭。例如：
--add_response_header=key1=value1
--add_response_header=key2=value2。
--append_response_header

在將回應傳送至下游用戶端前，先附加 HTTP 標頭。如果回應中已有標頭，系統會附加新的標頭。

支援 Envoy 自訂變數。

這個引數可重複多次，用於指定多個標頭。例如：
--append_response_header=key1=value1
--append_response_header=key2=value2。

安全性選項

使用這些標記進一步調整 ESPv2 允許的請求。

旗標 說明
--underscores_in_headers

允許含有底線的標頭名稱通過。預設值為 false。

根據 RFC-7230 規範，標頭名稱中可使用底線字元。不過，由於部分系統會將 _ 和 - 視為可互換，因此這項行為會做為安全措施實作。
--envoy_connection_buffer_limit_bytes

設定每個要求/回應主體的緩衝資料量上限 (以位元組為單位)。如果未設定，預設值會由 Envoy 決定。請參閱 Envoy 的事件監聽器設定。
--disable_normalize_path

根據 RFC 3986 停用 path HTTP 標頭的規範化。如果後端預設會執行路徑規格化，建議您保持啟用這個選項。

下表提供後端會根據此標記的設定，從 ESPv2 收到的要求 path 的範例。

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello/../world  | Rejected              | /world             |
        | /%4A             | /%4A                  | /J                 |
        | /%4a             | /%4a                  | /J                 |
        -----------------------------------------------------------------

根據預設，ESPv2 會將路徑標準化。只有在流量受到這項行為影響時，才停用這項功能。

注意：根據 RFC 3986，這個選項不會為百分比編碼的斜線字元解碼。請參閱標記 --disallow_escaped_slashes_in_path，啟用這項不符合規定的行為。

注意：即使啟用這個選項，系統也不支援 RFC 3986 的大小寫規範化。

詳情請參閱「瞭解路徑範本」。
--disable_merge_slashes_in_path

停用 path HTTP 標頭中相鄰斜線的合併功能。 如果後端預設會執行合併作業，建議您保持啟用這個選項。

下表提供後端會根據此標記的設定，從 ESPv2 收到的要求 path 的範例。

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello//world    | Rejected              | /hello/world       |
        | /hello///        | Rejected              | /hello             |
        -----------------------------------------------------------------

根據預設，ESPv2 會合併斜線。只有在流量受到這項行為影響時，才停用這項功能。

詳情請參閱「瞭解路徑範本」。
--disallow_escaped_slashes_in_path

禁止含有轉義百分比編碼斜線字元的請求：

  • %2F 或 %2f 會視為 /
  • %5C 或 %5c 會視為 \

啟用後，行為取決於使用的通訊協定：

  • 針對 OpenAPI 後端，含有經過轉譯百分比編碼的斜線要求路徑會透過重新導向自動解除轉譯。
  • 對於 gRPC 後端，系統會拒絕含有以百分比編碼的斜線逃逸字元的路徑要求 (gRPC 不支援重新導向)。

這個選項「不」符合 RFC 3986 標準，因此預設為關閉。如果後端不符合 RFC 3986 規範，且會轉義斜線，則必須在 ESPv2 中啟用這個選項。這麼做可避免路徑混淆攻擊，導致無法強制執行安全性規定。

詳情請參閱「瞭解路徑範本」。

JWT 驗證

請使用這些旗標設定 ESPv2，以便透過重試擷取遠端 JWK。

旗標 說明
--jwks_fetch_num_retries

在遠端 JWKS 擷取重試政策中指定重試次數。預設值為 0，不會重試。
--jwks_fetch_retry_back_off_base_interval_ms

指定 JWKS 擷取重試指數輪詢基礎間隔，以毫秒為單位。如未設定，預設值為 200 毫秒。

--jwks_fetch_retry_back_off_max_interval_ms

指定 JWKS 擷取重試指數輪詢的最大間隔時間 (以毫秒為單位)。如未設定，預設值為 32 秒。

--jwks_cache_duration_in_s

以秒為單位指定 JWT 公開金鑰快取時間長度。如果未設定，預設值為 5 分鐘。
--jwks_async_fetch_fast_listener

只有在未設定 --disable_jwks_async_fetch 旗標時才會套用。此標記會決定 ESPv2 是否會等待初始 jwks 擷取作業完成，再繫結事件監聽器端口。如果為 false，則會等待。 預設值為 false。
--jwt_cache_size

將專屬 JWT 權杖數量指定為 JWT 快取大小上限。快取只會儲存已驗證的權杖。如果設為 0，則會停用 JWT 快取。這個旗標會限制 JWT 快取的記憶體用量。快取使用的記憶體大約為每個符記的 (符記大小 + 64 位元組)。如未指定，則預設為 100000。
--disable_jwt_audience_service_name_check

通常，系統會根據 OpenAPI x-google-audiences 欄位指定的目標對象，檢查 JWT aud 欄位。此標記會變更未指定 x-google-audiences 欄位時的行為。如果未指定 x-google-audiences 欄位，且未使用這個旗標，系統會使用服務名稱檢查 JWT aud 欄位。如果使用這個標記，系統就不會檢查 JWT aud 欄位。

後續步驟

瞭解下列內容：