Skip to main content

Gate policies and bundles

Gate policy bundles are the packaging bridge between plans and runtime enforcement. This page defines how bundle selection is derived from plan/catalog configuration.

Concept split​

  • Bundle: named set of gate policies.
  • Policy: an individual rate/quota/seat rule.
  • Assignment: account gets a bundle through active plan state.

Bundle metadata boundary​

gate_policy_bundles.metadata is currently treated as extension metadata only.

  • Bundle metadata is stored and returned by management APIs.
  • Runtime bundle selection does not currently read bundle metadata fields.

Bundle selection sources​

Bundle key can come from:

  • billing_plans.metadata.gate_bundle_key
  • catalog_prices.metadata.gating.bundle (purchase-time candidate)

The selected bundle must exist and be active in the same realm.

Policy-level metadata can still affect runtime behavior for specific policy kinds. See Policy model.

Selection rules​

For an account at time T, candidates come from active assignments where:

  • assignment status is active
  • window_start <= T
  • window_end is null or window_end > T
  • plan is active
  • plan kind is base or addon

When multiple candidates exist:

  1. Resolve by bundle_key.
  2. Keep the highest-priority plan per same key.
  3. Pick the first candidate with an active bundle, ordered by plan priority descending.

Rollout strategy​

  1. Create non-system bundle for change set.
  2. Add or adjust policies.
  3. Verify authorize/commit outcomes in controlled accounts.
  4. Migrate account assignments progressively.
  5. Disable old bundles before deletion.

Pitfalls​

  • Defining a gate_bundle_key that has no active bundle.
  • Running overlapping plan windows without clear plan priority.
  • Treating purchase metadata bundle overrides as permanent plan design.

Next​