Config Policy
Every cell has configuration, identity rules, security posture, catalog and data behaviour, AI limits, the node and fleet knobs, and services such as Arrow Flight SQL. Config Policy is the one surface that governs all of it. There is no separate settings store: every setting resolves through a single, signed, topology-scoped plane, the same engine that carries Worker Policy, worker enablement and typed configuration are two documents on one plane, not two mechanisms.
An authorized administrator authors a config document for a scope in the topology, the platform overlays it on the section's defaults, and each cell resolves its own effective config locally, narrowest scope wins. Every change is written, key by key, to a tamper-evident config-change audit. There is no per-workspace configuration axis: config is a property of the cell and where it sits, so a workspace or clean room that needs distinct configuration is given dedicated cells and targeted by topology.
The whole story: author to effective config
Figure: Config Policy end to end. A config document is authored per section and scope; a tiered, deny-by-default authz check (green path) admits only a full cell operator or an administrator holding that section's own permission, and refuses (red) everyone else. An admitted change is written key by key to the config-change audit (scope, old → new, actor) and stored as an overlay, signed where it enables a capability, and optionally unsigned for a plain setting. Each cell then resolves base defaults ← overlays matched by its own topology, narrowest scope winning, producing an effective config with per-key provenance.
Table equivalent
| Stage | Where | What happens | Failure / guard |
|---|---|---|---|
| Author | Config Policy → section | Admin sets typed keys for a section at a scope | Typed validation against the section model |
| Authorize | Control plane | Admit iff caller is a cell operator or holds the section's permission | Deny by default; neither → refused |
| Audit | Control plane | Write one row per changed key: subsystem, target, key, old → new, actor | Tamper-evident; the write path is the only author path |
| Store | Control plane | Persist the overlay; sign it when it enables a capability | An enable without a signature is rejected |
| Resolve | Every cell | Merge base defaults ← matching overlays by topology, narrow-wins | No coordinator; a non-matching scope never applies |
| Read back | Every surface | Effective value carries per-key provenance (default / yaml / policy) | The resolver explains where each value came from |
One plane, nine sections, and services
Config Policy resolves two kinds of document through the same reader:
- The nine administrative sections, identity, security, catalog, data, AI, workspaces, node, fleet, org, the settings an operator recognizes from the sidebar. Each section is a typed model: its defaults are the model's own defaults, and every key is validated on the way in.
- Services configured by policy: for example Arrow Flight SQL
(
data.flight_sql, operator-only), whose block layers yaml overrides on top of the model default. Flight SQL is the first service consumer of the unified plane; see Connect a BI tool.
Effective config for any of them is computed the same way: base defaults (section model, then yaml overrides) ← signed policy overlays, with the narrowest matching scope winning.
The topology scope ladder
A config overlay targets a scope in the deployment topology, and a cell applies an overlay only when the overlay's target matches the cell's own topology facts. Broader scopes lay the baseline; narrower scopes win.
Figure: the seven-level topology scope ladder, broadest (org) to narrowest
(cell, green). A cell resolves overlays left to right; when two overlays set the
same key, the one at the narrower scope wins, so a cell-scoped value
overrides a rack value, which overrides a service_group value, and so on.
Table equivalent
| Rank | Scope | Matches a cell when… | Typical use |
|---|---|---|---|
| 1 (broadest) | org | The cell belongs to the organization | Fleet-wide baseline |
| 2 | node | The cell belongs to the node | Per-node posture |
| 3 | service_group | The cell is in the service group | Per-role tuning |
| 4 | zone | The cell is in the availability zone | Locality/residency posture |
| 5 | rack | The cell is on the rack | Per-rack (incl. air-gapped rack) |
| 6 | cell_profile | The cell runs that managed profile | Per-deployment-shape defaults |
| 7 (narrowest) | cell | The cell is that exact cell | One-cell override |
Who may author: tiered, delegated, deny-by-default
Config Policy is authorized by two tiers, and the default is deny:
- A full cell operator, holding
system.cells.inspect(read) orsystem.cells.manage(write), may read or author any section. - A delegated section administrator, holding only that section's own permission (for example the security section's own config permission), may author just that section, without an operator's fleet-wide reach.
This is least-privilege delegation without an operator bottleneck: a security
lead can own security config without being handed the keys to identity, catalog,
or fleet. The operator surface at /admin/config-policy ("Config Policy,
author topology-scoped cell configuration") self-gates: it reads the caller's
permissions, shows a read-only banner and disables authoring when the caller
lacks write, and defaults to denied while permissions load. The backend
re-enforces the same tiered check on every write regardless of what the
client renders.
Authoring cell config is an administrative action. Workspace and clean-room users, clean-room members, never manage cell config; there is no per-workspace or per-clean-room config axis to manage. A workspace that needs its own configuration is served by dedicating cells to it and targeting those cells by topology.
Every change is audited
There is exactly one write path, and it is the audited one. Authoring a config document writes a config-change audit row for each key that changed, the subsystem, the target scope, the key, its old value and new value, and the acting principal. Retiring a policy is audited the same way. Because the audit write is inseparable from the authoring path, "who changed which setting, where, from what to what" is always answerable, the plane is not write-only.
Config Policy and Worker Policy
Config Policy and Worker Policy are two documents on one engine, not two engines:
- Worker Policy decides which background workers are on, for a scope, and makes every cell attest what it actually ran.
- Config Policy carries typed configuration for the nine sections and for services, resolved for a cell against the same topology ladder.
Both are signed where the change is security-critical, both resolve per cell with
no coordinator, and both record provenance. The topology ladder above is the
config plane's axis; the Worker Policy precedence table adds the base service
defaults below org and a time-boxed break-glass pin above cell.
Across the deployment matrix
| Corner | How Config Policy behaves |
|---|---|
| Single-cell | The cell resolves base defaults plus any overlays it matches; with one cell there is nothing to disagree with. |
| Multi-cell (elastic) | Each cell resolves its own effective config from the shared overlays against its own topology facts; a hundred-cell burst inherits the right config at boot because ephemeral cells resolve at startup. |
| Sovereign / air-gapped | Resolution needs no network and no coordinator; a signed enable verifies offline against material the cell holds, so config converges across an isolated rack. |
| Cloud-enabled | The same plane and the same authz; connectivity changes only how quickly a new overlay reaches a cell, not whether it is enforced. |
Related topics
- Worker Policy, the same signed engine, governing worker enablement, with break-glass and fleet attestation.
- Config deployment, the declarative cycle; a Deployment preset authors policy that resolves through this plane.
- Connect a BI tool. Arrow Flight SQL, the first service configured through Config Policy.
- Administration & Configuration, the two administration surfaces and their gating models.