运行时

该 运行时配置 指定一个包含可重新加载配置元素的虚拟文件系统树。此虚拟文件系统可以通过一系列本地文件系统、静态引导配置、RTDS 和管理控制台派生的覆盖来实现。

• v3 API 参考

虚拟文件系统

分层

运行时可以被视为一个由多个层组成的虚拟文件系统。该 分层运行时 引导配置指定此分层。后面层的运行时设置会覆盖前面层的设置。典型的配置可能是

layers:
- name: static_layer_0
  static_layer:
    health_check:
      min_interval: 5
- name: disk_layer_0
  disk_layer: { symlink_root: /srv/runtime/current, subdirectory: envoy }
- name: disk_layer_1
  disk_layer: { symlink_root: /srv/runtime/current, subdirectory: envoy_override, append_service_cluster: true }
- name: admin_layer_0
  admin_layer: {}

在已弃用的 runtime 引导配置中，分层是隐式且固定的

1. 静态引导配置

2. 本地磁盘文件系统

3. 本地磁盘文件系统 *override_subdirectory*

4. 管理控制台覆盖

其中较高层的数值会覆盖较低层的对应数值。

文件系统布局

配置指南的各个部分描述了可用的运行时设置。例如，这里 是上游集群的运行时设置。

运行时键中的每个“.”都表示层次结构中的一个新目录。路径的终端部分是文件。文件的内容构成运行时值。从文件读取数值时，空格和换行符将被忽略。

numerator 或 denominator 是保留关键字，不能出现在任何目录中。

静态引导

静态基本运行时可以通过 引导配置 使用 protobuf JSON 表示 指定。

本地磁盘文件系统

当 运行时虚拟文件系统 在本地磁盘上实现时，它以 symlink_root + subdirectory 为根。例如，health_check.min_interval 键将具有以下完整文件系统路径（使用符号链接）

/srv/runtime/current/envoy/health_check/min_interval

覆盖

可以在 分层运行时 引导配置中叠加任意数量的磁盘文件系统层。

在已弃用的 runtime 引导配置中，存在一个专门的文件系统覆盖。假设文件夹 /srv/runtime/v1 指向全局运行时配置存储的实际文件系统路径。以下是运行时配置设置的典型示例

• symlink_root: /srv/runtime/current

• subdirectory: envoy

• override_subdirectory: envoy_override

其中 /srv/runtime/current 是指向 /srv/runtime/v1 的符号链接。

特定于集群的子目录

在已弃用的 runtime 引导配置中，override_subdirectory 与 --service-cluster CLI 选项一起使用。假设 --service-cluster 已设置为 my-cluster。Envoy 首先将在以下完整文件系统路径中查找 health_check.min_interval 键

/srv/runtime/current/envoy_override/my-cluster/health_check/min_interval

如果找到，该值将覆盖在主查找路径中找到的任何值。这允许用户在全局默认值之上为单个集群自定义运行时值。

使用 分层运行时 引导配置，可以通过 append_service_cluster 选项在任何磁盘层上专门针对服务集群。

通过符号链接交换更新运行时值

更新任何运行时值有两个步骤。首先，创建整个运行时树的硬拷贝并更新所需的运行时值。其次，原子地将符号链接根从旧树交换到新运行时树，使用与以下命令等效的命令

/srv/runtime:~$ ln -s /srv/runtime/v2 new && mv -Tf new current

文件系统数据的部署、垃圾收集等超出了本文档的范围。

运行时发现服务 (RTDS)

可以通过指定一个 rtds_layer 来指定和传递一个或多个运行时层。这会将运行时层指向一个常规的 xDS 端点，订阅给定层的单个 xDS 资源。这些层的资源类型是 运行时消息。

管理控制台

值可以在 /runtime 管理端点 查看。值可以在 /runtime_modify 管理端点 修改和添加。如果未配置运行时，将使用一个空的提供程序，其效果是使用内置于代码中的所有默认值，除了通过 /runtime_modify 添加的任何值。

注意

谨慎使用 /runtime_modify 端点。更改将立即生效。至关重要的是，管理界面 已正确保护。

最多可以指定一个管理层。如果指定了非空的 分层运行时 引导配置但缺少管理层，任何更改管理控制台的操作都将引发 503 响应。

原子性

运行时将在各种情况下重新加载并生成新的快照，即

• 在符号链接根目录下检测到文件移动操作或符号链接根目录发生更改时。

• 在添加或修改管理控制台覆盖时。

所有运行时层都在快照期间进行评估。包含错误的层将被忽略并从有效层中排除，请参阅 num_layers。遍历符号链接根目录将花费非零时间，因此如果需要真正的原子性，运行时目录应保持不变，并且应使用符号链接更改来协调更新。

具有相同符号链接根目录的磁盘层在检测到文件移动操作时只会触发一次刷新。具有不完全相同但重叠符号链接根路径的磁盘层在检测到文件移动操作时可能会触发多次重新加载。

Protobuf 和 JSON 表示

运行时 文件系统 可以通过 proto3 消息内的一个 google.protobuf.Struct 表示，该结构对 JSON 对象进行建模，遵循以下规则

• 点分隔符映射到树边。

• 标量叶子（整数、字符串、布尔值、双精度浮点数）用它们各自的 JSON 类型表示。

• FractionalPercent 通过其 规范的 JSON 编码 表示。

health_check.min_interval 键的设置在 YAML 中的示例表示形式为

health_check:
  min_interval: 5

注意

从双精度浮点数解析的整数值将向下舍入到最接近的整数。

注释

以 # 作为第一个字符开头的行将被视为注释。

注释可用于提供有关现有值的上下文。注释在其他情况下也有用，在一个原本为空的文件中保留占位符以备不时之需。

使用运行时覆盖已弃用的功能

Envoy 运行时也是 Envoy 功能弃用流程的一部分。

如 Envoy 重大变更策略 中所述，Envoy 中的功能弃用分为三个阶段：默认警告、默认失败和代码删除。

在第一阶段，Envoy 会向警告日志记录一条警告，指出该功能已弃用，并增加 deprecated_feature_use 运行时统计信息。建议用户访问 deprecated 查看如何迁移到新的代码路径，并确保它适合他们的用例。

在第二阶段，该字段将被标记为 disallowed_by_default，并且使用该配置字段会导致配置默认情况下被拒绝。这种禁止模式可以通过运行时配置来覆盖，方法是将 envoy.deprecated_features:full_fieldname 或 envoy.deprecated_features:full_enum_value 设置为 true。例如，对于弃用字段 Foo.Bar.Eep，将 envoy.deprecated_features:Foo.bar.Eep 设置为 true。这里有一个使用静态运行时的生产示例，它允许使用失败-默认字段：configs/using_deprecated_config.yaml。禁止模式也可以通过运行时配置来覆盖，方法是将 envoy.features.enable_all_deprecated_feature 设置为 true，这允许使用所有弃用字段。强烈建议不要使用这些覆盖，因此请谨慎使用，并尽快切换到新的字段。致命-默认配置表示旧代码路径即将删除。对于 Envoy 用户和 Envoy 贡献者来说，最好是在删除代码之前找出新代码路径中的任何错误或功能差距，而不是在删除代码之后！

通过启用运行时键 envoy.features.fail_on_any_deprecated_feature，Envoy 用户可以在典型的警告-默认阶段触发配置加载失败。这是一种在 Envoy 的弃用时间表之前验证正在使用哪些字段的有效方法。

注意

1.14.1 之前的 Envoy 版本无法从整数值解析运行时布尔值，并且需要显式的“true”或“false”。错误地放置整数值（例如“0”来表示“false”）会导致使用默认值。这一点尤其重要，要记住对于 弃用功能 的运行时覆盖的情况，因为它可能导致意外的 Envoy 行为。

统计信息

文件系统运行时提供程序在 runtime. 命名空间中发出一些统计信息。

名称	类型	描述
admin_overrides_active	Gauge	如果有任何管理覆盖处于活动状态，则为 1，否则为 0
deprecated_feature_use	计数器	已弃用功能使用的总次数。有关已使用功能的详细信息将以“从文件 Y 使用已弃用选项‘X’”的形式记录到警告日志中。
deprecated_feature_seen_since_process_start	Gauge	已弃用功能使用的次数。这不会在热重启期间传递。
load_error	计数器	导致任何层级出现错误的加载尝试的总数
load_success	计数器	在所有层级都成功的加载尝试的总数
num_keys	Gauge	当前加载的键的数量
num_layers	Gauge	当前活动的层级数量（没有加载错误）
override_dir_exists	计数器	使用覆盖目录进行加载的总次数
override_dir_not_exists	计数器	未使用覆盖目录进行加载的总次数