VolumeCaptureRequest and VolumeRestoreRequest

VolumeCaptureRequest (VCR) and VolumeRestoreRequest (VRR) are one-shot service resources intended for controllers such as state-snapshotter, not a stable end-user backup UX. Actual create/read access is determined by cluster RBAC; admission currently does not enforce a controller-only policy. Both are namespaced in storage-foundation.deckhouse.io/v1alpha1; their namespace is also the namespace of the source or target PVC.

This page summarizes the current generated CRDs and controller/sidecar behavior. The generated CRDs are the schema of record. How a domain controller consumes these resources is defined by the state-snapshotter domain snapshot SDK, which also owns the core Ready reason mapping.

VolumeCaptureRequest

VCR creates a durable data artifact for one PVC. The domain snapshot SDK uses only spec.mode: Snapshot; Detach is a separate storage-foundation flow.

apiVersion: storage-foundation.deckhouse.io/v1alpha1
kind: VolumeCaptureRequest
metadata:
  name: nss-vcr-4f2c8a91d0e3b7c2
  namespace: my-app
spec:
  mode: Snapshot
  target:
    uid: "2b4f6c7e-7e1d-4d85-95d0-8b52d61534d8"
    apiVersion: v1
    kind: PersistentVolumeClaim
    name: data
status:
  data:
    artifactRef:
      apiVersion: snapshot.storage.k8s.io/v1
      kind: VolumeSnapshotContent
      name: snapshot-73a4cda0-4f2c8a91d0e3
      uid: "1148b6bd-9de2-4c86-a814-7688300932eb"
  completionTimestamp: "2026-07-23T12:34:56Z"
  conditions:
    - type: Ready
      status: "True"
      lastTransitionTime: "2026-07-23T12:34:56Z"
      reason: Completed
      message: "target ready"

Contract:

• spec.target is one PVC identity; namespace is implicit from the VCR. This is a single-target request, not a bulk capture API.
• A request is point-in-time, but the enforcement is incomplete. The CRD requires non-empty uid, apiVersion, kind, and name for Snapshot mode, but has no transition-CEL making spec immutable. The SDK detects a changed existing target only when EnsureVCR reconciles it again. The storage-foundation controller currently resolves the live PVC by request namespace and target name, does not require apiVersion: v1 or kind: PersistentVolumeClaim, and does not compare the live PVC UID with spec.target.uid; the UID is used in deterministic artifact naming. Server-side immutability/typed drift is backlog item #26 and the remaining UID/GVK/admission hardening is #28. The CRD only requires target for Snapshot mode, although the Detach controller path requires it too.
• status.data.artifactRef points to the durable VolumeSnapshotContent or PersistentVolume. The source PVC identity remains in spec.target and is not duplicated in status.
• Ready=True/Completed is success.
• Ready=False/TargetsPending is non-terminal: CSI capture is still retrying. In particular, VolumeSnapshotContent.status.error does not by itself make the request terminal.
• Any other VCR Ready=False reason is terminal.
• Capture domains using the current state-snapshotter SDK contract create or adopt a VCR through snapshotsdk.EnsureVolumeCapture, publish its name, and drive their own lifecycle through DomainCaptureStatus(...).Phase(...).Reason(...).Message(...).Apply(ctx). Regular domains publish MCR/VCR plans before PhasePlanned; current subtree-gated aggregators may publish their own MCR after PhasePlanned as a compatibility exception while waiting for persisted descendant manifests.
• Domains do not read VCR conditions or write VCR status. The state-snapshotter core classifies a terminal VCR failure as Ready=False/VolumeCaptureFailed on the snapshot path. A domain observes the resulting core-owned state through snapshotsdk.CoreCaptureOutcome and publishes PhaseFinished after capture and any domain-specific consistency action. Childless domains may publish PhaseFinished immediately once the core reports capture complete. The target protocol removes the late-own-MCR exception by publishing every node’s own MCR before PhasePlanned.
• The in-tree VolumeSnapshot domain controller follows this contract: a missing source PVC remains recoverable in PhasePlanning, the published MCR freezes the plan at PhasePlanned, successful core capture advances the leaf to PhaseFinished, and core-owned terminal failures remain in Ready.

VolumeRestoreRequest

VRR asks the patched external-provisioner to create and bind one PVC from a VolumeSnapshotContent or PersistentVolume.

apiVersion: storage-foundation.deckhouse.io/v1alpha1
kind: VolumeRestoreRequest
metadata:
  name: restore-data
  namespace: restore-ns
spec:
  sourceRef:
    apiVersion: snapshot.storage.k8s.io/v1
    kind: VolumeSnapshotContent
    name: snapshot-73a4cda0-4f2c8a91d0e3
  pvcTemplate:
    metadata:
      name: data
    spec:
      accessModes: [ReadWriteOnce]
      storageClassName: local
      volumeMode: Filesystem
  fsType: ext4
status:
  pvcRef:
    kind: PersistentVolumeClaim
    namespace: restore-ns
    name: data
    uid: "8c37aa04-af6e-4671-9446-87062a18c189"
  completionTimestamp: "2026-07-23T12:36:04Z"
  conditions:
    - type: Ready
      status: "True"
      lastTransitionTime: "2026-07-23T12:36:04Z"
      reason: Completed
      message: "PVC restore-ns/data restored successfully"

Contract:

• The CRD schema requires sourceRef.name, pvcTemplate, and pvcTemplate.metadata.name. Restore is never cross-namespace.
• The executor additionally requires non-empty pvcTemplate.spec.storageClassName and an exact pvcTemplate.spec.volumeMode of Block or Filesystem. These fields are optional in the current schema. A schema-accepted request that omits either field is ignored by the executor with an event; the controller keeps waiting for a PVC without writing Ready or completionTimestamp. Such a VRR is non-terminal and therefore immortal to generic GC. This malformed empty-status gap needs a code fix; documentation does not make it an accepted execution contract.
• The same empty-status wait can occur for invalid accessModes, a missing StorageClass, or a StorageClass handled by another provisioner. Some paths emit an event and some are silently ignored; none currently gives the VRR controller a terminal result.
• pvcTemplate is only partially materialized, and source kinds differ. The executor validates template storage class and volume mode for every request. For a VolumeSnapshotContent source it uses the template’s storage class, volume mode and access modes (default ReadWriteOnce), plus root fsType for Filesystem volumes. For a PersistentVolume source, the source PV is authoritative for volume mode, access modes, filesystem type and capacity; corresponding template values are not the effective restore shape. Neither path copies template labels/annotations or treats pvcTemplate.spec.resources.requests.storage as authoritative.
• Supported source kinds are VolumeSnapshotContent and PersistentVolume. The current controller and executor select a source by kind and name; sourceRef.apiVersion, namespace, and uid are not enforced against the live source. Backlog item #28 tracks source identity and admission hardening.
• The patched external-provisioner watches VRRs, calls CSI CreateVolume, and creates the PV/PVC. It must not write VRR status.
• VolumeRestoreRequestController is the only status writer. It validates the source, observes the provisioned PVC, and publishes pvcRef, completionTimestamp, and Ready.
• The current pvcRef writer publishes kind, namespace, name, and uid, but leaves the optional apiVersion empty; the example intentionally matches the writer. Consumers must not require that optional field until the writer starts publishing it.
• A terminal VRR is one-shot; create a new request for another attempt.

Current conditions and reasons

SnapshotCreationFailed is compatibility-only and is no longer emitted: a VCR-side VolumeSnapshotContent.status.error stays TargetsPending. The shared constants Incompatible, UnsupportedTargetKind, PVBound, and RestoreFailed are currently unused by both request controllers. A VRR source VSC with status.error is a different path and is finalized as Ready=False/InternalError.

Retention and deletion

Terminal VCR/VRR objects are deleted by cron-driven generic GC using status.completionTimestamp. Defaults:

There are no per-object TTL annotations and no module settings for these values. On the successful state-snapshotter path, core may delete a VCR earlier after it has persisted the data handoff; generic GC is the cleanup path for terminal leftovers. A request without a terminal Ready condition and completionTimestamp, including the malformed VRR case above, is not collected. The current VRR keeper is not connected to the executor-created restore target PVC, so collecting the VRR does not delete that PVC.

Validation and RBAC

Validation is performed by CRD schema/CEL plus the controllers; there is no VCR/VRR admission webhook performing SelfSubjectAccessReview.

The user-facing grants mean these resources are not effectively controller-only today, despite their intended service-resource role. The 040-vrr-provisioner-rbac hook currently binds the executor grant only to the csi ServiceAccount in d8-sds-local-volume. Generic cross-driver VRR support requires extending the shared CSI deployment/RBAC contract.

DataExport

Short names: de

Scope: Namespaced
Version: v1alpha1

• spec

  object
  • spec.publicIngress

    string

    Type of public ingress for external access.

    Allowed values: KubernetesAPI, ConsoleFrontend

  • spec.publish

    boolean

    Enable external access to the exporter pod outside the cluster.
  • spec.targetRef

    object

    Required value

    GroupKind reference to the target resource for export (namespace is implicit = the DataExport’s own namespace). Live PersistentVolumeClaim and VirtualDisk are exported directly; any other (snapshot) kind is resolved generically through the leaf’s bound SnapshotContent.dataRef and restored via a VolumeRestoreRequest. A bare cluster-scoped VolumeSnapshotContent is rejected.
    • spec.targetRef.group

      string

      API group of the target resource ("" / omitted for the core group, e.g. for PersistentVolumeClaim).
    • spec.targetRef.kind

      string

      Required value

      Kind of the target (e.g. PersistentVolumeClaim, VirtualDisk, VolumeSnapshot, VirtualDiskSnapshot).

      Minimal length: 1

    • spec.targetRef.name

      string

      Required value

      Name of the target resource for export.

      Minimal length: 1

  • spec.ttl

    string

    Required value

    Time-to-live duration after the last user request. Acceptable values - <number>s, <number>m, <number>h, e.g. 5m, 2h45m, 1d

    Pattern: ^([0-9]+(\.[0-9]+)?h)?([0-9]+(\.[0-9]+)?m)?([0-9]+s)?$

• status

  object

  Status information for the DataExport resource.
  • status.accessTimestamp

    string

    Timestamp of the last access to the exported data.
  • status.ca

    string

    Base64 encoded CA certificate for TLS connection to the exporter pod.
  • status.completionTimestamp

    string

    Time the DataExport reached a terminal phase (Expired or Failed). Set once by the controller; the garbage collector measures retention age from this timestamp.
  • status.conditions

    array of objects

    Array of conditions describing the current state of the DataExport resource.
    • status.conditions.lastTransitionTime

      string

      Last time the condition transitioned from one status to another.
    • status.conditions.message

      string

      Message describing the condition.
    • status.conditions.observedGeneration

      integer

      Observed generation of the resource when the condition was last updated.
    • status.conditions.reason

      string

      Reason for the current condition status.

      Allowed values: Pending, ServerReady, ValidationFailed, TargetNotReady, TargetNotFound, PVConflict, DeploymentFailed, CleanupFailed, PublishFailed, Expired

    • status.conditions.status

      string

      Status of the condition.

      Allowed values: True, False, Unknown

    • status.conditions.type

      string

      Type of the condition.

      Allowed values: Ready

  • status.phase

    string

    Coarse-grained lifecycle state, written exclusively by the controller: Pending → Ready → Expired | Failed (a DataExport has no Completed phase). Terminating denotes an object with a deletion timestamp and is a transient state, not an outcome. Expired is a normal terminal outcome (the idle-TTL window elapsed), not a failure.

    Allowed values: Pending, Ready, Expired, Failed, Terminating

  • status.publicURL

    string

    Public URL for external access (e.g., https://api.<public-domain>/<namespace>/<target-kind>/<target-name>/). Here <target-kind> is the short kind of the export target: pvc, vd or snap (any snapshot-backed target), and <target-name> is the value of spec.targetRef.name.
  • status.serverState

    string

    Raw progress signal reported by the exporter server pod (the only writer): Ready when the server is serving, IdleExpired when the idle-TTL window elapsed. The controller derives phase and conditions from it.

    Allowed values: Ready, IdleExpired

  • status.url

    string

    Internal URL of the exporter pod (e.g., https://X.X.X.X:8085).
  • status.volumeMode

    string

    Volume mode of the exported data.

    Allowed values: Block, Filesystem

DataImport

Short names: di

Scope: Namespaced
Version: v1alpha1

• spec

  object
  • spec.mode

    string

    Discriminator selecting what the import does with the bytes:

    • CreatePVC: write into a preserved, newly created PVC (pvcTemplate). No durable artifact.
    • PopulateData: stage the bytes into a transient scratch volume (storageParams) and capture them into a durable VolumeSnapshotContent for the already-existing snapshot node referenced by snapshotRef.

    Default: CreatePVC

    Allowed values: CreatePVC, PopulateData

  • spec.publish

    boolean

    Expose the importer pod outside the cluster.

    Default: false

  • spec.pvcTemplate

    object

    CreatePVC only. PersistentVolumeClaim template fully describing the target PVC the imported bytes are written into; the PVC is preserved after the import.
    • spec.pvcTemplate.metadata

      object

      PersistentVolumeClaim metadata.
      • spec.pvcTemplate.metadata.annotations

        object

        PersistentVolumeClaim annotations.
      • spec.pvcTemplate.metadata.labels

        object

        PersistentVolumeClaim labels.
      • spec.pvcTemplate.metadata.name

        string

        PersistentVolumeClaim name.
    • spec.pvcTemplate.spec

      object

      PersistentVolumeClaim specification.
      • spec.pvcTemplate.spec.accessModes

        array of strings

        Desired access modes for the volume.
        • spec.pvcTemplate.spec.accessModes.Element of the array

          string

          Allowed values: ReadWriteOnce, ReadOnlyMany, ReadWriteMany, ReadWriteOncePod

      • spec.pvcTemplate.spec.resources

        object

        Minimum resource requirements for the volume.
        • spec.pvcTemplate.spec.resources.requests

          object

          Minimum amount of compute resources required.
      • spec.pvcTemplate.spec.storageClassName

        string

        Name of the StorageClass required by the PersistentVolumeClaim.
      • spec.pvcTemplate.spec.volumeMode

        string

        Volume mode required by the PersistentVolumeClaim.

        Allowed values: Block, Filesystem

  • spec.snapshotRef

    object

    PopulateData only. Reference to the already-existing xxxSnapshot node the produced durable artifact belongs to (namespace implicit = the DataImport namespace). Set by the external creator (d8/user/backup); the DataImport controller does not read it — it exists so the state-snapshotter reverse-lookup can match the leaf against spec.snapshotRef.
    • spec.snapshotRef.apiVersion

      string

      Group/version of the snapshot node (e.g. snapshot.storage.k8s.io/v1).
    • spec.snapshotRef.kind

      string

      Required value

      Kind of the snapshot node (e.g. VolumeSnapshot, VirtualDiskSnapshot).

      Minimal length: 1

    • spec.snapshotRef.name

      string

      Required value

      Name of the snapshot node.

      Minimal length: 1

  • spec.storageParams

    object

    PopulateData only. Parameters of the transient scratch volume the imported bytes are staged into before capture; it is destroyed after the durable VolumeSnapshotContent is produced. Its StorageClass must be snapshot-capable (it references a VolumeSnapshotClass via the storage.deckhouse.io/volumesnapshotclass annotation).
    • spec.storageParams.size

      string

      Required value

      Requested size of the scratch PVC (a Kubernetes quantity, e.g. 10Gi).

      Minimal length: 1

    • spec.storageParams.storageClassName

      string

      Required value

      StorageClass of the scratch PVC (must be snapshot-capable).

      Minimal length: 1

    • spec.storageParams.volumeMode

      string

      Volume mode of the scratch PVC. Defaults to Filesystem when omitted.

      Allowed values: Block, Filesystem

  • spec.ttl

    string

    Required value

    Time-to-live duration after the last user request.

    Acceptable values:

    • <number>s
    • <number>m
    • <number>h

    For example, 5m, 2h45m, or 1d.

    Pattern: ^([0-9]+(\.[0-9]+)?h)?([0-9]+(\.[0-9]+)?m)?([0-9]+s)?$

  • spec.waitForFirstConsumer

    boolean

    If set to false, a load pod is created to trigger volume population when the StorageClass has volumeBindingMode set to WaitForFirstConsumer.

    Default: true

• status

  object

  DataImport resource status details.
  • status.accessTimestamp

    string

    Last access timestamp updated by the importer pod.
  • status.ca

    string

    Base64-encoded CA certificate for establishing a TLS connection to the importer pod.
  • status.completionTimestamp

    string

    Time the DataImport reached a terminal phase (Completed, Expired or Failed). Set once by the controller; the garbage collector measures retention age from this timestamp.
  • status.conditions

    array of objects
    • status.conditions.lastTransitionTime

      string

      Last time the condition transitioned from one status to another.

      This should be when the underlying condition changed. If the last transition time is not known, then using the time when the API field changed is acceptable.

    • status.conditions.message

      string

      Human-readable message indicating details about the transition.

      This may be an empty string.

      Maximum length: 32768

    • status.conditions.observedGeneration

      integer

      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.

      Allowed values: 0 <= X

    • status.conditions.reason

      string

      Current condition status reason.

      Allowed values: Pending, PVCCreated, ServerReady, InProgress, Expired, Deleted, UploadFinished, Completed, Failed, TargetFailed, CleanupFailed

    • status.conditions.status

      string

      Condition status.

      Allowed values: True, False, Unknown

    • status.conditions.type

      string

      Condition type.

      Allowed values: Ready, UploadFinished, Completed

  • status.data

    object

    Captured-data block for this import. Carries the durable cluster-scoped data artifact under data.artifactRef (a VolumeSnapshotContent). Populated once the backing VolumeCaptureRequest completes.
    • status.data.artifactRef

      object

      Reference to the durable cluster-scoped data artifact produced by this import (a VolumeSnapshotContent).
      • status.data.artifactRef.apiVersion

        string
      • status.data.artifactRef.kind

        string
      • status.data.artifactRef.name

        string
      • status.data.artifactRef.uid

        string

        UID of the durable data artifact (for example the VolumeSnapshotContent UID), making the reference self-contained. Optional; producers fill it best-effort.
    • status.data.fsType

      string

      Filesystem the imported bytes were actually written onto, observed on the scratch volume’s PersistentVolume (spec.csi.fsType) before that volume was destroyed. The scratch volume is deleted right after capture and the artifact itself records no filesystem type, so this is the only surviving record of it.

      Empty means “not known”, never “default”: a Block import carries no filesystem at all, and a CSI driver may record no filesystem type on the volume.

  • status.phase

    string

    Coarse-grained lifecycle state, written exclusively by the controller: Pending → Ready → Completed | Expired | Failed. Terminating denotes an object with a deletion timestamp and is a transient state, not an outcome. Expired is a normal terminal outcome (the idle-TTL window elapsed), not a failure.

    Allowed values: Pending, Ready, Completed, Expired, Failed, Terminating

  • status.publicURL

    string

    Public URL of the importer service.
  • status.serverState

    string

    Raw progress signal reported by the importer server pod (the only writer): Ready when the server is serving, Finished when the client upload finished durably, IdleExpired when the idle-TTL window elapsed. The controller derives phase and conditions from it.

    Allowed values: Ready, Finished, IdleExpired

  • status.url

    string

    Internal URL of the importer service.
  • status.volumeMode

    string

    Volume mode of the exported data.

    Allowed values: Block, Filesystem

VolumeSnapshotClass

Short names: vsclass, vsclasses

Scope: Cluster

VolumeSnapshotContent

Short names: vsc, vscs

Scope: Cluster

VolumeSnapshot

Short names: vs

Scope: Namespaced