What OpenBao must grant¶
The plane cannot write its own policies. That takes an OpenBao administrator, a root
token or one allowed to write sys/policies/acl and the auth roles, which the plane
never is. So an administrator runs the lines below once, and again for a grant an
upgrade adds; nothing else here is done by hand.
The plane checks them. When it starts, and on the console's Overview, the plane asks
OpenBao what its own token may do at each path below, look-only
(sys/capabilities-self, which the default policy allows), and says in one sentence
for each grant it lacks what fails without it, with the lines that grant it, written
with the deployment's own mounts, key names, role and the policies its token already
carries. admin.overview answers the same as openbao.
The names are the defaults: mounts secret (KV v2) and transit, the Kubernetes auth
mount kubernetes, the role troupe-plane (the chart's bao.authPath and
bao.planeRole), and the release namespace troupe-system.
1. Before the plane starts¶
The engines, the session-token key, Kubernetes auth with a reviewer (integrations.md §2), and the plane's role, carrying the policy of every grant the plane needs:
bao secrets enable -path=transit transit
bao secrets enable -path=secret -version=2 kv
bao write -f transit/keys/troupe-session-tokens type=ecdsa-p256
bao auth enable kubernetes
bao write auth/kubernetes/config kubernetes_host=https://kubernetes.default.svc:443 # and the reviewer's JWT and CA
bao write auth/kubernetes/role/troupe-plane bound_service_account_names=troupe-plane bound_service_account_namespaces=troupe-system audience=troupe-kms token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane ttl=1h
Then write each policy in section 2. A plane whose role is missing or refuses its ServiceAccount token says so at start, and on the Overview, with the role line above.
2. What the plane's role carries¶
| grant | policy | what it is for | without it |
|---|---|---|---|
session-tokens |
troupe-plane-session-tokens |
sign session tokens, and read the key's public half that workers check them with | no session opens, and no pod or person's daemon can check a token |
plane-signing |
troupe-plane-signing |
make, rotate and sign with the plane's own key, which signs what it tells people's machines | the client versions and defaults go out unsigned, and every client that pinned this plane's key refuses them |
erasure |
troupe-plane |
destroy an erased session's key, a team's or a person's, and see which credentials a person has connected | erasing a session cannot destroy its key, and the console cannot say who has connected what |
invites (only for inviting people into private sessions) |
troupe-plane-invites |
destroy the copy of a private session's key its owner's daemon put in an invitee's own slot, when the invitation is taken back or the session erased | an erasure of a private session somebody was invited into stays pending, and taking an invitation back leaves the copy it gave in the invitee's slot |
github-app (only with a GitHub App) |
troupe-plane-github |
import, sign with and delete the GitHub App's key and webhook secret | a GitHub App cannot be set up, and one set up before stops signing |
token_policies replaces the role's whole list, so each section below ends with the
same line, naming every policy in the table, the optional ones too: OpenBao grants
nothing for a name it holds no policy under, and the plane checks what its token can
do, not what the role names. Run the sections in any order, one alone or again after
an upgrade, and the role still carries every policy written.
troupe-plane-session-tokens¶
To sign session tokens, and read the key's public half that workers check them with.
bao policy write troupe-plane-session-tokens - <<'POLICY'
path "transit/sign/troupe-session-tokens" {
capabilities = ["create", "update"]
}
path "transit/keys/troupe-session-tokens" {
capabilities = ["read"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github
troupe-plane-signing¶
To make, rotate and sign with the plane's own key, which signs what it tells people's machines.
bao policy write troupe-plane-signing - <<'POLICY'
path "transit/keys/troupe-plane-signing" {
capabilities = ["create", "read", "update"]
}
path "transit/keys/troupe-plane-signing/rotate" {
capabilities = ["update"]
}
path "transit/sign/troupe-plane-signing" {
capabilities = ["create", "update"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github
troupe-plane¶
To destroy an erased session's key, a team's or a person's, and see which credentials a person has connected.
bao policy write troupe-plane - <<'POLICY'
path "secret/metadata/troupe/teams/+/sessions/*" {
capabilities = ["delete", "list", "read"]
}
path "secret/metadata/troupe/people/+/sessions/*" {
capabilities = ["delete", "list", "read"]
}
path "secret/metadata/troupe/people/+/mcp/*" {
capabilities = ["list", "read"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github
troupe-plane-invites¶
To destroy the copy of a private session's key its owner's daemon put in an invitee's own slot, when the invitation is taken back or the session erased. Only where people are invited into private sessions.
bao policy write troupe-plane-invites - <<'POLICY'
path "secret/metadata/troupe/people/+/invited/*" {
capabilities = ["delete"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github
troupe-plane-github¶
To import, sign with and delete the GitHub App's key and webhook secret. Only where the plane has a GitHub App.
bao policy write troupe-plane-github - <<'POLICY'
path "transit/wrapping_key" {
capabilities = ["read"]
}
path "transit/keys/troupe-github-app" {
capabilities = ["read", "delete"]
}
path "transit/keys/troupe-github-app/config" {
capabilities = ["update"]
}
path "transit/keys/troupe-github-app/import" {
capabilities = ["create", "update"]
}
path "transit/keys/troupe-github-app/import_version" {
capabilities = ["create", "update"]
}
path "transit/sign/troupe-github-app" {
capabilities = ["create", "update"]
}
path "transit/keys/troupe-github-webhook" {
capabilities = ["read", "delete"]
}
path "transit/keys/troupe-github-webhook/config" {
capabilities = ["update"]
}
path "transit/keys/troupe-github-webhook/import" {
capabilities = ["create", "update"]
}
path "transit/keys/troupe-github-webhook/import_version" {
capabilities = ["create", "update"]
}
path "transit/hmac/troupe-github-webhook/sha2-256" {
capabilities = ["create", "update"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github
3. Workers and people¶
Their roles are not the plane's, and the plane cannot check them: a worker pod logs in
as troupe-worker (or a role per profile), and a person's daemon at the jwt auth mount
as troupe-person. Their policies and roles are in
roles-and-permissions.md §8, rendered by
the same module.