常用类型 (proto)

config.core.v3.Locality

[config.core.v3.Locality proto]

标识 Envoy 运行的位置或上游主机运行的位置。

{
  "region": ...,
  "zone": ...,
  "sub_zone": ...
}
地区

(string) 此 区域 所属的地区。

区域

(string) 定义 Envoy 运行的本地服务区域。虽然是可选的,但如果使用发现服务路由并且发现服务公开 区域数据(在本消息中或通过 --service-zone),则应设置此区域。区域的含义取决于上下文,例如 AWS 上的 可用区 (AZ),GCP 上的 区域 等。

子区域

(string) 当用于上游主机的区域时,此字段将区域进一步拆分为更小的子区域块,以便可以独立地对它们进行负载平衡。

config.core.v3.BuildVersion

[config.core.v3.BuildVersion proto]

BuildVersion 将扩展的 SemVer 版本与自由格式的构建信息(例如“alpha”、“private-build”)组合为一组字符串。

{
  "version": {...},
  "metadata": {...}
}
版本

(type.v3.SemanticVersion) 扩展的 SemVer 版本。

元数据

(Struct) 自由格式的构建信息。Envoy 在 source/common/version/version.h 文件中定义了一些众所周知的键

config.core.v3.Extension

[config.core.v3.Extension proto]

Envoy 扩展的版本和标识。

{
  "name": ...,
  "category": ...,
  "version": {...},
  "disabled": ...,
  "type_urls": []
}
名称

(string) 这是 Envoy 配置中指定的 Envoy 过滤器的名称,例如 envoy.filters.http.router、com.acme.widget。

类别

(string) 扩展的类别。扩展类别名称使用反向 DNS 符号。例如,Envoy 的内置监听器过滤器为“envoy.filters.listener”,acme.com 供应商的 HTTP 过滤器为“com.acme.filters.http”。

版本

(config.core.v3.BuildVersion) 版本是扩展的属性,独立于其他扩展和 Envoy API 维护。当扩展未提供版本信息时,此字段未设置。

已禁用

(bool) 表示扩展存在,但已通过动态配置禁用。

类型 URL

(repeated string) 扩展配置 proto 的类型 URL。

config.core.v3.Node

[config.core.v3.Node proto]

标识特定的 Envoy 实例。节点标识符将呈现给管理服务器,管理服务器可以使用此标识符区分用于服务的每个 Envoy 配置。

{
  "id": ...,
  "cluster": ...,
  "metadata": {...},
  "dynamic_parameters": {...},
  "locality": {...},
  "user_agent_name": ...,
  "user_agent_version": ...,
  "user_agent_build_version": {...},
  "extensions": [],
  "client_features": [],
  "listening_addresses": []
}
ID

(string) Envoy 节点的唯一节点标识符。这也提供了本地服务节点名称。如果使用以下任何功能,则应设置此标识符:statsdCDSHTTP 跟踪(在本消息中或通过 --service-node)。

集群

(string) 定义 Envoy 运行的本地服务集群名称。虽然是可选的,但如果使用以下任何功能,则应设置此标识符:statsd健康检查集群验证运行时覆盖目录用户代理添加HTTP 全局速率限制CDSHTTP 跟踪(在本消息中或通过 --service-cluster)。

元数据

(Struct) 扩展节点标识符的不透明元数据。Envoy 将将其直接传递给管理服务器。

动态参数

(repeated map<string, .xds.core.v3.ContextParams>) 从 xDS 资源类型 URL 到动态上下文参数的映射。这些参数可能在运行时发生变化(与此消息中的其他字段不同)。例如,xDS 客户端可能有一个在 xDS 客户端的生命周期内发生变化的分片标识符。在 Envoy 中,这将通过更新 Server::Instance 的 LocalInfo 上下文提供程序上的动态上下文来实现。然后,分片 ID 动态参数在将来的发现请求期间出现在此字段中。

区域

(config.core.v3.Locality) 指定 Envoy 实例运行位置的区域。

用户代理名称

(string) 标识请求配置的实体的自由格式字符串。例如,“envoy”或“grpc”

用户代理版本

(string) 标识请求配置的实体的版本的自由格式字符串。例如,“1.12.2”或“abcd1234”,或“SpecialEnvoyBuild”

只能设置 user_agent_versionuser_agent_build_version 之一。

用户代理构建版本

(config.core.v3.BuildVersion) 请求配置的实体的结构化版本。

只能设置 user_agent_versionuser_agent_build_version 之一。

扩展

(repeated config.core.v3.Extension) 节点支持的扩展及其版本的列表。

客户端功能

(repeated string) 客户端功能支持列表。这些是在 Envoy API 存储库中为特定 API 主要版本描述的众所周知的特征。客户端功能使用反向 DNS 命名方案,例如 com.acme.feature。查看 xDS 客户端可能支持的功能列表

监听地址

(repeated config.core.v3.Address) 节点上的已知监听端口,作为管理服务器用于过滤要返回的 监听器 的通用提示。例如,如果有一个绑定到端口 80 的监听器,则列表可以选择包含 SocketAddress (0.0.0.0,80)。该字段是可选的,只是一个提示。

config.core.v3.Metadata

[config.core.v3.Metadata proto]

Metadata 为过滤器提供基于匹配的监听器、过滤器链、路由和端点的附加输入。它被组织为一个映射,通常是从过滤器名称(以反向 DNS 格式)到特定于过滤器的元数据。在连接和请求处理发生时,过滤器的元数据键值将合并,较后的键值将覆盖较早的键值。

元数据的示例用例是向 envoy.http_connection_manager.access_log 命名空间中的 http_connection_manager 提供附加值。

元数据另一个示例用法是在集群元数据中存储每个服务的配置信息,这些信息可能会被多个过滤器使用。

对于负载均衡,元数据提供了一种对集群端点进行子集的方法。端点与元数据对象相关联,路由包含元数据对象以进行匹配。目前,有一些定义良好的元数据用于此目的。

  • {"envoy.lb": {"canary": <bool> }} 这表示端点的金丝雀状态,也用于报头处理(x-envoy-upstream-canary)和统计目的。

{
  "filter_metadata": {...},
  "typed_filter_metadata": {...}
}
filter_metadata

(**repeated** map<string, Struct>) 键是反向 DNS 过滤器名称,例如 com.acme.widget。 envoy.* 命名空间保留给 Envoy 的内置过滤器。如果 filter_metadatatyped_filter_metadata 字段在元数据中都存在且键相同,则只解析 typed_filter_metadata 字段。

typed_filter_metadata

(**repeated** map<string, Any>) 键是反向 DNS 过滤器名称,例如 com.acme.widget。 envoy.* 命名空间保留给 Envoy 的内置过滤器。该值被编码为 google.protobuf.Any。如果 filter_metadatatyped_filter_metadata 字段在元数据中都存在且键相同,则只解析 typed_filter_metadata 字段。

config.core.v3.RuntimeUInt32

[config.core.v3.RuntimeUInt32 proto]

运行时派生的 uint32,在未指定时使用默认值。

{
  "default_value": ...,
  "runtime_key": ...
}
default_value

(uint32) 如果运行时值不可用,则为默认值。

runtime_key

(string, REQUIRED) 获取比较值的运行时键。如果定义了此值,则使用此值。

config.core.v3.RuntimePercent

[config.core.v3.RuntimePercent proto]

运行时派生的百分比,在未指定时使用默认值。

{
  "default_value": {...},
  "runtime_key": ...
}
default_value

(type.v3.Percent) 如果运行时值不可用,则为默认值。

runtime_key

(string, REQUIRED) 获取比较值的运行时键。如果定义了此值,则使用此值。

config.core.v3.RuntimeDouble

[config.core.v3.RuntimeDouble proto]

运行时派生的双精度浮点数,在未指定时使用默认值。

{
  "default_value": ...,
  "runtime_key": ...
}
default_value

(double) 如果运行时值不可用,则为默认值。

runtime_key

(string, REQUIRED) 获取比较值的运行时键。如果定义了此值,则使用此值。

config.core.v3.RuntimeFeatureFlag

[config.core.v3.RuntimeFeatureFlag proto]

运行时派生的布尔值,在未指定时使用默认值。

{
  "default_value": {...},
  "runtime_key": ...
}
default_value

(BoolValue, REQUIRED) 如果运行时值不可用,则为默认值。

runtime_key

(string, REQUIRED) 获取比较值的运行时键。如果定义了此值,则使用此值。布尔值必须通过其 规范 JSON 编码 表示。

config.core.v3.KeyValue

[config.core.v3.KeyValue proto]

{
  "key": ...,
  "value": ...
}
key

(string, REQUIRED) 键值对的键。

value

(bytes) 键值对的值。

config.core.v3.KeyValueAppend

[config.core.v3.KeyValueAppend proto]

键值对以及控制追加行为的选项。这用于指定应追加到一组现有键值对的键值对。

{
  "entry": {...},
  "action": ...
}
entry

(config.core.v3.KeyValue, REQUIRED) 该选项用于追加或覆盖的键值对条目。

action

(config.core.v3.KeyValueAppend.KeyValueAppendAction) 描述对现有键执行的追加/覆盖给定值的动作,或仅在键不存在时添加此键。

Enum config.core.v3.KeyValueAppend.KeyValueAppendAction

[config.core.v3.KeyValueAppend.KeyValueAppendAction proto]

描述键值对追加操作支持的操作类型。

APPEND_IF_EXISTS_OR_ADD

(DEFAULT) ⁣如果键已存在,此操作将导致以下行为

  • 如果多个值不允许,则为逗号分隔的值。

  • 如果多个值允许,则将新值添加到值列表中。

如果键不存在,则将使用指定的键和值添加对。

ADD_IF_ABSENT

⁣此操作将在键不存在时添加键值对。如果键已存在,则此操作将为无操作。

OVERWRITE_IF_EXISTS_OR_ADD

⁣此操作将覆盖指定的值,如果键已存在,则丢弃任何现有值。如果键不存在,则将使用指定的键和值添加对。

OVERWRITE_IF_EXISTS

⁣此操作将覆盖指定的值,如果键已存在,则丢弃任何现有值。如果键不存在,则此操作将为无操作。

config.core.v3.KeyValueMutation

[config.core.v3.KeyValueMutation proto]

要追加或删除的键值对。

{
  "append": {...},
  "remove": ...
}
append

(config.core.v3.KeyValueAppend) 要追加或覆盖的键值对。只能设置 appendremove 中的一个。

remove

(string) 要删除的键。只能设置 appendremove 中的一个。

config.core.v3.QueryParameter

[config.core.v3.QueryParameter proto]

查询参数名称/值对。

{
  "key": ...,
  "value": ...
}
key

(string, REQUIRED) 查询参数的键。区分大小写。

value

(string) 查询参数的值。

config.core.v3.HeaderValue

[config.core.v3.HeaderValue proto]

报头名称/值对。

{
  "key": ...,
  "value": ...,
  "raw_value": ...
}
key

(string, REQUIRED) 报头名称。

value

(string) 报头值。

格式说明符 相同,用于 HTTP 访问日志记录,但是未知报头值将用空字符串替换,而不是 -。报头值被编码为字符串。这对于非 UTF-8 字符无效。只能设置 valueraw_value 中的一个。

raw_value

(bytes) 报头值被编码为字节,可以支持非 UTF-8 字符。只能设置 valueraw_value 中的一个。

config.core.v3.HeaderValueOption

[config.core.v3.HeaderValueOption proto]

报头名称/值对以及控制追加行为的选项。

{
  "header": {...},
  "append": {...},
  "append_action": ...,
  "keep_empty_value": ...
}
header

(config.core.v3.HeaderValue, REQUIRED) 该选项适用的报头名称/值对。

append

(BoolValue) 是否应追加值?如果为 true(默认),则将值追加到现有值。否则,它将替换任何现有值。此字段已弃用,请使用 append_action 作为替代。

注意

外部授权服务外部处理器服务 为此字段提供默认值(false)。

append_action

(config.core.v3.HeaderValueOption.HeaderAppendAction) 描述对现有报头执行的追加/覆盖给定值的动作,或仅在报头不存在时添加此报头。值默认为 APPEND_IF_EXISTS_OR_ADD

keep_empty_value

(bool) 是否允许报头值为为空?如果为 false(默认),则会删除具有空值的自定义报头,否则会添加它们。

Enum config.core.v3.HeaderValueOption.HeaderAppendAction

[config.core.v3.HeaderValueOption.HeaderAppendAction proto]

描述报头追加操作支持的操作类型。

APPEND_IF_EXISTS_OR_ADD

(DEFAULT) ⁣如果报头已存在,此操作将导致

  • 对于预定义的内联报头,为逗号分隔。

  • 对于其他报头,在 HeaderMap 中添加重复的报头。

如果报头不存在,则将使用指定的键和值添加新的报头。

ADD_IF_ABSENT

⁣此操作将在报头不存在时添加报头。如果报头已存在,则此操作将为无操作。

OVERWRITE_IF_EXISTS_OR_ADD

⁣此操作将覆盖指定的值,如果报头已存在,则丢弃任何现有值。如果报头不存在,则将使用指定的键和值添加报头。

OVERWRITE_IF_EXISTS

⁣此操作将覆盖指定的值,如果报头已存在,则丢弃任何现有值。如果报头不存在,则此操作将为无操作。

config.core.v3.HeaderMap

[config.core.v3.HeaderMap proto]

一组报头的包装器。

{
  "headers": []
}
headers

(**repeated** config.core.v3.HeaderValue)

config.core.v3.WatchedDirectory

[config.core.v3.WatchedDirectory proto]

一个用于监控变更的目录,例如 Linux 上的 inotify。此目录内的移动/重命名事件会触发监控。

{
  "path": ...
}
路径

(字符串, 必需) 要监控的目录路径。

config.core.v3.DataSource

[config.core.v3.DataSource 协议]

包含文件、内联值或环境变量的数据源。

{
  "filename": ...,
  "inline_bytes": ...,
  "inline_string": ...,
  "environment_variable": ...,
  "watched_directory": {...}
}
文件名

(字符串) 本地文件系统数据源。

必须准确设置 文件名内联字节内联字符串环境变量 中的一个。

内联字节

(字节) 配置中内联的字节。

必须准确设置 文件名内联字节内联字符串环境变量 中的一个。

内联字符串

(字符串) 配置中内联的字符串。

必须准确设置 文件名内联字节内联字符串环境变量 中的一个。

环境变量

(字符串) 环境变量数据源。

必须准确设置 文件名内联字节内联字符串环境变量 中的一个。

监控目录

(config.core.v3.WatchedDirectory) 监控用于文件更改的目录。如果明确设置了此选项,则在发生相关文件移动事件时,将重新加载 文件名 字段中指定的文件。

注意

此字段只有在设置了 文件名 字段时才有意义。

注意

Envoy 仅在文件被文件移动替换时更新,而不是在文件原地编辑时更新。

注意

并非所有 DataSource 的用例都支持监控目录。这取决于 DataSource 的具体用法。有关详细信息,请参阅父消息的文档。

config.core.v3.RetryPolicy

[config.core.v3.RetryPolicy 协议]

该消息指定在获取失败时远程数据源的重试策略。

{
  "retry_back_off": {...},
  "num_retries": {...},
  "retry_on": ...,
  "retry_priority": {...},
  "retry_host_predicate": [],
  "host_selection_retry_max_attempts": ...
}
重试回退

(config.core.v3.BackoffStrategy) 指定控制 重试回退策略 的参数。此参数是可选的,在这种情况下,默认基本间隔为 1000 毫秒。默认最大间隔是基本间隔的 10 倍。

重试次数

(UInt32Value) 指定允许的重试次数。此参数是可选的,默认为 1。

重试原因

(字符串) 有关详细信息,请参阅 重试原因

重试优先级

(config.core.v3.RetryPolicy.RetryPriority) 有关详细信息,请参阅 重试优先级

重试主机谓词

(重复 config.core.v3.RetryPolicy.RetryHostPredicate) 有关详细信息,请参阅 RetryHostPredicate

主机选择重试最大尝试次数

(int64) 有关详细信息,请参阅 主机选择重试最大尝试次数

config.core.v3.RetryPolicy.RetryPriority

[config.core.v3.RetryPolicy.RetryPriority 协议]

参阅 RetryPriority

{
  "name": ...,
  "typed_config": {...}
}
名称

(字符串, 必需)

类型化配置

(任何)

config.core.v3.RetryPolicy.RetryHostPredicate

[config.core.v3.RetryPolicy.RetryHostPredicate 协议]

参阅 RetryHostPredicate

{
  "name": ...,
  "typed_config": {...}
}
名称

(字符串, 必需)

类型化配置

(任何)

config.core.v3.RemoteDataSource

[config.core.v3.RemoteDataSource 协议]

该消息指定如何从远程获取数据以及如何验证数据。

{
  "http_uri": {...},
  "sha256": ...,
  "retry_policy": {...}
}
http_uri

(config.core.v3.HttpUri, 必需) 获取远程数据的 HTTP URI。

sha256

(字符串, 必需) 用于验证数据的 SHA256 字符串。

重试策略

(config.core.v3.RetryPolicy) 用于获取远程数据的重试策略。

config.core.v3.AsyncDataSource

[config.core.v3.AsyncDataSource 协议]

支持异步数据获取的异步数据源。

{
  "local": {...},
  "remote": {...}
}
本地

(config.core.v3.DataSource) 本地异步数据源。

必须准确设置 本地远程 中的一个。

远程

(config.core.v3.RemoteDataSource) 远程异步数据源。

必须准确设置 本地远程 中的一个。

config.core.v3.TransportSocket

[config.core.v3.TransportSocket 协议]

监听器集群 中的传输套接字配置。如果配置为空,将根据平台和 tls_context 的存在选择默认传输套接字实现和配置。

{
  "name": ...,
  "typed_config": {...}
}
名称

(字符串, 必需) 要实例化的传输套接字的名称。名称必须与支持的传输套接字实现匹配。

类型化配置

(任何) 取决于要实例化的实现的实现特定配置。有关更多文档,请参阅支持的传输套接字实现。

config.core.v3.RuntimeFractionalPercent

[config.core.v3.RuntimeFractionalPercent 协议]

运行时派生的 FractionalPercent,包含当分子或分母未通过运行时键指定时的默认值。

注意

运行时键数据的解析方式是,可以将其表示为 FractionalPercent 协议,该协议表示为 JSON/YAML,也可以表示为整数,假设该值是 100 中的整数百分比。例如,运行时键查找返回的值为“42”将解析为一个 FractionalPercent,其分子为 42,分母为 HUNDRED。

{
  "default_value": {...},
  "runtime_key": ...
}
default_value

(type.v3.FractionalPercent, 必需) 如果运行时值(用于分子/分母键)不可用,则使用默认值。

runtime_key

(字符串) 用于 FractionalPercent 的 YAML 表示的运行时键。

config.core.v3.ControlPlane

[config.core.v3.ControlPlane 协议]

标识 Envoy 连接到的特定 ControlPlane 实例。

{
  "identifier": ...
}
标识符

(字符串) 不透明的控制平面标识符,用于唯一标识控制平面实例。这可以用于识别 Envoy 连接到的哪个控制平面实例。

枚举 config.core.v3.RoutingPriority

[config.core.v3.RoutingPriority 协议]

Envoy 在路由和虚拟集群级别都支持 上游优先级路由。当前的优先级实现对每个优先级级别使用不同的连接池和断路器设置。这意味着即使对于 HTTP/2 请求,也会使用两个物理连接到上游主机。在将来,Envoy 可能支持通过单个上游连接实现真正的 HTTP/2 优先级。

默认

(默认)

枚举 config.core.v3.RequestMethod

[config.core.v3.RequestMethod 协议]

HTTP 请求方法。

METHOD_UNSPECIFIED

(默认)

GET

HEAD

POST

PUT

DELETE

CONNECT

OPTIONS

TRACE

PATCH

枚举 config.core.v3.TrafficDirection

[config.core.v3.TrafficDirection 协议]

标识相对于本地 Envoy 的流量方向。

未指定

(默认) ⁣默认选项为未指定。

入站

⁣传输用于传入流量。

出站

⁣传输用于传出流量。