Skip to content

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

1. Define the levels

Each AccessLevel lists capabilities on KV data and on metadata. versions: true also grants the version paths (delete, undelete, destroy):

examples/access/accesslevel.yaml
# 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.

examples/access/accessgrant.yaml
# 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:

kubectl -n openbao-config get accessgrant payments-workloads -o jsonpath='{.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:

examples/access/accesslayout.yaml
# 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