OPSaid – Envoy

Docs: 架构

Tue, 16 Jan 2024 16:34:31 +0800

简要概述

Envoy 是为面向服务架构（SOA）设计的 L7 层代理，主要围绕解决以下核心思想：

网络应对应用程序透明，当网络和应用程序发生问题时，应该很容易确定问题的根源。

功能特点

实现上述的目标非常困难，在设计上试图通过提供以下高级功能来实现这一目标：

独立进程架构

相比传统的 sdk 方式，部署升级更加简单方便；

L3/L4 过滤器架构

可插拔的过滤器链机制，可方便为 TCP/UDP 代理编译各自自定义任务；

HTTP L7 过滤器架构

方便为 HTTP 协议添加执行不同的任务，如缓冲、速率限制、路由/转发；

优先支持 HTTP/2

推荐服务使用 h2 以创建持久连接的网格，使得请求和响应可以通过多路复用；

HTTP/3 支持

支持上行和下行的HTTP/3，并能够在任何方向上进行HTTP/1.1、HTTP/2和HTTP/3的相互转换；

HTTP L7 路由

支持一个路由子系统，能够根据路径、权限、内容类型、运行时值等路由和重定向请求；

gRPC 支持

支持为 gRPC 请求和响应的路由和负载均衡；

服务发现和动态配置

支持 API 以及可动态更新集群本身能力；

健康检查

内置健康检查子系统，可以选择对上游服务集群执行主动的健康检查；

高级负载均衡

原生提供诸如自动重试、断路器、限速、异常检查等功能，并使其对任何应用程序都可使用；

前/边缘代理支持

原先提供了可观察性、管理、服务发现和负载均衡等非常易于在边缘端使用；

丰富的可观测性

为所有子系统提供了统计支持，对外暴露性能数据。

关键术语

术语	名称	说明
Host	主机	逻辑网络应用程序
Downstream	下游	下游客户端主机连接到 Envoy，发送请求并接收响应
Upstream	上游	上游服务端主机接收来自 Envoy 的连接和请求，并返回响应
Listener	监听器	提供给下游客户端连接的网络地址
Cluster	集群	Envoy 连接到逻辑上相同的一组上游主机
Mesh	网格	一组 Envoy 代理，它们之间互相协调网络拓扑
Runtime configuration	运行时配置	可以更改配置设置来影响运行，而无需重启 Envoy 或更改主要配置

xDS

Envoy xDS APIs（xDS 协议）使用 proto3 编写定义在官方代码仓库 api 中，它们支持：

通过 gRPC 进行 xDS API 更新
自动通过 proto3 映射为 reset api
支持本地配置文件、REST 接口或 gRPC 端点传递更新
通过扩展的端点分配 API 进行高级负载均衡
TODO; 在需要时提供更强的一致性和排序特性

启动配置

示例配置

在使用 xDS API，需提供引导配置文件以启动服务，支持两种配置：

静态配置（static_resources），启动前人工已编写好；
动态配置（dynamic_resources），通过 xDS 服务端自发现；

以下是静态配置的示例：

cat >> demo.yaml << EOF
static_resources:
 listeners:
 - name: listener_0
 address:
 # envoy 服务监听的地址
 socket_address:
 address: 0.0.0.0
 port_value: 80
 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 http_filters:
 - name: envoy.filters.http.router
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
 stat_prefix: ingress_http
 route_config:
 virtual_hosts:
 - name: local_service
 # 匹配所有入口域名
 domains: ["*"]
 routes:
 - match:
 # 匹配所有以 '/' 开头的路由
 prefix: "/"
 route:
 # 名称必须在 "clusters[_].name" 中存在
 cluster: oneops-syncds-v1
 # 对匹配到以 '/' 开头的路由，转发到后端 "oneops-syncds-v1" 时替换为 "/ds/" 前缀路径
 prefix_rewrite: "/ds/"

 clusters:
 - name: oneops-syncds-v1
 type: LOGICAL_DNS
 dns_lookup_family: V4_ONLY
 load_assignment:
 cluster_name: oneops-syncds-v1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 # 转发到后端真实服务器地址
 socket_address:
 address: 192.168.0.1
 port_value: 8080
EOF

启动服务，以在 “80” 端口监听，并对所有转入请求转发至后端 “192.168.0.1:8080” 服务，设置 url 前缀为 “/ds/"：

./envoy -c demo.yaml

静态配置

static_resources:
 listeners:
 ...

 clusters:
 ...

Docs: Bootstrap

Tue, 16 Jan 2024 16:34:31 +0800

简要概述

这里是 envoy 配置的定义。

proto 定义

Envoy 配置结构在源代码中使用 proto 定义，主要结构如下：

Bootstrap

message Bootstrap {
...
// Statically specified resources.
StaticResources static_resources = 2;
...
// Configuration for the local administration HTTP server.
Admin admin = 12;
...
}

message StaticResources {
option (udpa.annotations.versioning).previous_message_type =
"envoy.config.bootstrap.v2.Bootstrap.StaticResources";
// Static :ref:`Listeners <envoy_v3_api_msg_config.listener.v3.Listener>`. These listeners are
// available regardless of LDS configuration.
repeated listener.v3.Listener listeners = 1;
// If a network based configuration source is specified for :ref:`cds_config
// <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.DynamicResources.cds_config>`, it's necessary
// to have some initial cluster definitions available to allow Envoy to know
// how to speak to the management server. These cluster definitions may not
// use :ref:`EDS <arch_overview_dynamic_config_eds>` (i.e. they should be static
// IP or DNS-based).
repeated cluster.v3.Cluster clusters = 2;
// These static secrets can be used by :ref:`SdsSecretConfig
// <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.SdsSecretConfig>`
repeated envoy.extensions.transport_sockets.tls.v3.Secret secrets = 3;
}

message Admin {
option (udpa.annotations.versioning).previous_message_type = "envoy.config.bootstrap.v2.Admin";
// Configuration for :ref:`access logs <arch_overview_access_logs>`
// emitted by the administration server.
repeated accesslog.v3.AccessLog access_log = 5;
// The path to write the access log for the administration server. If no
// access log is desired specify ‘/dev/null’. This is only required if
// :ref:`address <envoy_v3_api_field_config.bootstrap.v3.Admin.address>` is set.
// Deprecated in favor of ``access_log`` which offers more options.
string access_log_path = 1
[deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
// The cpu profiler output path for the administration server. If no profile
// path is specified, the default is ‘/var/log/envoy/envoy.prof’.
string profile_path = 2;
// The TCP address that the administration server will listen on.
// If not specified, Envoy will not start an administration server.
core.v3.Address address = 3;
// Additional socket options that may not be present in Envoy source code or
// precompiled binaries.
repeated core.v3.SocketOption socket_options = 4;
// Indicates whether :ref:`global_downstream_max_connections <config_overload_manager_limiting_connections>`
// should apply to the admin interface or not.
bool ignore_global_conn_limit = 6;
}

完整信息查看 bootstrap.proto 定义。

StaticResources

listener.v3.Listener

TODO;

cluster.v3.Cluster

github.com/envoyproxy/envoy/api/envoy/config/cluster/v3/cluster.proto

message Cluster {
 ......
 // Supplies the name of the cluster which must be unique across all clusters.
 // The cluster name is used when emitting 
 // 集群名称，必须是唯一的
 string name = 1 [(validate.rules).string = {min_len: 1}];

 oneof cluster_discovery_type {
 // The :ref:`service discovery type <arch_overview_service_discovery_types>`
 // to use for resolving the cluster.
 DiscoveryType type = 2 [(validate.rules).enum = {defined_only: true}];

 // The custom cluster type.
 CustomClusterType cluster_type = 38;
 }

 // Configuration to use for EDS updates for the Cluster.
 EdsClusterConfig eds_cluster_config = 3;

 // The timeout for new network connections to hosts in the cluster.
 // If not set, a default value of 5s will be used.
 google.protobuf.Duration connect_timeout = 4 [(validate.rules).duration = {gt {}}];

 // Soft limit on size of the cluster’s connections read and write buffers. If
 // unspecified, an implementation defined default is applied (1MiB).
 google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5
 [(udpa.annotations.security).configure_for_untrusted_upstream = true];

 // The :ref:`load balancer type <arch_overview_load_balancing_types>` to use
 // when picking a host in the cluster.
 LbPolicy lb_policy = 6 [(validate.rules).enum = {defined_only: true}];

 // Setting this is required for specifying members of
 // :ref:`STATIC<envoy_v3_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STATIC>`,
 // :ref:`STRICT_DNS<envoy_v3_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>`
 // or :ref:`LOGICAL_DNS<envoy_v3_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>` clusters.
 // This field supersedes the ``hosts`` field in the v2 API.
 //
 // .. attention::
 //
 // Setting this allows non-EDS cluster types to contain embedded EDS equivalent
 // :ref:`endpoint assignments<envoy_v3_api_msg_config.endpoint.v3.ClusterLoadAssignment>`.
 //
 endpoint.v3.ClusterLoadAssignment load_assignment = 33;

 // Optional :ref:`active health checking <arch_overview_health_checking>`
 // configuration for the cluster. If no
 // configuration is specified no health checking will be done and all cluster
 // members will be considered healthy at all times.
 repeated core.v3.HealthCheck health_checks = 8;

 ......

 // The DNS IP address resolution policy. If this setting is not specified, the
 // value defaults to
 // :ref:`AUTO<envoy_v3_api_enum_value_config.cluster.v3.Cluster.DnsLookupFamily.AUTO>`.
 // 支持的网络协议栈，如 V4_ONLY、V6_ONLY、ALL，分别仅支持 IPv4、IPv6、IPv4 与 IPv6
 DnsLookupFamily dns_lookup_family = 17 [(validate.rules).enum = {defined_only: true}];

 ......

 // Optional custom transport socket implementation to use for upstream connections.
 // To setup TLS, set a transport socket with name ``envoy.transport_sockets.tls`` and
 // :ref:`UpstreamTlsContexts <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.UpstreamTlsContext>` in the ``typed_config``.
 // If no transport socket configuration is specified, new connections
 // will be set up with plaintext.
 core.v3.TransportSocket transport_socket = 24;

 ......
}

endpoint.v3.ClusterLoadAssignment

github.com/envoyproxy/envoy/api/envoy/config/endpoint/v3/endpoint.proto

message ClusterLoadAssignment {
......
// Name of the cluster. This will be the :ref:`service_name
// <envoy_v3_api_field_config.cluster.v3.Cluster.EdsClusterConfig.service_name>` value if specified
// in the cluster :ref:`EdsClusterConfig
// <envoy_v3_api_msg_config.cluster.v3.Cluster.EdsClusterConfig>`.
string cluster_name = 1 [(validate.rules).string = {min_len: 1}];
// List of endpoints to load balance to.
repeated LocalityLbEndpoints endpoints = 2;
// Map of named endpoints that can be referenced in LocalityLbEndpoints.
// [#not-implemented-hide:]
map<string, Endpoint> named_endpoints = 5;
// Load balancing policy settings.
Policy policy = 4;
}

core.v3.HealthCheck

api/envoy/config/core/v3/health_check.proto

https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto

Admin

TODO;

Docs: 监听器

Sun, 21 Jan 2024 21:34:26 +0800

简要概述

Envoy 支持在单个进程中使用任意数量的监听器配置，一般我们建议一台主机仅运行一个进程，而不管监听器数量。

支持 TCP 与 UDP 监听器。

TCP 监听器

每个监听器都配置了独立的网络层过滤器链（filter_chains），它由一个或多个网络层（L3/L4）过滤器组成，常见的有：

名称	描述	类型
rate limiting	限速	x
TLS client authentication	TLS 客户端身份验证	x
HTTP connection management	HTTP 连接管理	x
MongoDB sniffing	mongodb 嗅探	x
raw TCP proxy	原始 TCP 代理	x

当在监听器上接收到新连接时，根据配置的 “filter_chain_match” 条件选择适当的过滤器（filter_chain）然后开始处理后续事件。

监听器也可以选择配置监听器过滤器（listener filters），这些过滤器在网络层过滤器之前进行处理，并有机会操作连接元数据，通常是为了影响后续过滤器或集群如何处理连接。

static_resources:
 listeners:
 - name: listener_0
 address:
 ...
 # 监听器过滤器
 listener_filters:
 ...
 # 网络层过滤器
 filter_chains:
 ...

 clusters:
 ...

UDP 监听器

TODO;

过滤器

监听器过滤器

该过滤器主要目的用于管理连接的元数据，

发现服务 (LDS)

TODO;

Docs: HTTP

Mon, 22 Jan 2024 14:15:41 +0800

简要概述

Envoy 具有一个内置的网络层过滤器，称为 HTTP 连接管理器，它实现了大量的 HTTP 特定功能，接口定义在文件 http_connection_manager.proto 中。

因为是网络层过滤器，所以使用上是配置在 “filter_chains” 且类型名称为：

- name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager

示例配置

static_resources:
 listeners:
 - name: listener_0
 address:
 ...
 # 监听器过滤器
 listener_filters:
 ...
 # 网络层过滤器
 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 stat_prefix: ingress_http
 ...

 clusters:
 ...

功能特点

HTTP 协议原生支持：HTTP/1.1, HTTP/2 and HTTP/3
HTTP 头清理：为安全原因，会自动修正一些请求头
HTTP 路由表配置：支持静态或者动态 RDS 接口
HTTP 重试插件配置：多种充实机制可供选择

功能定义在：

github.com/envoyproxy/envoy/api/envoy/extensions/retry

HTTP 内部重定向
HTTP 超时处理

HTTP 过滤器

过滤器类型

类似网络层过滤器链（filter_chains），在 HTTP 连接管理器内，还支持专门处理该层协议的过滤器链配置（http_filters）。

HTTP 级别过滤器的API允许过滤器在不了解底层协议的情况下运行。

与网络级别过滤器一样，HTTP过滤器可以停止并继续迭代到后续过滤器。这允许更复杂的场景，如处理健康检查、调用速率限制服务、缓冲、路由、为应用程序流量生成DynamoDB等的统计信息。

编写过滤器无需过多底层协议知识，主要有三种类型：

Decoder（解码器）

当连接管理器解码请求流的部分（请求头、请求体和尾部）时，将调用解码器过滤器。

Encoder（编码器）

当连接管理器即将对部分响应流（响应头、响应体和尾部）进行编码时，将调用编码器过滤器。

Decoder/Encoder （解码器/编码器）

当连接管理器解码请求流的部分以及当连接管理器即将编码响应流的部分时，将同时调用解码器/编码器过滤器。

过滤器执行顺序

假设以下三个过滤器均是 “Decoder/Encoder” 类型：

http_filters:
- name: example.filters.a
 ...
- name: example.filters.b
 ...
- name: example.filters.c
 ...

当请求进入后，连接管理器按照以下顺序调用解码器过滤器：

example.filters.a
->
example.filters.b
->
example.filters.c

响应用户时按照相反的顺序调用编码器过滤器：

example.filters.c
->
example.filters.b
->
example.filters.a

HTTP 路由规则

基础结构

基础路由规则一般适合应用在处理边缘流量（传统的反向代理请求处理）以及服务端至服务端间组成的网格，它的配置在 “route_config” 部分：

static_resources:
 listeners:
 - name: listener_0
 address:
 ...
 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager

 # 路由配置
 route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"
 route:

注意 “scoped_routes” 与 “route_config” 只能二选一，见以下 proto 定义文件。

虚拟主机和集群

将匹配以下规则的请求转发至上游集群 “oneops-syncds-v1”：

匹配下游请求的所有域名，域名支持正则，配置 “domains” 为 “*”
匹配下游请求的所有 url 地址，配置 “routes.match[0].prefix” 为 “/”

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"
 route:
 cluster: oneops-syncds-v1

上游集群 “oneops-syncds-v1”：

 clusters:
 - name: oneops-syncds-v1
 type: LOGICAL_DNS
 dns_lookup_family: V4_ONLY
 load_assignment:
 cluster_name: oneops-syncds-v1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 address: 192.168.0.1
 port_value: 8080

客户端请求重定向

将匹配以下规则的请求转发重定向特定站点：

匹配下游请求的所有域名，域名支持正则，配置 “domains” 为 “*”
匹配下游请求的 url 前缀为 “/baidu”，配置 “routes.match[0].prefix” 为 “/baidu”
重定向站点配置 “host_redirect” 为 “www.baidu.com”
重定向站点使用 https 配置 “https_redirect” 为 true

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 # 支持 "NONE" "EXTERNAL_ONLY" "ALL"
 require_tls: NONE
 routes:
 - match:
 prefix: "/baidu"
 redirect:
 https_redirect: true
 host_redirect: www.baidu.com
 path_redirect: /

服务端响应 301 重定向：

* Trying 192.168.0.2:80...
* Connected to 192.168.0.2 (192.168.0.2) port 80 (#0)
> GET /baidu HTTP/1.1
> Host: 192.168.0.2
> User-Agent: curl/8.1.2
> Accept: */*
>
< HTTP/1.1 301 Moved Permanently
< location: https://192.168.0.2/baidu
< date: Mon, 22 Jan 2024 08:45:29 GMT
< server: envoy
< content-length: 0
<
* Connection #0 to host 192.168.0.2 left intact

路径前缀与请求匹配

将匹配以下规则的请求转发至上游集群 “oneops-syncds-v1”：

匹配下游请求的所有域名，域名支持正则，配置 “domains” 为 “*”
匹配下游请求的 url 为 “/"，配置 “routes[0].match.prefix” 为 “/”
匹配下游请求的 url 不区分大小写，配置 “routes[0].match.case_sensitive” 为 “true”
匹配下游请求头中 “user-agent” 值为 “SpecialClient”

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"
 case_sensitive: true
 headers:
 - name: user-agent
 exact_match: "SpecialClient"
 route:
 cluster: oneops-syncds-v1

curl -vvv -H "user-agent: SpecialClient" http://192.168.0.2:80

路径前缀与主机重写

将匹配以下规则的请求转发至上游集群 “oneops-syncds-v1”：

匹配下游请求为特定域名，配置 “domains” 为 “test.example.com”
匹配下游请求的 url 为 “/"，配置 “routes[0].match.prefix” 为 “/”

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["test.example.com"]
 routes:
 - match:
 prefix: "/"
 route:
 cluster: oneops-syncds-v1
 prefix_rewrite: "/ds/"
 host_rewrite_literal: "app.example.com"

同时转发上游集群时重写：

参数 “prefix_rewrite” 重写原始请求前缀为 “/ds/”
参数 “host_rewrite_literal” 重写原始请求域名为 “app.example.com”

请求超时重试与对冲

TODO;

未成功实现

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"
 route:
 cluster: oneops-syncds-v1
 retry_policy:
 retry_on: connect-failure,refused-stream,retriable-status-codes
 num_retries: 5
 retriable_status_codes:
 - "500"
 - "502"
 - "503"

请求流量分流与转移

根据权重负载到多个上游集群

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"
 route:
 weighted_clusters:
 clusters:
 - name: oneops-syncds-v1
 weight: 2
 - name: oneops-syncds-v2
 weight: 8

在两个上游集群进行流量转移

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"

 runtime_fraction:
 default_value:
 numerator: 20

 route:
 cluster: oneops-syncds-v1
 - match:
 prefix: "/"
 route:
 cluster: oneops-syncds-v2

支持基于策略的路由

TODO;

支持直接响应客户端

通过指令 “direct_response” 配置响应内容，这样无需从上游集群获取数据。

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"

 direct_response:
 status: 200
 body:
 inline_string: "hello world"

非 TLS 请求绝对转发

将匹配以下规则的请求转发至上游集群 “oneops-syncds-v1”：

匹配下游请求的所有域名，配置 “domains” 为 “*”
匹配下游请求的所有 url 地址，配置 “routes.match[0].prefix” 为 “/”

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"
 route:
 cluster: oneops-syncds-v1

通用匹配树指定路由表

使用 matcher 为通用匹配树，相比 routes 更具表达力的匹配引擎，允许在任意头部执行线性匹配，它提供了更大的灵活性，使得可以根据请求的各种头部信息进行更复杂的路由决策。

route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]

 matcher:
 matcher_tree:
 input:
 name: request-headers
 typed_config:
 "@type": type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
 header_name: :path
 exact_match_map:
 map:
 "/ds/v1":
 action:
 name: route_ds_v1
 typed_config:
 "@type": type.googleapis.com/envoy.config.route.v3.Route
 match:
 prefix: /
 route:
 cluster: oneops-syncds-v1
 "/ds/v2":
 action:
 name: route_ds_v1
 typed_config:
 "@type": type.googleapis.com/envoy.config.route.v3.Route
 match:
 prefix: /
 route:
 cluster: oneops-syncds-v2

详细使用见官方文档 Generic Matching。

HTTP 路由作用域

基础结构

路由作用域（Route Scope）用于将特定路由规则与某个作用域（scope）相关联，每个请求都会计算一个作用域键（scope key），并根据这个键来选择相应的路由规则，涉及以下两个概念：

Scope Key（作用域键）：对于每个请求，HTTP 连接管理器会动态计算一个作用域键，这个键用于决定选择哪个路由表。作用域键的计算可能基于请求的某些属性或上下文信息。
Route Table（路由表）：路由表是一组与特定作用域键相关联的路由规则。每个路由表定义了一组路由规则，当请求的作用域键与路由表相关联时，Envoy 将使用这个路由表来确定请求的最终路由。

static_resources:
 listeners:
 - name: listener_0
 address:
 ...
 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager

 # 路由作用域
 scoped_routes:
 name: scope_by_addr
 scope_key_builder:
 ......
 scoped_route_configurations_list:
 scoped_route_configurations:
 ......

注意 “scoped_routes” 与 “route_config” 只能二选一，在 “http_connection_manager.proto” 文件中定义的 “oneof route_specifier {}” 类型。

特定请求头

scoped_routes:
 name: scope_by_addr
 scope_key_builder:
 fragments:
 - header_value_extractor:
 name: Addr
 element_separator: ";"
 element:
 key: x-foo-key
 separator: "="

 scoped_route_configurations_list:
 scoped_route_configurations:
 - on_demand: true
 name: scoped_route_0
 key:
 fragments:
 - string_key: bar
 route_configuration:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"
 route:
 cluster: oneops-syncds-v2
 prefix_rewrite: "/ds/"

内置键中缺少片段（视为 NULL）会使请求无法匹配任何范围，即找不到该请求的路由条目。

HTTP 动态正向代理

下游使用明文访问

static_resources:
 listeners:
 - name: listener_0
 address:
 socket_address:
 protocol: TCP
 address: 0.0.0.0
 port_value: 80
 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 stat_prefix: ingress_http
 route_config:
 name: local_route
 virtual_hosts:
 - name: local_service
 domains: ["*"]
 routes:
 - match:
 prefix: "/"
 route:
 cluster: dynamic_forward_proxy_cluster
 http_filters:
 - name: envoy.filters.http.dynamic_forward_proxy
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.http.dynamic_forward_proxy.v3.FilterConfig
 dns_cache_config:
 name: dynamic_forward_proxy_cache_config
 dns_lookup_family: V4_ONLY
 typed_dns_resolver_config:
 name: envoy.network.dns_resolver.cares
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig
 - name: envoy.filters.http.router
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

 clusters:
 - name: dynamic_forward_proxy_cluster
 lb_policy: CLUSTER_PROVIDED
 cluster_type:
 name: envoy.clusters.dynamic_forward_proxy
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.clusters.dynamic_forward_proxy.v3.ClusterConfig
 dns_cache_config:
 name: dynamic_forward_proxy_cache_config
 dns_lookup_family: V4_ONLY
 typed_dns_resolver_config:
 name: envoy.network.dns_resolver.cares
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig
 transport_socket:
 name: envoy.transport_sockets.tls
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
 common_tls_context:
 validation_context:
 trusted_ca:
 filename: /etc/ssl/certs/ca-certificates.crt

下游使用 TLS 加密访问

static_resources:
 listeners:
 - name: listener_0
 address:
 socket_address:
 protocol: TCP
 address: 0.0.0.0
 port_value: 443
 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 stat_prefix: ingress_http
 ......
 http_filters:
 - name: envoy.filters.http.dynamic_forward_proxy
 ......

 transport_socket:
 name: envoy.transport_sockets.tls
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
 common_tls_context:
 tls_certificates:
 # The following self-signed certificate pair is generated using:
 # $ openssl req -x509 -newkey rsa:2048 -keyout a/front-proxy-key.pem -out a/front-proxy-crt.pem -days 3650 -nodes -subj '/CN=front-envoy'
 #
 # Instead of feeding it as an inline_string, certificate pair can also be fed to Envoy
 # via filename. Reference: https://envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.proto#config-core-v3-datasource.
 #
 # Or in a dynamic configuration scenario, certificate pair can be fetched remotely via
 # Secret Discovery Service (SDS). Reference: https://envoyproxy.io/docs/envoy/latest/configuration/security/secret.
 - certificate_chain:
 inline_string: |
 -----BEGIN CERTIFICATE-----

 -----END CERTIFICATE-----
 private_key:
 inline_string: |
 -----BEGIN PRIVATE KEY-----

 -----END PRIVATE KEY-----

 clusters:
 - name: dynamic_forward_proxy_cluster
 ......

Docs: 上游集群

Thu, 25 Jan 2024 21:55:29 +0800

简要概述

管理上游集群的配置，可以包含任意数量独立配置的上游集群，集群管理器处理了哪些主机可用和健康、负载平衡、线程本地存储上游连接数据、上游连接类型（TCP/IP、UDP）、上游协议在适用的情况下（HTTP/1.1、HTTP/2、HTTP/3）等所有复杂性。

集群管理配置可支持：

静态配置
集群发现服务（CDS）API

集群配置

静态配置

static_resources:
 listeners:
 - name: listener_0

 ......

 clusters:
 - name: oneops-syncds-v1
 type: LOGICAL_DNS
 dns_lookup_family: V4_ONLY
 load_assignment:
 cluster_name: oneops-syncds-v1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 address: 192.168.0.1
 port_value: 8080

服务发现

在配置中定义上游集群时，Envoy需要知道如何解析集群的成员。这被称为服务发现。

在 envoy 上最佳案例是使用最终一致的服务发现以及主动健康检查（Envoy 显式地对上游集群成员进行健康检查）来确定集群健康，而不是类似其他Zookeeper、etcd、Consul 等做一致性协调。

STATIC

静态是最简单的服务发现类型。配置明确指定了每个上游主机的解析网络名称（IP地址/端口、Unix域套接字等）。

clusters:
- name: oneops-syncds-v1
 type: STATIC
 dns_lookup_family: V4_ONLY
 load_assignment:
 cluster_name: oneops-syncds-v1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 address: 192.168.0.1
 port_value: 8080

STRICT_DNS

clusters:
- name: oneops-syncds-v1
 type: STRICT_DNS
 dns_lookup_family: V4_ONLY
 load_assignment:
 cluster_name: oneops-syncds-v1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 address: example.com
 port_value: 80

注意需配合主机头，否则会出现 403 错误等。

LOGICAL_DNS

TODO;

EDS

clusters:
- name: oneops-syncds-v1
 type: EDS
 dns_lookup_family: V4_ONLY
 eds_cluster_config:
 eds_config:
 resource_api_version: V3
 api_config_source:
 # 通过 http 接口
 api_type: REST
 transport_api_version: V3
 refresh_delay: 2s
 cluster_names:
 - eds_cluster
 # 通过 grpc 接口
 #api_type: GRPC
 #grpc_services:
 #- envoy_grpc:
 # cluster_name: eds_cluster

- name: eds_cluster
 type: STATIC
 dns_lookup_family: V4_ONLY
 load_assignment:
 cluster_name: eds_cluster
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 address: 10.5.17.224
 port_value: 80

以上配置含义，对使用到上游集群名为 “oneops-syncds-v1” 的路由，获取端点的方式是通过 REST 接口访问 “xds_cluster” 配置的 “10.5.17.224:80” 地址，接口为：

POST /v3/discovery:endpoints

ORIGINAL_DST

TODO;

健康检查

HTTP 主动健康检查

通过在 “clusters[_].health_checks” 添加参数，示例如下，更多可参考 Bootstrap 中 core.v3.HealthCheck 配置。

clusters:
- name: oneops-syncds-v2
 type: STATIC
 dns_lookup_family: V4_ONLY
 lb_policy: round_robin

 load_assignment:
 cluster_name: test1
 endpoints:
 - lb_endpoints:
 - endpoint:
 # 针对各端点单独的健康检查配置
 #health_check_config:
 # 上游端口健康检查的服务端口，有时候业务端口与健康检查端口分开
 # port_value: 8080
 # address:
 # socket_address:
 # address: 192.168.0.1
 # port_value: 8000
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8080
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8000

 health_checks:
 - timeout: 1s
 interval: 2s
 unhealthy_threshold: 1
 healthy_threshold: 1
 http_health_check:
 path: "/health"
 event_log_path: /var/log/envoy.log
 always_log_health_check_failures: true

这里上游端点 192.168.0.1:8080 与 192.168.0.1:8080 在 envoy 首次启动时，使用 HTTP 健康检查访问 “/health” 必须可用，否则即使探测失败，也是不会移除不可用端点的。

也就是所有上游端点健康检查失败情况下，则 envoy 行为是把所有端口都对外提供服务了。

HTTP 健康检查过滤器

在大规模网络中，如果上游服务对外提供 HTTP 健康检查地址（如："/ping"），下游探测器（如：prometheus）请求这类地址可能会产生较大的健康检查流量，你可以通过 HTTP 健康检查过滤器（配置在 http_filters 中）适当缓存以降低这种流量回到上游服务中，支持以下几种模式：

不透传（No pass through）

下游请求这类健康检查 URL 地址永远不会传递到上游服务，根据服务器当前的状态，Envoy 将回复 200 或 503。

filter_chains:
- filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 http_filters:
 - name: envoy.extensions.filters.http.health_check
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.http.health_check.v3.HealthCheck
 pass_through_mode: false
 headers:
 - name: ":method"
 string_match:
 exact: "GET"
 - name: ":path"
 prefix_match: "/ping"

不透传，根据上游集群健康计算 (No pass through, computed from upstream cluster health):

下游请求这类健康检查 URL 地址将根据一个或多个上游集群中至少指定百分比的服务器是否可用（健康 + 降级），返回 200 或 503，但是如果 Envoy 服务器处于排空状态，它将无论上游集群的健康状态如何都会回复503。

TODO;

透传 (Pass through):

下游请求这类健康检查 URL 地址将会传递到上游服务，上游服务根据其健康状态返回 200 或 503。

filter_chains:
- filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 http_filters:
 - name: envoy.extensions.filters.http.health_check
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.http.health_check.v3.HealthCheck
 pass_through_mode: true
 headers:
 - name: ":method"
 string_match:
 exact: "GET"
 - name: ":path"
 prefix_match: "/ping"

透传跟缓存 (Pass through with caching)

下游请求这类健康检查 URL 地址将会传递给上游服务，envoy 服务器会将结果缓存一段时间，随后的请求将在缓存时间内返回缓存值，当缓存时间达到时，下一个健康检查请求将被传递给下游服务。

filter_chains:
- filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 http_filters:
 - name: envoy.extensions.filters.http.health_check
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.http.health_check.v3.HealthCheck
 pass_through_mode: true
 cache_time: 30s
 headers:
 - name: ":method"
 string_match:
 exact: "GET"
 - name: ":path"
 prefix_match: "/ping"

以上几种模式，均需注意下配置下 “headers” 过滤特定的健康检查请求，否则会把所有请求均人为健康探测流量被缓存，从而影响了业务流量。

异常值检测

它也称为被动健康检查，在 config.cluster.v3.OutlierDetection 配置，区别于主动健康检查，在 config.core.v3.HealthCheck，它们可以配合使用也可以单独使用。

异常值检测是动态确定上游集群中某些主机的性能是否与其他主机不同，并将其从健康负载均衡集中移除的过程。常见的异常值包含：连续的故障、时间成功率、时间延迟等，它需要过滤器来报告数据，当前仅以下过滤器支持：[http router]，[tcp proxy]，[redis proxy]，[thrift proxy]

检测错误分为两类：

外部生成的错误

外部生成的错误是事务特定的，发生在上游服务器对接收到的请求做出响应时。例如，HTTP服务器返回错误代码500或者redis服务器返回无法解码的有效负载。这些错误是在Envoy成功连接到上游主机之后由上游主机生成的。

本地生成的错误

由 Envoy 生成的，响应于中断或阻止与上游主机通信的事件。本地生成错误的例子包括超时、TCP复位、无法连接到指定端口等。

连续的 5xx 错误

TODO;

网关连续故障

TODO;

连续本地起源失败

TODO;

成功率

TODO;

失败率

TODO;

异常检测日志

TODO;

负载均衡

TODO;

支持的类型

在单个上游集群中存在多个主机，需要把下游客户端请求负载均衡至各个主机，以有效的利用资源，envoy 这里分为两类：全局负载均衡和分布式负载均衡。

分布式负载均衡

是指 Envoy 根据上游主机的位置来确定如何将负载分配给端点。

在这种策略下，Envoy 可以根据上游主机的位置信息做出更智能的负载均衡决策。

这通常包括考虑主机的地理位置、网络延迟等因素，以优化流量的分发。这种方式使Envoy能够更好地适应不同主机之间的差异，提高系统的性能和稳定性。

激活的健康检查（Active health checking）：通过对上游主机进行健康检查，Envoy可以调整优先级和本地性的权重，以适应不可用主机。

区域感知路由（Zone aware routing）：这可以使Envoy在不需要在控制平面中明确配置优先级的情况下，更喜欢较近的端点。

负载均衡算法：Envoy可以使用多种不同的算法，利用提供的权重来确定选择哪个主机。这些算法有助于更精细地控制流量的分发，以满足系统的性能和可靠性需求。

全局负载均衡

是指有一个单一权威的数据来决定如何在主机之间分配负载，既控制平面完成，它可以通过指定各种参数（如优先级、本地性权重、端点权重和端点健康状况）来调整应用于单个端点的负载。

大多数复杂的部署都会同时使用这两类特性。例如，可以使用全局负载均衡来定义高级别的路由优先级和权重，同时使用分布式负载均衡来响应系统的变化（例如，使用主动健康检查）。通过结合使用这两种方式，可以充分发挥两者的优势：在宏观层面上，可以通过一个全局意识的权威来控制流量的流向，同时在微观层面上，个体代理可以对系统变化做出反应。

策略：加权轮询

加权轮询（Weighted Round Robin）是一种简单的策略，它按照轮询的顺序选择每个可用的上游主机，如果在某个地区给端点分配了权重，那么将使用加权轮询的调度表，其中具有较高权重的端点将更频繁地出现在轮换中，以实现有效的加权。

clusters:
- name: oneops-syncds-v2
 type: STATIC
 dns_lookup_family: V4_ONLY
 lb_policy: ROUND_ROBIN
 load_assignment:
 cluster_name: test1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8080
 load_balancing_weight: 1
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8000
 load_balancing_weight: 9

以上配置 “lb_policy” 与 “load_balancing_weight” 分布对应该策略与对应端点的权重。

策略：加权最小请求数

加权最小请求数（Weighted Least Request）取决于主机是否具有相同的权重，有以下区别：

所有权重相等

这是一种O(1)算法，根据配置选择 N 个随机的可用主机（默认为2），然后选择具有最少活动请求的主机，权重会随着这些主机上的活动请求数量的增加而减小。

所有权重不相等

如果集群中多个主机具有不同的权重，负载均衡器将使用加权轮询调度表，在请求时动态调整权重，权重是在选择主机时使用以下公式计算的：

weight = load_balancing_weight / (active_requests + 1)^active_request_bias.

active_request_bias 可以通过运行时进行配置，默认值为 1.0 且必须大于或等于 0.0。由公式知活动请求数越大，则相应的有效权重越低。同时 “active_request_bias=0” 时，等同于加权轮询。

clusters:
- name: oneops-syncds-v2
 type: STATIC
 dns_lookup_family: V4_ONLY
 lb_policy: LEAST_REQUEST
 load_assignment:
 cluster_name: test1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8080
 load_balancing_weight: 2
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8000
 load_balancing_weight: 1

TODO;

策略：环形哈希

环形哈希（Ring hash）实现了一致性哈希到上游主机，每个主机通过对其地址进行哈希映射到一个圆上（即由哈希组成的"环"），然后通过对请求的某个属性进行哈希，找到顺时针方向上最近的相应主机来路由每个请求。

如果希望使用主机地址以外的其他内容作为哈希键去组成圆环，则可以在 “envoy.lb” 的 LbEndpoint.Metadata 中指定，例如：

clusters:
- name: oneops-syncds-v2
 type: STATIC
 dns_lookup_family: V4_ONLY
 #lb_policy: ROUND_ROBIN
 lb_policy: RING_HASH

 ring_hash_lb_config:
 minimum_ring_size: 2
 maximum_ring_size: 2
 #hash_function: MURMUR_HASH_2
 #hash_function: XX_HASH

 load_assignment:
 cluster_name: test1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8080
 #load_balancing_weight: 1
 #metadata:
 # filter_metadata:
 # envoy.lb:
 # hash_key: "test1"
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8000
 #load_balancing_weight: 1
 #metadata:
 # filter_metadata:
 # envoy.lb:
 # hash_key: "test2"

TODO;

策略：Maglev

Maglev 算法是一种一致性哈希算法，可以作为环形哈希负载均衡器的替代方案，它提供更好的负载分布和可扩展性。

clusters:
- name: oneops-syncds-v2
 type: STATIC
 dns_lookup_family: V4_ONLY
 lb_policy: MAGLEV

 load_assignment:
 cluster_name: test1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8080
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8000

TODO;

策略：随机

随机（Random）负载均衡器是一种简单的策略，它从可用的上游主机中随机选择一个，与轮询策略相比，随机选择通常在没有健康检查策略的情况下表现更好。

clusters:
- name: oneops-syncds-v2
 type: STATIC
 dns_lookup_family: V4_ONLY
 lb_policy: MAGLEV

 load_assignment:
 cluster_name: test1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8080
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8000

TODO;

负载优先级

在负载均衡期间，如果上游集群存在多个 “lb_endpoints” 配置，则 envoy 只会考虑把流量转发至最高优先级级别一组主机。

对于每个 “lb_endpoints” config.endpoint.v3.LocalityLbEndpoints 可以指定一个可选的参数 “priority” 表示优先级，从数字 0 至 N 代表从高至低，当最高优先级级别的主机（P=0）健康时，所有流量都会落在该优先级级别的端点上，仅当最高优先级级别的端点变得不健康时，流量将开始流向较低的优先级级别调度，这个记得需配合健康检查使用。

clusters:
- name: oneops-syncds-v2
 type: STATIC
 dns_lookup_family: V4_ONLY
 lb_policy: RANDOM
 load_assignment:
 cluster_name: test1
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8080
 priority: 1
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 protocol: TCP
 address: 192.168.0.1
 port_value: 8000
 priority: 10

 health_checks:
 - timeout: 1s
 interval: 2s
 unhealthy_threshold: 1
 healthy_threshold: 1
 http_health_check:
 path: "/health"
 event_log_path: /var/log/envoy.log
 always_log_health_check_failures: true

以上端点 “192.168.0.1:8080” 如果正常，则所有流量均到该节点，仅当健康检测失败后才会被流量转发至 “192.168.0.1:8000” 端点，详细的算法调度表可参考 Priority levels。

聚合集群

TODO;

Docs: 可观测性

Wed, 31 Jan 2024 17:26:04 +0800

简要概述

包含 envoy 的访问日志、性能数据、链路跟踪三类数据。

其中 HTTP连接管理、TCP 代理、Thrift 代理还有以下特点：

可配置任意数量的访问日志模式；
可自定义访问日志过滤器，将不同类型的请求和响应写入不同的访问日志。

访问日志配置

在监听器中使用

见 config.listener.v3.Listener 数据结构中以下几个参数：

{
 ......
 "access_log": [],
 ......
}

配置示例：

static_resources:
 listeners:
 - name: listener_0

 access_log:
 - name: envoy.access_loggers.stdout
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog

访问示例：

$ curl -vvv 'http://192.168.0.2:80'
$ curl -vvv 'http://192.168.0.2:80'
$ curl -vvv 'http://192.168.0.2:80'
$ telnet 192.168.0.2 80

输出示例：

[2024-02-01T08:59:07.049Z] "- - HTTP/1.1" 0 - 74 201 32 - "-" "-" "-" "-" "-"
[2024-02-01T08:59:08.175Z] "- - HTTP/1.1" 0 - 74 200 3 - "-" "-" "-" "-" "-"
[2024-02-01T08:59:08.868Z] "- - HTTP/1.1" 0 - 74 201 15 - "-" "-" "-" "-" "-"
[2024-02-01T08:59:22.948Z] "- - -" 0 DPE 7 156 3131 - "-" "-" "-" "-" "-"

下游连接访问日志可以通过启用监听器访问日志来实现。

监听器访问日志是HTTP请求访问日志的补充，可以独立于过滤器访问日志单独启用。这提供了更灵活的配置选项，使得可以对下游连接的访问情况进行记录，从而更好地监测和分析网络流量。

在 UDP 代理中使用

见 extensions.filters.udp.udp_proxy.v3.UdpProxyConfig 数据结构。

{
 ......
 "access_log": [],
 "proxy_access_log": [],
 "access_log_options": {...}
 ......
}

TODO;

在 TCP 代理中使用

见 extensions.filters.network.tcp_proxy.v3.TcpProxy 数据结构。

{
 ......
 "access_log": [],
 "access_log_flush_interval": {...},
 "flush_access_log_on_connected": ...,
 "access_log_options": {...}
 ......
}

TODO;

在 HTTP 管理中使用

见 extensions.filters.network.http_connection_manager.v3.HttpConnectionManager 数据结构中以下几个参数：

{
 ......
 "access_log": [],
 "access_log_flush_interval": {...},
 "flush_access_log_on_new_request": ...,
 "access_log_options": {...},
 ......
}

配置示例：

static_resources:
 listeners:
 - name: listener_0
 ......
 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager

 access_log:
 - name: envoy.access_loggers.stdout
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog

访问示例：

$ curl -vvv 'http://192.168.0.2:80'
$ telnet 192.168.0.2 80

日志记录：

[2024-02-01T09:38:40.387Z] "GET / HTTP/1.1" 200 - 0 5 14 12 "-" "curl/8.1.2" "e84f1a02-bbec-4c64-b908-aaf9f2b025cd" "192.168.0.2" "192.168.0.1:8080"
[2024-02-01T09:39:17.379Z] "- - HTTP/1.1" 400 DPE 0 11 0 - "-" "-" "-" "-" "-"

在 HTTP 路由中使用

见 extensions.filters.http.router.v3.Router 数据结构。

配置示例：

http_filters:
- name: envoy.filters.http.router
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

 upstream_log:
 - name: envoy.access_loggers.stdout
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
 upstream_log_options:
 # 是否记录请求前日志
 flush_upstream_log_on_upstream_stream: false
 upstream_log_flush_interval: 1s

访问示例：

$ curl -vvv 'http://192.168.0.2:80'
$ telnet 192.168.0.2 80

日志示例：

[2024-02-01T09:28:24.230Z] "GET / HTTP/1.1" 200 - 5 0 13 - "-" "curl/8.1.2" "f43c6cae-a2c3-4722-991e-f8bab54bd0d1" "192.168.0.2" "192.168.0.1:8000"

在上面的 “telnet” 是不会在该阶段产生日志，所以仅存在一条。

访问日志格式

支持的变量

字段	HTTP	TCP	UDP	THRIFT
%START_TIME%	支持	支持	支持	支持
%EMIT_TIME%	支持	支持	支持	支持
%REQUEST_HEADERS_BYTES%	支持	-	-	-
%BYTES_RECEIVED%	支持	支持	-	-
%BYTES_RETRANSMITTED%	HTTP3	-	-	-
%PACKETS_RETRANSMITTED%	HTTP3	-	-	-
%PROTOCOL%	支持	-	-	-
%UPSTREAM_PROTOCOL%	支持	-	-	-
%RESPONSE_CODE%	支持	-	-	-
%RESPONSE_CODE_DETAILS%	支持	-	-	-
%CONNECTION_TERMINATION_DETAILS%	支持	支持	-	-
%RESPONSE_HEADERS_BYTES%	支持	-	-	-
%RESPONSE_TRAILERS_BYTES%	支持	-	-	-
%BYTES_SENT%	支持	支持	-	支持
%UPSTREAM_REQUEST_ATTEMPT_COUNT%	支持	支持	-	-
%UPSTREAM_WIRE_BYTES_SENT%	支持	支持	-	-
%UPSTREAM_WIRE_BYTES_RECEIVED%	支持	支持	-	-
%UPSTREAM_HEADER_BYTES_SENT%	支持	-	-	-
%UPSTREAM_HEADER_BYTES_RECEIVED%	支持	-	-	-
%DOWNSTREAM_WIRE_BYTES_SENT%	支持	支持	-	-
%DOWNSTREAM_WIRE_BYTES_RECEIVED%	支持	支持	-	-
%DOWNSTREAM_HEADER_BYTES_SENT%	支持	-	-	-
%DOWNSTREAM_HEADER_BYTES_RECEIVED%	支持	-	-	-
%DURATION%	支持	支持	-	支持
%REQUEST_DURATION%	支持	-	-	-
%REQUEST_TX_DURATION%	支持	-	-	-
%RESPONSE_DURATION%	支持	-	-	-
%ROUNDTRIP_DURATION%	HTTP3	-	-	-
%RESPONSE_TX_DURATION%	支持	-	-	-
%DOWNSTREAM_HANDSHAKE_DURATION%	-	支持	-	-
%UPSTREAM_CONNECTION_POOL_READY_DURATION%	支持	支持	-	-
%RESPONSE_FLAGS%	支持	支持	-	-
%RESPONSE_FLAGS_LONG%	支持	支持	-	-
%ROUTE_NAME%	支持	支持	-	-
%VIRTUAL_CLUSTER_NAME%	gRPC	-	-	-
%UPSTREAM_HOST%	支持	支持	支持	支持

这里仅列出部分，更多参考官方 Command Operators。

默认格式与自定义

默认日志格式为：

[%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%"
%RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION%
%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%"
"%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"\n

在 yaml 中编写时，注意 ‘"’ 引号转译，如：

access_log:
- name: envoy.access_loggers.stdout
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
 log_format:
 text_format: "[%START_TIME%] \"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%\" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% \"%REQ(X-FORWARDED-FOR)%\" \"%REQ(USER-AGENT)%\" \"%REQ(X-REQUEST-ID)%\" \"%REQ(:AUTHORITY)%\" \"%UPSTREAM_HOST%\"\n"

与 nginx 格式对比

nginx 日志格式：

log_format main '$msec "$remote_addr" $request_length "$request_method" "$host" "$request_uri"'
 ' "$server_name" "$server_addr" $server_port "$uri" "$args" "$server_protocol"'
 ' $bytes_sent $body_bytes_sent $status $request_time "$http_referer" "$http_user_agent"'
 ' "$http_x_tr_user_id" "$http_x_tr_pv_id" "$http_x_tr_request_id" "$http_x_tr_rpc_id"'
 ' "$upstream_addr" "$http_x_forwarded_for" [$time_local] ';

TODO;

性能数据配置

开启 prometheus 端点

admin:
 address:
 socket_address:
 address: 127.0.0.1
 port_value: 9902

访问 http://127.0.0.1:9902/stats/prometheus

链路跟踪配置

初始化服务

通过 extensions.filters.network.http_connection_manager.v3.HttpConnectionManager 配置以下内容：

{
 ......
 "tracing": {
 "client_sampling": {...},
 "random_sampling": {...},
 "overall_sampling": {...},
 "verbose": ...,
 "max_path_tag_length": {...},
 "custom_tags": [],
 "provider": {...},
 "spawn_upstream_span": {...}
 },
 ......
}

必须添加 “provider” 开启外部的链路跟踪服务提供方配置，支持以下几个：

envoy.tracers.datadog
envoy.tracers.dynamic_ot
envoy.tracers.opencensus
envoy.tracers.opentelemetry
envoy.tracers.skywalking
envoy.tracers.xray
envoy.tracers.zipkin

这里以 “envoy.tracers.opentelemetry” 为示例：

filter_chains:
- filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 tracing:
 provider:
 name: envoy.tracers.opentelemetry
 typed_config:
 "@type": type.googleapis.com/envoy.config.trace.v3.OpenTelemetryConfig
 # 上报到 otel 的服务名，默认为：unknown_service:envoy
 service_name: ingress-http:envoy
 http_service:
 http_uri:
 uri: "http://tracing-analysis-dc-hz.aliyuncs.com/adapt_******_******/api/otlp/traces"
 cluster: aliyun
 timeout: 3s

Docs: xDS 接口

Fri, 02 Feb 2024 16:51:48 +0800

简要概述

Envoy 支持静态与动态两种配置方式，具体使用哪种根据实际情况而定。

静态方式：由管理员预先编写好 “yaml” 文件启动；
动态方式：由外部的 grpc 或 http 服务提供 API 接口，这些接口称为 xDS（发现服务）。

xDS	类型
LDS	envoy.config.listener.v3.Listener
RDS	envoy.config.route.v3.RouteConfiguration
x	envoy.config.route.v3.ScopedRouteConfiguration
VHDS	envoy.config.route.v3.VirtualHost
CDS	[]envoy.config.cluster.v3.Cluster
EDS	envoy.config.endpoint.v3.ClusterLoadAssignment
x	envoy.extensions.transport_sockets.tls.v3.Secret
x	envoy.service.runtime.v3.Runtime

静态方式

在完全静态的配置中，实施者提供一组监听器（和过滤器链）、集群等。动态主机发现仅通过基于DNS的服务发现实现。配置重载必须通过内置的热重启机制进行。

尽管这种方式相对简单，但可以使用静态配置和优雅的热重启创建相当复杂的部署。这种方法适用于一些场景，尤其是在环境相对静态、变化不频繁的情况下。

动态方式

端点发现服务(EDS)

端点发现服务（Endpoint Discovery Service (EDS) API），相比在静态配置中使用 DNS 实现动态主机发现，但 EDS 更灵活可自定义性强。

见 eds.proto 服务定义：

service EndpointDiscoveryService {
 option (envoy.annotations.resource).type = "envoy.config.endpoint.v3.ClusterLoadAssignment";

 // The resource_names field in DiscoveryRequest specifies a list of clusters
 // to subscribe to updates for.
 rpc StreamEndpoints(stream discovery.v3.DiscoveryRequest)
 returns (stream discovery.v3.DiscoveryResponse) {
 }

 rpc DeltaEndpoints(stream discovery.v3.DeltaDiscoveryRequest)
 returns (stream discovery.v3.DeltaDiscoveryResponse) {
 }

 rpc FetchEndpoints(discovery.v3.DiscoveryRequest) returns (discovery.v3.DiscoveryResponse) {
 option (google.api.http).post = "/v3/discovery:endpoints";
 option (google.api.http).body = "*";
 }
}

在 envoy 的 cluster 中使用：

static_resources:
 ......

 clusters:
 - name: xds_cluster
 type: EDS
 eds_cluster_config:
 eds_config:
 resource_api_version: V3
 ......

示例配置见上游集群 / EDS。

集群发现服务(CDS)

集群发现服务 (CDS) API （Cluster Discovery Service (CDS) API）

见 cds.proto：

// Return list of all clusters this proxy will load balance to.
service ClusterDiscoveryService {
 option (envoy.annotations.resource).type = "envoy.config.cluster.v3.Cluster";

 rpc StreamClusters(stream discovery.v3.DiscoveryRequest)
 returns (stream discovery.v3.DiscoveryResponse) {
 }

 rpc DeltaClusters(stream discovery.v3.DeltaDiscoveryRequest)
 returns (stream discovery.v3.DeltaDiscoveryResponse) {
 }

 rpc FetchClusters(discovery.v3.DiscoveryRequest) returns (discovery.v3.DiscoveryResponse) {
 option (google.api.http).post = "/v3/discovery:clusters";
 option (google.api.http).body = "*";
 }
}

在 envoy 的 dynamic_resources 中使用：

......
static_resources:
 ......

dynamic_resources:
 cds_config:
 resource_api_version: V3
 api_config_source:
 api_type: REST
 transport_api_version: V3
 refresh_delay: 2s
 cluster_names:
 - xds-cluster

......

路由发现服务(RDS)

路由发现服务 (RDS) API

见 rcs.proto：

service RouteDiscoveryService {
 option (envoy.annotations.resource).type = "envoy.config.route.v3.RouteConfiguration";

 rpc StreamRoutes(stream discovery.v3.DiscoveryRequest)
 returns (stream discovery.v3.DiscoveryResponse) {
 }

 rpc DeltaRoutes(stream discovery.v3.DeltaDiscoveryRequest)
 returns (stream discovery.v3.DeltaDiscoveryResponse) {
 }

 rpc FetchRoutes(discovery.v3.DiscoveryRequest) returns (discovery.v3.DiscoveryResponse) {
 option (google.api.http).post = "/v3/discovery:routes";
 option (google.api.http).body = "*";
 }
}

在 envoy 的 HttpConnectionManager 中使用：

...

static_resources:
 listeners:
 - name: listener_0
 address:

 ......

 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 stat_prefix: ingress_http
 rds:
 route_config_name: test-route-1
 config_source:
 resource_api_version: V3
 api_config_source:
 api_type: REST
 transport_api_version: V3
 refresh_delay: 2s
 cluster_names:
 - xds-cluster
...

虚拟主机发现服务(VHDS)

TODO；

虚拟主机发现服务 Virtual Host Discovery Service

在 envoy 的 route.proto 中 “vhds” 使用：

虚拟主机发现服务（VHDS）协议使用增量xDS协议。

路由发现服务(SRDS)

TODO;

侦听器发现服务(LDS)

TODO;

见 lds.proto 服务定义：

service ListenerDiscoveryService {
 option (envoy.annotations.resource).type = "envoy.config.listener.v3.Listener";

 rpc DeltaListeners(stream discovery.v3.DeltaDiscoveryRequest)
 returns (stream discovery.v3.DeltaDiscoveryResponse) {
 }

 rpc StreamListeners(stream discovery.v3.DiscoveryRequest)
 returns (stream discovery.v3.DiscoveryResponse) {
 }

 rpc FetchListeners(discovery.v3.DiscoveryRequest) returns (discovery.v3.DiscoveryResponse) {
 option (google.api.http).post = "/v3/discovery:listeners";
 option (google.api.http).body = "*";
 }
}

密钥发现服务(SDS)

TODO;

运行时发现服务(RTDS)

TODO;

扩展配置发现服务(ECDS)

TODO;

Docs: 安全认证

Wed, 07 Feb 2024 09:57:41 +0800

简要概述

TODO;

证书验证

https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/transport_socket/transport_socket

配合上游使用

在 config.cluster.v3.Cluster 中的 transport_socket 配置使用，支持以下类型：

名称	类型
envoy.transport_sockets.tls	extensions.transport_sockets.tls.v3.UpstreamTlsContext

如在 clusters[_].transport_socket 中配置使用 “/tmp/http-ca.crt” 作为 ca 验证上游服务端：

static_resources:

 ......

 clusters:
 - name: oneops-syncds-v1
 type: STATIC

 ......

 transport_socket:
 name: envoy.transport_sockets.tls
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
 # 通用 tls 配置，则不做校验仅做通讯加密
 common_tls_context:
 # 这说明需使用 "/tmp/http-ca.crt" 去验证上游集群
 validation_context:
 trusted_ca:
 filename: /tmp/http-ca.crt

配合下游使用

在 config.listener.v3.FilterChain 中的 transport_socket 配置：

支持这几种类型：

名称	类型
envoy.transport_sockets.alts	x
envoy.transport_sockets.raw_buffer	x
envoy.transport_sockets.starttls	x
envoy.transport_sockets.tap	x
envoy.transport_sockets.tcp_stats	x
envoy.transport_sockets.tls	extensions.transport_sockets.tls.v3.DownstreamTlsContext

static_resources:
 listeners:
 - name: listener_0

 ......

 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager

 ......

 transport_socket:
 name: envoy.transport_sockets.tls
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
 common_tls_context:
 tls_certificates:
 - certificate_chain:
 filename: "./tls/example.pem"
 private_key:
 filename: "./tls/example.key"
......

内置鉴权模式

基于角色访问控制

基于角色的访问控制过滤器 (RBAC Filter) 负责验证传入请求的授权状态。该过滤器在 Envoy 进程中执行，根据预先配置的策略列表对每个请求进行检查。

可以在以下两个地方配置过滤器：

Network filter，当鉴权不通过则直接关闭连接；
HTTP filter，当鉴权不通过则以 403 返回。

角色与策略配置示例如下：

action: ALLOW
policies:
 # 角色名称
 "role-admin":
 # 权限列表
 permissions:
 - any: true
 # 用户主体
 principals:
 - authenticated:
 principal_name:
 exact: "cluster.local/ns/default/sa/admin"
 "role-guest":
 permissions:
 - and_rules:
 rules:
 - url_path:
 path:
 prefix: "/guest"
 principals:
 - any: true

更多请参考角色访问控制配置参数。

Network filter 配置示例

拒绝来自 “192.168.0.1” 且访问 “80” 端口的客户端，其他来源均允许：

static_resources:
 listeners:
 - name: listener_0

 ......

 filter_chains:
 - filters:
 - name: envoy.filters.network.rbac
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.rbac.v3.RBAC
 stat_prefix: network_filter
 rules:
 action: DENY
 policies:
 "guest":
 permissions:
 - and_rules:
 rules:
 - destination_port: 80
 principals:
 - remote_ip:
 address_prefix: 192.168.0.1
 prefix_len: 32
 ......

如果开启了 prometheus 则会产生相关性能指标项。

HTTP filter 配置示例

static_resources:
 listeners:
 - name: listener_0

 ......

 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 stat_prefix: ingress_http

 http_filters:
 - name: envoy.filters.http.rbac
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.http.rbac.v3.RBAC
 rules:
 action: ALLOW
 policies:
 "admin":
 permissions:
 - any: true
 principals:
 - metadata:
 filter: envoy.filters.http.jwt_authn
 path:
 - key: my_payload
 - key: sub
 value:
 string_match:
 exact: "admin@example.com"
 "guest":
 permissions:
 - and_rules:
 rules:
 - url_path:
 path:
 prefix: "/guest"
 principals:
 - any: true
 ......

外部鉴权模式

基于 OPA 的访问控制

外部鉴权模式同内置鉴权模式一样，也支持 “Network filter” 与 “HTTP filter” 两种过滤器。它的流程是当请求发生至 Envoy 时，由 Envoy 把请求的元信息（HTTP 请求头、源 IP 与端口、目标 IP 与端口等）传递给下游 OPA 服务端，由它判断鉴权是否通过。

这里 OPA 服务端由 opa-envoy-plugin 实现

服务启动配置参数

./main run \
 --server \
 --addr=0.0.0.0:8181 \
 --log-level=debug \
 --diagnostic-addr=0.0.0.0:8282 \
 --ignore=.* \
 --config-file=config.yaml \
 authz/policy.rego

配置 “config.yaml” 内容

plugins:
 envoy_ext_authz_grpc:
 addr: :9191
 path: envoy/authz/allow
 dry-run: false
 enable-reflection: true
 grpc-max-recv-msg-size: 40194304
 grpc-max-send-msg-size: 2147483647
 skip-request-body-parse: false
 enable-performance-metrics: false

decision_logs:
 console: true

鉴权文件 “authz/policy.rego” 内容

package envoy.authz

import rego.v1

default allow := false

allow if {
 input.attributes.source.address.socketAddress.address == "192.168.0.1"
}

默认不允许，因为 “path: envoy/authz/allow” 指向的 “authz/policy.rego” 文件中 “allow” 变量默认值为 false，当且仅当源 IP 为 “192.168.0.1” 时可访问。这个相比内置鉴权模式，存在更高的灵活性，能实现更加细粒度的控制，通过声明式编写策略文件即可。

Network filter 配置示例

用于实现源IP、源端口、目标IP、目标端口的限制，在 envoy 上配置使用外部验证服务地址：

static_resources:
 listeners:
 - name: listener_0

 ......

 filter_chains:
 - filters:
 - name: envoy.filters.network.ext_authz
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.ext_authz.v3.ExtAuthz
 transport_api_version: V3
 stat_prefix: ext_authz
 grpc_service:
 envoy_grpc:
 cluster_name: opa-envoy
 include_peer_certificate: true
 ......

 clusters:
 - name: opa-envoy
 connect_timeout: 1.25s
 type: STATIC
 http2_protocol_options: {}
 load_assignment:
 cluster_name: opa-envoy
 endpoints:
 - lb_endpoints:
 - endpoint:
 address:
 socket_address:
 address: 192.168.0.1
 port_value: 9191
 ......

以 opa-envoy-plugin 作为服务端接收到 envoy 数据，并转换为 opa 使用的 input 变量

{
 "input": {
 "attributes": {
 "destination": {
 "address": {
 "socketAddress": {
 "address": "192.168.0.2",
 "portValue": 80
 }
 }
 },
 "source": {
 "address": {
 "socketAddress": {
 "address": "192.168.0.1",
 "portValue": 56695
 }
 }
 }
 },
 "parsed_body": null,
 "parsed_path": [
 ""
 ],
 "parsed_query": {},
 "truncated_body": false,
 "version": {
 "encoding": "protojson",
 "ext_authz": "v3"
 }
 }
}

HTTP filter 配置示例

除IP、端口外，还可以实现对 HTTP 协议细节进行限制，在 envoy 上配置使用外部验证服务地址

static_resources:
 listeners:
 - name: listener_0

 ......

 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 stat_prefix: ingress_http

 http_filters:
 - name: envoy.ext_authz
 typed_config:
 '@type': type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
 transport_api_version: V3
 failure_mode_allow: false
 grpc_service:
 envoy_grpc:
 cluster_name: opa-envoy
 with_request_body:
 allow_partial_message: true
 max_request_bytes: 1024
 pack_as_bytes: true

 - name: envoy.filters.http.router
 typed_config:
 "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

 ......

以 opa-envoy-plugin 作为服务端接收到 envoy 数据，并转换为 opa 使用的 input 变量

{
 "input": {
 "attributes": {
 "destination": {
 "address": {
 "socketAddress": {
 "address": "192.168.0.2",
 "portValue": 80
 }
 }
 },
 "metadataContext": {},
 "request": {
 "http": {
 "headers": {
 ":authority": "hello.example.com",
 ":method": "GET",
 ":path": "/vw0tha/hello/test.jpg?arg1=test1&arg2=test2",
 ":scheme": "http",
 "accept": "*/*",
 "user-agent": "curl/8.4.0",
 "x-forwarded-proto": "http",
 "x-request-id": "ca5f65a7-e8e1-420a-adf6-466f04c623dd"
 },
 "host": "hello.example.com",
 "id": "5149459733649565588",
 "method": "GET",
 "path": "/vw0tha/hello/test.jpg?arg1=test1&arg2=test2",
 "protocol": "HTTP/1.1",
 "scheme": "http"
 },
 "time": "2024-03-19T03:39:00.986466Z"
 },
 "source": {
 "address": {
 "socketAddress": {
 "address": "192.168.0.1",
 "portValue": 57372
 }
 }
 }
 },
 "parsed_body": null,
 "parsed_path": [
 "vw0tha",
 "hello",
 "test.jpg"
 ],
 "parsed_query": {
 "arg1": [
 "test1"
 ],
 "arg2": [
 "test2"
 ]
 },
 "truncated_body": false,
 "version": {
 "encoding": "protojson",
 "ext_authz": "v3"
 }
 }
}

角色访问控制配置参数

RBAC

数据结构见 envoy/config/rbac/v3/rbac.proto

action: ALLOW
policies:
 "policy-name-1":
 {Policy}
 "policy-name-2":
 {Policy}

属性	格式	说明
action	string	可取 [“ALLOW”, “DENY”, “LOG”] 分别表示 “白名单”、“黑名单”、“日志” 模式
policies	map<string, Policy>	键值对，通过定义多个角色，每个角色对应的主体以及包含相关权限

策略匹配的动作 (action) 说明：

当 action: ALLOW 时：当且仅当存在与请求匹配的策略时才允许该请求，也就是白名单；
当 action: DENY 时：当且仅当没有与请求匹配的策略时才允许该请求，也就是黑名单；
当 action: LOG 时：允许所有请求，当请求匹配策略时，更改 “access_log_hint” 为 “true”。

见基于角色访问控制示例。

Policy

数据结构见 envoy/config/rbac/v3/rbac.proto

属性	格式	说明
permissions	repeated Permission	权限
principals	repeated Principal	主体

策略（Policy）由权限 (Permission) 与主体 (Principal) 组成：

权限：指定请求的操作，既做什么，例如 HTTP 请求的方法和路径；
主体：指定请求的下游客户端身份，既这是谁，例如 jwt 中的 sub 属性。

Permissions

数据结构见 envoy/config/rbac/v3/rbac.proto

permissions:
- and_rules:
 rules:
 - {Permissions}:
- or_rules:
 rules:
 - {Permissions}:
- any:
- header:
- url_path:
- destination_ip:
- destination_port:
- destination_port_range:
- metadata:
- not_rule:
- requested_server_name:
- matcher:
- uri_template:

属性	格式	说明
and_rules	{ “rules”: [Permission,…] }	满足所有里面的规则
or_rules	{ “rules”: [Permission,…] }	满足其中任意一个规则
any	bool	任意条件
header	route.v3.HeaderMatcher	仅 HTTP 协议下有效，请求头匹配
url_path	type.matcher.v3.PathMatcher	仅 HTTP 协议下有效，请求 URL 匹配
destination_ip	core.v3.CidrRange	目标 IP 地址段
destination_port	uint32	目标端口
destination_port_range	type.v3.Int32Range	目标端口范围
metadata	type.matcher.v3.MetadataMatcher	自定义元数据，如 jwt 属性
not_rule	Permission	不能满足这些规则
requested_server_name	type.matcher.v3.StringMatcher	客户端 TLS SNI 匹配值
matcher	core.v3.TypedExtensionConfig	自定义匹配扩展
uri_template	core.v3.TypedExtensionConfig	url 模版路径匹配

包含以上可配置属性，但同一时间仅可配置其中一项，不可同时配置。

Principal

数据结构见 envoy/config/rbac/v3/rbac.proto

principals:
- and_ids:
 ids:
 - {Principal}
- or_ids:
 ids:
 - {Principal}
- any:
- authenticated:
- source_ip:
- direct_remote_ip:
- remote_ip:
- header:
- url_path:
- metadata:
- filter_state:
- not_id:

属性	格式	说明
and_ids	{ “ids”: [Principal,…] }	一组身份标识，必须全匹配
or_ids	{ “ids”: [Principal,…] }	一组身份标识，至少匹配其中一项
any	bool	开启则允许所有
authenticated	{ “principal_name”: type.matcher.v3.StringMatcher }	用于匹配 URI SAN 或 DNS SAN
source_ip	core.v3.CidrRange	废弃，使用 “remote_ip” 代替
direct_remote_ip	core.v3.CidrRange	TODO；物理对接 IP 地址
remote_ip	core.v3.CidrRange	TODO；客户端 IP 地址，一般来自 xff 或者 protocol proxy 区别于 direct_remote_ip
header	route.v3.HeaderMatcher	仅 HTTP 协议下有效，请求头匹配
url_path	type.matcher.v3.PathMatcher	仅 HTTP 协议下有效，请求 URL 匹配
metadata	type.matcher.v3.MetadataMatcher	元数据匹配
filter_state	type.matcher.v3.FilterStateMatcher	-
not_id	Principal	-

route.v3.HeaderMatcher

数据结构见 envoy/config/route/v3/route_components.proto

permissions:
- header:
 name: ":method"
 string_match:
 exact: "POST"

principals:
- header:
 name: "x-tr-user"
 string_match:
 exact: "sysadmin"

属性	格式	说明
name	string	HTTP/2 请求头名称，如 “:authority” 表示为 HTTP/1 下的 “Host”
exact_match	string	废弃，使用 “string_match” 代替
safe_regex_match	type.matcher.v3.RegexMatcher	废弃，使用 “string_match” 代替
range_match	type.v3.Int64Range	求头值必须表示十进制的整数形式，即可包含可选的正负号
present_match	bool	为 “true” 将根据请求中是否存在该头来执行匹配；“false” 将根据请求头是否缺失来匹配
prefix_match	string	废弃，使用 “string_match” 代替
suffix_match	string	废弃，使用 “string_match” 代替
contains_match	string	废弃，使用 “string_match” 代替
string_match	type.matcher.v3.StringMatcher	根据请求头部值的字符串匹配进行匹配

以上参数除 “name” 外，其他同一时间仅可配置其中一项，不可同时配置。

type.matcher.v3.PathMatcher

数据结构见 envoy/type/matcher/v3/path.proto

permissions:
- url_path:
 path:
 exact: "/guest"

属性	格式	说明
path	type.matcher.v3.StringMatcher	匹配请求 url 且不包含参数，如 “/data” 匹配 “/data#fragment?param=value”

core.v3.CidrRange

数据结构见 envoy/config/core/v3/address.proto

permissions:
- destination_ip:
 address_prefix: 192.168.0.2
 prefix_len: 32

属性	格式	说明
address_prefix	string	目标 IPv4 或 IPv6 地址
prefix_len	int	子网掩码

type.v3.Int32Range

数据结构见 envoy/type/v3/range.proto

permissions:
- destination_port_range:
 start: 8080
 end: 8088

属性	格式	说明
start	int32	端口开始，包含
end	int32	端口结束，不包含

type.matcher.v3.MetadataMatcher

数据结构见 envoy/type/matcher/v3/metadata.proto

permissions:
- metadata:
 filter: envoy.filters.http.jwt_authn
 path:
 - key: playload
 - key: sub
 value:
 string_match:
 exact: user1

属性	格式	说明
filter	string	用于从元数据中检索结构体的过滤器名称
path	repeated PathSegment	从结构体中检索值的路径
value	type.matcher.v3.ValueMatcher	-
invert	bool	-

PathSegment

属性	格式	说明
key	string	指向需获取结构体中值的键名

TODO;

type.matcher.v3.StringMatcher

数据结构见 envoy/type/matcher/v3/string.proto

permissions:
- requested_server_name:
 exact: "hello"

pristinals:
 - header:
 name: ":authority"
 string_match:
 safe_regex:
 regex: "([0-9a-z]{6}).mi.test.opsaid.net"

属性	格式	说明
exact	string	全匹配，如 “abc” 则必须匹配为 “abc”
prefix	string	前缀匹配，如 “abc” 可匹配为 “abc.xyz”
suffix	string	后缀匹配，如 “abc” 可匹配为 “xyz.abc”
safe_regex	type.matcher.v3.RegexMatcher	正则表达匹配
contains	string	包含匹配，如 “abc” 可匹配为 “xyz.abc.def”
custom	xds.core.v3.TypedExtensionConfig	自定义匹配

以上参数同一时间仅可配置其中一项，不可同时配置。

core.v3.TypedExtensionConfig

数据结构见 envoy/config/core/v3/extension.proto

permissions:
- matcher:
 name:
 typed_config:

属性	格式	说明
name	string	-
typed_config	google.protobuf.Any	-

type.matcher.v3.ValueMatcher

数据结构见 envoy/type/matcher/v3/value.proto

属性	格式	说明
null_match	string	""
double_match	-	-
string_match	type.matcher.v3.StringMatcher	-
bool_match	bool	-
present_match	bool	-
list_match	type.matcher.v3.ListMatcher	-
or_match	type.matcher.v3.OrMatcher	-

以上参数同一时间仅可配置其中一项，不可同时配置。

type.matcher.v3.FilterStateMatcher

数据结构见 envoy/type/matcher/v3/filter_state.proto

属性	格式	说明
string_match	type.matcher.v3.StringMatcher	-

type.matcher.v3.RegexMatcher

数据结构见 envoy/type/matcher/v3/regex.proto

属性	格式	说明
regex	string	正则表达式