Two OPA bundles declare overlapping roots in their manifests — what happens?

## Roots as an ownership boundary OPA can be configured with more than one bundle, each polled from its own service and resource. That immediately raises the question of who owns which part of the document tree, and `roots` in the `.manifest` is the answer. A root is a slash-separated path prefix into the combined policy and data namespace, for example `k8s/payments`. Two rules follow from it: 1. **Everything the bundle ships must be inside one of its roots.** A Rego package or a data path outside the declared roots is a bundle error, not a silent import. 2. **Activation replaces the whole subtree.** OPA erases what is currently under the bundle's roots and writes the bundle's content in its place. This is what makes deletion work: drop a `.rego` file from the bundle, republish, and the rules it contained are gone from OPA after the next activation. It also means a bundle can never affect anything outside its roots, no matter what it contains. ## Why overlap is rejected If two bundles both claimed `k8s`, activation order would decide whose rules survive, and each poll of either bundle would wipe the other's content. Rather than allowing that race, OPA requires the roots of all configured bundles to be **disjoint** and refuses the activation when they are not, recording the conflict as a bundle error. The consequence is the part worth saying out loud: **the rejection is not loud to the team that caused it.** OPA keeps running on whatever it had already activated. The bundle service keeps serving happily. The team that just published a new rule sees a green pipeline and a published artifact, and their rule is simply not in the engine. You only see it in OPA's logs and in the status report's per-bundle error field. ## The default-root trap If a bundle has no `.manifest`, or a manifest with no `roots` key, the roots default to the empty root `""` — the whole document tree. That is fine and convenient in a single-bundle deployment, and it is exactly what most examples show. The moment a second bundle is added it becomes a conflict machine: the unscoped bundle claims everything, so it overlaps with any scoped bundle you add next. Teams hit this the first time they split a monolithic policy bundle into per-team bundles, and the fix is to add explicit roots to the original bundle in the same change that adds the second one. ## Designing the root layout A workable layout mirrors the ownership you actually have: | Bundle | roots | who publishes | |---|---|---| | platform baseline | `k8s/platform` | the platform team | | payments overlay | `k8s/payments` | the payments team | | shared reference data | `ref` | the data pipeline | Two things follow. First, a team can only ever break its own subtree, which is a meaningful blast-radius property when several groups publish independently. Second, cross-bundle references still work in one direction: policy in `k8s/payments` can read `data.ref`, because reading is not owning. Only writing is scoped. A common structural mistake is to try to have a team "extend" a baseline rule by shipping the same package from a second bundle. That is precisely the overlap OPA forbids. The composition has to happen inside a single owner's bundle — a baseline rule that reads a per-team data document another bundle owns — rather than by two bundles writing the same path. ## Diagnosing it Given "our new bundle publishes but the rule never fires", roots overlap belongs in the first three hypotheses along with a download failure and an activation error. All three look the same from outside: the active revision for that bundle is not the one you published, and the status report has an error string that names the cause. Checking the manifest of *every* configured bundle, not just the one you changed, is what makes overlap findable — the conflict is a property of the pair, and the bundle you did not touch is as likely to be the unscoped one.