Snapshot v1alpha1 — kopiur.home-operations.com

spec object required

A single kopia snapshot represented as a Kubernetes object.

deletionPolicy string

Lifecycle of the underlying kopia snapshot when its `Snapshot` CR is deleted. Produced backups default to `Delete`; discovered snapshots are forced to `Retain`.

enum: Delete, Retain, Orphan

description string

Free-form text recorded on the kopia snapshot manifest (`snapshot create --description`). Per-invocation by nature — scheduled/discovered `Snapshot`s never set this (no templated descriptions).

maxLength: 1024

failurePolicy object

Mover Job retry and deadline limits for this run.

activeDeadlineSeconds integer

Mover `Job.spec.activeDeadlineSeconds` — wall-clock cap after which a running run is killed.

format: int64

backoffLimit integer

Mover `Job.spec.backoffLimit` — retries before a failed run is marked failed.

format: int32

podStartupDeadlineSeconds integer

Seconds a non-starting (wedged) mover pod may sit before the run is failed; default 300s.

format: int64

onScheduleDelete string

What the deletion of a `SnapshotSchedule` does to the `Snapshot` CRs it produced (which Kubernetes GC cascade-deletes via their ownerReference). Default `Retain`: the CRs are removed but their kopia snapshots survive and the catalog rediscovers them as `origin: discovered`. `Delete` opts into the cascade: each Snapshot's own `deletionPolicy` applies. Deliberately 2-variant (not reusing [`DeletionPolicy`]): an `Orphan` in cascade position would differ from `Retain` only in per-CR event/metric bookkeeping — an invalid state made unrepresentable. The guard's `Retain` is exactly `DeletionPolicy::Retain`'s semantics (CR removed, kopia snapshot stays, catalog rediscovers it), deliberately NOT the `Orphan` event storm (no per-CR "orphaned" event/metric for every produced Snapshot).

enum: Retain, Delete

pin boolean

Exempt this snapshot from GFS retention.

policyRef object

The `SnapshotPolicy` recipe to run; absent for `discovered` backups.

name string required

Name of the referenced `SnapshotPolicy`.

namespace string

Namespace of the `SnapshotPolicy`; absent = same namespace as the referrer.

tags object

Arbitrary kopia snapshot tags (e.g. `reason: scheduled-nightly`).

status object

Observed state of a [`Snapshot`].

cleanup object

Post-run cleanup bookkeeping, so each cleanup runs at most once per Snapshot.

credsReapedAt string

When the run's projected credential Secrets were reclaimed (RFC 3339); absent until the reap has run. A projected copy is only needed while a mover Job can still load it via `envFrom`, but it is owner-ref'd to this CR, which long outlives that Job — so without an explicit reap it would sit in the workload namespace holding live repository credentials until the CR is pruned (#240).

conditions []object

Standard Kubernetes conditions (e.g. `SourcesQuiesced`, `SnapshotCreated`).

lastTransitionTime string required

lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

format: date-time

message string required

message is a human readable message indicating details about the transition. This may be an empty string.

observedGeneration integer

observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

format: int64

reason string required

reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

status string required

status of the condition, one of True, False, Unknown.

type string required

type of condition in CamelCase or in foo.example.com/CamelCase.

failure object

Structured terminal-failure detail (kopia error class, stderr tail, retry hint).

exitCode integer

The process exit code, if one was reported.

format: int32

kopiaErrorClass string required

kopia error class (e.g. `RepositoryUnavailable`, `AuthFailure`).

message string required

A short human-readable message: what failed, why, and how to fix it.

retryRecommended boolean required

Whether retrying the same operation unchanged could succeed.

stderrTail string

The last lines of kopia's stderr, if any were captured (bounded by [`MAX_LOG_TAIL_BYTES`]).

hooks object

Hook-execution bookkeeping so each hook list runs exactly once per Snapshot.

postCompletedAt string

When the `afterSnapshot` list completed (RFC3339); absent until it has.

preCompletedAt string

When the `beforeSnapshot` list completed (RFC3339); absent until it has.

job object

The mover Job backing this run; absent for discovered.

attempts integer

Number of attempts so far (bounded by `failurePolicy.backoffLimit`).

format: int32

name string

Name of the mover `Job`.

logTail string

The last lines of the run's output, written by the mover at the terminal transition.

observedGeneration integer

`metadata.generation` last reconciled, for staleness detection.

format: int64

origin string

How a `Snapshot` came to exist. Canonical value mirrored from the `kopiur.home-operations.com/origin` label. Origin drives the deletion-policy default: `discovered` backups are forced to `Retain` because the operator did not create those snapshots.

enum: scheduled, manual, discovered, adopted

phase string

Lifecycle phase of a `Snapshot`.

enum: Pending, Running, Succeeded, Failed, Deleting, Discovered

pinned boolean

The observed kopia-side pin state: `Some(true)` if pinned, `Some(false)` if unpinned, `None` before any pin reconcile.

preflightSince string

RFC 3339 timestamp of the first reconcile where the repository was `Ready` but a `spec.preflight` check was failing. The one-shot anchor for the preflight `timeout` deadline (so the budget covers preflight only, not the earlier repository-not-Ready wait). Cleared once every preflight check passes, so a later failing episode gets a fresh budget rather than a stale anchor.

resolved object

Frozen recipe values at run time (scheduled/manual).

credentialProjection object

The recipe's `spec.credentialProjection` as it stood for this run. The deletion path re-projects the mover's credentials, but the opt-in lives on the `SnapshotPolicy` — which a user may delete first. Pinning it here lets the finalizer honor the opt-in that was actually in force, instead of reading an absent recipe as "projection off" and blocking on a Secret that was never meant to be namespace-local (#255). Absent only on a `Snapshot` that predates the pin or never ran; a run always writes it, including `enabled: false`, so absent stays distinguishable from off.

enabled boolean

Copy the repository's credential Secret(s) into the namespace of each mover Job; off by default.

repository object

The repository this run targeted, frozen at run time.

kind string

Which repository CRD this points at; defaults to [`RepositoryKind::Repository`].

enum: Repository, ClusterRepository

name string required

Name of the referenced `Repository`/`ClusterRepository`.

namespace string

Cross-namespace `Repository` reference; ignored/forbidden for `ClusterRepository`.

sources []object

The concrete PVCs + source paths backed up this run.

pvc string

`namespace/name` of the PVC, as kopia sees it.

sourcePath string

The source path kopia recorded for this PVC.

snapshot object

The kopia artifact this CR represents.

identity object required

The `username@hostname:path` identity recorded for this snapshot.

hostname string required

The final `hostname` kopia records, fixed at admission.

sourcePath string

The resolved snapshot source path, when applicable (`username@hostname:path`).

username string required

The final `username` kopia records, fixed at admission.

kopiaSnapshotID string required

kopia's snapshot ID — the handle the finalizer uses to delete content.

staged object

The CSI staging objects the run created for `copyMethod: Snapshot`/`Clone`.

copyMethod string

The resolved capture method (`Snapshot` or `Clone`) that produced this stage.

pvcName string

Name of the staged `PersistentVolumeClaim` the mover mounts in place of the live source PVC.

ready boolean

`true` once the stage is ready for the mover.

stagingTimeoutSeconds integer

The resolved `spec.staging.timeout` (seconds) pinned when the stage was stamped, so the running-Job staged-PVC bind watchdog never re-resolves a policy that may have been edited or deleted mid-run. `0` = wait indefinitely.

format: int64

storageClassName string

StorageClass of the staged PVC — `spec.staging.storageClassName` when set, else the source PVC's class. Pinned for observability (e.g. confirming a CephFS shallow-clone class actually took effect).

volumeSnapshotName string

Name of the `VolumeSnapshot` created from the source PVC (`copyMethod: Snapshot` only).

stats object

Byte/file counts parsed from kopia's JSON output.

bytesNew integer

Bytes newly uploaded this run (after dedup/compression).

format: int64

filesFailed integer

Count of source entries kopia could not read and excluded, making the snapshot incomplete.

format: int64

filesModified integer

Count of files changed since the previous snapshot.

format: int64

filesNew integer

Count of files new since the previous snapshot.

format: int64

filesUnchanged integer

Count of files unchanged since the previous snapshot.

format: int64

sizeBytes integer

Total logical size of the snapshot in bytes.

format: int64

timing object

Start/end/duration of the snapshot run.

durationSeconds integer

Wall-clock duration in seconds.

format: int64

endTime string

RFC3339 end time of the run.

startTime string

RFC3339 start time of the run.