Skip to content

Volumes and scratch space

An app often has more than one PVC. The default example here is nextcloud with two: html (files) and pgdata (database). A RestoreCheck lists both in restoredVolumes. A Restore (or RestoreTest) has one source for each. sourcePVC is the key that ties them together.

RestoreCheck volumes and Restore sources matched by sourcePVC
Provider What a source restores Restored claim Namespace
kopiur The PVC in one Snapshot. One Snapshot holds one PVC. <restore>-<sourcePVC>-<hash> The Restore namespace.
volsync The PVC of one ReplicationSource. <restore>-<sourcePVC>-<hash> The Restore namespace.
velero Its sourcePVC from the one Backup that all sources name. spec.velero can narrow the restore with label selectors. The source PVC name, for example html and pgdata. bret-scratch-<hash>.
  • A Kopiur or VolSync claim name is <restore>-<sourcePVC>-<hash>. The hash of the pair keeps the names of two Restore objects apart, for example db with data-x and db-data with x. When the name is longer than 63 characters, the operator shortens it.
  • Velero restores all PVCs of the Restore namespace from the Backup. The optional selectors in spec.velero match the labels stored in the backup. labelSelector and orLabelSelectors are exclusive.
  • One restore reads all sources. The check pod mounts every restored claim at the mountPath of its sourcePVC.

The operator checks that the pieces fit. Each one ends the Restore as Failed: the Ready condition is False with that reason, a Warning Event is written, and no check pod runs. A RestoreTest retries it like any failed attempt, until retries run out:

  • SourceMissing: the sourcePVC set of the check and of the Restore differ. A volume of the check has no source, or a source has no volume.
  • SourceMismatch (Kopiur and VolSync): the backup holds another PVC than the sourcePVC of its source. For example, html points at the Snapshot of pgdata.
  • RestoredVolumeMissing (Velero): a sourcePVC of the Restore was not restored. The selector did not match it, or the backup does not contain it.
  • CheckRefMissing (Velero): a Secret or ConfigMap that the check needs is not in the Restore namespace, so the operator cannot copy it into the scratch namespace.
  • BackupUnsupported (Velero): the backup holds no volume data that a PVC restore brings back. The PVC was saved with file system backup (Velero writes that data only when it restores the pod), or the Backup has snapshotVolumes: false. The restore would give an empty volume.
  • BackupNotFound (VolSync): the mover found no snapshot at or before restoreAsOf, so the restored volume is empty.

A one-volume app has one entry on each side. It works the same way.

The operator creates a volume for each restore attempt. The Restore owns the volume (except for Velero), because Velero creates the PVC itself in the scratch namespace. A restore never writes into a live application volume.

The check pod mounts the scratch volume. It reads the restored data. It must not change the application’s own volume.

The diagram shows how a Restore picks the size of its scratch volume, and which reason it sets when it cannot.

How a Restore picks the scratch volume size

size is optional on every source (Kopiur and VolSync). The size is resolved for each source. With an unknown source size, a set size is used without the capacity check.

Two more failures are reported as reasons on the Restore. Both end it as Failed, and nothing is created:

  • SizeUnknown: the source size is unknown and size is not set. It is also set for a running Restore from an older operator version that has no status.resolvedSize.
  • InsufficientCapacity: size, or the autoExpand result, is smaller than the source size.

The source size comes from the provider:

  • Kopiur: the data size of the Snapshot.
  • Velero: the PVC request in the backup.
  • VolSync: the request of the source PVC.

autoExpand has these fields:

  • percentage: headroom on top of the source. Above 0, at most 1000.
  • min and max: optional bounds. min must not exceed max.

Example: a 20Gi source with the default gives 22Gi. For a fixed size, set size. Or use percentage: 100, min: X, max: X with X at least the source size.