Skip to main content

Module token

Module token 

Source
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_grace is 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.
ObservedSecret
An owned config Secret, as read from the API.
ObservedToken
A token listed on the dedicated Kanidm account.
TemplateRef
What the Deployment pod template points at.
TokenPlan
Planner output. All lists are sorted.
TokenPolicy
Rotation and safety parameters.
TokenWorld
Everything the planner looks at. Deliberately has no CR status field.

Enums§

ConsumerKind
Kind of a running consumer of a token.
CurrentToken
The token pods should run with after this reconcile.
MintReason
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 expiry falls within EXPIRY_WARNING of now (or has passed); an out-of-range difference counts as within.
plan_tokens
Decide token actions from the observed world. Pure and deterministic.