1.4.2 概述
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
标志,即:
./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服务代理的运行示例。
全静态
下面提供了一个全静态最小引导配置:
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管理服务,然后返回服务发现应答的原始编码:
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订阅协议文档中有更详细的解释。
全动态
下面提供了一个全动态的引导配置,其中除了管理服务的其他所有资源都是通过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协议。当Envoy作为客户端时,这被使用:
cds_config:
api_config_source:
api_type: GRPC
cluster_name: [some_xds_cluster]
在引导配置的dynamic_resources
中设置。
POST /envoy.api.v2.EndpointDiscoveryService/StreamEndpoints
有关服务定义,请参阅eds.proto协议。当Envoy作为客户端时,这被使用:
eds_config:
api_config_source:
api_type: GRPC
cluster_name: [some_xds_cluster]
在集群配置的eds_cluster_config
字段中设置。
POST /envoy.api.v2.ListenerDiscoveryService/StreamListeners
有关服务定义,请参阅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。当Envoy作为客户端时,这被使用:
route_config_name: some_route_name
config_source:
api_config_source:
api_type: GRPC
cluster_name: [some_xds_cluster]
在Http Connection Manager配置的rds字段中设置。
REST端口
POST /v2/discovery:clusters
有关服务定义,请参阅cds.proto协议。当Envoy作为客户端时,这被使用:
cds_config:
api_config_source:
api_type: REST
cluster_name: [some_xds_cluster]
在引导配置的dynamic_resources
中设置。
POST /v2/discovery:endpoints
有关服务定义,请参阅eds.proto协议。当Envoy作为客户端时,这被使用:
eds_config:
api_config_source:
api_type: REST
cluster_name: [some_xds_cluster]
在集群配置的eds_cluster_config
字段中设置。
POST /v2/discovery:listeners
有关服务定义,请参阅lds.proto。当Envoy作为客户端时,这被使用:
lds_config:
api_config_source:
api_type: REST
cluster_name: [some_xds_cluster]
在引导配置的dynamic_resources
中设置。
POST /v2/discovery:routes
有关服务定义,请参阅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配置的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作为客户端时,这被使用:
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参考中描述的所有功能。在v2 API参考和v2 API库中,所有接口原型都被冻结,除非它们被标记为草稿或实验原型。在这里,冻结意味着我们不会打破兼容性的底线。
通过添加新的字段,以不破坏向后兼容性的方式,尽可能的进一步延长冻结原型的期限。上述原型中的字段可能会在不再使用相关功能的情况下,随着策略的改变而被弃用。虽然冻结的API保持其格式兼容性,但我们保留更改原名,文件位置和嵌套关系的权利,这可能导致代码更改中断。我们的目标是尽量减少这里的损失。
当Protos标记为草案( draft ),意味着它们已经接近完成,至少可能在Envoy中部分实施,但可能会在冻结之前破坏原型格式。
当Protos标记为实验性的( experimental ),与原始草案有相同的告警提示,并可能在Envoy执行冻结之前做出重大改变。
当前所有v2 API问题在这里被跟踪。
返回
- 上一级