Keep each operator capability on its own policy surface.

Authentication answers who a workload is. Authorization answers what that workload can do. OpenBao Operator stays safer when controller, backup, restore, and upgrade work authenticate separately and only receive the policies each path actually needs.

Diagram

Policies stay attached to job-specific identities

Each operator path maps to its own JWT role and policy set. The controller is not the universal credential for all day 2 work.

Decision matrix

Keep policies separated by lifecycle capability

Keep policies separated 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	This path should stay available for routine reconciliation and maintenance without inheriting destructive restore powers.
Backup	The generated backup Job	sys/storage/raft/snapshot read access	Snapshot reads are narrower than normal controller maintenance and should be easy to reason about independently.
Restore	The generated restore Job	sys/storage/raft/snapshot-force update access	Restore can replace the full cluster state and should only exist on the specific 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 that should not widen steady-state controller access.

Treat restore as 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/autopilot/configuration" {
capabilities = ["read", "update"]
}

This is the steady-state controller scope. It should not expand to cover backup, restore, or blue-green peer management unless you are intentionally breaking the model.

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.

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