What is the difference between polling bundles and pushing data into OPA through an API?

Polling bundles retrieves policy and data on a schedule from a central source, which is simple and good for relatively static environments. API pushes update OPA whenever data changes, which reduces latency and allows more targeted updates. The trade-off is operational: bundles are easier to centralize, while API pushes demand more ongoing development and maintenance.

Polling bundles vs API pushes: what actually changes

Polling bundles means OPA periodically fetches a packaged set of policy and supporting data from a central source, then evaluates against that snapshot until the next refresh. API pushes mean an external system updates OPA when the underlying data changes, so the policy engine can reflect changes sooner and with finer granularity. The practical difference is not just timing, it is how much control you keep in one place versus how much integration work you accept across producing systems.

With bundles, the main advantage is operational simplicity. One published artifact can serve many OPA instances, which makes versioning, rollback, and distribution easier when the underlying inputs are relatively stable. That pattern also reduces the number of moving parts that must remain available at decision time. The limitation is staleness, because the evaluation state only changes on the next poll, so the policy result can lag behind the source of truth.

With API pushes, the main advantage is responsiveness. When source data changes frequently, pushing updates can reduce the window where OPA is evaluating against outdated information and can let teams update only the affected records instead of republishing a full bundle. The trade-off is that the surrounding platform must handle event delivery, retries, consistency, and lifecycle logic, which makes the integration more complex than a schedule-based fetch.

When bundle polling is the better fit

Polling bundles is usually the cleaner choice when the data changes slowly, the same policy package is consumed by multiple OPA deployments, or you want a simple operational boundary between policy authorship and policy distribution. It also fits environments where availability and predictability matter more than sub-second freshness, because a missed poll or delayed refresh is usually easier to absorb than a broken push pipeline.

Bundle delivery also gives teams a clearer deployment artifact to test and promote. If your change model already revolves around releases, approvals, and controlled rollout windows, bundles align well with that cadence. The main thing to watch is whether the snapshot age is acceptable for the decision you are making, especially if the policy depends on rapidly changing entitlements, resource state, or user context.

When API pushes are worth the extra complexity

API pushes are the stronger pattern when the decision quality depends on freshness, per-object updates, or event-driven state changes. They are useful when a full bundle refresh would be wasteful, or when the system that owns the data can emit reliable change notifications and you want OPA to converge quickly after each change. In those cases, the engineering effort buys you lower latency and less unnecessary churn.

That said, API pushes shift the burden from periodic distribution to operational correctness. You need to think about idempotency, partial failure, replay, ordering, and what happens when the push path is temporarily unavailable. If those concerns are not designed up front, the “faster” path can become the less trustworthy one because policy decisions depend on whether every update was delivered and applied in the right order.

Choosing the model based on freshness, scale, and failure tolerance

The right answer usually comes down to the update pattern of the data, not the policy language itself. If the inputs are mostly static, bundles keep the system simpler and easier to reason about. If the inputs are highly dynamic and the cost of stale decisions is material, API pushes can be justified, but only if the surrounding integration is engineered with the same care as the policy logic.

A useful rule is to treat bundles as the default for broad distribution and API pushes as the exception for high-change, high-precision data. Many teams end up with a hybrid model, where bundles carry the stable baseline and pushed updates handle the subset of records that must change quickly. That approach preserves operational simplicity where possible while limiting the complexity to the places where latency actually matters.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

OWASP API Security Top 10 addresses the attack and risk surface, while NIST SP 800-53 Rev 5 sets the governance and control requirements practitioners need to meet.

Framework	Control / Reference	Relevance
OWASP API Security Top 10	API8 — Security Misconfiguration	API-driven updates add integration and delivery failure modes to the OPA data path.
Recommendation — Harden the update API and validate update handling to prevent policy state drift.
NIST SP 800-53 Rev 5	AU-6 — Audit Record Review, Analysis, and Reporting	Both polling and push models need traceability for policy/data refresh and applied changes.
	CM-3 — Configuration Change Control	Bundle publishing and API pushes both change policy inputs and need controlled promotion.
Recommendation — Log and review every policy or data refresh so stale or failed updates are detectable. Require controlled change approval for policy and data updates before they reach OPA.

Practitioner Guidance

What to verify: Check whether the decision depends on snapshot freshness or on deterministic rollout. If stale data changes the outcome in a way that affects access, entitlement, or enforcement, polling alone may not be enough.

Decision rule: Use bundles when the main requirement is repeatable distribution with low operational overhead; use API pushes when the source system can reliably emit changes and the policy result must track those changes closely.

Common mistake: Teams often optimize for faster update delivery without accounting for the maintenance burden of the update path itself. If the push mechanism is fragile, the policy engine may become only as reliable as the least reliable integration in the chain.

Practitioner takeaway: The real choice is between centralized simplicity and event-driven freshness, so pick the model that matches the acceptable staleness of the decision, not the elegance of the implementation.