What is OPA's data document, and what are the ways facts get loaded into it?

### The two documents a rule can read Every OPA decision is a query evaluated against two things. `input` is the object under decision — an admission request, a Terraform plan JSON, a CI job payload. `data` is everything else OPA knows: a JSON tree, held in the process's memory, that any rule can reference by path as `data.<something>`. Their lifecycles differ completely. `input` arrives with the query and is gone when the answer returns; `data` is loaded once and then serves every decision until something changes it. A realistic guardrail needs both. "A workload may only request an instance type on the organisation's approved list" reads the requested type out of `input` and the list out of `data`: ```rego package platform.workloads deny contains msg if { not data.approved.instance_types[input.instance_type] msg := sprintf("instance type %v is not on the approved list", [input.instance_type]) } ``` The approved list is a fact about the organisation rather than about the change, so it has to already be inside the engine when the request arrives. ### Path one: files at startup `opa run` accepts files and directories. JSON and YAML files are loaded into `data` at the path implied by their location on disk, so `approved/instance_types.json` lands at `data.approved.instance_types`. This is the simplest thing that works and is fine for a fact that only changes when you redeploy — but it makes every fact update a restart, and it makes the facts invisible to anyone reading the deployment rather than the image. ### Path two: bundles OPA periodically fetches a bundle — a gzipped tarball carrying policy modules and data files — from a bundle service, and activates the whole thing at once. This is the dominant model, because the facts a policy reads are versioned, reviewed and shipped exactly like the policy that reads them: one artifact, one revision, and any new replica becomes correct as soon as it has completed its first fetch. A bundle declares `roots` in its manifest; everything under those paths is owned by that bundle and is erased and rewritten on each activation. ### Path three: the Data API A running OPA exposes its store over HTTP. `PUT /v1/data/approved/instance_types` writes the document at that path; `PATCH` applies JSON Patch operations to it; `GET` reads back exactly what the engine currently holds, which is the single most useful diagnostic on this whole subject. Here the direction of travel is inverted: instead of OPA pulling on a schedule, whatever owns the source of truth pushes when it changes. That suits a fact that moves many times an hour, or one produced by a system that has no place in a bundle build. ### The three things people get wrong **Pushed data is memory only.** OPA's default store is in-process and in-memory. Restart the pod and everything pushed over the Data API is gone; what comes back is only what loads at boot — startup files and the first bundle fetch. A push pipeline therefore has to be re-drivable on demand, not fire-and-forget. **Replicas do not share a store.** Each OPA holds its own copy. There is no replication and no shared cache between them, so a push must reach every instance. In a sidecar deployment that is one write per pod, which is exactly why bundles win at scale: every instance converges on the same artifact by polling, without anyone tracking who has been written to. **One owner per subtree.** A bundle's declared roots are owned by that bundle and are rewritten on every activation, so a path inside a bundle root is not a safe home for pushed data. Decide per subtree whether the bundle or the push job owns it, and keep pushed facts outside the bundle's roots. ### Choosing between them A workable rule of thumb: if a human reviews changes to the fact and it moves on the same cadence as policy, put it in the bundle — you get review, versioning and a revision you can name when explaining a decision. If a machine owns the fact and it changes far faster than a bundle build, push it, and accept that you now own the freshness and the re-push-after-restart problem yourself.