可擴充服務 Proxy V2 啟動選項

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

設定設定旗標

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

Compute Engine VM

Compute Engine 適用的 ESPv2 設定標記是在 docker run 指令中指定。例如：

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 for 無伺服器平台

如要為 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 時，必須使用這些標記。部署至無伺服器平台時，無法設定這些變數。

``

旗標 說明
--service 設定 Endpoints 服務的名稱。
--version 設定 Endpoints 服務的服務設定 ID。
--rollout_strategy 指定服務設定的發布策略，[fixed|managed]。 預設值為 fixed。
--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」標頭的值，則 Endpoints 記錄會包含：

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

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

--log_jwt_payload=sub,project_id,foo.foo_name

如果 JWT 酬載中提供這些值，則 Endpoints 記錄檔會包含：

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 服務的專案 ID 計費。

專案 ID 是在啟動時呼叫 Google Cloud 執行個體中繼資料伺服器所決定。 如果 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 秒。 可接受的格式為一連串小數，每個小數可選擇性加上分數和單位後置字串，例如「5s」、「100ms」或「2m」。 有效時間單位包括「m」(分鐘)、「s」(秒) 和「ms」(毫秒)。

偵錯

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

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

非Google Cloud Deployment

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

旗標 說明
--service_account_key

指定用來存取 Google 服務的服務帳戶金鑰 JSON 檔案。 如果省略這個選項，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 查詢系列。選項包括 auto、v4only、v6only、v4preferred 和 all。預設值為 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 回應中會包含值為 true 的 Access-Control-Allow-Credentials 標頭。根據預設，回應中不會包含 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 Service Control 除外) 發出的要求設定逾時時間 (以秒為單位)。 包括 Google ServiceManagement、中繼資料伺服器和 Google IAM 伺服器。 必須大於 0，如未設定，預設值為 30 秒。

--service_control_network_fail_policy

如果連線至 Google 服務控制項時發生網路故障，只要這個標記為「open」，系統就會允許要求。預設值為 open。

--service_control_check_timeout_ms 設定服務控制項檢查要求逾時時間 (以毫秒為單位)。 必須大於 0，如未設定，預設值為 1000。
--service_control_report_timeout_ms 設定服務控制項 Report 要求的逾時時間 (以毫秒為單位)。 必須大於 0，如未設定，預設值為 1000。
--service_control_quota_timeout_ms 以毫秒為單位，設定服務控制配額要求的逾時時間。 必須大於 0，如未設定，預設值為 1000。
--service_control_check_retries 設定服務控制項 Check 要求的重試次數。 必須>= 0，如未設定，預設值為 3
--service_control_report_retries 設定服務控制項 Report 要求的重試次數。 必須>= 0，如未設定，預設值為 5
--service_control_quota_retries 設定服務控制配額要求的重試次數。 必須>= 0，如未設定，預設值為 1
--backend_retry_ons

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

請參閱下列連結瞭解可接受的狀況：

--backend_retry_num 允許的重試次數。必須 >= 0，預設為 1。

gRPC 轉碼

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

旗標 說明
--transcoding_always_print_primitive_fields

指定是否要列印原始欄位，以進行 grpc-json 轉碼。根據預設，JSON 輸出內容會省略含有預設值的原始欄位。舉例來說，如果將 int32 欄位設為 0，系統就會省略該欄位。將此標記設為 true 會覆寫預設行為，並列印原始欄位，無論其值為何。預設值為 false。

--transcoding_always_print_enums_as_ints

指定是否要將列舉列印為整數，以進行 grpc-json 轉碼。 預設會以字串形式呈現。預設值為 false。

--transcoding_stream_newline_delimited

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

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

--transcoding_preserve_proto_field_names

指定是否要保留 grpc-json 轉碼的 proto 欄位名稱。 根據預設，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，以透過重試機制擷取遠端 Jwks。

旗標 說明
--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 欄位。

後續步驟

瞭解下列內容：