← Back to index Esc
Kind
Snapshot
Group
kopiur.home-operations.com
Version
v1alpha1
apiVersion: kopiur.home-operations.com/v1alpha1 kind: Snapshot metadata: name: example
Tip: use .spec.deletionPolicy for path-only search
View raw schema
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.
repository object
The ONE repository this `Snapshot` targets, pinned by value at mint time. Stamped by a multi-repository `SnapshotPolicy` fan-out (each child covers exactly one member of the policy's repository set) and by `SnapshotReplication` copy CRs (the destination repository). Absent for the legacy single-repository case, where the policy's own `spec.repository` (or, for catalog rows, the owning repository CR) is the answer — an absent pin resolves exactly as before this field existed, so pre-feature `Snapshot`s are untouched.
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`.
source object
The ONE concrete source this `Snapshot` covers, when `policyRef` names a recipe whose `sources[]` expands to many — i.e. a [`pvcSelector`](crate::snapshot_policy::PvcSelector). Stamped by whoever minted the CR: a `SnapshotSchedule` fire, or `kubectl kopiur snapshot now`. Absent for the ordinary single-source case, where the policy's own `sources[0]` is the target. Absent against a *selector* policy is refused rather than guessed. The operator must never pick a PVC on the user's behalf: silently backing up one arbitrary volume out of N looks exactly like success.
group object
The consistency group this child belongs to, present only when the policy asked for one (`groupBy: VolumeGroupSnapshot`) AND the expansion produced more than one member in this namespace.
namespace string required
Namespace the `VolumeGroupSnapshot` lives in. A `VolumeGroupSnapshot` is namespaced and its `source.selector` is namespace-local, so a selector spanning namespaces yields ONE GROUP PER NAMESPACE, not one group. The consistency guarantee is per-namespace and this field is where that shows.
volumeGroupSnapshotName string required
Name of the shared `VolumeGroupSnapshot`.
sourceIndex integer required
Zero-based index into `policyRef`'s `spec.sources` this child expanded from. Pins WHICH source's knobs (`readOnly`, `sourcePathOverride`, `sourcePathStrategy`, `acknowledgeLiveMutation`) govern this run, so a policy carrying several sources stays unambiguous. An index that is out of range at reconcile time — the policy shrank mid-run — is a named terminal failure, never a silent fallback to `sources[0]`.
format: uint32
minimum: 0
target object required
What the expansion resolved to.
pvc object
One `PersistentVolumeClaim`, fully qualified.
name string required
Name of the matched `PersistentVolumeClaim`.
namespace string required
Namespace of the matched `PersistentVolumeClaim`. Explicit rather than inferred from the `Snapshot`'s own namespace: a `pvcSelector` under a `ClusterRepository` may match across namespaces.
tags object
Free-form tags attached to the kopia snapshot manifest itself (`snapshot create --tags`), e.g. `reason: pre-upgrade` — durable in the repository, independent of this CR. Keys must be non-empty, colon-free (kopia splits on the first colon), and must not start with the reserved `kopiur` prefix; at most 10 tags, keys ≤ 63 bytes, values ≤ 256 bytes (webhook-enforced).
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.
copiedFrom object
Lineage for `origin: replicated` rows: the source repository, source manifest id, and `startTime` the copy was migrated from. Written by the `SnapshotReplication` mover in the same atomic PATCH as `status.snapshot`; absent on every other origin. See [`CopiedFrom`] for why this lives on the CR rather than as kopia tags.
repository object required
The SOURCE repository the snapshot was migrated from (the `SnapshotReplication`'s `sourceRef`, resolved 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`.
sourceManifestId string required
The kopia manifest id the snapshot had in the SOURCE repository. Migrate assigns a NEW manifest id on the destination (`status.snapshot.kopiaSnapshotID`); this is the old one, kept for cross-repository correlation.
startTime string required
The snapshot's RFC3339 `startTime` — preserved verbatim by migrate and the key (together with the identity triple) both idempotent re-migration and `pruning: mirrorSource` correlate source and destination rows on.
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.
op string
The mover operation that failed, as a stable label (e.g. `repository connect`, `snapshot create`) — the values of the mover's `KopiaOp::as_str()`. Distinguishes a repository-level connect failure from a source-level failure (a broken PVC), which share `kopiaErrorClass` values (e.g. `NotFound`). Absent on failures that occurred outside a kopia invocation.
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, replicated
phase string
Lifecycle phase of a `Snapshot`.
enum: Pending, Running, Succeeded, Failed, Deleting, Discovered, Unchanged
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.
recorded object
The mover identity recorded on the kopia snapshot itself (the `kopiur-meta` tag): the resolved effective uid/gid/fsGroup the backup ran as, plus its provenance. Produced runs stamp this at launch (from the same value written into the tag); discovered rows decode it from the tag during the catalog scan. Absent for pre-feature snapshots, foreign backups without the tag, or a tag this operator version cannot decode.
fsGroup integer
The resolved pod-level `fsGroup` the mover ran with (the hardened default is `65532`). Absent = no layer set one.
format: int64
gid integer
The resolved effective `runAsGroup` the mover ran as at backup time (container `runAsGroup`, else pod). Absent = image-determined.
format: int64
schema integer required
The `kopiur-meta` schema version this value was written under. Writers emit the lowest schema that represents the data (currently [`KOPIUR_META_SCHEMA_V1`]); readers reject only a schema NEWER than they understand (degrading to recorded-absent, never an error).
format: int64
src string required
Which layer pinned the recorded identity. Only `inherited` means the identity tracked the workload.
enum: inherited, explicit, defaults, unknown
uid integer
The resolved effective `runAsUser` the mover ran as at backup time (container `runAsUser`, else pod). Absent = no layer pinned a UID, so the mover's UID was image-determined.
format: int64
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.
description string
The kopia snapshot description (`snapshot create --description`), when one is recorded and non-empty. For discovered rows this is copied from the repository listing TRUNCATED to 1024 bytes (char-boundary-safe) — the value is foreign-writer-controlled and must never fail the CR write.
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).
volumeGroupSnapshotName string
Name of the shared CSI `VolumeGroupSnapshot` this member staged from, when the recipe asked for a consistency group ([`groupBy: VolumeGroupSnapshot`](crate::snapshot_policy::GroupBy)). Recorded because the group is otherwise invisible: it deliberately carries no ownerReferences (see `io::group_staging`), so this is how an operator tells which capture a backup came from — and how `kubectl kopiur doctor` finds one that outlived its members.
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.

No matches. Try .spec.deletionPolicy for an exact path

Copied!