| name | ovstorage-operator-configure-broker-policy |
| description | Use when authoring or rotating the broker's authz policy - covers the [authz] TOML block, plugin selection, policy-epoch advance/invalidate, and grace-window freshness mode. |
| license | CC-BY-4.0 |
| version | 0.1.0 |
| author | NVIDIA Omniverse |
| tags | ["ovstorage","broker","authz"] |
| tools | ["Read","Write"] |
| compatibility | Requires access to broker configuration files and the operator's approved policy source. Secrets and deployment details are user-supplied. |
Configure Broker Authz Policy
Goal
Write a correct [authz] policy block for ovstorage-broker,
manage policy_epoch advances on policy rotation, and pick
freshness modes (strict vs grace_window) that match the
deployment's tolerance for cached decisions.
Recipe
- Read
docs/public/plugin-authz/README.md
for the SPI shape, the stable list of 21 operation names, the
copy / rename decomposition rule, and the policy-epoch model.
- Pick an authz plugin.
ovstorage-authz-toml ships in-tree;
third-party plugins build against the SPI per the same doc.
- Author the
[authz] block:
[authz]
plugin = "ovstorage-authz-toml"
decision_ttl_max_seconds = 30
[[authz.policy]]
id = "team-read"
effect = "allow"
principal = "team-*"
operations = ["read", "stat", "list"]
prefix = "s3://corp-prod/team/"
Rules: longest-prefix wins; ties go to the later rule. Denies by
default. Prefix is the incoming caller-facing URL, never a
resolved physical target.
- Decompose
copy and rename: those are NOT standalone authz
ops. Grant read on source + write on destination instead.
add_alias keeps its own op AND requires read on the alias
to target.
- Pick freshness:
strict (default) — reauthorize every cache hit against the
current policy_epoch. Most secure; slowest for policy
churn.grace_window — honor request_epoch + 1 == current_epoch
for cache hits (unless explicitly invalidated). Trades some
freshness for lower load on the authz plugin during reload
windows.
- Validate before deploying:
cargo run -p xtask -- list-routes --config /etc/ovstorage/broker.toml
- On Unix, advance the policy with SIGHUP. The
LifecycleController re-reads and re-validates the config,
builds a fresh Broker, advances policy_epoch, and
atomically swaps. New RPCs see the swapped broker immediately;
in-flight RPCs continue against their captured snapshot.
- On Windows, restart the process — no SIGHUP equivalent.
Policy rotation runbook
- Add a new allow rule for a new team. Edit TOML; SIGHUP. New
rule applies on the next RPC.
- Revoke access immediately. Add a
deny rule, SIGHUP. Pair
with grace_window: false if you cannot tolerate the previous
epoch's cached decisions.
- Wholesale policy rewrite. Edit TOML; SIGHUP. The fresh
policy_epoch advances past the old; stale requests stamped with
the old epoch fail with PolicyEpochStale (which the SDK turns
into a refresh-and-retry).
- Invalidate one specific older epoch without a full advance:
use the broker's internal
PolicyEpochState::invalidate path
(currently only exposed to in-process maintenance; no operator
CLI today).
Common mistakes
- Writing rules against the resolved physical target instead of
the caller-facing alias. The broker authorizes the
caller-facing address; aliases are compatibility gates, not
policy-bypass holes.
- Forgetting that
prefix = "*" matches calls without an
address (list_address_roots, list_backend_kinds, etc.); a
concrete prefix only matches requests carrying an address.
- Granting
copy or rename directly — those decompose into
primitives at the broker before they reach the plugin. Grant the
primitives.
- Forgetting the alias-write
read(to) check. Creating an alias
to data the caller can't read themselves would let others reach
it through the alias.
- Skipping
state_root in production. In-memory mode resets the
epoch counter to 0 on every restart.
References
