Wasm 能力限制配置迁移指南从 PluginConfig 到 VmConfig【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本指南聚焦 Envoy 中 Proxy-Wasm 能力限制capability restriction配置的弃用迁移PluginConfig.capability_restriction_config字段已在 API 中标记为 deprecated并迁移至VmConfig.capability_restriction_config。文章将梳理该字段的语义变化、兼容性行为、底层实现逻辑以及如何正确编写迁移后的配置。一、背景什么是 Proxy-Wasm 能力限制Envoy 的 Wasm 扩展HTTP/Network 过滤器、Access Loggers、统计输出等允许用户加载由 Proxy-Wasm ABI 编写的插件模块见 api/envoy/extensions/wasm/v3/wasm.proto。这些模块运行在嵌入的 Wasm 虚拟机中会调用 Proxy-Wasm 定义的宿主函数host function以及部分 WASI 系统调用。能力限制Capability Restriction是 Envoy 为 Wasm 模块提供的安全沙箱能力它按名称允许allow-list模块可调用的 Proxy-Wasm 能力与 WASI 能力未在允许列表中的能力会被拒绝调用。其配置载体为CapabilityRestrictionConfig// Configuration for restricting Proxy-Wasm capabilities available to modules. message CapabilityRestrictionConfig { // 按名称映射的能力列表每个能力映射到一个 SanitizationConfig当前未实现保持为空。 mapstring, SanitizationConfig allowed_capabilities 1; }能力名称分为两类来源注释见 wasm.protoProxy-Wasm ABI 宿主能力名称由 Proxy-Wasm ABI 规范abi-versions/vNEXT给出WASI 能力当前已实现并允许配置的包括fd_write、fd_read、fd_seek、fd_close、fd_fdstat_get、environ_get、environ_sizes_get、args_get、args_sizes_get、proc_exit、clock_time_get、random_get。注意每个能力映射到的SanitizationConfig目前尚未实现应当留空仅使用 map 的 key 作为能力的开启开关源码中对应TODO(rapilado): Set the SanitizationConfig fields once sanitization is implemented注释见 plugin.cc。二、变更核心限制属于 VM 而非单个 Plugin变更记录changelogs/current/deprecated/wasm__plugin-level-capability-restriction.rst明确指出PluginConfig.capability_restriction_config字段已弃用迁移至新的VmConfig.capability_restriction_config字段理由是限制在 Wasm VM 创建时生效并被运行在该 VM 中的所有插件共享因此限制是 VM 的属性而非单个插件的属性。这一语义在 proto 定义中同样得到印证wasm.proto// Configuration for restricting Proxy-Wasm capabilities available to modules. // // The restrictions are applied when the VM is created and are shared by every plugin running in // that VM, so they are a property of the VM rather than of an individual plugin. CapabilityRestrictionConfig capability_restriction_config 8;也就是说在 Envoy 中多个插件可以共享同一个 VM通过vm_id与代码哈希共同决定 VM 归属见 wasm.proto。如果把限制挂在单个插件上会出现同一 VM 内不同插件配置不一致的歧义迁移到 VM 级别后限制的生效范围与 VM 的生命周期严格对齐语义清晰且无法绕过。三、兼容性行为旧字段如何继续工作变更记录明确承诺向后兼容旧字段继续可用当旧字段被设置、而 VM 级别字段未设置时旧字段的值会被用来填充 VM 级别字段。对应实现位于 source/extensions/common/wasm/plugin.cc 的normalizeConfig函数envoy::extensions::wasm::v3::PluginConfig normalizeConfig(const envoy::extensions::wasm::v3::PluginConfig config) { // The capability restrictions are applied when the Wasm VM is created and are shared by every // plugin running in it, so they belong to the VM configuration. The plugin level field is // deprecated in favor of the VM level one: move it there and clear it, so that the VM level field // is the only place the restrictions are ever read from. if (!config.has_capability_restriction_config()) { return config; } envoy::extensions::wasm::v3::PluginConfig normalized config; // The VM level restrictions win when both are set. if (!config.vm_config().has_capability_restriction_config()) { *normalized.mutable_vm_config()-mutable_capability_restriction_config() config.capability_restriction_config(); } normalized.clear_capability_restriction_config(); return normalized; }关键行为总结场景行为仅设置插件级字段迁移到 VM 级字段后生效随后清空插件级字段仅设置 VM 级字段直接使用 VM 级字段两者都设置VM 级字段优先注释明确 The VM level restrictions win when both are set两者都不设置不启用任何限制normalizeConfig的输出被WasmConfig构造函数接收能力列表随后被读入allowed_capabilities_内部映射plugin.ccWasmConfig::WasmConfig(const envoy::extensions::wasm::v3::PluginConfig config) : config_(normalizeConfig(config)) { for (auto capability : config_.vm_config().capability_restriction_config().allowed_capabilities()) { // TODO(rapilado): Set the SanitizationConfig fields once sanitization is implemented. allowed_capabilities_[capability.first] proxy_wasm::SanitizationConfig(); } ... }可以看到由于normalizeConfig已统一了字段来源后续所有读取点都只从vm_config读取插件级字段在配置归一化后即被清除避免了两处读取产生分歧。四、VM 复用与限制的一致性问题由于限制作用于 VM且同一 VM 可被多个插件共享Envoy 在**VM 查找键VM key**中纳入了能力限制配置确保不同限制配置的插件不会错误地复用同一个 VM。实现在 source/extensions/common/wasm/wasm.ccenvoy::extensions::wasm::v3::VmConfig vm_key_config; vm_key_config.set_runtime(vm_config.runtime()); *vm_key_config.mutable_environment_variables() vm_config.environment_variables(); *vm_key_config.mutable_capability_restriction_config() vm_config.capability_restriction_config(); // ... 与 vm_id 一起做哈希 absl::StrCat(vm_config.vm_id(), |, MessageUtil::hash(vm_key_config));从源码结构可以推断Envoy 使用vm_id与VmConfig相关字段runtime、environment variables、capability restriction config的哈希共同确定 VM 归属因此使用不同能力限制的插件会被分配到不同的 VM限制配置在运行时不会出现“串台”。这也再次印证了限制是 VM 属性的设计它参与 VM 的身份标识。五、迁移实战如何编写新配置5.1 迁移前弃用的写法http_filters: - name: envoy.filters.http.wasm typed_config: type: type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm config: name: my_plugin root_id: my_root vm_config: vm_id: my_vm runtime: envoy.wasm.runtime.v8 code: local: filename: /etc/envoy/my_plugin.wasm # 弃用限制写在 PluginConfig 层级 capability_restriction_config: allowed_capabilities: fd_write: {} random_get: {} proxy_log: {}5.2 迁移后推荐的写法http_filters: - name: envoy.filters.http.wasm typed_config: type: type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm config: name: my_plugin root_id: my_root vm_config: vm_id: my_vm runtime: envoy.wasm.runtime.v8 code: local: filename: /etc/envoy/my_plugin.wasm # 限制移动到 VmConfig 层级作为 VM 的属性 capability_restriction_config: allowed_capabilities: fd_write: {} random_get: {} proxy_log: {}5.3 过渡期策略如果你暂时无法一次性迁移所有配置保留插件级写法依然有效只要没有同时设置 VM 级字段插件级字段会自动“上移”填充 VM 级字段由normalizeConfig保证避免双重设置同时设置两个字段时以 VM 级为准插件级字段会被忽略并清除容易造成“配置了却不生效”的误解尽早统一到 VM 级插件级字段已在 API 中标记[deprecated true]并注明deprecated_at_minor_version 3.0见 wasm.proto意味着它将在 Envoy 3.0 及后续版本被移除。建议在配置生成与校验工具链中同步切换。六、注意事项多插件共享 VM 时的取舍限制是 VM 的属性共享同一 VM 的所有插件共同受同一份限制约束。若不同插件需要不同的能力集应当为它们配置不同的vm_id或不同的限制配置后者会因 VM key 不同而自然分离。允许列表语义allowed_capabilities是白名单——未列出的能力一律不可用限制过严可能导致插件运行时报错建议先在测试环境验证插件实际需要的能力集合。WASI 能力子集目前可配置的 WASI 能力仅为 wasm.proto 中列出的十余项其他 WASI 能力暂不可通过此机制放行。SanitizationConfig 未实现每个能力映射的值当前被忽略源码中统一填充空的SanitizationConfig不要依赖该值做任何输入清洗配置。适用前提以上 API 行为以当前仓库api/envoy/extensions/wasm/v3/wasm.proto与实现source/extensions/common/wasm/plugin.cc、wasm.cc为准能力限制的实际拦截行为由 Proxy-Wasm 宿主运行时配合生效可参考 source/extensions/common/wasm 目录下的 Wasm 公共实现进一步阅读。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考