V2 API 概述 · ENVOY 智能代理中文參考文檔

# V2 API概述 Envoy的v2 API采用[Protobuf3](https://developers.google.com/protocol-buffers/)作為數據面API集。由現有[v1 API](Overviewv1API.md)概念演變而來的： - 基于gRPC流傳輸[xDS](https://github.com/envoyproxy/data-plane-api/blob/master/XDS_PROTOCOL.md) API。減少對資源開銷和更低的延遲。 - 基于REST-JSON API，其中JSON/YAML格式需要符合[proto3-JSON規范](https://developers.google.com/protocol-buffers/docs/proto3#json)。 - 通過文件系統，REST-JSON 或者 gRPC端口進行更新。 - 通過高級負載均衡API端口，向管理服務上報負載和資源利用率信息。 - 更強的一致性和時序屬性。V2 API仍然能保持最終一致性模型。有關Envoy與管理服務之間，消息交互方面的更多詳細信息，請參閱[xDS協議](https://github.com/envoyproxy/data-plane-api/blob/master/XDS_PROTOCOL.md)說明。 ## 引導配置若要使用v2 API，需要提供配置文件啟動程序。這提供了靜態服務配置，并配置Envoy以在需要時訪問動態配置。與v1的JSON/YAML配置一樣，這通過在命令行上提供`-c`標志，即： ``` ./envoy -c <path to config>.{json,yaml,pb,pb_text} --v2-config-only ``` 其中擴展標志表示僅支持v2配置。`--v2-config-only`標志不是必選的，因為Envoy會嘗試自動檢測配置文件的版本，當配置解析失敗時，這個選項可以增強調試能力。 [引導](../v2APIreference/Bootstrap.md)是根配置。引導的一個關鍵概念是靜態和動態資源之間的區別。`Listener`或`Cluster`等資源可以在`static_resources`中靜態配置，也可以在`dynamic_resources`中配置[LDS](Listeners.md)或[CDS](Clustermanager.md)之類的動態xDS服務。 ## 例子下面我們將使用YAML配置原型，表示從`127.0.0.1:10000`到`127.0.0.2:1234`的HTTP服務代理的運行示例。 ### 全靜態下面提供了一個全靜態最小引導配置： ``` admin: access_log_path: /tmp/admin_access.log address: socket_address: { address: 127.0.0.1, port_value: 9901 } static_resources: listeners: - name: listener_0 address: socket_address: { address: 127.0.0.1, port_value: 10000 } filter_chains: - filters: - name: envoy.http_connection_manager config: stat_prefix: ingress_http codec_type: AUTO route_config: name: local_route virtual_hosts: - name: local_service domains: ["*"] routes: - match: { prefix: "/" } route: { cluster: some_service } http_filters: - name: envoy.router clusters: - name: some_service connect_timeout: 0.25s type: STATIC lb_policy: ROUND_ROBIN hosts: [{ socket_address: { address: 127.0.0.2, port_value: 1234 }}] ``` ### 大部分靜態&動態服務發現下面提供了一個引導配置，從上面的示例中繼續，通過在`127.0.0.3:5678`上監聽的EDS gRPC管理服務進行動態`endpoint`發現： ``` admin: access_log_path: /tmp/admin_access.log address: socket_address: { address: 127.0.0.1, port_value: 9901 } static_resources: listeners: - name: listener_0 address: socket_address: { address: 127.0.0.1, port_value: 10000 } filter_chains: - filters: - name: envoy.http_connection_manager config: stat_prefix: ingress_http codec_type: AUTO route_config: name: local_route virtual_hosts: - name: local_service domains: ["*"] routes: - match: { prefix: "/" } route: { cluster: some_service } http_filters: - name: envoy.router clusters: - name: some_service connect_timeout: 0.25s lb_policy: ROUND_ROBIN type: EDS eds_cluster_config: eds_config: api_config_source: api_type: GRPC cluster_name: [xds_cluster] - name: xds_cluster connect_timeout: 0.25s type: STATIC lb_policy: ROUND_ROBIN http2_protocol_options: {} hosts: [{ socket_address: { address: 127.0.0.3, port_value: 5678 }}] ``` 注意：上面的`xds_cluster`被定義為Envoy的管理服務。即使在全動態的配置中，也需要定義一些靜態資源，如指定Envoy對應的xDS管理服務。在上面的例子中，請求EDS管理服務，然后返回[服務發現應答](../v2APIreference/CommondiscoveryAPIcomponents.md)的原始編碼： ``` version_info: "0" resources: - "@type": type.googleapis.com/envoy.api.v2.ClusterLoadAssignment cluster_name: some_service endpoints: - lb_endpoints: - endpoint: address: socket_address: address: 127.0.0.2 port_value: 1234 ``` 以上出現的版本控制和URL類型方案，在流式[gRPC訂閱協議](https://github.com/envoyproxy/data-plane-api/blob/master/XDS_PROTOCOL.md#streaming-grpc-subscriptions)文檔中有更詳細的解釋。 ### 全動態下面提供了一個全動態的引導配置，其中除了管理服務的其他所有資源都是通過xDS發現的： ``` admin: access_log_path: /tmp/admin_access.log address: socket_address: { address: 127.0.0.1, port_value: 9901 } dynamic_resources: lds_config: api_config_source: api_type: GRPC cluster_name: [xds_cluster] cds_config: api_config_source: api_type: GRPC cluster_name: [xds_cluster] static_resources: clusters: - name: xds_cluster connect_timeout: 0.25s type: STATIC lb_policy: ROUND_ROBIN http2_protocol_options: {} hosts: [{ socket_address: { address: 127.0.0.3, port_value: 5678 }}] ``` 管理服務可以通過以下方式響應LDS請求： ``` version_info: "0" resources: - "@type": type.googleapis.com/envoy.api.v2.Listener name: listener_0 address: socket_address: address: 127.0.0.1 port_value: 10000 filter_chains: - filters: - name: envoy.http_connection_manager config: stat_prefix: ingress_http codec_type: AUTO rds: route_config_name: local_route config_source: api_config_source: api_type: GRPC cluster_name: [xds_cluster] http_filters: - name: envoy.router ``` 管理服務可以通過以下方式響應RDS請求： ``` version_info: "0" resources: - "@type": type.googleapis.com/envoy.api.v2.RouteConfiguration name: local_route virtual_hosts: - name: local_service domains: ["*"] routes: - match: { prefix: "/" } route: { cluster: some_service } ``` 管理服務可以通過以下方式響應CDS請求： ``` version_info: "0" resources: - "@type": type.googleapis.com/envoy.api.v2.Cluster name: some_service connect_timeout: 0.25s lb_policy: ROUND_ROBIN type: EDS eds_cluster_config: eds_config: api_config_source: api_type: GRPC cluster_name: [xds_cluster] ``` 管理服務可以通過以下方式響應EDS請求： ``` version_info: "0" resources: - "@type": type.googleapis.com/envoy.api.v2.ClusterLoadAssignment cluster_name: some_service endpoints: - lb_endpoints: - endpoint: address: socket_address: address: 127.0.0.2 port_value: 1234 ``` ### 管理服務一個v2 xDS管理服務，需要按照gRPC/REST服務的要求提供以下API端口。在同時支持流式gRPC和REST-JSON情況下，在接收一個發現請求時，按照xDS協議返回發現響應。 #### gRPC流端口 **`POST /envoy.api.v2.ClusterDiscoveryService/StreamClusters`** 有關服務定義，請參閱[cds.proto](https://github.com/envoyproxy/data-plane-api/blob/master/api/cds.proto)協議。當Envoy作為客戶端時，這被使用： ``` cds_config: api_config_source: api_type: GRPC cluster_name: [some_xds_cluster] ``` 在引導配置的`dynamic_resources`中設置。 **`POST /envoy.api.v2.EndpointDiscoveryService/StreamEndpoints`** 有關服務定義，請參閱[eds.proto](https://github.com/envoyproxy/data-plane-api/blob/master/api/eds.proto)協議。當Envoy作為客戶端時，這被使用： ``` eds_config: api_config_source: api_type: GRPC cluster_name: [some_xds_cluster] ``` 在[集群配置](../v2APIreference/ClustersandCDS.md)的`eds_cluster_config`字段中設置。 **`POST /envoy.api.v2.ListenerDiscoveryService/StreamListeners`** 有關服務定義，請參閱[lds.proto](https://github.com/envoyproxy/data-plane-api/blob/master/api/lds.proto)。當Envoy作為客戶端時，這被使用： ``` lds_config: api_config_source: api_type: GRPC cluster_name: [some_xds_cluster] ``` 在引導配置的`dynamic_resources`中設置。 **`POST /envoy.api.v2.RouteDiscoveryService/StreamRoutes`** 有關服務定義，請參閱[rds.proto](https://github.com/envoyproxy/data-plane-api/blob/master/api/rds.proto)。當Envoy作為客戶端時，這被使用： ``` route_config_name: some_route_name config_source: api_config_source: api_type: GRPC cluster_name: [some_xds_cluster] ``` 在[Http Connection Manager](../v2APIreference/Filters/Networkfilters/HTTPconnectionmanager.md)配置的rds字段中設置。 #### REST端口 **`POST /v2/discovery:clusters`** 有關服務定義，請參閱[cds.proto](https://github.com/envoyproxy/data-plane-api/blob/master/api/cds.proto)協議。當Envoy作為客戶端時，這被使用： ``` cds_config: api_config_source: api_type: REST cluster_name: [some_xds_cluster] ``` 在引導配置的`dynamic_resources`中設置。 **`POST /v2/discovery:endpoints`** 有關服務定義，請參閱[eds.proto](https://github.com/envoyproxy/data-plane-api/blob/master/api/eds.proto)協議。當Envoy作為客戶端時，這被使用： ``` eds_config: api_config_source: api_type: REST cluster_name: [some_xds_cluster] ``` 在[集群配置](../v2APIreference/ClustersandCDS.md)的`eds_cluster_config`字段中設置。 **`POST /v2/discovery:listeners`** 有關服務定義，請參閱[lds.proto](https://github.com/envoyproxy/data-plane-api/blob/master/api/lds.proto)。當Envoy作為客戶端時，這被使用： ``` lds_config: api_config_source: api_type: REST cluster_name: [some_xds_cluster] ``` 在引導配置的`dynamic_resources`中設置。 **`POST /v2/discovery:routes`** 有關服務定義，請參閱[rds.proto](https://github.com/envoyproxy/data-plane-api/blob/master/api/rds.proto)。當Envoy作為客戶端時，這被使用： ``` route_config_name: some_route_name config_source: api_config_source: api_type: REST cluster_name: [some_xds_cluster] ``` 在[Http Connection Manager](../v2APIreference/Filters/Networkfilters/HTTPconnectionmanager.md)配置的rds字段中設置。 ### 聚合發現服務雖然Envoy從根本上采用了最終一致性的模型，但是ADS提供了一個機會來對API更新推送進行排序，并確保Envoy節點面向單個管理服務，進行相關API更新。ADS允許一個或多個API及其資源，由管理服務在單個雙向gRPC流上進行傳輸。沒有這個，一些API（如RDS和EDS）可能需要管理多個流和連接到不同的管理服務。 ADS將允許通過適當的排序無損地更新配置。例如，假設 *foo.com* 映射到集群X。我們希望將路由表中 *foo.com* 映射為集群Y。為此，必須首先傳遞包含兩個集群的CDS/EDS更新X和Y。如果沒有ADS，CDS/EDS/RDS流可能指向不同的管理服務器，或者位于同一個管理服務器上的不同gRPC流/連接進行協商。EDS資源請求可以分成兩個不同的流，一個用于X，另一個用于Y。ADS允許將這些流合并為單個流到單個管理服務器，避免了分布式同步對正確排序更新的需要。借助ADS，管理服務器將在單個數據流上提供CDS，EDS和RDS更新。 ADS僅適用于gRPC流（不是REST），在[本文檔](https://github.com/envoyproxy/data-plane-api/blob/master/XDS_PROTOCOL.md#aggregated-discovery-services-ads)中有更詳細的描述。gRPC端口是： **`POST /envoy.api.v2.AggregatedDiscoveryService/StreamAggregatedResources`** 有關服務定義，請參閱[discovery.proto](https://github.com/envoyproxy/data-plane-api/blob/master/api/discovery.proto)。當Envoy作為客戶端時，這被使用： ``` ads_config: api_type: GRPC cluster_name: [some_ads_cluster] ``` 在引導配置的`dynamic_resources`中設置。設置此項時，可以將上述任何配置源設置為使用ADS通道。例如，一個LDS配置可以從 ``` lds_config: api_config_source: api_type: REST cluster_name: [some_xds_cluster] ``` 修改為 ``` lds_config: {ads: {}} ``` 其效果是LDS流將通過共享的ADS通道被引導到`some_ads_cluster`。 ### 狀態除非另有說明，否則將在[v2 API參考](../v2APIreference.md)中描述的所有功能。在v2 API參考和[v2 API庫](https://github.com/envoyproxy/data-plane-api/tree/master/api)中，所有接口原型都被凍結，除非它們被標記為草稿或實驗原型。在這里，凍結意味著我們不會打破兼容性的底線。通過添加新的字段，以不破壞向后兼容性的方式，盡可能的進一步延長凍結原型的期限。上述原型中的字段可能會在不再使用相關功能的情況下，隨著策略的改變而被棄用。雖然凍結的API保持其格式兼容性，但我們保留更改原名，文件位置和嵌套關系的權利，這可能導致代碼更改中斷。我們的目標是盡量減少這里的損失。當Protos標記為草案( *draft* )，意味著它們已經接近完成，至少可能在Envoy中部分實施，但可能會在凍結之前破壞原型格式。當Protos標記為實驗性的( *experimental* )，與原始草案有相同的告警提示，并可能在Envoy執行凍結之前做出重大改變。當前所有v2 API[問題](https://github.com/envoyproxy/envoy/issues?q=is%3Aopen+is%3Aissue+label%3A%22v2+API%22)在這里被跟蹤。 ## 返回 - [上一級](../Configurationreference.md) - [首頁目錄](../README.md)