HTTP 路由組件 (proto)

路由架構概觀
HTTP 路由器篩選器

config.route.v3.VirtualHost

路由設定中的頂層元素是虛擬主機。每個虛擬主機都有一個邏輯名稱以及一組根據傳入請求的 host 標頭路由到它的網域。這允許單一的監聽器服務多個頂層網域路徑樹。一旦根據網域選定了虛擬主機，就會依序處理路由，以查看要路由到哪個上游叢集，或是否要執行重新導向。

{
  "name": ...,
  "domains": [],
  "routes": [],
  "matcher": {...},
  "require_tls": ...,
  "virtual_clusters": [],
  "rate_limits": [],
  "request_headers_to_add": [],
  "request_headers_to_remove": [],
  "response_headers_to_add": [],
  "response_headers_to_remove": [],
  "cors": {...},
  "typed_per_filter_config": {...},
  "include_request_attempt_count": ...,
  "include_attempt_count_in_response": ...,
  "retry_policy": {...},
  "hedge_policy": {...},
  "include_is_timeout_retry_header": ...,
  "per_request_buffer_limit_bytes": {...},
  "request_mirror_policies": [],
  "metadata": {...}
}

name: (字串，必要) 虛擬主機的邏輯名稱。這用於發出某些統計數據，但與路由無關。

domains

(重複字串，必要) 將與此虛擬主機匹配的網域（主機/授權標頭）列表。萬用字元主機支援後綴或前綴形式。

網域搜尋順序

精確的網域名稱：www.foo.com。
後綴網域萬用字元：*.foo.com 或 *-bar.foo.com。
前綴網域萬用字元：foo.* 或 foo-*。
特殊萬用字元 * 匹配任何網域。

注意

萬用字元不會匹配空字串。例如，*-bar.foo.com 會匹配 baz-bar.foo.com，但不會匹配 -bar.foo.com。最長的萬用字元先匹配。整個路由設定中只能有一個虛擬主機匹配 *。網域在所有虛擬主機中必須是唯一的，否則設定將無法載入。

網域不能包含控制字元。這會由 well_known_regex HTTP_HEADER_VALUE 驗證。

routes: (重複 config.route.v3.Route) 將針對傳入請求依序匹配的路由列表。將使用第一個匹配的路由。只能指定此項和 matcher 其中一項。

matcher: (.xds.type.matcher.v3.Matcher) 用於解析傳入請求的路由動作的匹配樹。只能指定此項和 routes 其中一項。

require_tls: (config.route.v3.VirtualHost.TlsRequirementType) 指定虛擬主機預期的 TLS 強制類型。如果未指定此選項，則虛擬主機沒有 TLS 要求。

virtual_clusters: (重複 config.route.v3.VirtualCluster) 為此虛擬主機定義的虛擬叢集列表。虛擬叢集用於額外的統計資料收集。

rate_limits: (重複 config.route.v3.RateLimit) 指定將應用於虛擬主機的一組速率限制設定。

request_headers_to_add: (重複 config.core.v3.HeaderValueOption) 指定應新增至此虛擬主機處理的每個請求的 HTTP 標頭列表。在此層級指定的標頭會在封閉的 config.route.v3.Route 中的標頭之後，以及在封閉的 config.route.v3.RouteConfiguration 中的標頭之前應用。如需詳細資訊，包括標頭值語法的詳細資訊，請參閱關於自訂請求標頭的文件。

request_headers_to_remove: (重複字串) 指定應從此虛擬主機處理的每個請求中移除的 HTTP 標頭列表。

response_headers_to_add: (重複 config.core.v3.HeaderValueOption) 指定應新增至此虛擬主機處理的每個回應的 HTTP 標頭列表。在此層級指定的標頭會在封閉的 config.route.v3.Route 中的標頭之後，以及在封閉的 config.route.v3.RouteConfiguration 中的標頭之前應用。如需詳細資訊，包括標頭值語法的詳細資訊，請參閱關於自訂請求標頭的文件。

response_headers_to_remove: (重複字串) 指定應從此虛擬主機處理的每個回應中移除的 HTTP 標頭列表。

cors: (config.route.v3.CorsPolicy) 表示虛擬主機具有 CORS 原則。如果在 VirtualHost.typed_per_filter_config 中找到相關的 cors 原則，則會忽略此欄位。

注意

此選項已淘汰。請使用 VirtualHost.typed_per_filter_config 來設定 CORS HTTP 篩選器。

typed_per_filter_config: (重複 map<字串, Any>) 此欄位可用於提供虛擬主機層級的每個篩選器設定。金鑰應符合篩選器設定名稱。請參閱 Http 篩選器路由特定設定以取得詳細資訊。

include_request_attempt_count: (布林值) 決定是否應在上游請求中包含 x-envoy-attempt-count 標頭。設定此選項會導致它覆寫任何現有的標頭值，因此如果請求路徑上有兩個啟用此選項的 Envoy，則上游會將嘗試次數視為第二個 Envoy 感知的次數。預設值為 false。此標頭不受 suppress_envoy_headers 旗標影響。

include_attempt_count_in_response: (布林值) 決定是否應在下游回應中包含 x-envoy-attempt-count 標頭。設定此選項會導致路由器覆寫任何現有的標頭值，因此如果請求路徑上有兩個啟用此選項的 Envoy，則下游會將嘗試次數視為最接近自身的上游 Envoy 感知的次數。預設值為 false。此標頭不受 suppress_envoy_headers 旗標影響。

retry_policy: (config.route.v3.RetryPolicy) 指示此虛擬主機中所有路由的重試原則。請注意，設定路由層級的項目會優先於此設定，並且會獨立處理（例如：值不會繼承）。

hedge_policy: (config.route.v3.HedgePolicy) 指示此虛擬主機中所有路由的避險原則。請注意，設定路由層級的項目會優先於此設定，並且會獨立處理（例如：值不會繼承）。

include_is_timeout_retry_header: (布林值) 決定是否在每個嘗試逾時啟動的重試中包含 x-envoy-is-timeout-retry 請求標頭。

per_request_buffer_limit_bytes: (UInt32Value) 將用於重試和鏡像的最大緩衝位元組數。如果已設定且未設定特定於路由的限制，則實際緩衝的位元組數將為此值與監聽器的 per_connection_buffer_limit_bytes 的最小值。

request_mirror_policies: (repeated config.route.v3.RouteAction.RequestMirrorPolicy) 指定此虛擬主機下每個路由的一組預設請求鏡像策略。它完全優先於路由配置鏡像策略。也就是說，策略不會合併，最明確的非空策略會成為鏡像策略。

metadata: (config.core.v3.Metadata) metadata 欄位可用於提供有關虛擬主機的其他資訊。它可用於配置、統計和日誌記錄。metadata 應放在需要它的篩選器命名空間下。例如，如果 metadata 適用於路由器篩選器，則應將篩選器名稱指定為 envoy.filters.http.router。

Enum config.route.v3.VirtualHost.TlsRequirementType

[config.route.v3.VirtualHost.TlsRequirementType proto]

NONE: (預設值) 虛擬主機沒有 TLS 要求。

EXTERNAL_ONLY: 外部請求必須使用 TLS。如果請求是外部的且未使用 TLS，則會發送 301 重新導向，告知用戶端使用 HTTPS。

ALL: 所有請求都必須使用 TLS。如果請求未使用 TLS，則會發送 301 重新導向，告知用戶端使用 HTTPS。

config.route.v3.FilterAction

[config.route.v3.FilterAction proto]

篩選器定義的動作類型。

{
  "action": {...}
}

action: (Any)

config.route.v3.RouteList

[config.route.v3.RouteList proto]

這可用於路由比對器 VirtualHost.matcher。當比對器符合時，將比對並執行路由。

{
  "routes": []
}

routes: (repeated config.route.v3.Route) 將依序比對並執行的路由清單。將使用第一個符合的路由。

config.route.v3.Route

[config.route.v3.Route proto]

路由既是指定如何比對請求，也是指示下一步操作（例如，重新導向、轉送、重寫等）。

注意

Envoy 支援透過標頭比對在 HTTP 方法上路由。

{
  "name": ...,
  "match": {...},
  "route": {...},
  "redirect": {...},
  "direct_response": {...},
  "metadata": {...},
  "decorator": {...},
  "typed_per_filter_config": {...},
  "request_headers_to_add": [],
  "request_headers_to_remove": [],
  "response_headers_to_add": [],
  "response_headers_to_remove": [],
  "tracing": {...},
  "per_request_buffer_limit_bytes": {...},
  "stat_prefix": ...
}

name: (string) 路由的名稱。

match: (config.route.v3.RouteMatch, 必要) 路由比對參數。

route

(config.route.v3.RouteAction) 將請求路由到某個上游叢集。

必須設定 route、redirect 或 direct_response 中的其中一項。

redirect

(config.route.v3.RedirectAction) 傳回重新導向。

必須設定 route、redirect 或 direct_response 中的其中一項。

direct_response

(config.route.v3.DirectResponseAction) 直接傳回任意 HTTP 回應，而不需透過 Proxy。

必須設定 route、redirect 或 direct_response 中的其中一項。

metadata: (config.core.v3.Metadata) Metadata 欄位可用於提供有關路由的其他資訊。它可用於配置、統計和日誌記錄。metadata 應放在需要它的篩選器命名空間下。例如，如果 metadata 適用於路由器篩選器，則應將篩選器名稱指定為 envoy.filters.http.router。

decorator: (config.route.v3.Decorator) 符合路由的裝飾器。

typed_per_filter_config: (repeated map<string, Any>) 此欄位可用於提供特定於路由的每個篩選器配置。金鑰應符合篩選器配置名稱。如需詳細資訊，請參閱 Http 篩選器特定於路由的配置。

request_headers_to_add: (repeated config.core.v3.HeaderValueOption) 指定一組將新增至符合此路由的請求的標頭。在此層級指定的標頭會先於封閉的 config.route.v3.VirtualHost 和 config.route.v3.RouteConfiguration 中的標頭套用。如需詳細資訊，包括標頭值語法的詳細資訊，請參閱自訂請求標頭的文件。

request_headers_to_remove: (repeated string) 指定應從符合此路由的每個請求中移除的 HTTP 標頭清單。

response_headers_to_add: (repeated config.core.v3.HeaderValueOption) 指定一組將新增至符合此路由的請求的回應的標頭。在此層級指定的標頭會先於封閉的 config.route.v3.VirtualHost 和 config.route.v3.RouteConfiguration 中的標頭套用。如需詳細資訊，包括標頭值語法的詳細資訊，請參閱自訂請求標頭的文件。

response_headers_to_remove: (repeated string) 指定應從符合此路由的請求的每個回應中移除的 HTTP 標頭清單。

tracing: (config.route.v3.Tracing) 此物件的存在定義了連線管理員的追蹤配置是否由此特定於路由的執行個體覆寫。

per_request_buffer_limit_bytes: (UInt32Value) 將用於重試和鏡像的最大緩衝位元組數。如果已設定，則實際緩衝的位元組數將為此值與監聽器的 per_connection_buffer_limit_bytes 的最小值。

stat_prefix

(string) 發出此端點統計資料時要使用的人工可讀前置詞。統計資料的根目錄為 vhost.<虛擬主機名稱>.route.<stat_prefix>。這應針對希望取得「每個路由」統計資料的高度關鍵端點設定。如果未設定，則不會產生端點統計資料。

發出的統計資料與為虛擬叢集記錄的統計資料相同。

警告

我們不建議為每個應用程式端點設定統計前置詞。這不僅不容易維護，而且統計資料會使用大量的記憶體（每個路由約 1KiB）。

config.route.v3.WeightedCluster

[config.route.v3.WeightedCluster proto]

與指定單個上游叢集作為請求目標的叢集欄位相比，weighted_clusters 選項允許指定多個上游叢集，以及指示轉送到每個叢集的流量百分比的權重。路由器會根據權重選擇上游叢集。

{
  "clusters": [],
  "total_weight": {...},
  "runtime_key_prefix": ...,
  "header_name": ...
}

clusters: (repeated config.route.v3.WeightedCluster.ClusterWeight, 必要) 指定與路由關聯的一或多個上游叢集。

total_weight: (UInt32Value) 指定所有叢集的總權重。如果此值大於 0，則所有叢集權重的總和必須等於此值。此欄位現在已棄用，用戶端將使用所有叢集權重的總和。由管理伺服器提供正確的權重。

runtime_key_prefix: (string) 指定應用於建立與每個叢集關聯的執行階段金鑰的執行階段金鑰前置詞。當指定 runtime_key_prefix 時，路由器會在金鑰 runtime_key_prefix + . + cluster[i].name 下尋找與每個上游叢集關聯的權重，其中 cluster[i] 表示叢集陣列欄位中的項目。如果叢集的執行階段金鑰不存在，則會使用組態檔案中指定的值作為預設權重。如需金鑰名稱如何對應到基礎實作的資訊，請參閱執行階段文件。

header_name: (string) 指定用於查閱請求標頭中傳遞的隨機值的標頭名稱。這是用來確保跨多個 Proxy 層級為加權流量選擇一致的叢集。如果標頭不存在或無效，Envoy 將會改為使用內部產生的隨機值。此標頭預期為單一值標頭，因為我們只希望在整個過程中都有一個選取的值，以確保一致性。而且該值是介於 0 和 UINT64_MAX 之間的無號碼。

config.route.v3.WeightedCluster.ClusterWeight

[config.route.v3.WeightedCluster.ClusterWeight proto]

{
  "name": ...,
  "cluster_header": ...,
  "weight": {...},
  "metadata_match": {...},
  "request_headers_to_add": [],
  "request_headers_to_remove": [],
  "response_headers_to_add": [],
  "response_headers_to_remove": [],
  "typed_per_filter_config": {...},
  "host_rewrite_literal": ...
}

name: (string) 只能指定 name 和 cluster_header 中的一個。上游叢集的名稱。叢集必須存在於叢集管理員配置中。

cluster_header: (string) name 和 cluster_header 只能指定其中一個。Envoy 會讀取請求標頭中由 cluster_header 指定的 HTTP 標頭值，以決定要路由到的叢集。如果找不到標頭或參考的叢集不存在，Envoy 將會回傳 404 回應。

注意

在內部，Envoy 總是使用 HTTP/2 的 :authority 標頭來表示 HTTP/1 的 Host 標頭。因此，如果嘗試比對 Host，請改為比對 :authority。

注意

如果標頭出現多次，則只會使用第一個值。

weight (權重): (UInt32Value) 叢集的權重。此值相對於其他叢集的權重。當請求符合路由時，上游叢集的選擇取決於其權重。clusters 陣列中所有項目的權重總和必須大於 0，且不得超過 uint32_t 的最大值 (4294967295)。

metadata_match (元數據比對): (config.core.v3.Metadata) 子集負載平衡器使用的可選端點元數據比對條件。只有上游叢集中具有與此欄位中設定的元數據相符的端點，才會被考慮用於負載平衡。請注意，這將與 RouteAction.metadata_match 中提供的內容合併，此處的值優先。篩選器名稱應指定為 envoy.lb。

request_headers_to_add: (repeated config.core.v3.HeaderValueOption) 指定當透過封閉的 config.route.v3.RouteAction 選擇此叢集時，要新增至請求的標頭清單。在此層級指定的標頭會先於封閉的 config.route.v3.Route、config.route.v3.VirtualHost 和 config.route.v3.RouteConfiguration 中的標頭套用。如需更多資訊，包括標頭值語法的詳細資訊，請參閱自訂請求標頭的文件。

request_headers_to_remove: (repeated string) 指定當透過封閉的 config.route.v3.RouteAction 選擇此叢集時，應從每個請求中移除的 HTTP 標頭清單。

response_headers_to_add: (repeated config.core.v3.HeaderValueOption) 指定當透過封閉的 config.route.v3.RouteAction 選擇此叢集時，要新增至回應的標頭清單。在此層級指定的標頭會先於封閉的 config.route.v3.Route、config.route.v3.VirtualHost 和 config.route.v3.RouteConfiguration 中的標頭套用。如需更多資訊，包括標頭值語法的詳細資訊，請參閱自訂請求標頭的文件。

response_headers_to_remove: (repeated string) 指定當透過封閉的 config.route.v3.RouteAction 選擇此叢集時，應從回應中移除的標頭清單。

typed_per_filter_config: (repeated map<string, Any>) 此欄位可用於提供加權叢集特定的每個篩選器配置。金鑰應與篩選器配置名稱相符。有關詳細資訊，請參閱 Http 篩選器路由特定配置。

host_rewrite_literal (主機重寫文字): (string) 表示在轉送期間，主機標頭將會被此值取代。

config.route.v3.ClusterSpecifierPlugin

[config.route.v3.ClusterSpecifierPlugin proto]

叢集指定器外掛程式的配置。

{
  "extension": {...},
  "is_optional": ...
}

extension (擴展): (config.core.v3.TypedExtensionConfig, 必要) 外掛程式的名稱及其不透明配置。

is_optional (是否為可選): (bool) 如果未設定 is_optional 或將其設定為 false，且此訊息定義的外掛程式不是受支援的類型，則包含的資源會被 NACK。如果將 is_optional 設定為 true，則不會因此而 NACK 該資源。在這種情況下，參考此外掛程式名稱的路由不會被視為非法配置，但如果選擇了該路由，則會導致失敗。

config.route.v3.RouteMatch

[config.route.v3.RouteMatch proto]

{
  "prefix": ...,
  "path": ...,
  "safe_regex": {...},
  "connect_matcher": {...},
  "path_separated_prefix": ...,
  "path_match_policy": {...},
  "case_sensitive": {...},
  "runtime_fraction": {...},
  "headers": [],
  "query_parameters": [],
  "grpc": {...},
  "tls_context": {...},
  "dynamic_metadata": []
}

prefix (前綴)

(string) 如果指定，則路由是前綴規則，表示前綴必須與 :path 標頭的開頭相符。

prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy 必須設定其中一個。

path (路徑)

(string) 如果指定，則路由是精確路徑規則，表示路徑必須在移除查詢字串後，與 :path 標頭完全相符。

prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy 必須設定其中一個。

safe_regex (安全正規表達式)

(type.matcher.v3.RegexMatcher) 如果指定，則路由是正規表達式規則，表示正規表達式必須在移除查詢字串後，與 :path 標頭相符。整個路徑（不含查詢字串）必須與正規表達式相符。如果只有 :path 標頭的子序列與正規表達式相符，則規則將不會相符。

prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy 必須設定其中一個。

connect_matcher

(config.route.v3.RouteMatch.ConnectMatcher) 如果使用此作為比對器，則比對器只會比對 CONNECT 或 CONNECT-UDP 請求。請注意，這不會比對其他延伸的 CONNECT 請求（WebSocket 之類），因為它們在 Envoy 中會被標準化為 HTTP/1.1 樣式的升級。這是比對 HTTP/1.1 的 CONNECT 請求的唯一方法。對於 HTTP/2 和 HTTP/3，如果擴充的 CONNECT 請求具有路徑，則如果存在路徑，路徑比對器將會起作用。請注意，Envoy 中的 CONNECT 支援目前被視為 Alpha 版本。

prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy 必須設定其中一個。

path_separated_prefix (路徑分隔前綴)

(string) 如果指定，則路由是路徑分隔前綴規則，表示 :path 標頭（不含查詢字串）必須完全符合 path_separated_prefix，或者以其為前綴，後接 /。

例如，/api/dev 將會比對 /api/dev、/api/dev/、/api/dev/v1 和 /api/dev?param=true，但不會比對 /api/developer。

預期值不包含 ? 或 #，且不會以 / 結尾。

prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy 必須設定其中一個。

path_match_policy (路徑比對策略)

(config.core.v3.TypedExtensionConfig)

提示

此擴充類別具有以下已知擴充功能

envoy.path.match.uri_template.uri_template_matcher

prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy 必須設定其中一個。

case_sensitive (區分大小寫): (BoolValue) 表示前綴/路徑比對應區分大小寫。預設值為 true。忽略安全正規表達式比對。

runtime_fraction (執行階段百分比): (config.core.v3.RuntimeFractionalPercent) 表示路由還應比對執行階段金鑰。每次考慮路由是否比對時，它也必須屬於此欄位所指示的相符百分比。對於某些分數 N/D，會選擇 [0,D) 範圍內的隨機數字。如果該數字小於等於分子 N 的值，或者如果金鑰不存在，則為預設值，路由器會繼續評估其餘的比對條件。執行階段百分比路由配置可用於以漸進的方式推出路由變更，而無需完整程式碼/配置部署。有關其他文件，請參閱流量轉移文件。

注意

這個欄位的解析方式是，執行階段金鑰的資料可以用 JSON/YAML 表示的 FractionalPercent proto 來呈現，也可以用整數表示，並假設該值是 100 分的整數百分比。例如，執行階段金鑰查詢傳回值「42」，會被解析為分子為 42，分母為 HUNDRED 的 FractionalPercent。這樣可以保留舊有的語義。

headers: (repeated config.route.v3.HeaderMatcher) 指定路由應匹配的一組標頭。路由器會檢查請求的標頭是否與路由組態中指定的所有標頭匹配。如果路由中的所有標頭都存在於請求中，且具有相同的值（或基於是否存在，如果組態中沒有值欄位），則會發生匹配。

query_parameters: (repeated config.route.v3.QueryParameterMatcher) 指定路由應匹配的一組 URL 查詢參數。路由器會檢查來自 path 標頭的查詢字串是否與指定的所有查詢參數匹配。如果指定的查詢參數數量不為零，則它們都必須與 path 標頭的查詢字串匹配才會發生匹配。如果查詢參數重複，則只會考慮每個鍵的第一個值。

注意

如果在使用 grpc_json_transcoder 時，使用查詢參數傳遞請求訊息欄位，則轉碼後的訊息欄位可能會不同。查詢參數會進行 URL 編碼，但訊息欄位不會。例如，如果查詢參數是「foo%20bar」，則訊息欄位會是「foo bar」。

grpc: (config.route.v3.RouteMatch.GrpcRouteMatchOptions) 如果指定，則只會匹配 gRPC 請求。路由器會檢查 content-type 標頭是否具有 application/grpc 或各種 application/grpc+ 值之一。

tls_context: (config.route.v3.RouteMatch.TlsContextMatchOptions) 如果指定，則用戶端 TLS 內容將會與定義的匹配選項進行匹配。

dynamic_metadata: (repeated type.matcher.v3.MetadataMatcher) 指定路由應匹配的一組動態中繼資料匹配器。路由器會檢查動態中繼資料是否與指定的所有動態中繼資料匹配器匹配。如果指定的動態中繼資料匹配器數量不為零，則它們都必須與動態中繼資料匹配才會發生匹配。

config.route.v3.RouteMatch.GrpcRouteMatchOptions

[config.route.v3.RouteMatch.GrpcRouteMatchOptions proto]

config.route.v3.RouteMatch.TlsContextMatchOptions

[config.route.v3.RouteMatch.TlsContextMatchOptions proto]

{
  "presented": {...},
  "validated": {...}
}

presented: (BoolValue) 如果指定，則路由將會根據是否呈現憑證進行匹配。如果未指定，則在路由匹配時，不會考慮憑證呈現狀態（true 或 false）。

validated: (BoolValue) 如果指定，則路由將會根據是否驗證憑證進行匹配。如果未指定，則在路由匹配時，不會考慮憑證驗證狀態（true 或 false）。

警告

目前不會在 TLS 會話恢復時執行用戶端憑證驗證。對於恢復的 TLS 會話，只有當 validated 為 false 時，路由才會匹配，無論用戶端 TLS 憑證是否有效。

此問題唯一已知的解決方法是完全停用 TLS 會話恢復，方法是在 DownstreamTlsContext 上同時設定 disable_stateless_session_resumption 和 disable_stateful_session_resumption。

config.route.v3.RouteMatch.ConnectMatcher

[config.route.v3.RouteMatch.ConnectMatcher proto]

用於匹配 CONNECT 或 CONNECT-UDP 請求的可延伸訊息。

config.route.v3.CorsPolicy

[config.route.v3.CorsPolicy proto]

CORS 策略組態。

注意

這個訊息已被棄用。請使用篩選器擴充中的 CorsPolicy 作為替代方案。

{
  "allow_origin_string_match": [],
  "allow_methods": ...,
  "allow_headers": ...,
  "expose_headers": ...,
  "max_age": ...,
  "allow_credentials": {...},
  "filter_enabled": {...},
  "shadow_enabled": {...},
  "allow_private_network_access": {...},
  "forward_not_matching_preflights": {...}
}

allow_origin_string_match: (repeated type.matcher.v3.StringMatcher) 指定匹配允許來源的字串模式。如果任何字串匹配器匹配，則允許來源。

allow_methods: (string) 指定 access-control-allow-methods 標頭的內容。

allow_headers: (string) 指定 access-control-allow-headers 標頭的內容。

expose_headers: (string) 指定 access-control-expose-headers 標頭的內容。

max_age: (string) 指定 access-control-max-age 標頭的內容。

allow_credentials: (BoolValue) 指定資源是否允許憑證。

filter_enabled

(config.core.v3.RuntimeFractionalPercent) 指定啟用 CORS 篩選器的請求百分比。

如果未指定 enabled、filter_enabled 和 shadow_enabled，則會為 100% 的請求啟用 CORS 篩選器。

如果指定 runtime_key，則 Envoy 會查詢執行階段金鑰，以取得要篩選的請求百分比。

shadow_enabled

(config.core.v3.RuntimeFractionalPercent) 指定將評估和追蹤 CORS 策略但不強制執行的請求百分比。

此欄位旨在當 filter_enabled 和 enabled 關閉時使用。其中一個欄位必須明確停用篩選器，此設定才會生效。

如果指定 runtime_key，Envoy 會查詢執行階段金鑰，以取得要評估和追蹤請求的 Origin，以判斷其是否有效，但不會強制執行任何策略的請求百分比。

allow_private_network_access

(BoolValue) 指定是否允許目標伺服器的 IP 位址比發出請求的起始端更私有的請求。

更多詳細資訊請參閱 https://developer.chrome.com/blog/private-network-access-preflight。

forward_not_matching_preflights: (BoolValue) 指定是否應將未匹配已配置允許來源的預檢請求轉發到上游。預設值為 true。

config.route.v3.RouteAction

[config.route.v3.RouteAction proto]

{
  "cluster": ...,
  "cluster_header": ...,
  "weighted_clusters": {...},
  "cluster_specifier_plugin": ...,
  "inline_cluster_specifier_plugin": {...},
  "cluster_not_found_response_code": ...,
  "metadata_match": {...},
  "prefix_rewrite": ...,
  "regex_rewrite": {...},
  "path_rewrite_policy": {...},
  "host_rewrite_literal": ...,
  "auto_host_rewrite": {...},
  "host_rewrite_header": ...,
  "host_rewrite_path_regex": {...},
  "append_x_forwarded_host": ...,
  "timeout": {...},
  "idle_timeout": {...},
  "early_data_policy": {...},
  "retry_policy": {...},
  "request_mirror_policies": [],
  "priority": ...,
  "rate_limits": [],
  "include_vh_rate_limits": {...},
  "hash_policy": [],
  "cors": {...},
  "max_grpc_timeout": {...},
  "grpc_timeout_offset": {...},
  "upgrade_configs": [],
  "internal_redirect_policy": {...},
  "internal_redirect_action": ...,
  "max_internal_redirects": {...},
  "hedge_policy": {...},
  "max_stream_duration": {...}
}

cluster

(string) 指示應將請求路由到的上游叢集。

必須設定 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 其中之一。

cluster_header

(string) Envoy 會透過從請求標頭中讀取 cluster_header 所命名的 HTTP 標頭的值來決定要路由到的叢集。如果找不到標頭或參考的叢集不存在，Envoy 會傳回 404 回應。

注意

在內部，Envoy 總是使用 HTTP/2 的 :authority 標頭來表示 HTTP/1 的 Host 標頭。因此，如果嘗試比對 Host，請改為比對 :authority。

注意

如果標頭出現多次，則只會使用第一個值。

必須設定 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 其中之一。

weighted_clusters

(config.route.v3.WeightedCluster) 可以為給定的路由指定多個上游叢集。請求會根據指派給每個叢集的權重路由到其中一個上游叢集。有關其他文件，請參閱流量分割。

必須設定 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 其中之一。

cluster_specifier_plugin

(string) 用於決定此路由請求叢集的叢集指定器外掛程式名稱。叢集指定器外掛程式名稱必須在叢集指定器外掛程式中，以及在 name 欄位中定義。

必須設定 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 其中之一。

inline_cluster_specifier_plugin

(config.route.v3.ClusterSpecifierPlugin) 自訂叢集指定器外掛程式設定，用於決定此路由上的請求所使用的叢集。

必須設定 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 其中之一。

cluster_not_found_response_code: (config.route.v3.RouteAction.ClusterNotFoundResponseCode) 當找不到已設定的叢集時，要使用的 HTTP 狀態碼。預設的回應碼為 503 Service Unavailable。

metadata_match (元數據比對): (config.core.v3.Metadata) 子集負載平衡器使用的可選端點中繼資料比對條件。只有上游叢集中符合此欄位設定的中繼資料的端點才會被考慮用於負載平衡。如果使用 weighted_clusters，中繼資料將會被合併，且該處提供的值將具有優先權。篩選器名稱應指定為 envoy.lb。

prefix_rewrite

(string) 表示在轉送期間，應將符合的前綴（或路徑）與此值交換。此選項允許應用程式 URL 的根目錄與反向代理層公開的路徑不同。路由器篩選器會將重寫之前的原始路徑放置在 x-envoy-original-path 標頭中。

只能指定 regex_rewrite、path_rewrite_policy 或 prefix_rewrite 其中之一。

注意

請仔細注意在路由的匹配前綴值中使用尾部斜線。從路徑中移除前綴需要多個路由來處理所有情況。例如，將 /prefix 重寫為 / 以及將 /prefix/etc 重寫為 /etc 無法在單一路由中完成，如下面的設定項目所示

- match:
    prefix: "/prefix/"
  route:
    prefix_rewrite: "/"
- match:
    prefix: "/prefix"
  route:
    prefix_rewrite: "/"

在設定中有以上項目，對 /prefix 的請求將會被移除為 /，而對 /prefix/etc 的請求將會被移除為 /etc。

regex_rewrite

(type.matcher.v3.RegexMatchAndSubstitute) 表示在轉送期間，應重寫符合模式的路徑部分，甚至允許將模式中的捕獲組替換為新的路徑，如重寫替換字串所指定。這對於允許以可感知具有可變內容（如識別符）的區段的方式重寫應用程式路徑非常有用。路由器篩選器會將重寫之前的原始路徑放置在 x-envoy-original-path 標頭中。

只能指定 regex_rewrite、prefix_rewrite 或 path_rewrite_policy 其中之一。

使用 Google RE2 引擎的範例

路徑模式 ^/service/([^/]+)(/.*)$ 與替換字串 \2/instance/\1 配對，會將 /service/foo/v1/api 轉換為 /v1/api/instance/foo。
模式 one 與替換字串 two 配對，會將 /xxx/one/yyy/one/zzz 轉換為 /xxx/two/yyy/two/zzz。
模式 ^(.*?)one(.*)$ 與替換字串 \1two\2 配對，將只會替換第一個出現的 one，將路徑 /xxx/one/yyy/one/zzz 轉換為 /xxx/two/yyy/one/zzz。
模式 (?i)/xxx/ 與替換字串 /yyy/ 配對，會執行不區分大小寫的比對，並將路徑 /aaa/XxX/bbb 轉換為 /aaa/yyy/bbb。

path_rewrite_policy

(config.core.v3.TypedExtensionConfig)

提示

此擴充類別具有以下已知擴充功能

envoy.path.rewrite.uri_template.uri_template_rewriter

host_rewrite_literal (主機重寫文字)

(string) 表示在轉送期間，主機標頭將會與此值交換。如果設定 append_x_forwarded_host，使用此選項將會附加 x-forwarded-host 標頭。

只能設定 host_rewrite_literal、auto_host_rewrite、host_rewrite_header、host_rewrite_path_regex 其中之一。

auto_host_rewrite

(BoolValue) 表示在轉送期間，主機標頭將會與叢集管理員選擇的上游主機的主機名稱交換。此選項僅適用於路由的目的地叢集類型為 strict_dns 或 logical_dns，或當 hostname 欄位不為空時。將此值設定為 true 並使用其他叢集類型則沒有效果。如果設定 append_x_forwarded_host，使用此選項將會附加 x-forwarded-host 標頭。

只能設定 host_rewrite_literal、auto_host_rewrite、host_rewrite_header、host_rewrite_path_regex 其中之一。

host_rewrite_header

(string) 表示在轉送期間，主機標頭將會與給定的下游或自訂標頭的內容交換。如果標頭值為空，主機標頭將保持不變。如果設定 append_x_forwarded_host，使用此選項將會附加 x-forwarded-host 標頭。

注意

請注意使用此選項可能造成的安全性隱患。提供的標頭必須來自受信任的來源。

注意

如果標頭出現多次，則只會使用第一個值。

只能設定 host_rewrite_literal、auto_host_rewrite、host_rewrite_header、host_rewrite_path_regex 其中之一。

host_rewrite_path_regex

(type.matcher.v3.RegexMatchAndSubstitute) 表示在轉送期間，主機標頭將會與在移除查詢和片段的路徑值上執行的 regex 替換結果交換。這對於在路徑區段和子網域之間轉換可變內容非常有用。如果設定 append_x_forwarded_host，使用此選項將會附加 x-forwarded-host 標頭。

例如，使用以下設定

host_rewrite_path_regex:
  pattern:
    google_re2: {}
    regex: "^/(.+)/.+$"
  substitution: \1

給定路徑 /envoyproxy.io/some/path，會將主機標頭重寫為 envoyproxy.io。

只能設定 host_rewrite_literal、auto_host_rewrite、host_rewrite_header、host_rewrite_path_regex 其中之一。

append_x_forwarded_host: (bool) 如果設定此值，則主機重寫動作（host_rewrite_literal、auto_host_rewrite、host_rewrite_header 或 host_rewrite_path_regex 其中之一）會導致主機標頭的原始值（如果有的話）附加到 x-forwarded-host HTTP 標頭，前提是它與附加的最後一個值不同。

timeout: (Duration) 指定路由的上游逾時。如果未指定，則預設值為 15 秒。此逾時時間範圍從整個下游請求（即資料流結束）處理完成時開始，到上游回應完全處理完成時結束。值為 0 將會停用路由的逾時。

注意

此逾時時間包含所有重試。另請參閱 x-envoy-upstream-rq-timeout-ms、x-envoy-upstream-rq-per-try-timeout-ms 和重試概述。

idle_timeout

(Duration) 指定路由的閒置逾時時間。如果未指定，則不會有每個路由的閒置逾時，儘管連線管理器的全域 stream_idle_timeout 仍然適用。值為 0 將完全停用路由的閒置逾時，即使已設定連線管理器的串流閒置逾時也一樣。

閒置逾時與 timeout 不同，後者提供上游回應時間的上限；idle_timeout 則是限制請求串流可以閒置的時間。

在標頭解碼後，閒置逾時將適用於下游和上游請求事件。每次處理串流的標頭或資料的編碼/解碼事件時，計時器都會重置。如果逾時觸發，且尚未收到上游回應標頭，則串流將以 408 Request Timeout 錯誤代碼終止，否則會發生串流重置。

如果設定了過載動作 “envoy.overload_actions.reduce_timeouts”，則此逾時時間會根據 HTTP_DOWNSTREAM_STREAM_IDLE 的值進行縮放。

early_data_policy

(config.core.v3.TypedExtensionConfig) 指定如何透過 TLS Early Data 發送請求。如果不存在，則允許安全的 HTTP 請求在 Early Data 上發送。

提示

此擴充類別具有以下已知擴充功能

envoy.route.early_data_policy.default

retry_policy: (config.route.v3.RetryPolicy) 表示路由具有重試策略。請注意，如果設定此項，它將完全優先於虛擬主機層級的重試策略（例如：策略不會合併，最內部的策略會變成強制執行的策略）。

request_mirror_policies: (repeated config.route.v3.RouteAction.RequestMirrorPolicy) 指定一組路由請求鏡像策略。它完全優先於虛擬主機和路由配置鏡像策略。也就是說，策略不會合併，最明確的非空策略會變成鏡像策略。

priority: (config.core.v3.RoutingPriority) 可選地指定路由優先順序。

rate_limits: (repeated config.route.v3.RateLimit) 指定一組可以應用於路由的速率限制配置。

include_vh_rate_limits

(BoolValue) 指定速率限制篩選器是否應包含虛擬主機速率限制。預設情況下，如果路由配置了速率限制，則虛擬主機的 rate_limits 不會應用於請求。

此欄位已棄用。請使用 vh_rate_limits

hash_policy: (repeated config.route.v3.RouteAction.HashPolicy) 指定用於環形雜湊負載平衡的雜湊策略列表。每個雜湊策略都會單獨評估，並將組合結果用於路由請求。組合方法是確定性的，因此相同的雜湊策略列表將產生相同的雜湊。由於雜湊策略會檢查請求的特定部分，因此它可能無法產生雜湊（例如，如果雜湊的標頭不存在）。如果（且僅當）所有設定的雜湊策略都無法產生雜湊，則不會為該路由產生雜湊。在這種情況下，行為與未指定任何雜湊策略時相同（也就是說，環形雜湊負載平衡器將選擇一個隨機的後端）。如果雜湊策略的「terminal」屬性設定為 true，且已產生雜湊，則會立即返回該雜湊，並忽略雜湊策略列表的其餘部分。

cors: (config.route.v3.CorsPolicy) 表示路由具有 CORS 策略。如果在 Route.typed_per_filter_config 或 WeightedCluster.ClusterWeight.typed_per_filter_config 中找到相關的 cors 策略，則會忽略此欄位。

注意

此選項已棄用。請使用 Route.typed_per_filter_config 或 WeightedCluster.ClusterWeight.typed_per_filter_config 來配置 CORS HTTP 篩選器。

max_grpc_timeout: (Duration) 已由 grpc_timeout_header_max 棄用如果存在，且請求是 gRPC 請求，則使用 grpc-timeout 標頭，或其預設值（無限大）而不是 timeout，但將應用逾時限制為此處指定的最大值。如果設定為 0，則 gRPC 請求允許的最大逾時時間為無限大。如果完全未設定，則不會使用 grpc-timeout 標頭，且 gRPC 請求會像其他請求一樣使用 timeout 或其預設值逾時。這可以用來防止由於 gRPC 串流模式中 gRPC 請求和回應之間潛在的長時間間隔而導致意外的上游請求逾時。

注意

如果使用 x-envoy-upstream-rq-timeout-ms 指定逾時，則當兩者都存在時，它將優先於 grpc-timeout 標頭。另請參閱 x-envoy-upstream-rq-timeout-ms、x-envoy-upstream-rq-per-try-timeout-ms，以及重試概述。

grpc_timeout_offset: (Duration) 已由 grpc_timeout_header_offset 棄用。如果存在，Envoy 會從標頭中減去提供的持續時間來調整 grpc-timeout 標頭提供的逾時時間。這在允許 Envoy 將其全域逾時設定為小於呼叫用戶端所設定的截止時間時很有用，這使得 Envoy 更可能處理逾時，而不是讓用戶端取消呼叫。只有在提供的 grpc_timeout 大於 offset 時才會應用 offset。這可確保 offset 只會減少逾時時間，而永遠不會將其設定為 0（表示無限大）。

upgrade_configs: (repeated config.route.v3.RouteAction.UpgradeConfig)

internal_redirect_policy: (config.route.v3.InternalRedirectPolicy) 如果存在，Envoy 會嘗試遵循上游重新導向回應，而不是將回應代理回下游。上游重新導向回應由 redirect_response_codes 定義。

internal_redirect_action: (config.route.v3.RouteAction.InternalRedirectAction)

max_internal_redirects

(UInt32Value) 只有當下游請求遇到的先前內部重新導向次數低於此值，且 internal_redirect_action 設定為 HANDLE_INTERNAL_REDIRECT 時，才會處理內部重新導向。如果下游請求在多個路由之間透過內部重新導向跳轉，則第一個達到此閾值或將 internal_redirect_action 設定為 PASS_THROUGH_INTERNAL_REDIRECT 的路由會將重新導向傳回下游。

如果未指定，則最多會遵循一次重新導向。

hedge_policy: (config.route.v3.HedgePolicy) 表示路由具有對沖策略。請注意，如果設定此項，它將完全優先於虛擬主機層級的對沖策略（例如：策略不會合併，最內部的策略會變成強制執行的策略）。

max_stream_duration: (config.route.v3.RouteAction.MaxStreamDuration) 指定此路由的最大串流持續時間。

config.route.v3.RouteAction.RequestMirrorPolicy

[config.route.v3.RouteAction.RequestMirrorPolicy proto]

路由器能夠將流量從一個叢集鏡像到另一個叢集。目前的實作是「發送後不理」，表示 Envoy 不會等待陰影叢集回應，而是返回來自主要叢集的回應。所有正常的統計資料都會為陰影叢集收集，這使得此功能對於測試很有用。

在鏡像期間，主機/授權標頭會被更改，使得附加 -shadow。這對於記錄很有用。例如，cluster1 會變成 cluster1-shadow。可以透過將 disable_shadow_host_suffix_append 設定為 true 來停用此行為。

注意

如果主要叢集不存在，則不會觸發鏡像。

注意

鏡像不支援 Http CONNECT 和升級。

{
  "cluster": ...,
  "cluster_header": ...,
  "runtime_fraction": {...},
  "trace_sampled": {...},
  "disable_shadow_host_suffix_append": ...
}

cluster: (string) 只能指定 cluster 和 cluster_header 中的一個。指定請求將鏡像到的叢集。該叢集必須存在於叢集管理器配置中。

cluster_header: (字串) cluster 和 cluster_header 只能指定其中一個。Envoy 將會從請求標頭中讀取由 cluster_header 指定的 HTTP 標頭值，以決定要路由到的叢集。只會使用標頭中的第一個值，如果標頭中找不到該值，則不會發生影子請求。Envoy 不會在主要叢集返回響應之前等待影子叢集響應。

注意

在內部，Envoy 總是使用 HTTP/2 的 :authority 標頭來表示 HTTP/1 的 Host 標頭。因此，如果嘗試比對 Host，請改為比對 :authority。

注意

如果標頭出現多次，則只會使用第一個值。

runtime_fraction (執行階段百分比)

(config.core.v3.RuntimeFractionalPercent) 如果未指定，則所有對目標叢集的請求都將被鏡像。

如果指定了此欄位，則此欄位的優先級高於 runtime_key 欄位，並且請求還必須符合此欄位指示的匹配百分比。

對於某個分數 N/D，會選擇範圍 [0,D) 中的隨機數。如果該數字 <= 分子 N 的值，或者如果該鍵不存在（預設值），則該請求將被鏡像。

trace_sampled: (BoolValue) 決定是否應該對追蹤跨度進行取樣。預設值為 true。

disable_shadow_host_suffix_append: (bool) 禁用在陰影 Host 標頭上附加 -shadow 後綴。預設值為 false。

config.route.v3.RouteAction.HashPolicy

[config.route.v3.RouteAction.HashPolicy proto]

指定上游叢集使用雜湊負載平衡器時的路由雜湊策略。

{
  "header": {...},
  "cookie": {...},
  "connection_properties": {...},
  "query_parameter": {...},
  "filter_state": {...},
  "terminal": ...
}

header

(config.route.v3.RouteAction.HashPolicy.Header) 標頭雜湊策略。

header、cookie、connection_properties、query_parameter、filter_state 中必須恰好設定一個。

connection_properties

(config.route.v3.RouteAction.HashPolicy.ConnectionProperties) 連線屬性雜湊策略。

header、cookie、connection_properties、query_parameter、filter_state 中必須恰好設定一個。

query_parameter

(config.route.v3.RouteAction.HashPolicy.QueryParameter) 查詢參數雜湊策略。

header、cookie、connection_properties、query_parameter、filter_state 中必須恰好設定一個。

filter_state

(config.route.v3.RouteAction.HashPolicy.FilterState) 過濾器狀態雜湊策略。

header、cookie、connection_properties、query_parameter、filter_state 中必須恰好設定一個。

terminal

(bool) 短路雜湊計算的標誌。此欄位提供一種「回退」風格的配置：「如果終端策略不起作用，則回退到其餘的策略列表」，這可以在終端策略起作用時節省時間。

如果為 true，且已計算出雜湊，則忽略其餘的雜湊策略列表。例如，如果配置了以下雜湊方法

specifier

terminal

標頭 A

true

標頭 B

false

標頭 C

false

如果策略「標頭 A」產生雜湊，則 generateHash 過程結束，因為它是終端策略。

config.route.v3.RouteAction.HashPolicy.Header

[config.route.v3.RouteAction.HashPolicy.Header proto]

{
  "header_name": ...,
  "regex_rewrite": {...}
}

header_name: (字串, 必要) 將用於獲取雜湊鍵的請求標頭的名稱。如果請求標頭不存在，則不會產生雜湊。

regex_rewrite: (type.matcher.v3.RegexMatchAndSubstitute) 如果指定，請求標頭值將被重寫並用於產生雜湊鍵。

config.route.v3.RouteAction.HashPolicy.CookieAttribute

[config.route.v3.RouteAction.HashPolicy.CookieAttribute proto]

CookieAttribute 定義用於為 HTTP Cookie 新增額外屬性的 API。

{
  "name": ...,
  "value": ...
}

name: (字串, 必要) Cookie 屬性的名稱。

value: (字串) Cookie 屬性的可選值。

config.route.v3.RouteAction.HashPolicy.ConnectionProperties

[config.route.v3.RouteAction.HashPolicy.ConnectionProperties proto]

{
  "source_ip": ...
}

source_ip: (bool) 根據來源 IP 位址進行雜湊。

config.route.v3.RouteAction.HashPolicy.QueryParameter

[config.route.v3.RouteAction.HashPolicy.QueryParameter proto]

{
  "name": ...
}

name: (字串, 必要) 將用於獲取雜湊鍵的 URL 查詢參數的名稱。如果參數不存在，則不會產生雜湊。查詢參數名稱區分大小寫。如果重複查詢參數，則僅會考慮第一個值。

config.route.v3.RouteAction.HashPolicy.FilterState

[config.route.v3.RouteAction.HashPolicy.FilterState proto]

{
  "key": ...
}

key: (字串, 必要) 每個請求 filterState 中物件的名稱，該物件為 Envoy::Hashable 物件。如果沒有與該鍵相關聯的資料，或者儲存的物件不是 Envoy::Hashable，則不會產生雜湊。

config.route.v3.RouteAction.UpgradeConfig

[config.route.v3.RouteAction.UpgradeConfig proto]

允許在每個路由的基礎上啟用和停用升級。這會覆寫 HttpConnectionManager 中指定的任何已啟用/停用升級篩選器鏈 upgrade_configs，但不影響其中指定的任何自訂篩選器鏈。

{
  "upgrade_type": ...,
  "enabled": {...},
  "connect_config": {...}
}

upgrade_type: (字串, 必要) 此升級的不區分大小寫的名稱，例如「websocket」。對於 upgrade_configs 中存在的每個升級類型，具有 Upgrade: [upgrade_type] 的請求將被代理到上游。

enabled: (BoolValue) 決定此路由上是否提供升級。預設值為 true。

connect_config: (config.route.v3.RouteAction.UpgradeConfig.ConnectConfig) 將資料作為原始資料酬載傳送到上游的配置。這用於 CONNECT 請求，當將 CONNECT 酬載作為原始 TCP 轉送時。請注意，Envoy 中目前認為 CONNECT 支援為 alpha 版本。

config.route.v3.RouteAction.UpgradeConfig.ConnectConfig

[config.route.v3.RouteAction.UpgradeConfig.ConnectConfig proto]

將資料作為原始資料酬載傳送到上游的配置。這用於 CONNECT 或 POST 請求，當將請求酬載作為原始 TCP 轉送時。

{
  "proxy_protocol_config": {...},
  "allow_post": ...
}

proxy_protocol_config: (config.core.v3.ProxyProtocolConfig) 如果存在，代理通訊協定標頭將附加到傳送到上游的 CONNECT 酬載。

allow_post: (bool) 如果設定，該路由也將允許將 POST 酬載作為原始 TCP 轉送。

config.route.v3.RouteAction.MaxStreamDuration

[config.route.v3.RouteAction.MaxStreamDuration proto]

{
  "max_stream_duration": {...},
  "grpc_timeout_header_max": {...},
  "grpc_timeout_header_offset": {...}
}

max_stream_duration: (Duration) 指定路由上允許的最大資料流持續時間。如果未指定，則會使用 max_stream_duration 欄位中的值，該值來自 HttpConnectionManager.common_http_protocol_options。如果此欄位明確設定為零，則會針對此路由停用任何 HttpConnectionManager max_stream_duration 超時。

grpc_timeout_header_max: (Duration) 如果存在，且請求包含 grpc-timeout 標頭，則使用該值作為 max_stream_duration，但將套用的超時限制為此處指定的最大值。如果設定為 0，則使用 grpc-timeout 標頭而不進行修改。

grpc_timeout_header_offset: (Duration) 如果存在，Envoy 會調整 grpc-timeout 標頭提供的逾時時間，方法是從該標頭減去提供的持續時間。這對於允許 Envoy 將其全域逾時時間設定為小於呼叫客戶端施加的截止期限非常有用，這使得 Envoy 更有可能處理逾時，而不是讓呼叫被客戶端取消。如果套用偏移量後，產生的逾時時間為零或負數，則串流會立即逾時。

列舉 config.route.v3.RouteAction.ClusterNotFoundResponseCode

[config.route.v3.RouteAction.ClusterNotFoundResponseCode proto]

SERVICE_UNAVAILABLE: (預設) ⁣HTTP 狀態碼 - 503 Service Unavailable (服務不可用)。

NOT_FOUND: ⁣HTTP 狀態碼 - 404 Not Found (找不到)。

INTERNAL_SERVER_ERROR: ⁣HTTP 狀態碼 - 500 Internal Server Error (內部伺服器錯誤)。

列舉 config.route.v3.RouteAction.InternalRedirectAction

[config.route.v3.RouteAction.InternalRedirectAction proto]

設定內部重新導向行為。

PASS_THROUGH_INTERNAL_REDIRECT: (預設) ⁣

HANDLE_INTERNAL_REDIRECT: ⁣

config.route.v3.RetryPolicy

[config.route.v3.RetryPolicy proto]

HTTP 重試架構概述。

{
  "retry_on": ...,
  "num_retries": {...},
  "per_try_timeout": {...},
  "per_try_idle_timeout": {...},
  "retry_priority": {...},
  "retry_host_predicate": [],
  "retry_options_predicates": [],
  "host_selection_retry_max_attempts": ...,
  "retriable_status_codes": [],
  "retry_back_off": {...},
  "rate_limited_retry_back_off": {...},
  "retriable_headers": [],
  "retriable_request_headers": []
}

retry_on: (字串) 指定發生重試的條件。這些條件與x-envoy-retry-on和x-envoy-retry-grpc-on的文件中記錄的條件相同。

num_retries: (UInt32Value) 指定允許的重試次數。此參數為選填，預設值為 1。這些條件與x-envoy-max-retries的文件中記錄的條件相同。

per_try_timeout: (Duration) 指定每次重試嘗試 (包括初始嘗試) 的非零上游逾時時間。此參數為選填。套用的條件與x-envoy-upstream-rq-per-try-timeout-ms的文件中記錄的條件相同。

注意

如果未指定，Envoy 將使用請求的全域路由逾時。因此，當使用基於5xx的重試策略時，逾時的請求將不會重試，因為總逾時預算將已用完。

per_try_idle_timeout: (Duration) 指定每次重試嘗試 (包括初始嘗試) 的上游閒置逾時時間。此參數為選填，如果不存在，則沒有每次嘗試的閒置逾時時間。每次嘗試的閒置逾時的語義與 HTTP 連線管理員強制執行的路由閒置逾時和串流閒置逾時類似。不同之處在於，此閒置逾時時間由路由器針對每次單獨的嘗試強制執行，因此在所有先前的篩選器執行之後，而不是在其他閒置逾時時間執行所有先前的篩選器之前執行。當總請求逾時時間受限於重試次數和per_try_timeout，但希望確保每次嘗試都有進展時，此逾時時間很有用。另請注意，與per_try_timeout類似，此閒置計時器在路由器收到整個請求且已取得連線池連線之後才會開始。與per_try_timeout不同，閒置計時器會在回應開始串流回下游用戶端後繼續。這可確保回應資料持續取得進展，而不會使用 HTTP 連線管理員的閒置逾時時間之一。

retry_priority: (config.route.v3.RetryPolicy.RetryPriority) 指定 RetryPriority 的實作，該實作用於確定重試所用優先順序之間的負載分配。請參閱重試外掛程式組態以取得更多詳細資訊。

retry_host_predicate: (重複 config.route.v3.RetryPolicy.RetryHostPredicate) 指定在選擇主機進行重試時將參考的 RetryHostPredicate 集合。如果任何述詞拒絕主機，將會重新嘗試主機選擇。請參閱重試外掛程式組態以取得更多詳細資訊。

retry_options_predicates: (重複 config.core.v3.TypedExtensionConfig) 重試選項述詞，這些述詞將在重試請求之前套用。這些述詞允許自訂重試之間的請求行為。[當有內建擴充功能時]

host_selection_retry_max_attempts: (int64) 在放棄之前重新嘗試主機選擇的最大次數，此時將路由到上次選擇的主機。如果未指定，則預設為重試一次。

retriable_status_codes: (重複 uint32) 除了 retry_on 指定的狀態碼外，還應觸發重試的 HTTP 狀態碼。

retry_back_off: (config.route.v3.RetryPolicy.RetryBackOff) 指定控制指數重試退避的參數。此參數為選填，在這種情況下，預設基本間隔為 25 毫秒，如果設定，則為 upstream.base_retry_backoff_ms 執行時間參數的目前值。預設最大間隔為基本間隔的 10 倍。x-envoy-max-retries的文件中說明了 Envoy 的退避演算法。

rate_limited_retry_back_off: (config.route.v3.RetryPolicy.RateLimitedRetryBackOff) 指定在請求受到上游伺服器速率限制時使用的重試退避策略的參數。伺服器可能會傳回類似 Retry-After 或 X-RateLimit-Reset 的回應標頭，以向用戶端提供有關重試前應等待多長時間的回饋。如果已設定，每當回應包含相符的標頭時，將使用此退避策略，而不是預設指數退避策略 (使用 retry_back_off 設定)。

retriable_headers: (重複 config.route.v3.HeaderMatcher) 如果回應中存在，則觸發重試的 HTTP 回應標頭。如果任何標頭比對與上游回應標頭相符，則將觸發重試。只有在「retriable-headers」重試策略處於作用中狀態時，才會參考該欄位。

retriable_request_headers: (重複 config.route.v3.HeaderMatcher) 必須在請求中存在的 HTTP 標頭才能嘗試重試。

config.route.v3.RetryPolicy.RetryPriority

[config.route.v3.RetryPolicy.RetryPriority proto]

{
  "name": ...,
  "typed_config": {...}
}

name: (字串, 必要)

typed_config

(Any)

提示

此擴充類別具有以下已知擴充功能

envoy.retry_priorities.previous_priorities

config.route.v3.RetryPolicy.RetryHostPredicate

[config.route.v3.RetryPolicy.RetryHostPredicate proto]

{
  "name": ...,
  "typed_config": {...}
}

name: (字串, 必要)

typed_config

(Any)

提示

此擴充類別具有以下已知擴充功能

config.route.v3.RetryPolicy.RetryBackOff

[config.route.v3.RetryPolicy.RetryBackOff proto]

{
  "base_interval": {...},
  "max_interval": {...}
}

base_interval: (Duration, 必要) 指定重試之間的基本間隔。此參數為必要參數，且必須大於零。小於 1 毫秒的值會四捨五入到 1 毫秒。請參閱x-envoy-max-retries以了解有關 Envoy 退避演算法的討論。

max_interval: (Duration) 指定重試之間的最大間隔。此參數為選填，但如果設定，則必須大於或等於 base_interval。預設值為 base_interval 的 10 倍。請參閱x-envoy-max-retries以了解有關 Envoy 退避演算法的討論。

config.route.v3.RetryPolicy.ResetHeader

[config.route.v3.RetryPolicy.ResetHeader proto]

{
  "name": ...,
  "format": ...
}

name: (string, 必要) 重設標頭的名稱。

注意

如果標頭出現多次，則只會使用第一個值。

格式: (config.route.v3.RetryPolicy.ResetHeaderFormat) 重設標頭的格式。

config.route.v3.RetryPolicy.RateLimitedRetryBackOff

[config.route.v3.RetryPolicy.RateLimitedRetryBackOff proto]

當上游伺服器限制請求速率時，所套用的重試退避策略。

給定此設定

rate_limited_retry_back_off:
  reset_headers:
  - name: Retry-After
    format: SECONDS
  - name: X-RateLimit-Reset
    format: UNIX_TIMESTAMP
  max_interval: "300s"

將會套用以下演算法

如果回應包含標頭 Retry-After，其值必須為 120 的形式（表示重試前等待的秒數的整數）。如果是這樣，此值將用作退避間隔。

否則，如果回應包含標頭 X-RateLimit-Reset，其值必須為 1595320702 的形式（表示重試時間點的整數，以 Unix 時間戳記表示，單位為秒）。如果是這樣，則會從此值減去目前時間，並將結果用作退避間隔。

否則，Envoy 將使用預設的指數退避策略。

無論使用哪種格式，如果產生的退避間隔超過 max_interval，則會捨棄該間隔，並嘗試 reset_headers 中的下一個標頭。如果為路由設定了請求逾時，則會進一步限制允許請求執行的時間長度。

為了防止許多用戶端同時在同一時間點重試，會將抖動添加到退避間隔中，因此產生的間隔取決於以下方式：random(interval, interval * 1.5)。

注意

設定 rate_limited_retry_back_off 本身不會導致請求被重試。您仍然需要設定正確的重試策略，以匹配來自上游伺服器的回應。

{
  "reset_headers": [],
  "max_interval": {...}
}

reset_headers: (重複 config.route.v3.RetryPolicy.ResetHeader, 必要) 指定要與回應匹配的重設標頭（例如 Retry-After 或 X-RateLimit-Reset）。將依序嘗試標頭，並以不區分大小寫的方式進行匹配。將使用第一個成功解析的標頭。如果沒有標頭匹配，則會改用預設的指數退避。

max_interval: (Duration) 指定 Envoy 允許的最大退避間隔。如果重設標頭包含的時間間隔長於此間隔，則會將其捨棄，並嘗試下一個標頭。預設值為 300 秒。

列舉 config.route.v3.RetryPolicy.ResetHeaderFormat

[config.route.v3.RetryPolicy.ResetHeaderFormat proto]

SECONDS: (預設) ⁣

UNIX_TIMESTAMP: ⁣

config.route.v3.HedgePolicy

[config.route.v3.HedgePolicy proto]

HTTP 請求對沖架構概觀。

{
  "hedge_on_per_try_timeout": ...
}

hedge_on_per_try_timeout

(bool) 指示在達到每次嘗試逾時時，應傳送對沖請求。這表示將發出重試，而不會重設原始請求，導致有多個上游請求正在進行中。第一個成功完成的請求將是返回給呼叫者的請求。

在任何時候，成功的響應（即不觸發任何重試條件）都將返回給用戶端。
在每次嘗試逾時之前，錯誤響應（根據重試條件）將立即重試，如果沒有剩餘重試，則返回給用戶端。
在每次嘗試逾時之後，將會捨棄錯誤響應，因為已在進行中以對沖請求形式的重試。

注意：為了使其生效，您必須具有一個 RetryPolicy，該策略至少會重試一個錯誤代碼，並指定最大重試次數。

預設值為 false。

config.route.v3.RedirectAction

[config.route.v3.RedirectAction proto]

{
  "https_redirect": ...,
  "scheme_redirect": ...,
  "host_redirect": ...,
  "port_redirect": ...,
  "path_redirect": ...,
  "prefix_rewrite": ...,
  "regex_rewrite": {...},
  "response_code": ...,
  "strip_query": ...
}

https_redirect

(bool) URL 的 scheme 部分將被替換為 "https"。

當 scheme 重定向發生時，將套用以下規則

如果來源 URI scheme 為 http 且連接埠明確設定為 :80，則在重定向後將移除連接埠
如果來源 URI scheme 為 https 且連接埠明確設定為 :443，則在重定向後將移除連接埠

只能設定 https_redirect 和 scheme_redirect 其中之一。

scheme_redirect

(string) URL 的 scheme 部分將被替換為此值。

當 scheme 重定向發生時，將套用以下規則

如果來源 URI scheme 為 http 且連接埠明確設定為 :80，則在重定向後將移除連接埠
如果來源 URI scheme 為 https 且連接埠明確設定為 :443，則在重定向後將移除連接埠

只能設定 https_redirect 和 scheme_redirect 其中之一。

host_redirect: (string) URL 的 host 部分將被替換為此值。

port_redirect: (uint32) URL 的連接埠值將被替換為此值。

path_redirect

(string) URL 的 path 部分將被替換為此值。請注意，path_redirect 中的查詢字串將覆寫請求的查詢字串，並且不會被剝離。

例如，假設我們有以下路由

match: { path: “/old-path-1” } redirect: { path_redirect: “/new-path-1” }
match: { path: “/old-path-2” } redirect: { path_redirect: “/new-path-2”, strip-query: “true” }
match: { path: “/old-path-3” } redirect: { path_redirect: “/new-path-3?foo=1”, strip_query: “true” }

如果請求 uri 為 “/old-path-1?bar=1”，則用戶將被重定向到 “/new-path-1?bar=1”
如果請求 uri 為 “/old-path-2?bar=1”，則用戶將被重定向到 “/new-path-2”
如果請求 uri 為 “/old-path-3?bar=1”，則用戶將被重定向到 “/new-path-3?foo=1”

只能設定 path_redirect、 prefix_rewrite 和 regex_rewrite 其中之一。

prefix_rewrite

(string) 表示在重定向期間，應將匹配的前綴（或路徑）替換為此值。此選項允許根據請求動態建立重定向 URL。

注意

請注意 RouteAction 的 prefix_rewrite 中提到的尾隨斜線的使用。

只能設定 path_redirect、 prefix_rewrite 和 regex_rewrite 其中之一。

regex_rewrite

(type.matcher.v3.RegexMatchAndSubstitute) 表示在重定向期間，應重寫與模式匹配的路徑部分，甚至允許將模式中的捕獲群組替換為新的路徑，如重寫替換字串所指定。這對於允許以感知具有可變內容（如識別碼）的片段的方式重寫應用程式路徑非常有用。

使用 Google RE2 引擎的範例

路徑模式 ^/service/([^/]+)(/.*)$ 與替換字串 \2/instance/\1 配對，會將 /service/foo/v1/api 轉換為 /v1/api/instance/foo。
模式 one 與替換字串 two 配對，會將 /xxx/one/yyy/one/zzz 轉換為 /xxx/two/yyy/two/zzz。
模式 ^(.*?)one(.*)$ 與替換字串 \1two\2 配對，將只會替換第一個出現的 one，將路徑 /xxx/one/yyy/one/zzz 轉換為 /xxx/two/yyy/one/zzz。
模式 (?i)/xxx/ 與替換字串 /yyy/ 配對，會執行不區分大小寫的比對，並將路徑 /aaa/XxX/bbb 轉換為 /aaa/yyy/bbb。

只能設定 path_redirect、 prefix_rewrite 和 regex_rewrite 其中之一。

response_code: (config.route.v3.RedirectAction.RedirectResponseCode) 要在重定向響應中使用的 HTTP 狀態代碼。預設響應代碼為 MOVED_PERMANENTLY (301)。

strip_query: (bool) 表示在重定向期間，URL 的查詢部分將被移除。預設值為 false。

列舉 config.route.v3.RedirectAction.RedirectResponseCode

[config.route.v3.RedirectAction.RedirectResponseCode proto]

MOVED_PERMANENTLY: (預設) ⁣永久移動 HTTP 狀態代碼 - 301。

FOUND: ⁣找到 HTTP 狀態代碼 - 302。

SEE_OTHER: ⁣請參閱其他 HTTP 狀態代碼 - 303。

TEMPORARY_REDIRECT: ⁣臨時重定向 HTTP 狀態代碼 - 307。

PERMANENT_REDIRECT: ⁣永久重定向 HTTP 狀態代碼 - 308。

config.route.v3.DirectResponseAction

[config.route.v3.DirectResponseAction proto]

{
  "status": ...,
  "body": {...}
}

status: (uint32) 指定要返回的 HTTP 響應狀態。

body: (config.core.v3.DataSource) 指定響應內文的內容。如果省略此設定，則產生的響應中將不包含內文。

注意

可以使用封閉的 config.route.v3.Route、config.route.v3.RouteConfiguration 或 config.route.v3.VirtualHost 中的 response_headers_to_add 來指定標頭。

config.route.v3.Decorator

[config.route.v3.Decorator proto]

{
  "operation": ...,
  "propagate": {...}
}

operation: (字串, 必填) 與此路由匹配的請求相關聯的操作名稱。如果啟用追蹤，此資訊將用作此請求回報的 span 名稱。

注意

對於入口 (inbound) 請求或出口 (outbound) 回應，此值可能會被 x-envoy-decorator-operation 標頭覆寫。

propagate: (BoolValue) 是否應將裝飾的詳細資訊傳播到另一方。預設值為 true。

config.route.v3.Tracing

[config.route.v3.Tracing proto]

{
  "client_sampling": {...},
  "random_sampling": {...},
  "overall_sampling": {...},
  "custom_tags": []
}

client_sampling: (type.v3.FractionalPercent) 如果設定了 x-client-trace-id 標頭，則此 HTTP 連線管理員管理的請求中，將強制追蹤的目標百分比。此欄位與 HTTP 連線管理員中的執行時間變數 'tracing.client_enabled' 直接對應。預設值：100%

random_sampling: (type.v3.FractionalPercent) 如果客戶端未要求或未強制追蹤，則此 HTTP 連線管理員管理的請求中，將隨機選取以產生追蹤的目標百分比。此欄位與 HTTP 連線管理員中的執行時間變數 'tracing.random_sampling' 直接對應。預設值：100%

overall_sampling: (type.v3.FractionalPercent) 在套用所有其他取樣檢查（客戶端導向、強制追蹤、隨機取樣）後，此 HTTP 連線管理員管理的請求中將被追蹤的目標百分比。此欄位作為設定的總取樣率的上限。例如，將 client_sampling 設定為 100%，但將 overall_sampling 設定為 1%，則只有 1% 具有適當標頭的客戶端請求會被強制追蹤。此欄位與 HTTP 連線管理員中的執行時間變數 'tracing.global_enabled' 直接對應。預設值：100%

custom_tags: (repeated type.tracing.v3.CustomTag) 具有唯一標籤名稱的自訂標籤列表，用於為活動 span 建立標籤。它會在與 HTTP 連線管理員中設定的對應設定合併後生效。如果 HTTP 連線管理員和路由層級中都設定了兩個名稱相同的標籤，則此處設定的標籤優先。

config.route.v3.VirtualCluster

[config.route.v3.VirtualCluster proto]

虛擬叢集是一種針對某些重要端點指定 regex 匹配規則的方式，以便為匹配的請求明確產生統計資訊。這樣做的原因是，當執行前綴/路徑匹配時，Envoy 並不總是知道應用程式認為什麼是端點。因此，Envoy 無法通用地發出每個端點的統計資訊。但是，系統通常有一些高度關鍵的端點，他們希望獲得關於這些端點的「完美」統計資訊。虛擬叢集統計資訊是完美的，因為它們在下游發出，因此包含網路層級的失敗。

虛擬叢集統計資訊的文件。

注意

虛擬叢集是一個有用的工具，但我們不建議為每個應用程式端點設定虛擬叢集。這不僅不容易維護，而且匹配和統計輸出也不是免費的。

{
  "headers": [],
  "name": ...
}

headers: (repeated config.route.v3.HeaderMatcher) 指定用於匹配請求的標頭匹配器列表。每個指定的標頭都必須匹配。虛擬標頭 :path 和 :method 可分別用於匹配請求路徑和方法。

name: (字串, 必填) 指定虛擬叢集的名稱。發出統計資訊時，會使用虛擬叢集名稱以及虛擬主機名稱。統計資訊由路由器篩選器發出，並記錄在此處。

config.route.v3.RateLimit

[config.route.v3.RateLimit proto]

全域速率限制架構概述。也適用於使用描述器的本機速率限制。

{
  "stage": {...},
  "disable_key": ...,
  "actions": [],
  "limit": {...}
}

stage: (UInt32Value) 指的是篩選器中設定的階段。速率限制設定僅適用於具有相同階段編號的篩選器。預設階段編號為 0。

注意

篩選器支援階段編號 0 - 10（含）。

disable_key: (字串) 要在執行時間設定以停用此速率限制設定的金鑰。

actions: (repeated config.route.v3.RateLimit.Action, 必填) 要為此速率限制設定套用的一系列動作。順序很重要，因為動作是按順序處理的，並且描述器是由按照該順序附加的描述器項目組成的。如果某個動作無法附加描述器項目，則不會為該設定產生描述器。請參閱組合動作以取得其他文件。

limit: (config.route.v3.RateLimit.Override) 可選的限制覆寫，要附加到此速率限制設定產生的描述器。如果覆寫值無效或無法從中繼資料解析，則不提供覆寫。請參閱速率限制覆寫以取得更多資訊。

config.route.v3.RateLimit.Action

[config.route.v3.RateLimit.Action proto]

{
  "source_cluster": {...},
  "destination_cluster": {...},
  "request_headers": {...},
  "remote_address": {...},
  "generic_key": {...},
  "header_value_match": {...},
  "dynamic_metadata": {...},
  "metadata": {...},
  "extension": {...},
  "masked_remote_address": {...},
  "query_parameter_value_match": {...}
}

source_cluster

(config.route.v3.RateLimit.Action.SourceCluster) 針對來源叢集的速率限制。

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

destination_cluster

(config.route.v3.RateLimit.Action.DestinationCluster) 針對目標叢集的速率限制。

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

request_headers

(config.route.v3.RateLimit.Action.RequestHeaders) 針對請求標頭的速率限制。

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

remote_address

(config.route.v3.RateLimit.Action.RemoteAddress) 針對遠端位址的速率限制。

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

generic_key

(config.route.v3.RateLimit.Action.GenericKey) 針對一般金鑰的速率限制。

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

header_value_match

(config.route.v3.RateLimit.Action.HeaderValueMatch) 針對請求標頭存在性的速率限制。

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

dynamic_metadata

(config.route.v3.RateLimit.Action.DynamicMetaData) 針對動態中繼資料的速率限制。

注意

此欄位已棄用，建議改用 metadata 欄位

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

metadata

(config.route.v3.RateLimit.Action.MetaData) 針對中繼資料的速率限制。

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

extension (擴展)

(config.core.v3.TypedExtensionConfig) 速率限制描述符擴展。請參閱速率限制描述符擴展文件。

HTTP 匹配輸入函式允許作為描述符擴展。只有在沒有與類型 URL 匹配的速率限制描述符擴展時，才會查找輸入函式。

提示

此擴充類別具有以下已知擴充功能

envoy.rate_limit_descriptors.expr

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

masked_remote_address

(config.route.v3.RateLimit.Action.MaskedRemoteAddress) 針對遮蔽的遠端位址進行速率限制。

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

query_parameter_value_match

(config.route.v3.RateLimit.Action.QueryParameterValueMatch) 針對查詢參數的存在與否進行速率限制。

必須設定 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address 或 query_parameter_value_match 其中一個。

config.route.v3.RateLimit.Action.SourceCluster

[config.route.v3.RateLimit.Action.SourceCluster proto]

以下描述符條目將附加到描述符中

("source_cluster", "<local service cluster>")

<local service cluster> 是從 --service-cluster 選項取得。

config.route.v3.RateLimit.Action.DestinationCluster

[config.route.v3.RateLimit.Action.DestinationCluster proto]

以下描述符條目將附加到描述符中

("destination_cluster", "<routed target cluster>")

一旦請求與路由表規則匹配，路由的叢集會根據以下其中一個路由表組態設定決定

cluster 指示要路由到的上游叢集。
weighted_clusters 從一組具有權重的叢集中隨機選擇一個叢集。
cluster_header 指示請求中哪個標頭包含目標叢集。

config.route.v3.RateLimit.Action.RequestHeaders

[config.route.v3.RateLimit.Action.RequestHeaders proto]

當標頭包含與 header_name 匹配的鍵時，會附加以下描述符條目

("<descriptor_key>", "<header_value_queried_from_header>")

{
  "header_name": ...,
  "descriptor_key": ...,
  "skip_if_absent": ...
}

header_name: (string, 必需) 要從請求標頭中查詢的標頭名稱。標頭的值會用來填入 descriptor_key 的描述符條目的值。

descriptor_key: (string, 必需) 要在描述符條目中使用的鍵。

skip_if_absent: (bool) 如果設定為 true，當請求中不存在標頭時，Envoy 會在呼叫速率限制服務時跳過描述符。預設情況下，如果請求中不存在此標頭，則會跳過呼叫速率限制服務。

config.route.v3.RateLimit.Action.RemoteAddress

[config.route.v3.RateLimit.Action.RemoteAddress proto]

以下描述符條目會附加到描述符，並使用來自 x-forwarded-for 的信任位址填入

("remote_address", "<trusted address from x-forwarded-for>")

config.route.v3.RateLimit.Action.MaskedRemoteAddress

[config.route.v3.RateLimit.Action.MaskedRemoteAddress proto]

以下描述符條目會附加到描述符，並使用來自 x-forwarded-for 的遮蔽位址填入

("masked_remote_address", "<masked address from x-forwarded-for>")

{
  "v4_prefix_mask_len": {...},
  "v6_prefix_mask_len": {...}
}

v4_prefix_mask_len: (UInt32Value) IPv4 的前綴遮罩長度 (例如 0, 32)。未設定時預設為 32。例如，來自 x-forwarded-for 的信任位址為 192.168.1.1，描述符條目為 ("masked_remote_address", "192.168.1.1/32")；如果遮罩長度為 24，則描述符條目為 ("masked_remote_address", "192.168.1.0/24")。

v6_prefix_mask_len: (UInt32Value) IPv6 的前綴遮罩長度 (例如 0, 128)。未設定時預設為 128。例如，來自 x-forwarded-for 的信任位址為 2001:abcd:ef01:2345:6789:abcd:ef01:234，描述符條目為 ("masked_remote_address", "2001:abcd:ef01:2345:6789:abcd:ef01:234/128")；如果遮罩長度為 64，則描述符條目為 ("masked_remote_address", "2001:abcd:ef01:2345::/64")。

config.route.v3.RateLimit.Action.GenericKey

[config.route.v3.RateLimit.Action.GenericKey proto]

以下描述符條目將附加到描述符中

("generic_key", "<descriptor_value>")

{
  "descriptor_value": ...,
  "descriptor_key": ...
}

descriptor_value: (string, 必需) 要在描述符條目中使用的值。

descriptor_key: (string) 要在描述符條目中使用的選用鍵。如果未設定，則預設為 'generic_key' 作為描述符鍵。

config.route.v3.RateLimit.Action.HeaderValueMatch

[config.route.v3.RateLimit.Action.HeaderValueMatch proto]

以下描述符條目將附加到描述符中

("header_match", "<descriptor_value>")

{
  "descriptor_key": ...,
  "descriptor_value": ...,
  "expect_match": {...},
  "headers": []
}

descriptor_key: (string) 要在描述符條目中使用的鍵。預設為 header_match。

descriptor_value: (string, 必需) 要在描述符條目中使用的值。

expect_match: (BoolValue) 如果設定為 true，則當請求與標頭匹配時，動作會附加一個描述符條目。如果設定為 false，則當請求與標頭不匹配時，動作會附加一個描述符條目。預設值為 true。

headers: (重複 config.route.v3.HeaderMatcher, 必需) 指定一組速率限制動作應匹配的標頭。動作會檢查請求的標頭是否與組態中所有指定的標頭匹配。如果組態中的所有標頭都以相同的值 (或者根據是否存在，如果值欄位不在組態中) 出現在請求中，則會發生匹配。

config.route.v3.RateLimit.Action.DynamicMetaData

[config.route.v3.RateLimit.Action.DynamicMetaData proto]

當動態中繼資料包含鍵值時，會附加以下描述符條目

("<descriptor_key>", "<value_queried_from_dynamic_metadata>")

注意

此動作已棄用，改用 metadata 動作

{
  "descriptor_key": ...,
  "metadata_key": {...},
  "default_value": ...
}

descriptor_key: (string, 必需) 要在描述符條目中使用的鍵。

metadata_key: (type.metadata.v3.MetadataKey, 必需) 中繼資料結構，定義用來擷取字串值的鍵和路徑。只有在動態中繼資料中的值為字串類型時，才會發生匹配。

default_value: (string) 如果 metadata_key 為空時使用的選用值。如果未設定，且 metadata_key 下不存在任何值，則不會產生描述符。

config.route.v3.RateLimit.Action.MetaData

[config.route.v3.RateLimit.Action.MetaData proto]

當中繼資料包含鍵值時，會附加以下描述符條目

("<descriptor_key>", "<value_queried_from_metadata>")

{
  "descriptor_key": ...,
  "metadata_key": {...},
  "default_value": ...,
  "source": ...,
  "skip_if_absent": ...
}

descriptor_key: (string, 必需) 要在描述符條目中使用的鍵。

metadata_key: (type.metadata.v3.MetadataKey, 必需) 中繼資料結構，定義用來擷取字串值的鍵和路徑。只有在中繼資料中的值為字串類型時，才會發生匹配。

default_value: (string) 如果 metadata_key 為空時使用的選用值。如果未設定，且 metadata_key 下不存在任何值，則會依照 skip_if_absent 跳過呼叫速率限制服務或跳過描述符。

source: (config.route.v3.RateLimit.Action.MetaData.Source) 中繼資料的來源

skip_if_absent: (bool) 如果設定為 true，當 metadata_key 為空且未設定 default_value 時，Envoy 會在呼叫速率限制服務時跳過描述符。預設情況下，會在此情況下跳過呼叫速率限制服務。

列舉 config.route.v3.RateLimit.Action.MetaData.Source

[config.route.v3.RateLimit.Action.MetaData.Source proto]

DYNAMIC: (預設) ⁣查詢動態中繼資料

ROUTE_ENTRY: ⁣查詢路由條目中繼資料

config.route.v3.RateLimit.Action.QueryParameterValueMatch

[config.route.v3.RateLimit.Action.QueryParameterValueMatch proto]

以下描述符條目將附加到描述符中

("query_match", "<descriptor_value>")

{
  "descriptor_key": ...,
  "descriptor_value": ...,
  "expect_match": {...},
  "query_parameters": []
}

descriptor_key: (string) 要在描述符條目中使用的鍵。預設為 query_match。

descriptor_value: (string, 必需) 要在描述符條目中使用的值。

expect_match: (BoolValue) 如果設定為 true，則當請求與標頭匹配時，動作會附加一個描述符條目。如果設定為 false，則當請求與標頭不匹配時，動作會附加一個描述符條目。預設值為 true。

query_parameters: (重複 config.route.v3.QueryParameterMatcher, 必需) 指定一組速率限制動作應匹配的查詢參數。動作會檢查請求的查詢參數是否與組態中所有指定的查詢參數匹配。如果組態中的所有查詢參數都以相同的值 (或者根據是否存在，如果值欄位不在組態中) 出現在請求中，則會發生匹配。

config.route.v3.RateLimit.Override

[config.route.v3.RateLimit.Override proto]

{
  "dynamic_metadata": {...}
}

dynamic_metadata: (config.route.v3.RateLimit.Override.DynamicMetadata, 必需) 來自動態中繼資料的限制覆寫。

config.route.v3.RateLimit.Override.DynamicMetadata

[config.route.v3.RateLimit.Override.DynamicMetadata proto]

從動態中繼資料擷取覆寫。

{
  "metadata_key": {...}
}

metadata_key: (type.metadata.v3.MetadataKey, 必需) 中繼資料結構，定義用來擷取結構值的鍵和路徑。該值必須是一個包含整數 "requests_per_unit" 屬性和一個 "unit" 屬性的結構，其值可解析為 RateLimitUnit 列舉

config.route.v3.HeaderMatcher

[config.route.v3.HeaderMatcher proto]

注意

在內部，Envoy 總是使用 HTTP/2 的 :authority 標頭來表示 HTTP/1 的 Host 標頭。因此，如果嘗試比對 Host，請改為比對 :authority。

注意

若要根據 HTTP 方法進行路由，請使用特殊的 HTTP/2 :method 標頭。這適用於 HTTP/1 和 HTTP/2，因為 Envoy 會正規化標頭。例如，

{
  "name": ":method",
  "string_match": {
    "exact": "POST"
  }
}

注意

在沒有任何標頭匹配指定器的情況下，匹配預設為 present_match。也就是說，具有 name 標頭的請求將會匹配，而無論標頭的值為何。

{
  "name": ...,
  "exact_match": ...,
  "safe_regex_match": {...},
  "range_match": {...},
  "present_match": ...,
  "prefix_match": ...,
  "suffix_match": ...,
  "contains_match": ...,
  "string_match": {...},
  "invert_match": ...,
  "treat_missing_header_as_empty": ...
}

name: (string, 必要) 指定請求中標頭的名稱。

exact_match

(string) 如果指定，將根據標頭的值執行標頭匹配。此欄位已棄用。請使用 string_match。

指定如何執行標頭匹配以路由請求。

只能設定 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 其中之一。

safe_regex_match

(type.matcher.v3.RegexMatcher) 如果指定，此正規表示式字串是一個正規表示式規則，表示整個請求標頭值必須符合該正規表示式。如果請求標頭值的子序列符合正規表示式，則該規則將不匹配。此欄位已棄用。請使用 string_match。

指定如何執行標頭匹配以路由請求。

只能設定 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 其中之一。

range_match

(type.v3.Int64Range) 如果指定，將根據範圍執行標頭匹配。如果請求標頭值在此範圍內，則該規則將匹配。整個請求標頭值必須以 10 進位表示一個整數：由一個可選的正負號後跟一串數字組成。如果標頭值不表示整數，則該規則將不匹配。空值、浮點數或僅標頭值的子序列為整數時，匹配將失敗。

範例

對於範圍 [-10,0)，路由將匹配標頭值 -1，但不匹配 0、 somestring、10.9、 -1somestring

指定如何執行標頭匹配以路由請求。

只能設定 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 其中之一。

present_match

(bool) 如果指定為 true，將根據標頭是否在請求中執行標頭匹配。如果指定為 false，將根據標頭是否不存在執行標頭匹配。

指定如何執行標頭匹配以路由請求。

只能設定 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 其中之一。

prefix_match

(string) 如果指定，將根據標頭值的前綴執行標頭匹配。注意：不允許使用空前綴，請改用 present_match。此欄位已棄用。請使用 string_match。

範例

前綴 abcd 匹配值 abcdxyz，但不匹配 abcxyz。

指定如何執行標頭匹配以路由請求。

只能設定 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 其中之一。

suffix_match

(string) 如果指定，將根據標頭值的後綴執行標頭匹配。注意：不允許使用空後綴，請改用 present_match。此欄位已棄用。請使用 string_match。

範例

後綴 abcd 匹配值 xyzabcd，但不匹配 xyzbcd。

指定如何執行標頭匹配以路由請求。

只能設定 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 其中之一。

contains_match

(string) 如果指定，將根據標頭值是否包含給定值來執行標頭匹配。注意：不允許使用空的 contains 匹配，請改用 present_match。此欄位已棄用。請使用 string_match。

範例

值 abcd 匹配值 xyzabcdpqr，但不匹配 xyzbcdpqr。

指定如何執行標頭匹配以路由請求。

只能設定 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 其中之一。

string_match

(type.matcher.v3.StringMatcher) 如果指定，將根據標頭值的字串匹配執行標頭匹配。

指定如何執行標頭匹配以路由請求。

只能設定 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 其中之一。

invert_match

(bool) 如果指定，將在檢查之前反轉匹配結果。預設為 false。

範例

正規表示式 \d{3} 不匹配值 1234，因此反轉時會匹配。
範圍 [-10,0) 將匹配值 -1，因此反轉時將不匹配。

treat_missing_header_as_empty

(bool) 如果指定，對於任何標頭匹配規則，如果標頭匹配規則指定的標頭不存在，則此標頭值將被視為空值。預設為 false。

範例

標頭匹配規則指定的標頭 “header1” 與 [0, 10] 的範圍匹配，invert_match 設定為 true，且 treat_missing_header_as_empty 設定為 true； “header1” 標頭不存在。匹配規則會將 “header1” 視為空標頭。空標頭不匹配範圍，因此反轉時會匹配。
標頭匹配規則指定的標頭 “header2” 與 [0, 10] 的範圍匹配，invert_match 設定為 true，且 treat_missing_header_as_empty 設定為 false； “header2” 標頭不存在，且 “header2” 的標頭匹配器規則將被忽略，因此不會匹配。
標頭匹配規則指定的標頭 “header3” 與字串正規表示式匹配 ^$，表示空字串，且 treat_missing_header_as_empty 設定為 true； “header3” 標頭不存在。匹配規則會將 “header3” 標頭視為空標頭，因此會匹配。
標頭匹配規則指定的標頭 “header4” 與字串正規表示式匹配 ^$，表示空字串，且 treat_missing_header_as_empty 設定為 false； “header4” 標頭不存在。“header4” 的匹配規則將被忽略，因此不會匹配。

config.route.v3.QueryParameterMatcher

[config.route.v3.QueryParameterMatcher proto]

查詢參數匹配將請求的 :path 標頭的查詢字串視為以 & 分隔的鍵和/或鍵=值元素列表。

{
  "name": ...,
  "string_match": {...},
  "present_match": ...
}

name: (string, 必要) 指定請求的 path 的查詢字串中必須存在的鍵名稱。

string_match

(type.matcher.v3.StringMatcher) 指定查詢參數值是否應與字串匹配。

只能設定 string_match、present_match 其中之一。

present_match

(bool) 指定是否應存在查詢參數。

只能設定 string_match、present_match 其中之一。

config.route.v3.InternalRedirectPolicy

[config.route.v3.InternalRedirectPolicy proto]

HTTP 內部重新導向架構總覽。

{
  "max_internal_redirects": {...},
  "redirect_response_codes": [],
  "predicates": [],
  "allow_cross_scheme_redirect": ...,
  "response_headers_to_copy": []
}

max_internal_redirects

(UInt32Value) 除非下游請求遇到的先前內部重新導向次數低於此值，否則不會處理內部重新導向。在下游請求在多個路由之間通過內部重新導向彈回的情況下，第一個達到此閾值或未設定 internal_redirect_policy 的路由會將重新導向傳回下游。

如果未指定，則最多會遵循一次重新導向。

redirect_response_codes: (repeated uint32) 定義允許觸發內部重新導向的上游回應碼。如果未指定，則僅將 302 視為內部重新導向。僅 301、302、303、307 和 308 是有效值。任何其他程式碼將被忽略。

predicates

(repeated config.core.v3.TypedExtensionConfig) 指定一個謂詞列表，當上游回應被所有其他條件視為觸發內部重新導向時，將查詢這些謂詞。列表中的任何謂詞都可以拒絕重新導向，導致回應被代理到下游。

提示

此擴充類別具有以下已知擴充功能

allow_cross_scheme_redirect: (bool) 允許內部重新導向追蹤與 x-forwarded-proto 值不同的協定之目標 URI。預設為 false。

response_headers_to_copy: (repeated string) 指定要從內部重新導向複製到後續請求的標頭列表（依名稱）。如果此處指定了標頭，但該標頭不存在於重新導向中，則將在後續請求中清除該標頭。

config.route.v3.FilterConfig

[config.route.v3.FilterConfig proto]

一個簡單的 HTTP 過濾器配置的封裝器。其目的為作為 VirtualHost.typed_per_filter_config、 Route.typed_per_filter_config 或 WeightedCluster.ClusterWeight.typed_per_filter_config 中 map 值的封裝器使用，以便為過濾器添加額外的標誌。

{
  "config": {...},
  "is_optional": ...,
  "disabled": ...
}

config: (Any) 過濾器配置。

is_optional (是否為可選): (bool) 如果為 true，則該過濾器為可選，這表示如果客戶端不支援指定的過濾器，它可以忽略該 map 條目，而不是拒絕配置。

disabled: (bool) 如果為 true，則該過濾器在路由或虛擬主機中被禁用，並且 config 欄位會被忽略。有關更多詳細資訊，請參閱基於路由的過濾器鏈。

注意

此欄位將在請求到達並且為請求建立過濾器鏈時生效。如果為請求選擇了初始路由，並且過濾器在初始路由中被禁用，則該過濾器將不會被添加到過濾器鏈中。如果請求稍後發生變異並重新匹配到另一個路由，則由於過濾器鏈已建立，因此初始路由禁用的過濾器將不會被加回過濾器鏈，因為現在更改鏈已為時已晚。

此欄位目前僅對下游 HTTP 過濾器有意義。

HTTP 路由組件 (proto)

config.route.v3.VirtualHost

Enum config.route.v3.VirtualHost.TlsRequirementType

config.route.v3.FilterAction

config.route.v3.RouteList

config.route.v3.Route

config.route.v3.WeightedCluster

config.route.v3.WeightedCluster.ClusterWeight

config.route.v3.ClusterSpecifierPlugin

config.route.v3.RouteMatch

config.route.v3.RouteMatch.GrpcRouteMatchOptions

config.route.v3.RouteMatch.TlsContextMatchOptions

config.route.v3.RouteMatch.ConnectMatcher

config.route.v3.CorsPolicy

config.route.v3.RouteAction

config.route.v3.RouteAction.RequestMirrorPolicy

config.route.v3.RouteAction.HashPolicy

config.route.v3.RouteAction.HashPolicy.Header

config.route.v3.RouteAction.HashPolicy.CookieAttribute

config.route.v3.RouteAction.HashPolicy.Cookie

config.route.v3.RouteAction.HashPolicy.ConnectionProperties

config.route.v3.RouteAction.HashPolicy.QueryParameter

config.route.v3.RouteAction.HashPolicy.FilterState

config.route.v3.RouteAction.UpgradeConfig

config.route.v3.RouteAction.UpgradeConfig.ConnectConfig

config.route.v3.RouteAction.MaxStreamDuration

列舉 config.route.v3.RouteAction.ClusterNotFoundResponseCode

列舉 config.route.v3.RouteAction.InternalRedirectAction

config.route.v3.RetryPolicy

config.route.v3.RetryPolicy.RetryPriority

config.route.v3.RetryPolicy.RetryHostPredicate

config.route.v3.RetryPolicy.RetryBackOff

config.route.v3.RetryPolicy.ResetHeader

config.route.v3.RetryPolicy.RateLimitedRetryBackOff

列舉 config.route.v3.RetryPolicy.ResetHeaderFormat

config.route.v3.HedgePolicy

config.route.v3.RedirectAction

列舉 config.route.v3.RedirectAction.RedirectResponseCode

config.route.v3.DirectResponseAction

config.route.v3.Decorator

config.route.v3.Tracing

config.route.v3.VirtualCluster

config.route.v3.RateLimit

config.route.v3.RateLimit.Action

config.route.v3.RateLimit.Action.SourceCluster

config.route.v3.RateLimit.Action.DestinationCluster

config.route.v3.RateLimit.Action.RequestHeaders

config.route.v3.RateLimit.Action.RemoteAddress

config.route.v3.RateLimit.Action.MaskedRemoteAddress

config.route.v3.RateLimit.Action.GenericKey

config.route.v3.RateLimit.Action.HeaderValueMatch

config.route.v3.RateLimit.Action.DynamicMetaData

config.route.v3.RateLimit.Action.MetaData

列舉 config.route.v3.RateLimit.Action.MetaData.Source

config.route.v3.RateLimit.Action.QueryParameterValueMatch

config.route.v3.RateLimit.Override

config.route.v3.RateLimit.Override.DynamicMetadata

config.route.v3.HeaderMatcher

config.route.v3.QueryParameterMatcher

config.route.v3.InternalRedirectPolicy

config.route.v3.FilterConfig