Design notes
Audience: contributor · Profile:
both· Read this when: you are about to change a subsystem and want the reasoning that is not recoverable from its code.
These are not user guides. Each one records why a subsystem is shaped the way it is — the constraint that forced the shape, the alternatives that were rejected, and the failure the current design avoids. That is the part a diff cannot tell you, and the part most likely to be undone by someone who reads only the code.
They are deliberately not on the /docs index in the app. An operator following a
Settings panel's instruction should land on a guide, not a design argument; these are
reachable by path, and from here.
| Page | Read this when |
|---|---|
| Machine-identity JIT cloud access | you are changing how the dashboard's own cloud writes are authorised. |
| Entitle user-based JIT (Entra) | you are wiring the dashboard into an existing Entra ID and Entitle deployment, or migrating off that path. |
| Entitle resource registration | you are changing how built resources register themselves as Entitle integrations. |
| Cloud Functions | you are extending Cloud Functions or its workload catalog. |
| k8s ServiceAccount token rotation | you are touching ServiceAccount token rotation and need the reasoning that is not in the code. |
| A workload reaching Kubernetes with a short-lived token | you are changing how a SPIRE lab reaches a k3s cluster with a JWT-SVID, or deciding whether a SPIFFE identity should authenticate to a cluster at all. Built (the lab's Kubernetes action), never run against a live pair. |
| SPIRE for agents, Dex for people | you are giving the remote agent a SPIFFE identity, putting Dex in front of SSO or an on-prem cluster's API server, or wondering why the Ed25519 agent path was kept. Dex for managed clusters is paused. |
| The dashboard as a SPIFFE workload | you are retiring one of the dashboard's stored cloud keys, moving a Workload Lab demo off the lab's SPIRE server, or deciding whether something else should use a SPIFFE token. Built except L3, which waits on the lab's attribute probe; nothing has run against a live cloud. |
| PRA's session-issuing CA | you are making Password Safe the issuer and rotator of the CA that PRA Vault uses to mint session certificates. The plugin half is built; the delivery into PRA is not. |
| Oracle and MongoDB engines | you are adding Oracle or MongoDB to a database layer, or swapping their tcp tunnels for PRA 26.3's dedicated ones. All five slices are built; live validation and PRA 26.3's dedicated tunnels remain. |
The dashboard deploys bt-dbops |
you are working on the in-VPC service the Cloud SQL rotation plugin calls. |
| The demo cells we do not have | you are deciding what to build after the network cell, or wondering why a role you expected to find has no page. Nothing in it is built. |
Two more design notes sit with the profile they belong to, in profiles/pov/design/.
The procedures that prove a design's phases actually landed are in runbooks/; several of them are numbered against the phases in cloud-identity-jit.md.