Module maintenance 

The Maintenance CRD — schedules kopia maintenance run quick + full and manages the ownership lease. At most one per repository. ADR-0001 §3.7.

Structs

Maintenance

Auto-generated derived type for MaintenanceSpec via CustomResource

MaintenanceSchedule

quick (cheap) and full (--full, reclamation) maintenance crons and a shared timezone.

MaintenanceSpec

Maintenance schedule and ownership lease for one Repository/ClusterRepository.

MaintenanceStatus

Observed maintenance state: lease holder and per-kind run results.

ManualRunStatus

Bookkeeping for the most recent annotation-requested run.

Ownership

Maintenance ownership lease holder and takeover policy.

OwnershipStatus

Observed ownership-lease state: who holds it and since when.

RepositoryMaintenanceSpec

Inline maintenance control on a Repository/ClusterRepository (spec.maintenance).

RunStatus

Per-kind (quick/full) run status.

Enums

LeaseAction

What to do about the ownership lease, decided from the takeover policy and whether another owner currently holds it (ADR §3.7). Exhaustive over TakeoverPolicy.

ManualRunMode

Which maintenance kind a manual (annotation-requested) run performs; the wire values are the run-mode annotation values. Defaults to quick.

ManualRunPhase

Lifecycle of a manual run. Closed enum.

TakeoverPolicy

What to do when another owner already holds the lease. Defaults to Never (the safest: never seize a lease another owner holds).

Constants

LEASE_HELD_BY_OTHER_REASON

LeaseOwned=False reason: a foreign owner holds the lease and takeoverPolicy: Never — the run yielded.

LEASE_OWNED_CONDITION

The mover-owned condition recording lease state on Maintenance.status: True (lease claimed, run proceeded) or False with one of the reasons below. Written by the mover, matched by the controller (Ready degradation) and the kubectl plugin — one definition so the producers and readers cannot drift.

LEASE_TAKEOVER_PROMPT_REASON

LeaseOwned=False reason: a foreign owner holds the lease and takeoverPolicy: PromptCondition — the run yielded, prompting the operator to set Force.

Functions

default_maintenance_schedule

The schedule an operator-managed Maintenance uses when the owning Repository/ClusterRepository does not override it: quick every 6h (30m jitter), full daily at 03:00 (1h jitter). Shared by the webhook (defaulting), the controller (projection), and tests, so the default lives in exactly one place. ADR §3.7.

kopia_lease_identity

The STABLE kopia client identity a maintenance mover assumes for lease ((username, hostname)); the mover sets it with kopia repository set-client so kopia’s designated-owner check compares something stable — the pod’s own identity is ephemeral (a new hostname every run), which is why comparing kopia’s recorded owner against it can never work.

kopia_owner_for_lease

The full user@hostname owner string kopia records for lease — what the mover compares maintenance info’s owner against, and what the bootstrap stamps on a repository it CREATES.

lease_action

Decide the lease action. held_by_other is true when a different owner currently holds the maintenance lease for this repository.

lease_held_by_other

Whether kopia’s currently-recorded maintenance owner is a DIFFERENT owner than us — i.e. neither our own lease’s owner nor one of our recognized Ownership::owner_aliases (the migration path: a repo whose managed Maintenance moved to a new lease format still recognizes the owner it used to stamp as itself, so the transition claims and re-stamps rather than yielding to what would otherwise look like a foreign owner).

managed_lease

The logical maintenance-lease string the operator uses for a repository’s DEFAULT-MANAGED Maintenance (ADR §3.7). Single derivation, shared by the managed-Maintenance projection and the bootstrap mover’s initial kopia owner stamp, so they cannot drift.

parse_run_annotations

Parse the run-requested/run-mode annotations into a manual-run request. Ok(None) = no request; Err = the annotations are present but malformed (the messages say how to fix). Shared by the admission webhook and the controller so validation cannot fork (SKILL “one validator, two callers”).