When OPA’s Bundle Loader Runs Past a .manifest Typo

当 OPA 的 Bundle 加载器忽略 .manifest 中的拼写错误时

In bundle mode, a one-character .manifest key typo (rego_verison for rego_version) draws no diagnostic that names the key; the failure can surface as rego_parse_error pointing at your .rego — OPA v1.20.1 When It Runs — Run Report #RR03 · Testing what infrastructure actually does. 在 Bundle 模式下，.manifest 文件中一个字符的键名拼写错误（如将 rego_version 误写为 rego_verison）不会触发任何指明该键名的诊断信息；故障可能会表现为指向 .rego 文件的 rego_parse_error —— OPA v1.20.1 “When It Runs” —— 运行报告 #RR03 · 测试基础设施的实际行为。

Provider · Component: OPA (Open Policy Agent) · bundle .manifest loading — unknown top-level keys and rego_version Versions tested: OPA v1.20.1 (official opa_linux_amd64_static release, Build 2026-08-28; measured on our lab VM — see §2). 提供商 · 组件：OPA (Open Policy Agent) · Bundle .manifest 加载 —— 未知的顶层键与 rego_version。测试版本：OPA v1.20.1（官方 opa_linux_amd64_static 发行版，构建日期 2026-08-28；于实验室虚拟机测量 —— 见 §2）。

Documentation, published schema, and source facts checked against the live docs and the v1.20.1 source tag (2026-09-02). Config profile: Single official opa binary; minimal two-file bundles (.manifest + one policy.rego, full contents in §2); one minimal config.yaml used only for the contrast check in §4. 文档、已发布的模式及源代码事实已与实时文档和 v1.20.1 源码标签（2026-09-02）进行了核对。配置概况：单一官方 OPA 二进制文件；最小化的双文件 Bundle（.manifest + 一个 policy.rego，完整内容见 §2）；一个仅用于 §4 对比检查的最小化 config.yaml。

Verified on: 2026-09-22 (desk sources re-checked; v1.20.2 is the current release) · lab measured 2026-09-11 on v1.20.1. Affects: OPA bundles whose .manifest carries a mistyped or unknown top-level key — for example rego_verison instead of rego_version (measured on v1.20.1). 验证日期：2026-09-22（已重新核对桌面端来源；v1.20.2 为当前版本）· 实验室于 2026-09-11 在 v1.20.1 上完成测量。影响范围：.manifest 文件中包含拼写错误或未知顶层键的 OPA Bundle —— 例如将 rego_version 误写为 rego_verison（在 v1.20.1 上测量）。

TL;DR: OPA’s own docs state that the bundle loader “has always ignored unknown top-level keys” in .manifest, so when a bundle is loaded in bundle mode (opa build -b, or at runtime) a mistyped rego_version produces no diagnostic that names the key (measured on OPA v1.20.1) — the failure can surface instead as rego_parse_error: if keyword is required before rule body pointing at your .rego source file, while a mistyped key in the sibling config.yaml has drawn an explicit unknown configuration option warning since v1.19.0. 简而言之：OPA 官方文档指出，Bundle 加载器“一直忽略”.manifest 中未知的顶层键。因此，当以 Bundle 模式（opa build -b 或运行时）加载 Bundle 时，拼写错误的 rego_version 不会产生任何指明该键名的诊断信息（在 OPA v1.20.1 上测量）—— 故障反而可能表现为指向 .rego 源码文件的 rego_parse_error: if keyword is required before rule body。相比之下，自 v1.19.0 起，同级 config.yaml 中的拼写错误键名已能触发明确的“未知配置选项”警告。

Full report: https://whenitruns.substack.com/p/when-opas-bundle-loader-runs-past 完整报告：https://whenitruns.substack.com/p/when-opas-bundle-loader-runs-past