Operator authorization surfaces

Use separate policy surfaces for controller, backup, restore, and upgrade work. Each path authenticates separately and receives only the capabilities it needs.

Diagram

Policies stay attached to job-specific identities

Each operator path maps to its own JWT role and policy set, with separate controller, backup, restore, and upgrade identities.

Decision matrix

Policy surfaces by lifecycle capability

Policy surfaces by lifecycle capability.

Policy surface	Used by	Typical capabilities	Why it stays separate
Controller maintenance	The main controller Deployment	sys/health, sys/step-down, and autopilot configuration reads or updates	Keep this path available for routine reconciliation and maintenance without adding destructive restore powers.
Backup	The generated backup Job	sys/storage/raft/snapshot read access	Snapshot reads are narrower than controller maintenance and remain easier to reason about independently.
Restore	The generated restore Job	sys/storage/raft/snapshot-force update access	Restore can replace the full cluster state and belongs only on the workload that performs restore.
Upgrade	The generated upgrade Job	Step-down, autopilot state, snapshot read, and optional peer-management operations for blue-green flows	Upgrade paths often need time-bounded orchestration permissions without widening steady-state controller access.

Restore is a destructive role

The restore capability can replace data, policies, and keys across the cluster. Do not bind the restore policy to the controller or to a broad multi-purpose ServiceAccount just because it is convenient during setup.

Default policy surfaces

Controller

Configure

Controller maintenance policy

hcl

path "sys/health" {
capabilities = ["read"]
}

path "sys/step-down" {
capabilities = ["sudo", "update"]
}

path "sys/storage/raft/configuration" {
capabilities = ["read"]
}

path "sys/storage/raft/remove-peer" {
capabilities = ["update"]
}

path "sys/storage/raft/autopilot/configuration" {
capabilities = ["read", "update"]
}

path "sys/storage/raft/autopilot/state" {
capabilities = ["read"]
}

This is the steady-state controller scope. Keep backup, restore, and blue-green peer management in separate roles unless you are intentionally changing the model.

Existing clusters must update the controller policy manually

The operator does not rewrite OpenBao policies after bootstrap. If an operator upgrade adds a new controller-side capability, such as read on sys/storage/raft/autopilot/state, update the openbao-operator policy manually on existing clusters. Until that policy includes the new path, features that depend on it will report Unknown rather than a concrete health state.

Backup

Configure

Backup policy

hcl

path "sys/storage/raft/snapshot" {
capabilities = ["read"]
}

Backup only needs snapshot streaming. Storage-provider credentials are a separate boundary outside this OpenBao policy.

Restore

Configure

Restore policy

hcl

path "sys/storage/raft/snapshot-force" {
capabilities = ["update"]
}

Keep this policy tightly bound to the generated restore Job identity and only for the period where restore is actually needed.

Upgrade

Configure

Rolling and blue-green upgrade policy surfaces

hcl

# Rolling upgrade baseline
path "sys/health" {
capabilities = ["read"]
}

path "sys/step-down" {
capabilities = ["sudo", "update"]
}

path "sys/storage/raft/autopilot/state" {
capabilities = ["read"]
}

# Blue-green adds peer-management paths
path "sys/storage/raft/join" {
capabilities = ["update"]
}

path "sys/storage/raft/configuration" {
capabilities = ["read", "update"]
}

path "sys/storage/raft/remove-peer" {
capabilities = ["update"]
}

path "sys/storage/raft/promote" {
capabilities = ["update"]
}

path "sys/storage/raft/demote" {
capabilities = ["update"]
}

Rolling upgrades need less authority than blue-green cutovers. Keep those strategies separate in your head when you review the required policy surface.

Policy upgrade notes

Reference table

When the controller policy surface changes

When the controller policy surface changes.

Situation	What the operator does	What you must do
A new operator release adds a controller-side capability	Uses the new capability if the openbao-operator policy already includes it, otherwise reports Unknown or a permission error for the dependent feature.	Update the openbao-operator policy manually on existing clusters. The operator does not rewrite OpenBao policies after bootstrap.
A cluster was bootstrapped with self-init in an earlier release	Keeps using the already-created JWT role and policy.	Treat the policy as cluster security configuration that you own after bootstrap. Review release notes and add any newly required paths deliberately.
JWT auth and policies are fully manually managed	Never mutates that auth surface.	Carry the full policy diff yourself as part of operator upgrades.

Reference table

Common authorization failures

Common authorization failures.

Symptom	Likely boundary	Check first
JWT login succeeds but the request returns permission denied	The workload authenticated correctly but the policy is missing the needed path capability	Which job or controller path is making the request, then the matching policy surface
Backup works but restore fails	The restore Job identity or restore policy is missing or misbound	Restore ServiceAccount, restore role binding, and snapshot-force policy
Rolling upgrade works but blue-green cutover stalls	Peer-management permissions were not added for the upgrade strategy in use	Upgrade strategy and the corresponding upgrade policy paths
Controller can do too much	A shortcut merged job-specific capabilities into the controller role	Manual auth configuration drift from the intended separation model

Go deeper

Operator authenticationReturn to the JWT audience and bound-subject model when auth fails before policy even matters.Backup operationsSee how the backup Job uses its own auth and storage credentials during normal operation.Restore manager architectureReview why restore stays isolated from the controller and how the operator drives it.

Official OpenBao background

• Policy concepts
• Policy command reference
• Token concepts