Access model¶
This guide gives workloads and people access to KV version 2 secrets without writing ACL policies by hand. Three kinds work together:
| kind | for | writes in OpenBao |
|---|---|---|
AccessLevel |
a named set of capabilities, such as read, write or owner | nothing; grants and layouts cite it |
AccessGrant |
Kubernetes ServiceAccounts (machine access) | one policy grant_<namespace>_<name> and one Kubernetes auth role per subject |
AccessLayout |
identity provider groups (human access) | one policy per role, OpenBao namespace and organisation, and per auth mount an external group with a group alias |
A tenant is a team boundary in Kubernetes and in OpenBao. How those namespaces relate is in Concepts: servers, connections and the tenant boundary.
Before you begin¶
- A KV version 2 mount (KV secrets).
- For grants, a Kubernetes auth method (Kubernetes auth); for layouts, an OIDC or JWT auth method that sends a groups claim (JWT and OIDC auth).
- A
Readyconnection whose OpenBao policy allows the policy, role and identity group paths the access kinds write; OpenBao policy for the operator lists them.
1. Define the levels¶
Each AccessLevel lists capabilities on KV data and on metadata. versions: true also grants the
version paths (delete, undelete, destroy):
# Reusable capability sets on KV data and metadata (read, write, owner) that AccessGrant and AccessLayout rules name.
apiVersion: access.openbaoconfig.io/v1alpha1
kind: AccessLevel
metadata:
name: read
namespace: openbao-config
spec:
data:
- read
metadata:
- read
- list
---
apiVersion: access.openbaoconfig.io/v1alpha1
kind: AccessLevel
metadata:
name: write
namespace: openbao-config
spec:
data:
- create
- read
- update
- patch
metadata:
- read
- list
---
apiVersion: access.openbaoconfig.io/v1alpha1
kind: AccessLevel
metadata:
name: owner
namespace: openbao-config
spec:
data:
- create
- read
- update
- patch
- delete
- list
metadata:
- create
- read
- update
- patch
- delete
- list
versions: true
A level cannot be deleted while a grant or layout cites it: it reports InUse and lists the
citing resources in status.citedBy.
2. Grant access to workloads¶
An AccessGrant lists subjects (ServiceAccounts, by name and namespace or by a namespace
selector) and rules of the form mount, path, level. In a path, {sa.namespace} and {sa.name}
become OpenBao identity templates, so each ServiceAccount reaches only its own path through one
shared policy. A broad subject, a glob or a selector, must scope every path with
{sa.namespace}; the CRD refuses it otherwise.
# Gives the payments ServiceAccounts write access to their own KV paths and read access to shared paths per
# organization, through one generated ACL policy and one Kubernetes auth role per subject.
apiVersion: access.openbaoconfig.io/v1alpha1
kind: AccessGrant
metadata:
name: payments-workloads
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Delete
driftDetection: Enabled
driftInterval: 15m
managementPolicy: Manage
mountPath: kubernetes
subjects:
- name: payments-api
namespace: payments
- name: "*"
namespaceSelector:
matchLabels:
team: payments
tier: workloads
rules:
- mount: secret
path: apps/{sa.namespace}/{sa.name}/*
metadataPath: apps/{sa.namespace}/{sa.name}
level: write
- mount: secret
path: shared/{org}/{sa.namespace}/+/*
metadataPath: shared/{org}/{sa.namespace}/*
level: read
organizations:
- acme
- globex
tokenTTL: 15m
---
apiVersion: access.openbaoconfig.io/v1alpha1
kind: AccessGrant
metadata:
name: payments-batch
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
authMountRef:
name: kubernetes
subjects:
- name: nightly-report
namespace: payments
rules:
- mount: secret
path: reports/*
level: read
tokenTTL: 10m
---
apiVersion: access.openbaoconfig.io/v1alpha1
kind: AccessGrant
metadata:
name: payments-migrations
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
mountAccessor: auth_kubernetes_1a2b3c4d
subjects:
- name: schema-migrator
namespace: payments
rules:
- mount: secret
path: databases/payments
level: owner
The three grants name the Kubernetes auth method in the three supported ways: mountPath,
authMountRef (an AuthMount resource) and mountAccessor. The grant looks the accessor up on
every reconcile. A workload logs in with the role in status.roles:
3. Give people access by group¶
An AccessLayout is a matrix: for each role of people, its level in each OpenBao namespace,
optionally repeated per organisation. groupAliasTemplate builds the name of the identity provider
group that each generated external group matches:
# Gives people access by identity provider group: per organization, developers can write and leads own the org
# paths, while in the prod namespace developers only read and leads write.
apiVersion: access.openbaoconfig.io/v1alpha1
kind: AccessLayout
metadata:
name: platform-teams
namespace: openbao-config
annotations:
openbaoconfig.io/allow-disruptive-update: "false"
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Delete
driftDetection: Enabled
driftInterval: 15m
managementPolicy: Manage
authMounts:
- oidc
organizations:
- acme
- globex
groupAliasTemplate: "{org}_{role}"
paths:
- mount: orgs
path: "{org}/+/*"
metadataPath: "{org}/*"
roles:
- name: developer
levels:
- namespace: ""
level: write
- namespace: prod
level: read
- name: lead
levels:
- namespace: ""
level: owner
- namespace: prod
level: write
Here the identity provider group acme_developer gets write on orgs/acme/ in the base
namespace and read in prod.
Narrowing a level or a path rewrites the policies at once. An update that would delete a policy or
group the layout created before, because a role, namespace, organisation or auth mount left the
spec, waits until the resource carries openbaoconfig.io/allow-disruptive-update: "true". This
keeps a typo from removing people's access.
4. Check that it worked¶
kubectl -n openbao-config get accesslevels,accessgrants,accesslayouts
bao policy read grant_openbao-config_payments-workloads
The grants and layouts show Ready True, and OpenBao holds the rendered policy. Log in as a
subject ServiceAccount with the role from status.roles and read its path to prove the access.
Troubleshooting¶
| symptom | check |
|---|---|
kubectl apply refuses a grant with a message about {sa.namespace} |
a glob or selector subject needs {sa.namespace} in every path |
a grant or layout reports ReferenceNotReady |
the AccessLevel it cites exists in the same Kubernetes namespace, and the auth mount exists |
deleting an AccessLevel hangs with reason InUse |
change or delete the resources in status.citedBy first |
| a layout change does not remove a group | removing access needs openbaoconfig.io/allow-disruptive-update: "true"; see Troubleshooting |
| a person gets no access | the identity provider group name against groupAliasTemplate, and the groups claim of the auth role |
Related¶
- API reference: AccessLevel, AccessGrant, AccessLayout.
- Templated policies: how
{sa.namespace}becomes an identity template. - Architecture: access models.