路由 · ENVOY 智能代理中文參考文檔

### 路由路由指定請求如何匹配相應的路徑以及接下來要做什么（例如，重定向，轉發，重寫等）的規范。注意：Envoy支持通過匹配HTTP頭中的方法進行路由。 ``` { "prefix": "...", "path": "...", "regex": "...", "cluster": "...", "cluster_header": "...", "weighted_clusters" : "{...}", "host_redirect": "...", "path_redirect": "...", "prefix_rewrite": "...", "host_rewrite": "...", "auto_host_rewrite": "...", "case_sensitive": "...", "use_websocket": "...", "timeout_ms": "...", "runtime": "{...}", "retry_policy": "{...}", "shadow": "{...}", "priority": "...", "headers": [], "rate_limits": [], "include_vh_rate_limits" : "...", "hash_policy": "{...}", "request_headers_to_add" : [], "opaque_config": [], "cors": "{...}", "decorator" : "{...}" } ``` - **prefix** (sometimes required, string) 如果指定，則路由使用匹配前綴規則，這意味著前綴必須匹配路徑頭的開始部分。注意：必須指定`prefix`，`path`或`regex`其中之一。 - **path** (sometimes required, string) 如果指定，則路由采用一個精確的路徑匹配規則，這意味著一旦路徑字符串匹配，則將會被移除，注意：必須指定`prefix`，`path`或`regex`其中之一。 - **regex** (sometimes required, string) 如果指定，則路由采用正則表達式匹配規則，這意味著一旦路徑字符串匹配，則將會被移除，正則表達式必須匹配`:path`頭。整個完整的路徑（不含查詢字符串）必須匹配正則表達式。如果只有`:path`頭的子序列與正則表達式匹配，則規則上不匹配。這里定義了[正則表達式語法](http://en.cppreference.com/w/cpp/regex/ecmascript)。示例： - 正則表達式 /b[io]t 匹配路徑 /bit - 正則表達式 /b[io]t 匹配路徑 /bot - 正則表達式 /b[io]t 不匹配路徑 /bite - 正則表達式 /b[io]t 不匹配路徑 /bit/bot 注意：必須指定`prefix`，`path`或`regex`其中之一。 - **cors** (optional, object) 指定路由的CORS策略。 - **cluster** (sometimes required, string) 如果不是重定向路由（未指定`host_redirect`或`path_redirect`），則必須指定`cluster`，`cluster_header`或`weighted_clusters`其中之一。指定群集時，其值指示請求應轉發到的上游群集。 - **cluster_header** (sometimes required, string) 如果不是重定向路由（未指定`host_redirect`或`path_redirect`），則必須指定`cluster`，`cluster_header`或`weighted_clusters`其中之一。當指定`cluster_header`時，Envoy將通過從請求頭中讀取由`cluster_header`命名的HTTP頭的值，來明確要路由到的集群。如果相應的頭沒有找到，或者引用的群集不存在，Envoy將返回一個404響應。注意：在內部，Envoy始終使用HTTP/2的`:authority`頭來表示HTTP/1主機頭。因此，如果在試圖匹配主機，應該匹配`:authority`頭。 - **weighted_clusters** (sometimes required, object) 如果不是重定向路由（未指定`host_redirect`或`path_redirect`），則必須指定`cluster`，`cluster_header`或`weighted_clusters`其中之一。使用`weighted_clusters`選項，可以為該路由指定多個上游群集。根據每個集群的權重，將請求轉發到其中一個上游集群。請參閱[流量拆分](../../Configurationreference/HTTPconnectionmanager/TrafficShiftingSplitting.md)以獲取相應的文檔。 - **host_redirect** (sometimes required, string) 表示該路由是重定向規則。如果匹配，則會發送301重定向的響應，該響應將使用該值交換URL的主機部分。也可以使用`path_redirect`選項一起指定。 - **path_redirect** (sometimes required, string) 表示該路由是重定向規則。如果匹配，則會發送一個301重定向的響應，用這個值交換URL的路徑部分。可以與`host_redirect`選項一起指定。路由器過濾器將在重寫`x-envoy-original-path`頭之前放置原始路徑。 - **prefix_rewrite** (optional, string) 表示在轉發過程中，此值將替換所匹配的前綴（或路徑）。當使用正則表達式路徑匹配時，將替換整個路徑（不包括查詢字符串）。此選項允許應用程序的URL與反向代理層公開的路徑不同。 - **host_rewrite** (optional, string) 表示在轉發過程中，此值將替換主機頭。 - **auto_host_rewrite** (optional, boolean) 表示在轉發過程中，主機頭將與群集管理器選擇的上游主機的主機名進行交換。此選項僅適用于路由的目標群集的類型為`strict_dns`或`logical_dns`。對于其他群集類型，設置為`true`將無效。`auto_host_rewrite`和`host_rewrite`是互斥的選項。只能指定一個。 - **case_sensitive** (optional, boolean) 表示前綴/路徑匹配是否區分大小寫。默認值是true。 - **use_websocket** (optional, boolean) 表示是否允許與此路由連接的HTTP/1.1客戶端升級到WebSocket連接。默認值是false。注意：如果設置為true，Envoy期望與此路由匹配的第一個請求包含WebSocket升級頭。如果升級頭不存在，連接將作為普通的HTTP/1.1連接進行處理。如果升級頭存在，Envoy將在客戶端和上游服務器之間建立純TCP代理。因此，如果要拒絕WebSocket升級請求，上游服務器將要負責關閉相關的連接。在關閉連接之前，Envoy將持續從客戶端代理數據到上游服務器。具有WebSocket升級頭的請求不支持重定向，超時和重試。 - **timeout_ms** (optional, integer) 指定路由的超時時間。如果未指定，則默認值為15秒。請注意，此超時包括所有重試。另請參閱[x-envoy-upstream-rq-timeout-ms](../../Configurationreference/HTTPfilters/Router.md#x-envoy-upstream-rq-timeout-ms)，[x-envoy-upstream-rq-per-try-timeout-ms](../../Configurationreference/HTTPfilters/Router.md#x-envoy-upstream-rq-per-try-timeout-ms)和[重試概述](../../Introduction/Architectureoverview/HTTProuting.md)。 - **runtime** (optional, object) 可選，指定路由的[運行時](#Runtime)配置。 - **retry_policy** (optional, object) 可選，表示該路由具有[重試策略](#Retry-policy)。 - **shadow** (optional, object) 可選，表示路由具有[影子策略](#Shadow)。 - **priority** (optional, string) 可選，指定路由[優先級](../../Introduction/Architectureoverview/HTTProuting.md)。 - **headers** (optional, array) 指定與該路由匹配的一組[頭](#Headers)列表。路由器將根據配置中指定頭檢查請求的頭部。如果路由中的所有頭都與請求中頭的值相同（或者配置中沒有指定相應的值，則認定存在），則將發生匹配。 - **request_headers_to_add** (optional, array) 指定應添加到由此虛擬主機處理的每個請求的HTTP頭列表。以下面的形式指定頭部： ``` [ {"key": "header1", "value": "value1"}, {"key": "header2", "value": "value2"} ] ``` 有關更多信息，請參閱[自定義請求頭](../../Configurationreference/HTTPconnectionmanager/HTTPheadermanipulation.md)的文檔。 - **opaque_config** (optional, array) 指定可由過濾器訪問的一組可選[路由配置值](#Opaque-Config)。 - **rate_limits** (optional, array) 指定可應用與該路由的一組[速率限制配置](../../v1APIreference/HTTPRouteconfiguration/Ratelimitconfiguration.md)。 - **include_vh_rate_limits** (optional, boolean) 指定速率限制過濾器是否應包含虛擬主機的速率限制。默認情況下，如果路由配置的速率限制，虛擬主機`rate_limits`將不適用于請求。 - **hash_policy** (optional, object) 如果上游群集使用哈希負載平衡器，則通過此選項指定路由的[哈希策略](../../Introduction/Architectureoverview/Loadbalancing.md)。 - **decorator** (optional, object) 指定用于增強相關匹配的路由描述信息，用于信息上報。 ### Runtime 可用于路由的[運行時](../../Introduction/Architectureoverview/Runtimeconfiguration.md)配置，開展路由的逐步變更，而無需部署完整的代碼/配置。請參閱[流量轉移文檔](../../Configurationreference/HTTPconnectionmanager/TrafficShiftingSplitting.md)。 ``` { "key": "...", "default": "..." } ``` - **key** (required, string) 指定運行時應查詢的鍵的名稱，以確定路由是否匹配。有關鍵名稱如何映射到底層實現，請參閱[運行時文檔](../../Operationsandadministration/Runtime.md)。 - **default** (required, integer) 一個0-100之間的整數，每當路由匹配時，會選擇0-99之間的隨機數。若該值<=在該鍵中找到的值（優先檢查），或者若該鍵不存在，則為默認值，該路由是匹配的（假定所有的都路由匹配）。 ### Retry policy HTTP重試[架構概述](../../Introduction/Architectureoverview/HTTProuting.md)。 ``` { "retry_on": "...", "num_retries": "...", "per_try_timeout_ms" : "..." } ``` - **retry_on** (required, string) 指定重試的發生條件。這些是與[x-envoy-retry-on](../../Configurationreference/HTTPfilters/Router.md#x-envoy-retry-on)和[x-envoy-retry-grpc-on](../../Configurationreference/HTTPfilters/Router.md#x-envoy-retry-grpc-on)記錄的條件相同。 - **num_retries** (optional, integer) 指定允許的重試次數。此參數是可選的，默認值為1。這些與[x-envoy-max-retries](../../Configurationreference/HTTPfilters/Router.md#x-envoy-max-retries)記錄的條件相同。 - **per_try_timeout_ms** (optional, integer) 指定每個重試嘗試的非零超時。該參數是可選的。與[x-envoy-upstream-rq-per-try-timeout-ms](../../Configurationreference/HTTPfilters/Router.md#x-envoy-upstream-rq-per-try-timeout-ms)記錄的條件相同。注意：如果未指定，Envoy將使用全局路由請求超時。因此，當使用基于`5xx`的重試策略時，超時請求將不會被重試，因為總超時預算已經耗盡。 ### Shadow 路由器能夠實現將流量從一個集群映射到另一個集群。目前的實現是“fire and forget”，這意味著Envoy在返回來自主集群的響應之前不會等待影子集群作出響應。所有正常的統計數據都會被收集用于陰影集群，使得該功能對測試很有用。在shadow期間，host/authority頭被改變，使得`-shadow`被附加。這對于日志記錄很有用。例如：`cluster1`變為`cluster1-shadow`。 ``` { "cluster": "...", "runtime_key": "..." } ``` - **cluster** (required, string) 指定請求將被映射到的群集。群集必須存在于[群集管理器](../../Configurationreference/Clustermanager.md)配置中。 - **runtime_key** (optional, string) 如果未指定，則對目標群集的所有請求都將被映射。如果指定，Envoy將查找運行時鍵，以獲取請求的百分比。有效值從0到10000，允許0.01％的增幅。如果運行時鍵在配置中指定，但運行時不存在，則默認為0，因此請求的0％將被映射。 ### Headers ``` { "name": "...", "value": "...", "regex": "..." } ``` - **name** (required, string) 指定請求中頭部的名稱。 - **value** (optional, string) 指定頭的值。如果值不存在，則具有頭名的請求都將匹配，而不管頭的值如何。 - **regex** (optional, boolean) 指定頭的值是否采用正則表達式。默認為`false`。整個請求頭的值必須與正則表達式匹配。如果只有請求頭值的子序列與正則表達式匹配，則規則不匹配。這里定義了值字段中使用的[正則表達式語法](http://en.cppreference.com/w/cpp/regex/ecmascript)。示例： - 正則表達式d{3}匹配123值 - 正則表達式d{3}不匹配1234值 - 正則表達式d{3}不匹配123.456值注意：在內部，Envoy始終使用HTTP/2的`:authority`來表示HTTP/1主機頭。因此，如果試圖匹配主機，則匹配`:authority`替代。注意：若要使用HTTP的`method`進行路由，請使用特殊的HTTP/2的`:method`頭。這適用于HTTP/1和HTTP/2，因為Envoy標準化頭。例如： ``` { "name": ":method", "value": "POST" } ``` ### Weighted Clusters 與指定單個上游群集作為請求的目標群集相比，`weighted_clusters`選項允許指定多個上游群集，以及指定要轉發給每個群集的流量的百分比權重。路由器將根據權重選擇上游集群。 ``` { "clusters": [], "runtime_key_prefix" : "..." } ``` - **clusters** (required, array) 指定與路由器相關的一個或多個上游群集。 ``` { "name" : "...", "weight": "..." } ``` - **name** (required, string) 上游群集的名稱。群集必須存在于[群集管理器](../../Configurationreference/Clustermanager.md)配置中。 - **weight** (required, integer) 一個0-100之間的整數，當請求與路由匹配時，選擇上游集群的權重比。集群組中所有權重之和必須為100。 - **runtime_key_prefix** (optional, string) 指定運行時每個群集相關的運行時鍵的前綴。當指定`runtime_key_prefix`時，路由器將在鍵為`runtime_key_prefix + "." + cluster[i].name`下查找與每個上游集群相關的權重。其中，`cluster[i]`表示集群組中的條目。如果群集的運行時鍵不存在，則配置文件中指定的值將用作默認權重。有關鍵名稱如何映射到底層實現，請參閱[運行時](../../Operationsandadministration/Runtime.md)文檔。注意：如果運行時權重之和超過100，則流量拆分的行為將未定義（盡管請求將被路由到其中一個集群）。 ### Hash policy 如果上游群集使用哈希負載平衡器，則指定路由的哈希策略。 ``` { "header_name": "..." } ``` - **header_name** (required, string) 獲取的請求頭部的名稱作為哈希值。如果請求頭不存在，負載均衡器將使用一個隨機數作為哈希值，從而使得有效地使負載均衡策略變為隨機策略。 ### Decorator 指定路由的修飾符。 ``` { "operation": "..." } ``` - **operation** (required, string) 與此路由匹配的請求相關的操作名稱。如果已啟用跟蹤，則將使用此信息作為為此請求跟蹤記錄的span名稱。注意：對于入口（入站）請求或出口（出站）響應，此值可能會被`x-envoy-decorator-operation`頭部覆蓋。 ### Opaque Config 可以通過“不透明配置”機制為過濾器提供額外的配置。在路由配置中指定屬性列表。該配置不能未被Envoy解釋，可以在用戶定義的過濾器中訪問。該配置是一個通用的字符串映射。不支持嵌套對象。 ``` [ {"...": "..."} ] ``` ### Cors 設置路由的優先于虛擬主機的設置。 ``` { "enabled": false, "allow_origin": ["http://foo.example"], "allow_methods": "POST, GET, OPTIONS", "allow_headers": "Content-Type", "allow_credentials": false, "expose_headers": "X-Custom-Header", "max_age": "86400" } ``` - **enabled** (optional, boolean) 默認為true。只有在路由上啟用并設置為false，才會禁用此路由的CORS。該設置對虛擬主機沒有影響。 - **allow_origin** (optional, array) 將允許做CORS請求的來源。通配符“*”表示允許任何來源。 - **allow_methods** (optional, string) `access-control-allow-methods`頭的內容。以逗號分隔的HTTP方法列表。 - **allow_headers** (optional, string) `access-control-allow-headers`頭的內容。以逗號分隔的HTTP標題列表。 - **allow_credentials** (optional, boolean) 資源是否允許憑證。 - **expose_headers** (optional, string) `access-control-expose-headers`頭的內容。以逗號分隔的HTTP標題列表。 - **max_age** (optional, string) `access-control-max-age`頭的內容。以秒為單位的值，可以緩存對預檢請求的響應時間。 ## 返回 - [上一級](../HTTPRouteconfiguration.md) - [首頁目錄](../../README.md)