Envoy 扩展治理全指南EXTENSION_POLICY 质量门槛、引入流程、移除机制与安全分级实践【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoyEnvoy 以高度可扩展的架构著称其能力几乎全部以扩展extension的形式组织。本篇指南以仓库根目录 EXTENSION_POLICY.md 为骨架完整讲解 Envoy 主仓库对扩展的全生命周期治理从质量要求、新增/移除流程、PR 审查规则到status/security_posture元数据分级体系并结合 source/extensions/extensions_metadata.yaml、contrib/extensions_metadata.yaml、tools/extensions/extensions_schema.yaml 等仓库证据做源码级验证。读完本文你将能判断一个扩展是否符合 Envoy 的质量与安全门槛、理解如何为扩展提交准入申请并学会阅读扩展元数据以评估其生产可用性与安全加固程度。一、质量门槛主仓库内的扩展与核心代码同一标准EXTENSION_POLICY 开宗明义所有进入 Envoy 主仓库的扩展必须与核心 Envoy 代码接受相同的质量标准。这一标准覆盖编码风格Coding style代码审查Code reviews测试覆盖率Test coverage也就是说不存在扩展代码可以放松要求的特例——即使扩展只服务于少数用户也必须按核心代码的规格来打磨。文档同时提到未来可能考虑为默认不编译、不测试、质量要求更低的扩展设立独立 sandbox 仓库但这一计划在当前政策中明确标记为超出当前范围out of scope。从仓库结构看扩展代码与核心代码共处一室source/extensions/ 按功能类别组织access_loggers、clusters、filters、transport_sockets、stat_sinks、tracers 等数十个目录与 source/common/、source/server/ 等核心目录平行存在这正是同一质量杆在工程布局上的体现——扩展会被与核心代码一同编译、一同测试、一同接受贡献者 PR 流的持续维护。二、新增扩展六步准入流程任何向 Envoy 主仓库提议新扩展的贡献者都需要走以下程序原文六条逐一展开1. 先开 GitHub Issue 描述提案与任何重大功能提案一样扩展提案应首先通过 GitHub Issue 描述扩展的用途、目标场景与设计思路让社区先行讨论。2. 必须有现有维护者赞助Sponsorship所有扩展都必须由一位现有 maintainer 赞助。赞助的含义是该维护者负责引导扩展通过设计/代码审查。维护者也可以自我赞助条件是他们将编写、引导并长期维护该扩展。赞助有两重目的确保扩展最终达到 Envoy 质量门槛保证激励对齐——扩展不会被没有对未来维护做充分思考地加入仓库。如果找不到维护者赞助组织可以考虑按 GOVERNANCE.md 中成为维护者的流程做相关准备工作从而获得自我赞助的资格。这是将责任与权利绑定的典型治理设计谁引入谁维护。3. 每个扩展必须提名两名 PR 审查者两名审查者中不得有高级维护者senior maintainer现有维护者包括赞助者本人和其他贡献者都可以计入这两席初始审查者会被固化到 CODEOWNERS 文件中用于长期维护后续可根据需要更换。也就是说赞助维护者负责把方向两名普通审查者负责把质量且审查责任通过 CODEOWNERS 长期绑定到具体的人。4. 扩展成为仓库的完整组成部分一旦按此流程加入扩展就完全成为仓库的一部分核心代码的任何 API 破坏性变更都会由其他贡献者在常规 PR 流程中自动修复。这是加入主仓库的红利——扩展不必自己负担核心 API 迁移成本。5. 新增依赖必须遵守依赖政策扩展引入的任何新依赖都必须符合 DEPENDENCY_POLICY.md并按其列出的步骤操作许可证审查、版本锁定等。这一点在仓库的 bazel/deps.yaml 与 bazel/repositories.bzl 中都有对应落地所有外部依赖都需登记。6. 平台相关功能必须在构建系统中加防护如果扩展依赖平台特定功能按 PULL_REQUESTS.md 的说明在构建系统中加 guard将扩展加入必要的*_SKIP_TARGETS即 bazel/extension_configs.bzl 中的PPC_SKIP_TARGETS、WINDOWS_SKIP_TARGETS、NO_HTTP3_SKIP_TARGETS等列表并将测试标记为在不支持的平台上跳过或失败。以 bazel/extension_configs.bzl 为证WINDOWS_SKIP_TARGETS中列出了envoy.filters.http.sxg、envoy.filters.http.wasm、envoy.tracers.datadog、envoy.filters.http.rbac等大量 Windows 不支持的扩展PPC_SKIP_TARGETS则排除了envoy.string_matcher.lua、envoy.filters.http.lua等 Lua 相关扩展——这正是平台防护政策在构建层的直接体现。从源码结构看这些宏通常在扩展的 BUILD 目标中通过条件如select()或if not windows引用确保在不支持的平台上既不编译也不运行测试。三、移除现有扩展投票驱动的六步退役流程如前所述扩展一旦进入仓库就由全体 Envoy 贡献者集体维护。但如果扩展存在已知问题且原始赞助者、审查者或愿意接任的新贡献者都无人修复则可发起维护者投票流程见 GOVERNANCE.md决定将其移除。扩展移除的正式流程开 GitHub Issue列出移除原因及任何可用的替代方案修改扩展工厂factory使其在实例化时输出弃用警告deprecation warning启动 6 个月弃用窗口窗口结束后扩展停用向 envoy-announce 邮件列表发布公告附上可到 Issue 留言申请延长弃用期的说明。重度使用的扩展可将弃用期再延长 6 个月弃用期届满后删除扩展源码。这套流程的关键在于弃用警告先行、公告窗口缓冲、重度使用可延期既给了存量用户迁移时间又避免了无限期维护僵尸扩展。四、扩展 PR 审查边界与审批规则对扩展相关 PR 有两条明确约束扩展 PR 不得修改核心 Envoy 代码。如果扩展确实需要核心代码变更这些变更应作为独立 PR 提交走常规代码审查流程见 CONTRIBUTING.md。这样核心代码的审查轨迹保持干净扩展改动也不会夹带进核心变更。审批权限扩展 PR 必须至少获得一位赞助维护者和一位扩展审查者的批准。两者可以是同一个人但文档明确可行时总是倾向多位审查者。特殊情形如果 PR 作者本人就是赞助维护者且当时没有其他赞助维护者可用可以请另一位维护者做一次最小化审查侧重风格与常见 C 反模式但该 PR 仍必须由一名非维护者审查者批准。这一条防止了维护者既写又审、无人把关的自我背书。五、Wasm 扩展明确禁止进入主仓库Wasm 扩展不允许进入主 envoyproxy/envoy 仓库除非属于 Wasm 实现本身的验证用途。政策给出三点理由ABI 独立性Wasm 扩展运行在版本无关的 ABI 之后不应依赖 Envoy 实现细节因此在主仓库做合格性验证价值不大依赖膨胀Wasm 扩展会通过 crates 等引入大量依赖Envoy 希望主仓库依赖保持精简、易推理、易维护实现取向Envoy 不打算用 Wasm 实现任何核心扩展中期内也无此计划。从仓库看Wasm 相关扩展envoy.filters.http.wasm、envoy.bootstrap.wasm、envoy.stat_sinks.wasm等在 bazel/extension_configs.bzl 的WINDOWS_SKIP_TARGETS中出现且其元数据如 source/extensions/extensions_metadata.yaml 中的envoy.bootstrap.wasm、envoy.access_loggers.wasm状态多为alpha——这与其验证为主、不进入主流程的定位一致。六、扩展稳定性与安全态势分级status 与 security_posture这是 EXTENSION_POLICY 中信息密度最高的部分每个扩展都必须在扩展元数据文件中打上status和security_posture标签核心扩展source/extensions/extensions_metadata.yaml共 2527 行登记数百个扩展Contrib 扩展contrib/extensions_metadata.yaml这两个文件的 schema 定义在 tools/extensions/extensions_schema.yaml6.1 status实现成熟度三档取值含义stable扩展稳定预期可用于生产环境alpha功能可用但尚无大量生产环境运行时间burn time仅在此前提下使用wip进行中work-in-progress功能不完整不用于生产值得注意的是status_upstream字段同时可用于 downstream 与 upstream 场景的扩展例如同时出现在envoy.filters.http与envoy.filters.http.upstream类别下的 HTTP filter可以为 upstream 用法声明不同于 downstream 的成熟度。在 source/extensions/extensions_metadata.yaml 中可以看到真实案例envoy.filters.http.admission_control标记为status: stable同时status_upstream: alpha第 308-314 行envoy.filters.http.ai_protocol_manager则两处均为alpha——即下游已稳定、上游仍属早期的精细表达。扩展状态可由扩展的 CODEOWNERS 和/或 Envoy 维护者依据上述标准调整。文档特别澄清了一个易混淆点状态反映的是实现成熟度与 API 稳定性正交——例如 API 被标记为(xds.annotations.v3.file_status).work_in_progress的扩展其实现可能已是stable反之config proto 稳定的扩展其实现也可能是wip。6.2 security_posture安全加固姿态五档取值含义robust_to_untrusted_downstream已针对不受信任的下游流量加固假定上游可信robust_to_untrusted_downstream_and_upstream对下游与上游的不可信流量均已加固requires_trusted_downstream_and_upstream未加固仅应在下游、上游均可信的部署中使用unknown功能上等同于requires_trusted_downstream_and_upstream但作为占位符用于识别尚未分类的扩展data_plane_agnostic与数据平面威胁无关如统计 sink这些定义与 tools/extensions/extensions_schema.yaml 中security_postures列表逐一对应含unknown、data_plane_agnostic的详细描述schema 顶部还注释说明了这些是详尽标签用于让运维者清楚对扩展可寄予何种信任。6.3 如何评估扩展是否robust八项安全审查指南文档列出了评估扩展能否获得 robust 安全姿态的指导性问题原文八条逐条列出是否有 fuzz 覆盖如果只是蹭通用 listener/network/HTTP filter fuzzer 的顺风车代码中受益的部分是否有专用 fuzzer是否有无界内部缓冲是否按需通过 watermarking 参与流控是否至少有某个部署承载实时不可信流量 N 个月所依赖的第三方库是否满足扩展成熟度模型Envoy 安全团队是否易于审计该扩展是否没有明显可怕的东西——例如memcpy、艰深的解析代码等是否有活跃的 CODEOWNERS 愿意为扩展的健壮性背书是否不在 test/coverage.yaml 的低覆盖率豁免名单里这几条共同构成一个生产级安全声明的取证清单fuzz 覆盖、流控参与、真实流量运行时长、依赖成熟度、可审计性、代码卫生、责任人和覆盖率——任何一条不过关扩展都难以宣称 robust。6.4 元数据文件的真实格式以 source/extensions/extensions_metadata.yaml 前几行为例一个扩展条目的标准结构是envoy.access_loggers.file: categories: - envoy.access_loggers security_posture: robust_to_untrusted_downstream status: stable type_urls: - envoy.extensions.access_loggers.file.v3.FileAccessLog其中type_urls列出该扩展对应的 protobuf 消息类型。contrib 侧 contrib/extensions_metadata.yaml 格式相同例如envoy.filters.http.dynamo标记为status: stable、security_posture: requires_trusted_downstream_and_upstream而envoy.filters.http.golang、envoy.filters.http.sxg等则为alpha——直观反映了各扩展的成熟度差异。七、新增扩展点Extension Points当 Envoy 缺少某个扩展所需的挂载点时需要先在核心代码中安装扩展点流程如下开 GitHub Issue描述提议的扩展点及用例在核心 Envoy 中完成扩展点代码变更更新 docs/root/extending/extending.rst列出新扩展点并补充说明文档——至少应链接到对应的 proto 定义。从 docs/root/extending/extending.rst 可以看到 Envoy 现有哪些扩展点类型access loggers、access log filters、clusters、listener filters、network filters、HTTP filters、gRPC credential providers、health checkers、resource monitors、retry implementations、stat sinks、tracers、request ID、transport sockets、BoringSSL private key methods、watchdog actions、internal redirect policies、compression libraries、bootstrap extensions、fatal actions、formatters、connection balance extensions 等。扩展点越丰富第三方扩展就越不需要侵入核心代码。八、Contrib 扩展低门槛的替代路径除核心扩展外Envoy 提供一条门槛更低的替代路径contrib/目录见 contrib/ 下按功能组织的众多子目录。Contrib 扩展的特点与权衡门槛低于核心扩展代价是默认不包含在主镜像构建中使用者需要按安装指南从 contrib 镜像直接拉取必须有一位最终用户end-user赞助赞助人是以足够规模运行该扩展、使构建维护等开销值得的人。何为足够规模由维护者判断且随时可变。最终用户赞助者不必编写扩展但需要在讨论新扩展的 GitHub Issue 中**公开记录on the record对其计划用途的声明**。此处最终用户的定义与 SECURITY.md 安全政策成员标准第 1.3.5 点一致不享受 Envoy 安全团队覆盖按链接文档约定contrib 扩展一般应使用v3alphaAPI以避免 API shepherd 审查要求。对比可见核心扩展要求维护者赞助 两名审查者 全套质量门槛contrib 扩展则要求最终用户赞助 较低准入门槛但失去默认构建与安全团队背书。选择哪条路径取决于扩展的成熟度与使用者规模。九、实践清单贡献者与运维者速查综合全文给两类读者一份速查如果你是扩展贡献者先开 Issue 论证再找维护者赞助可查阅 GOVERNANCE.md 了解维护者机制提名两名非高级维护者审查人并确保写入 CODEOWNERS遵守 DEPENDENCY_POLICY.md平台相关功能记得进 bazel/extension_configs.bzl 的*_SKIP_TARGETS在 source/extensions/extensions_metadata.yaml 或 contrib/extensions_metadata.yaml 中如实登记status与security_postureschema 见 tools/extensions/extensions_schema.yaml若缺少挂载点按 docs/root/extending/extending.rst 流程先补扩展点若不想承担核心扩展的高门槛可评估走 contrib 路径需最终用户赞助、用v3alpha、无安全团队背书。如果你是部署运维者使用扩展前先查它的statusstable/alpha/wip与security_posture据此决定生产可用性与数据平面信任边界警惕wip与requires_trusted_downstream_and_upstream/unknown组合的扩展暴露在不可信流量前上游场景如envoy.filters.http.upstream类别注意status_upstream可能低于status对标记为 robust 的扩展可按 6.3 节的八项指南反向验证其声明是否站得住脚。EXTENSION_POLICY 的本质是用一套可操作、可投票、可审计的治理规则在开放扩展生态与核心质量红线之间取得平衡——理解这套规则是安全、高效地使用和贡献 Envoy 扩展的前提。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考