docs: add OpenBao secret namespaces page #4

Open
kennethz wants to merge 1 commit from kennethz/openbao-secret-namespaces into main AGit
Member

Covers the "OpenBao secret namespaces" onboarding docs task.

What

  • New page governance/OpenBao Secret Namespaces.md (linked in SUMMARY under Governance):
    • which slugs become secret namespaces, and the two validator rules that enforce it
    • what the openbao generator emits per slug (<slug>-dev / <slug>-prod policies, members/admins identity groups, per-repo CI entities)
    • how Keycloak /projects/<slug>[/admins] groups reach Vault through the groups claim and external group aliases
    • capability matrix for members, leads, CI, Kennel, governance AppRole and devops
    • gotchas: re-login after group changes, the secret-name allowlist in infrastructure, KV v2 delete semantics, the Kennel namespace check
  • Specs/governance.md: fixed the stale OpenBao section (devops exemption was removed in governance 969149b, admins only carry -prod, the allowlist now lives in infrastructure modules/terranix/configurations/governance.nix).
  • governance/AGENTS.md: two short pointers.

How it was checked

  • Regenerated governance tofu/ from current main: no drift, so the page matches the committed output.
  • Ran governance validate on deliberately broken data to confirm both namespace errors.
  • Member column of the matrix checked with sys/capabilities-self against the live server; other columns read from the policy source.
  • mdbook build passes and all in-page anchors resolve.

Needs a look from DevOps leads

Since 969149b governance no longer generates the /projects/devops Keycloak group, but infrastructure still keys the devops Vault policy, Grafana admin, the Forgejo admin group, headscale and LiteLLM admin on it. Members added after that commit do not get the devops policy. Details and options are in the page's last gotcha.

Covers the "OpenBao secret namespaces" onboarding docs task. ## What - New page `governance/OpenBao Secret Namespaces.md` (linked in SUMMARY under Governance): - which slugs become secret namespaces, and the two validator rules that enforce it - what the openbao generator emits per slug (`<slug>-dev` / `<slug>-prod` policies, members/admins identity groups, per-repo CI entities) - how Keycloak `/projects/<slug>[/admins]` groups reach Vault through the `groups` claim and external group aliases - capability matrix for members, leads, CI, Kennel, governance AppRole and devops - gotchas: re-login after group changes, the secret-name allowlist in infrastructure, KV v2 delete semantics, the Kennel namespace check - `Specs/governance.md`: fixed the stale OpenBao section (devops exemption was removed in governance `969149b`, admins only carry `-prod`, the allowlist now lives in infrastructure `modules/terranix/configurations/governance.nix`). - `governance/AGENTS.md`: two short pointers. ## How it was checked - Regenerated governance `tofu/` from current `main`: no drift, so the page matches the committed output. - Ran `governance validate` on deliberately broken data to confirm both namespace errors. - Member column of the matrix checked with `sys/capabilities-self` against the live server; other columns read from the policy source. - `mdbook build` passes and all in-page anchors resolve. ## Needs a look from DevOps leads Since `969149b` governance no longer generates the `/projects/devops` Keycloak group, but infrastructure still keys the `devops` Vault policy, Grafana admin, the Forgejo admin group, headscale and LiteLLM admin on it. Members added after that commit do not get the `devops` policy. Details and options are in the page's last gotcha.
docs: add OpenBao secret namespaces page
Some checks are pending
Build and Deploy DevOps Runbooks / Build and Deploy (pull_request) Blocked by required conditions
f994ae6119
Document how the governance openbao generator builds per-slug policies,
how Keycloak groups link to Vault identity groups, CI JWT identities,
and a capability matrix checked against the live server.

Also correct the stale OpenBao section in Specs/governance.md (devops
exemption, admin policies, secret allowlist location) and record the
missing /projects/devops group in governance/AGENTS.md.
Some checks are pending
Build and Deploy DevOps Runbooks / Build and Deploy (pull_request) Blocked by required conditions
This pull request can be merged automatically.
Some workflows are waiting to be reviewed.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin '+refs/pull/4/head:kennethz/openbao-secret-namespaces'
git switch 'kennethz/openbao-secret-namespaces'

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch 'main'
git merge --no-ff 'kennethz/openbao-secret-namespaces'
git switch 'kennethz/openbao-secret-namespaces'
git rebase 'main'
git switch 'main'
git merge --ff-only 'kennethz/openbao-secret-namespaces'
git switch 'kennethz/openbao-secret-namespaces'
git rebase 'main'
git switch 'main'
git merge --no-ff 'kennethz/openbao-secret-namespaces'
git switch 'main'
git merge --squash 'kennethz/openbao-secret-namespaces'
git switch 'main'
git merge --ff-only 'kennethz/openbao-secret-namespaces'
git switch 'main'
git merge 'kennethz/openbao-secret-namespaces'
git push origin 'main'
Sign in to join this conversation.
No description provided.