VolumeCaptureRequest и VolumeRestoreRequest

VolumeCaptureRequest (VCR) и VolumeRestoreRequest (VRR) — one-shot служебные ресурсы, предназначенные для контроллеров наподобие state-snapshotter, а не стабильный пользовательский backup UX. Фактический create/read-доступ определяется RBAC кластера; admission пока не enforce’ит controller-only policy. Оба ресурса namespaced и находятся в storage-foundation.deckhouse.io/v1alpha1; namespace запроса совпадает с namespace исходного/целевого PVC.

Эта страница резюмирует текущие generated CRD и поведение controller/sidecar. Схема истины — generated CRD. Контракт использования этих ресурсов доменными контроллерами задаёт domain snapshot SDK state-snapshotter, он же владеет core-маппингом Ready reasons.

VolumeCaptureRequest

VCR создаёт durable data artifact для одного PVC. Domain snapshot SDK использует только spec.mode: Snapshot; Detach — отдельный flow storage-foundation.

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"

Контракт:

• spec.target — identity одного PVC; namespace неявно равен namespace VCR. Это single-target request, а не bulk capture API.
• Request point-in-time, но enforcement неполон. Для Snapshot-mode CRD требует непустые uid, apiVersion, kind и name, однако transition-CEL с иммутабельностью spec отсутствует. SDK обнаруживает изменение существующего target только при следующем reconcile EnsureVCR. Controller storage-foundation сейчас резолвит live PVC по namespace запроса и имени target, не требует точные apiVersion: v1 и kind: PersistentVolumeClaim и не сравнивает UID live PVC с spec.target.uid; UID используется в детерминированном имени артефакта. Server-side immutability/typed drift вынесены в backlog #26, остальные UID/GVK/admission hardening — в #28. CRD требует target только для Snapshot-mode, хотя controller-path Detach тоже без него не работает.
• status.data.artifactRef указывает на durable VolumeSnapshotContent/PersistentVolume. Identity исходного PVC остаётся в spec.target и в status не дублируется.
• Ready=True/Completed — успех.
• Ready=False/TargetsPending — нетерминальное ожидание: CSI capture продолжает retry. Сам по себе VolumeSnapshotContent.status.error request не терминалит.
• Любой другой VCR Ready=False терминален.
• Capture-домены на текущем SDK-контракте state-snapshotter создают или принимают VCR через snapshotsdk.EnsureVolumeCapture, публикуют его имя и управляют собственным lifecycle через DomainCaptureStatus(...).Phase(...).Reason(...).Message(...).Apply(ctx). Обычные домены публикуют планы MCR/VCR до PhasePlanned; текущие subtree-gated агрегаторы могут публиковать собственный MCR после PhasePlanned как compatibility exception, пока ожидают сохранения манифестов потомков.
• Домены не читают conditions VCR и не пишут его status. Core state-snapshotter классифицирует терминальный VCR как Ready=False/VolumeCaptureFailed на snapshot-пути. Домен наблюдает core-owned результат через snapshotsdk.CoreCaptureOutcome и публикует PhaseFinished после завершения capture и доменного consistency-action. Childless-домен может сразу опубликовать PhaseFinished, когда core сообщает о завершении capture. Целевой протокол убирает late-own-MCR exception: собственный MCR каждого узла публикуется до PhasePlanned.
• Встроенный VolumeSnapshot domain controller следует этому контракту: отсутствующий source PVC остаётся восстанавливаемым ожиданием в PhasePlanning, опубликованный MCR фиксирует план в PhasePlanned, успешный core capture переводит leaf в PhaseFinished, а терминальные ошибки core остаются в Ready.

VolumeRestoreRequest

VRR просит patched external-provisioner создать и забайндить один PVC из VolumeSnapshotContent или 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"

Контракт:

• CRD schema требует sourceRef.name, pvcTemplate и pvcTemplate.metadata.name. Cross-namespace restore не поддерживается.
• Executor дополнительно требует непустой pvcTemplate.spec.storageClassName и точный pvcTemplate.spec.volumeMode со значением Block или Filesystem. В текущей schema эти поля optional. Schema-accepted request без любого из них executor игнорирует с Event, а controller продолжает ждать PVC без записи Ready и completionTimestamp. Такой VRR нетерминален и потому бессмертен для generic GC. Этот malformed empty-status gap требует исправления кода; документация не объявляет его допустимым execution-контрактом.
• Такое же empty-status ожидание возможно при невалидных accessModes, отсутствующем StorageClass или StorageClass другого provisioner. Часть путей публикует Event, часть игнорируется молча; ни один из них сейчас не передаёт VRR controller терминальный результат.
• pvcTemplate материализуется лишь частично, и source kinds ведут себя по-разному. Executor валидирует template storage class и volume mode для каждого request. Для источника VolumeSnapshotContent он использует template storage class, volume mode и access modes (default ReadWriteOnce), а также root fsType для Filesystem-томов. Для источника PersistentVolume авторитетен source PV: volume mode, access modes, filesystem type и capacity берутся из него, а соответствующие template-поля не определяют фактическую форму restore. Ни один путь не копирует template labels/annotations и не считает pvcTemplate.spec.resources.requests.storage авторитетным.
• Поддерживаемые source kinds — VolumeSnapshotContent и PersistentVolume. Текущие controller и executor выбирают источник по kind и name; sourceRef.apiVersion, namespace и uid не проверяются относительно live source. Hardening source identity и admission отслеживается в backlog #28.
• Patched external-provisioner watch’ит VRR, вызывает CSI CreateVolume и создаёт PV/PVC, но не пишет VRR status.
• VolumeRestoreRequestController — единственный status writer: валидирует source, наблюдает PVC и публикует pvcRef, completionTimestamp, Ready.
• Текущий writer pvcRef публикует kind, namespace, name и uid, но оставляет optional apiVersion пустым; пример намеренно совпадает с writer. Пока writer не начнёт публиковать это поле, consumers не должны считать его обязательным.
• Терминальный VRR одноразовый; для новой попытки создаётся новый request.

Текущие conditions и reasons

SnapshotCreationFailed оставлен только для совместимости и больше не выставляется: на VCR-пути VolumeSnapshotContent.status.error остаётся TargetsPending. Общие константы Incompatible, UnsupportedTargetKind, PVBound и RestoreFailed сейчас не используются ни одним из двух request controllers. Ошибка status.error у VSC-источника VRR — другой путь: он терминалится как Ready=False/InternalError.

Retention и удаление

Терминальные VCR/VRR удаляет cron-driven generic GC по status.completionTimestamp.

Per-object TTL-аннотаций и module settings для этих значений нет. На успешном пути state-snapshotter может удалить VCR раньше, после durable handoff; generic GC чистит терминальные остатки. Request без терминального Ready и completionTimestamp, включая malformed VRR выше, collector не удаляет. Текущий VRR keeper не связан с созданным executor’ом restore target PVC, поэтому GC запроса не удаляет этот PVC.

Валидация и RBAC

Валидация выполняется CRD schema/CEL и контроллерами; admission webhook с SelfSubjectAccessReview для VCR/VRR отсутствует.

Из-за user-facing grants эти ресурсы фактически не controller-only, несмотря на предназначение служебного API. Хук 040-vrr-provisioner-rbac сейчас bind’ит executor-grant только ServiceAccount csi в d8-sds-local-volume. Generic cross-driver VRR требует расширения общего CSI deployment/RBAC-контракта.

DataExport

Короткие имена: de

Область: Namespaced
Версия: v1alpha1

• spec

  объект
  • spec.publicIngress

    строка

    Тип публичного доступа к экспортеру.

    Допустимые значения: KubernetesAPI, ConsoleFrontend

  • spec.publish

    булевый

    Включение внешнего доступа к экспортер-поду за пределами кластера.
  • spec.targetRef

    объект

    Обязательный параметр

    GroupKind-ссылка на целевой ресурс для экспорта (namespace неявный — тот же, что у DataExport).
    • spec.targetRef.group

      строка

      API-группа целевого ресурса ("" или отсутствует для core-группы, например для PersistentVolumeClaim).
    • spec.targetRef.kind

      строка

      Обязательный параметр

      Kind целевого объекта (например, PersistentVolumeClaim, VirtualDisk, VolumeSnapshot, VirtualDiskSnapshot).

      Минимальная длина: 1

    • spec.targetRef.name

      строка

      Обязательный параметр

      Имя целевого ресурса для экспорта.

      Минимальная длина: 1

  • spec.ttl

    строка

    Обязательный параметр

    Время жизни после последнего запроса пользователя.

    Шаблон: ^([0-9]+(\.[0-9]+)?h)?([0-9]+(\.[0-9]+)?m)?([0-9]+s)?$

• status

  объект

  Информация о статусе ресурса DataExport.
  • status.accessTimestamp

    строка

    Временная метка последнего доступа к экспортированным данным.
  • status.ca

    строка

    CA-сертификат в кодировке Base64 для TLS-подключения к экспортер-поду.
  • status.completionTimestamp

    строка

    Время перехода DataExport в терминальную фазу (Expired или Failed). Проставляется контроллером один раз; сборщик мусора отсчитывает время хранения от этой метки.
  • status.conditions

    массив объектов

    Массив условий, описывающих текущее состояние ресурса DataExport.
    • status.conditions.lastTransitionTime

      строка

      Время последнего перехода условия из одного статуса в другой.
    • status.conditions.message

      строка

      Сообщение, описывающее условие.
    • status.conditions.observedGeneration

      целое число

      Наблюдаемое поколение ресурса при последнем обновлении условия.
    • status.conditions.reason

      строка

      Причина текущего статуса условия.

      Допустимые значения: Pending, ServerReady, ValidationFailed, TargetNotReady, TargetNotFound, PVConflict, DeploymentFailed, CleanupFailed, PublishFailed, Expired

    • status.conditions.status

      строка

      Статус условия.

      Допустимые значения: True, False, Unknown

    • status.conditions.type

      строка

      Тип условия.

      Допустимые значения: Ready

  • status.phase

    строка

    Укрупнённое состояние жизненного цикла, которое пишет только контроллер: Pending → Ready → Expired | Failed (у DataExport нет фазы Completed). Значение Terminating означает объект с установленной меткой удаления и является переходным состоянием, а не исходом. Expired — штатный терминальный исход (истекло окно неактивности), а не сбой.

    Допустимые значения: Pending, Ready, Expired, Failed, Terminating

  • status.publicURL

    строка

    Публичный URL для внешнего доступа (например, https://api.<public-domain>/<namespace>/<вид-таргета>/<имя-таргета>/). Здесь <вид-таргета> — краткий вид таргета экспорта: pvc, vd или snap (любой таргет на основе снимка), а <имя-таргета> — значение spec.targetRef.name.
  • status.serverState

    строка

    Необработанный сигнал прогресса от экспортер-пода (единственного писателя): Ready — сервер обслуживает запросы, IdleExpired — истекло окно неактивности. Контроллер выводит из него фазу и условия.

    Допустимые значения: Ready, IdleExpired

  • status.url

    строка

    Внутренний URL экспортер-пода (например, https://X.X.X.X:8085).
  • status.volumeMode

    строка

    Режим тома экспортированных данных.

    Допустимые значения: Block, Filesystem

DataImport

Короткие имена: di

Область: Namespaced
Версия: v1alpha1

• spec

  объект
  • spec.mode

    строка

    Дискриминатор, определяющий, что импорт делает с данными:

    • CreatePVC: запись в сохраняемый, создаваемый PVC (pvcTemplate). Долговечный артефакт не создаётся.
    • PopulateData: данные заливаются во временный (scratch) том (storageParams) и захватываются в долговечный VolumeSnapshotContent для уже существующего узла-снимка, указанного в snapshotRef.

    По умолчанию: CreatePVC

    Допустимые значения: CreatePVC, PopulateData

  • spec.publish

    булевый

    Включение внешнего доступа к импортер-поду за пределами кластера.

    По умолчанию: false

  • spec.pvcTemplate

    объект

    Только для режима CreatePVC. Шаблон PersistentVolumeClaim, полностью описывающий целевой PVC, в который записываются импортируемые данные; PVC сохраняется после импорта.
    • spec.pvcTemplate.metadata

      объект

      Метаданные PersistentVolumeClaim.
      • spec.pvcTemplate.metadata.annotations

        объект

        Аннотации PersistentVolumeClaim.
      • spec.pvcTemplate.metadata.labels

        объект

        Метки PersistentVolumeClaim.
      • spec.pvcTemplate.metadata.name

        строка

        Имя PersistentVolumeClaim.
    • spec.pvcTemplate.spec

      объект

      Спецификация PersistentVolumeClaim.
      • spec.pvcTemplate.spec.accessModes

        массив строк

        Желаемые режимы доступа к тому.
        • spec.pvcTemplate.spec.accessModes.Элемент массива

          строка

          Допустимые значения: ReadWriteOnce, ReadOnlyMany, ReadWriteMany, ReadWriteOncePod

      • spec.pvcTemplate.spec.resources

        объект

        Минимальные требования к ресурсам тома.
        • spec.pvcTemplate.spec.resources.requests

          объект

          Минимальный объём требуемых вычислительных ресурсов.
      • spec.pvcTemplate.spec.storageClassName

        строка

        Имя StorageClass, требуемого для PersistentVolumeClaim.
      • spec.pvcTemplate.spec.volumeMode

        строка

        Режим тома, требуемый для PersistentVolumeClaim.

        Допустимые значения: Block, Filesystem

  • spec.snapshotRef

    объект

    Только для режима PopulateData. Ссылка на уже существующий узел xxxSnapshot, которому принадлежит создаваемый долговечный артефакт (пространство имён неявно совпадает с пространством имён DataImport). Проставляется внешним создателем (d8/пользователь/система резервного копирования); контроллер DataImport её не читает — она нужна, чтобы обратный поиск state-snapshotter сопоставил лист по spec.snapshotRef.
    • spec.snapshotRef.apiVersion

      строка

      Группа/версия узла-снимка (например, snapshot.storage.k8s.io/v1).
    • spec.snapshotRef.kind

      строка

      Обязательный параметр

      Вид узла-снимка (например, VolumeSnapshot, VirtualDiskSnapshot).

      Минимальная длина: 1

    • spec.snapshotRef.name

      строка

      Обязательный параметр

      Имя узла-снимка.

      Минимальная длина: 1

  • spec.storageParams

    объект

    Только для режима PopulateData. Параметры временного (scratch) тома, в который заливаются импортируемые данные до захвата; уничтожается после создания долговечного VolumeSnapshotContent. Его StorageClass должен поддерживать снимки (ссылается на VolumeSnapshotClass через аннотацию storage.deckhouse.io/volumesnapshotclass).
    • spec.storageParams.size

      строка

      Обязательный параметр

      Запрашиваемый размер временного (scratch) PVC (величина Kubernetes, например 10Gi).

      Минимальная длина: 1

    • spec.storageParams.storageClassName

      строка

      Обязательный параметр

      StorageClass временного (scratch) PVC (должен поддерживать снимки).

      Минимальная длина: 1

    • spec.storageParams.volumeMode

      строка

      Режим тома временного (scratch) PVC. По умолчанию Filesystem.

      Допустимые значения: Block, Filesystem

  • spec.ttl

    строка

    Обязательный параметр

    Время жизни после последнего запроса пользователя.

    Допустимые значения:

    • <number>s;
    • <number>m;
    • <number>h.

    Например, 5m, 2h45m, или 1d.

    Шаблон: ^([0-9]+(\.[0-9]+)?h)?([0-9]+(\.[0-9]+)?m)?([0-9]+s)?$

  • spec.waitForFirstConsumer

    булевый

    Если параметр установлен в false, создаётся load-под для запуска процесса заполнения тома, когда в StorageClass для параметра volumeBindingMode задано значение WaitForFirstConsumer.

    По умолчанию: true

• status

  объект

  Информация о статусе ресурса DataImport.
  • status.accessTimestamp

    строка

    Временная метка последнего доступа, обновляемая импортер-подом.
  • status.ca

    строка

    CA-сертификат в кодировке Base64 для TLS-соединения с импортер-подом.
  • status.completionTimestamp

    строка

    Время перехода DataImport в терминальную фазу (Completed, Expired или Failed). Проставляется контроллером один раз; сборщик мусора отсчитывает время хранения от этой метки.
  • status.conditions

    массив объектов
    • status.conditions.lastTransitionTime

      строка

      Время последнего перехода условия из одного статуса в другой.

      Обычно соответствует моменту изменения базового условия. Если время последнего перехода неизвестно, допускается использование времени изменения поля API.

    • status.conditions.message

      строка

      Человекочитаемое сообщение с подробностями о переходе статуса.

      Может быть пустой строкой.

      Максимальная длина: 32768

    • status.conditions.observedGeneration

      целое число

      Значение .metadata.generation, на основе которого было установлено условие.

      Например, если текущее значение .metadata.generation равно 12, а .status.conditions[x].observedGeneration равно 9, то статус условия не соответствует текущему состоянию ресурса.

      Допустимые значения: 0 <= X

    • status.conditions.reason

      строка

      Причина текущего статуса условия.

      Допустимые значения: Pending, PVCCreated, ServerReady, InProgress, Expired, Deleted, UploadFinished, Completed, Failed, TargetFailed, CleanupFailed

    • status.conditions.status

      строка

      Статус условия.

      Допустимые значения: True, False, Unknown

    • status.conditions.type

      строка

      Тип условия.

      Допустимые значения: Ready, UploadFinished, Completed

  • status.data

    объект

    Блок захваченных данных импорта. Содержит долговечный кластерный артефакт данных под data.artifactRef (VolumeSnapshotContent). Заполняется после завершения соответствующего VolumeCaptureRequest.
    • status.data.artifactRef

      объект

      Ссылка на долговечный кластерный артефакт данных (VolumeSnapshotContent), созданный этим импортом.
      • status.data.artifactRef.apiVersion

        строка

        Версия API артефакта данных.
      • status.data.artifactRef.kind

        строка

        Тип артефакта данных.
      • status.data.artifactRef.name

        строка

        Имя артефакта данных.
      • status.data.artifactRef.uid

        строка

        UID артефакта данных (например, UID VolumeSnapshotContent). Необязательное; заполняется по возможности.
    • status.data.fsType

      строка

      Файловая система, на которую фактически были записаны импортированные данные. Считывается с PersistentVolume временного (scratch) тома (spec.csi.fsType) до его уничтожения: том удаляется сразу после захвата, а сам артефакт тип файловой системы не хранит, поэтому это единственная сохраняющаяся запись о нём.

      Пустое значение означает «неизвестно», а не значение по умолчанию: при импорте в блочный том (Block) файловой системы нет вовсе, а CSI-драйвер может не записать её тип на томе.

  • status.phase

    строка

    Укрупнённое состояние жизненного цикла, которое пишет только контроллер: Pending → Ready → Completed | Expired | Failed. Значение Terminating означает объект с установленной меткой удаления и является переходным состоянием, а не исходом. Expired — штатный терминальный исход (истекло окно неактивности), а не сбой.

    Допустимые значения: Pending, Ready, Completed, Expired, Failed, Terminating

  • status.publicURL

    строка

    Публичный URL-адрес сервиса импортера.
  • status.serverState

    строка

    Необработанный сигнал прогресса от импортер-пода (единственного писателя): Ready — сервер обслуживает запросы, Finished — заливка клиента завершена долговечно, IdleExpired — истекло окно неактивности. Контроллер выводит из него фазу и условия.

    Допустимые значения: Ready, Finished, IdleExpired

  • status.url

    строка

    Внутренний URL-адрес сервиса импортера.
  • status.volumeMode

    строка

    Режим тома импортированных данных.

    Допустимые значения: Block, Filesystem

VolumeSnapshotClass

Короткие имена: vsclass, vsclasses

Область: Cluster

VolumeSnapshotContent

Короткие имена: vsc, vscs

Область: Cluster

VolumeSnapshot

Короткие имена: vs

Область: Namespaced