Expand description
Pure token planner: which token to run, revoke and garbage-collect. Pure token planner for the RADIUS service account.
Every reconcile observes the world (tokens on the dedicated Kanidm account,
owned config Secrets, the Deployment pod template, ReplicaSets and pods)
and plan_tokens decides which token pods should use, which tokens to
revoke and which config Secrets to garbage-collect. The planner performs no
I/O and never reads CR status, so losing status cannot change a decision.
Safety invariants, each covered by a test below:
- The current token, the template’s token and every token a consumer (template, ReplicaSet, pod) references are never revoked.
- If any consumer reference cannot be resolved to a token id (unparsable annotation, or a mounted config Secret that is gone or carries no parsable token id), nothing is revoked in that pass: the planner cannot prove which token that consumer holds.
- No token younger than
TokenPolicy::orphan_graceis revoked, whether or not it has an owned Secret. A token minted by a reconcile that crashed (or is still in flight) before its Secret or Deployment landed is therefore safe until the grace expires. - A config change alone never mints: the current token is derived from the template’s Secret, not from the rendered content.
- Replication lag never mints twice: the template’s token is kept while it is missing from the token list only if every config Secret naming it is younger than the orphan grace. A token that is not listed is never revoked, so this rule cannot revoke anything.
- Minting never raises the account above
TokenPolicy::max_tokens. - Output lists are sorted, so equal inputs give equal plans.
Clock assumption: issued_at and expiry come from the Kanidm server
clock and now from the operator clock. Skew is assumed to be well below
the orphan grace (10 minutes) and the safety margin (1 day). If Kanidm
runs ahead, tokens look younger and are held longer (safe direction); if
it runs behind, the grace shrinks by the skew. All date arithmetic is
checked: an out-of-range result means “not yet” for due and grace checks
and “already” for the expiry check, so overflow never panics and always
errs toward keeping tokens alive and minting early.
Executors must take revoke and gc_secrets only from a plan computed on
a fresh observation made after the Deployment apply (reconcile step 8),
never from the plan that decided to mint.
Structs§
- Consumer
- A ReplicaSet or pod that may hold a token.
- Observed
Secret - An owned config Secret, as read from the API.
- Observed
Token - A token listed on the dedicated Kanidm account.
- Template
Ref - What the Deployment pod template points at.
- Token
Plan - Planner output. All lists are sorted.
- Token
Policy - Rotation and safety parameters.
- Token
World - Everything the planner looks at. Deliberately has no CR status field.
Enums§
- Consumer
Kind - Kind of a running consumer of a token.
- Current
Token - The token pods should run with after this reconcile.
- Mint
Reason - Why a new token is needed.
Constants§
- EXPIRY_
WARNING - A blocked reconcile warns when the running token expires within this
window: twice
SAFETY_MARGIN, so the warning comes a margin before the planner would have replaced the token. - MAX_
TOKENS - Upper bound on tokens on the account; minting stops at this count.
- ORPHAN_
GRACE - Tokens younger than this are never revoked (crash and in-flight safety).
- SAFETY_
MARGIN - A token whose expiry falls within this margin is replaced before it lapses.
Functions§
- expires_
within_ warning - Whether
expiryfalls withinEXPIRY_WARNINGofnow(or has passed); an out-of-range difference counts as within. - plan_
tokens - Decide token actions from the observed world. Pure and deterministic.