• V2 API概述
    • 引导配置
    • 例子
      • 全静态
      • 大部分静态&动态服务发现
      • 全动态
      • 管理服务
        • gRPC流端口
        • REST端口
      • 聚合发现服务
      • 状态
    • 返回

    V2 API概述

    Envoy的v2 API采用Protobuf3作为数据面API集。由现有v1 API概念演变而来的：

    • 基于gRPC流传输xDS API。减少对资源开销和更低的延迟。
    • 基于REST-JSON API，其中JSON/YAML格式需要符合proto3-JSON规范。
    • 通过文件系统，REST-JSON 或者 gRPC端口进行更新。
    • 通过高级负载均衡API端口，向管理服务上报负载和资源利用率信息。
    • 更强的一致性和时序属性。V2 API仍然能保持最终一致性模型。

    有关Envoy与管理服务之间，消息交互方面的更多详细信息，请参阅xDS协议说明。

    引导配置

    若要使用v2 API，需要提供配置文件启动程序。这提供了静态服务配置，并配置Envoy以在需要时访问动态配置。与v1的JSON/YAML配置一样，这通过在命令行上提供-c标志，即：

    1. ./envoy -c <path to config>.{json,yaml,pb,pb_text} --v2-config-only

    其中扩展标志表示仅支持v2配置。--v2-config-only标志不是必选的，因为Envoy会尝试自动检测配置文件的版本，当配置解析失败时，这个选项可以增强调试能力。

    引导是根配置。引导的一个关键概念是静态和动态资源之间的区别。Listener或Cluster等资源可以在static_resources中静态配置，也可以在dynamic_resources中配置LDS或CDS之类的动态xDS服务。

    例子

    下面我们将使用YAML配置原型，表示从127.0.0.1:10000到127.0.0.2:1234的HTTP服务代理的运行示例。

    全静态

    下面提供了一个全静态最小引导配置：

    1. admin:
    2.   access_log_path: /tmp/admin_access.log
    3.   address:
    4.     socket_address: { address: 127.0.0.1, port_value: 9901 }
    6. static_resources:
    7.   listeners:
    8.   - name: listener_0
    9.     address:
    10.       socket_address: { address: 127.0.0.1, port_value: 10000 }
    11.     filter_chains:
    12.     - filters:
    13.       - name: envoy.http_connection_manager
    14.         config:
    15.           stat_prefix: ingress_http
    16.           codec_type: AUTO
    17.           route_config:
    18.             name: local_route
    19.             virtual_hosts:
    20.             - name: local_service
    21.               domains: ["*"]
    22.               routes:
    23.               - match: { prefix: "/" }
    24.                 route: { cluster: some_service }
    25.           http_filters:
    26.           - name: envoy.router
    27.   clusters:
    28.   - name: some_service
    29.     connect_timeout: 0.25s
    30.     type: STATIC
    31.     lb_policy: ROUND_ROBIN
    32.     hosts: [{ socket_address: { address: 127.0.0.2, port_value: 1234 }}]

    大部分静态&动态服务发现

    下面提供了一个引导配置，从上面的示例中继续，通过在127.0.0.3:5678上监听的EDS gRPC管理服务进行动态endpoint发现：

    1. admin:
    2.   access_log_path: /tmp/admin_access.log
    3.   address:
    4.     socket_address: { address: 127.0.0.1, port_value: 9901 }
    6. static_resources:
    7.   listeners:
    8.   - name: listener_0
    9.     address:
    10.       socket_address: { address: 127.0.0.1, port_value: 10000 }
    11.     filter_chains:
    12.     - filters:
    13.       - name: envoy.http_connection_manager
    14.         config:
    15.           stat_prefix: ingress_http
    16.           codec_type: AUTO
    17.           route_config:
    18.             name: local_route
    19.             virtual_hosts:
    20.             - name: local_service
    21.               domains: ["*"]
    22.               routes:
    23.               - match: { prefix: "/" }
    24.                 route: { cluster: some_service }
    25.           http_filters:
    26.           - name: envoy.router
    27.   clusters:
    28.   - name: some_service
    29.     connect_timeout: 0.25s
    30.     lb_policy: ROUND_ROBIN
    31.     type: EDS
    32.     eds_cluster_config:
    33.       eds_config:
    34.         api_config_source:
    35.           api_type: GRPC
    36.           cluster_name: [xds_cluster]
    37.   - name: xds_cluster
    38.     connect_timeout: 0.25s
    39.     type: STATIC
    40.     lb_policy: ROUND_ROBIN
    41.     http2_protocol_options: {}
    42.     hosts: [{ socket_address: { address: 127.0.0.3, port_value: 5678 }}]

    注意：上面的xds_cluster被定义为Envoy的管理服务。即使在全动态的配置中，也需要定义一些静态资源，如指定Envoy对应的xDS管理服务。

    在上面的例子中，请求EDS管理服务，然后返回服务发现应答的原始编码：

    1. version_info: "0"
    2. resources:
    3. - "@type": type.googleapis.com/envoy.api.v2.ClusterLoadAssignment
    4.   cluster_name: some_service
    5.   endpoints:
    6.   - lb_endpoints:
    7.     - endpoint:
    8.         address:
    9.           socket_address:
    10.             address: 127.0.0.2
    11.             port_value: 1234

    以上出现的版本控制和URL类型方案，在流式gRPC订阅协议文档中有更详细的解释。

    全动态

    下面提供了一个全动态的引导配置，其中除了管理服务的其他所有资源都是通过xDS发现的：

    1. admin:
    2.   access_log_path: /tmp/admin_access.log
    3.   address:
    4.     socket_address: { address: 127.0.0.1, port_value: 9901 }
    6. dynamic_resources:
    7.   lds_config:
    8.     api_config_source:
    9.       api_type: GRPC
    10.       cluster_name: [xds_cluster]
    11.   cds_config:
    12.     api_config_source:
    13.       api_type: GRPC
    14.       cluster_name: [xds_cluster]
    16. static_resources:
    17.   clusters:
    18.   - name: xds_cluster
    19.     connect_timeout: 0.25s
    20.     type: STATIC
    21.     lb_policy: ROUND_ROBIN
    22.     http2_protocol_options: {}
    23.     hosts: [{ socket_address: { address: 127.0.0.3, port_value: 5678 }}]

    管理服务可以通过以下方式响应LDS请求：

    1. version_info: "0"
    2. resources:
    3. - "@type": type.googleapis.com/envoy.api.v2.Listener
    4.   name: listener_0
    5.   address:
    6.     socket_address:
    7.       address: 127.0.0.1
    8.       port_value: 10000
    9.   filter_chains:
    10.   - filters:
    11.     - name: envoy.http_connection_manager
    12.       config:
    13.         stat_prefix: ingress_http
    14.         codec_type: AUTO
    15.         rds:
    16.           route_config_name: local_route
    17.           config_source:
    18.             api_config_source:
    19.               api_type: GRPC
    20.               cluster_name: [xds_cluster]
    21.         http_filters:
    22.         - name: envoy.router

    管理服务可以通过以下方式响应RDS请求：

    1. version_info: "0"
    2. resources:
    3. - "@type": type.googleapis.com/envoy.api.v2.RouteConfiguration
    4.   name: local_route
    5.   virtual_hosts:
    6.   - name: local_service
    7.     domains: ["*"]
    8.     routes:
    9.     - match: { prefix: "/" }
    10.       route: { cluster: some_service }

    管理服务可以通过以下方式响应CDS请求：

    1. version_info: "0"
    2. resources:
    3. - "@type": type.googleapis.com/envoy.api.v2.Cluster
    4.   name: some_service
    5.   connect_timeout: 0.25s
    6.   lb_policy: ROUND_ROBIN
    7.   type: EDS
    8.   eds_cluster_config:
    9.     eds_config:
    10.       api_config_source:
    11.         api_type: GRPC
    12.         cluster_name: [xds_cluster]

    管理服务可以通过以下方式响应EDS请求：

    1. version_info: "0"
    2. resources:
    3. - "@type": type.googleapis.com/envoy.api.v2.ClusterLoadAssignment
    4.   cluster_name: some_service
    5.   endpoints:
    6.   - lb_endpoints:
    7.     - endpoint:
    8.         address:
    9.           socket_address:
    10.             address: 127.0.0.2
    11.             port_value: 1234

    管理服务

    一个v2 xDS管理服务，需要按照gRPC/REST服务的要求提供以下API端口。在同时支持流式gRPC和REST-JSON情况下，在接收一个发现请求时，按照xDS协议返回发现响应。

    gRPC流端口

    POST /envoy.api.v2.ClusterDiscoveryService/StreamClusters

    有关服务定义，请参阅cds.proto协议。当Envoy作为客户端时，这被使用：

    1. cds_config:
    2.   api_config_source:
    3.     api_type: GRPC
    4.     cluster_name: [some_xds_cluster]

    在引导配置的dynamic_resources中设置。

    POST /envoy.api.v2.EndpointDiscoveryService/StreamEndpoints

    有关服务定义，请参阅eds.proto协议。当Envoy作为客户端时，这被使用：

    1. eds_config:
    2.   api_config_source:
    3.     api_type: GRPC
    4.     cluster_name: [some_xds_cluster]

    在集群配置的eds_cluster_config字段中设置。

    POST /envoy.api.v2.ListenerDiscoveryService/StreamListeners

    有关服务定义，请参阅lds.proto。当Envoy作为客户端时，这被使用：

    1. lds_config:
    2.   api_config_source:
    3.     api_type: GRPC
    4.     cluster_name: [some_xds_cluster]

    在引导配置的dynamic_resources中设置。

    POST /envoy.api.v2.RouteDiscoveryService/StreamRoutes

    有关服务定义，请参阅rds.proto。当Envoy作为客户端时，这被使用：

    1. route_config_name: some_route_name
    2. config_source:
    3.   api_config_source:
    4.     api_type: GRPC
    5.     cluster_name: [some_xds_cluster]

    在Http Connection Manager配置的rds字段中设置。

    REST端口

    POST /v2/discovery:clusters

    有关服务定义，请参阅cds.proto协议。当Envoy作为客户端时，这被使用：

    1. cds_config:
    2.   api_config_source:
    3.     api_type: REST
    4.     cluster_name: [some_xds_cluster]

    在引导配置的dynamic_resources中设置。

    POST /v2/discovery:endpoints

    有关服务定义，请参阅eds.proto协议。当Envoy作为客户端时，这被使用：

    1. eds_config:
    2.   api_config_source:
    3.     api_type: REST
    4.     cluster_name: [some_xds_cluster]

    在集群配置的eds_cluster_config字段中设置。

    POST /v2/discovery:listeners

    有关服务定义，请参阅lds.proto。当Envoy作为客户端时，这被使用：

    1. lds_config:
    2.   api_config_source:
    3.     api_type: REST
    4.     cluster_name: [some_xds_cluster]

    在引导配置的dynamic_resources中设置。

    POST /v2/discovery:routes

    有关服务定义，请参阅rds.proto。当Envoy作为客户端时，这被使用：

    1. route_config_name: some_route_name
    2. config_source:
    3.   api_config_source:
    4.     api_type: REST
    5.     cluster_name: [some_xds_cluster]

    在Http Connection Manager配置的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），在本文档中有更详细的描述。gRPC端口是：

    POST /envoy.api.v2.AggregatedDiscoveryService/StreamAggregatedResources

    有关服务定义，请参阅discovery.proto。当Envoy作为客户端时，这被使用：

    1. ads_config:
    2.   api_type: GRPC
    3.   cluster_name: [some_ads_cluster]

    在引导配置的dynamic_resources中设置。

    设置此项时，可以将上述任何配置源设置为使用ADS通道。例如，一个LDS配置可以从

    1. lds_config:
    2.   api_config_source:
    3.     api_type: REST
    4.     cluster_name: [some_xds_cluster]

    修改为

    1. lds_config: {ads: {}}

    其效果是LDS流将通过共享的ADS通道被引导到some_ads_cluster。

    状态

    除非另有说明，否则将在v2 API参考中描述的所有功能。在v2 API参考和v2 API库中，所有接口原型都被冻结，除非它们被标记为草稿或实验原型。在这里，冻结意味着我们不会打破兼容性的底线。

    通过添加新的字段，以不破坏向后兼容性的方式，尽可能的进一步延长冻结原型的期限。上述原型中的字段可能会在不再使用相关功能的情况下，随着策略的改变而被弃用。虽然冻结的API保持其格式兼容性，但我们保留更改原名，文件位置和嵌套关系的权利，这可能导致代码更改中断。我们的目标是尽量减少这里的损失。

    当Protos标记为草案( draft )，意味着它们已经接近完成，至少可能在Envoy中部分实施，但可能会在冻结之前破坏原型格式。

    当Protos标记为实验性的( experimental )，与原始草案有相同的告警提示，并可能在Envoy执行冻结之前做出重大改变。

    当前所有v2 API问题在这里被跟踪。

    返回

    • 上一级
    • 首页目录