Skip to content

Data Flow

How data moves through Retour during backup and restore.

Backup Flow

  1. User creates a Backup CR (or a BackupSchedule creates one on schedule)
  2. Operator: Ensures per-backup RBAC — a ServiceAccount, ClusterRole, and ClusterRoleBinding scoped with resourceNames to this backup's own CR status — and spawns the worker pod
  3. Worker: Creates a CSI VolumeSnapshot for each PVC
  4. Worker: Creates one carrier Job per volume. Non-secret backend parameters go inline in the job config; credentials go in a per-operation Kubernetes Secret (RCLONE_SECRET_* env vars, rendered from the typed StorageBackend CR and its referenced Secret)
  5. Carrier: rclone-copies the snapshot data to the storage backend, then writes the metadata JSON document and the cluster manifest YAMLs next to it
  6. Carrier: Emits single-line {"retourProgress":{...}} JSON on stdout; the worker tails the logs and patches the Backup CR's status live
  7. Worker: Writes the terminal phase (Completed or Failed) and exits non-zero on failure, so the pod phase is truthful

If the worker pod dies before it can report, the operator — which watches worker pods — writes the terminal status itself with condition reason OperatorFallback. That is the only time the operator touches backup status.

Backup flow

Restore Flow

  1. User creates a Restore CR naming a backup (backupName or backupJobUUID) or giving an explicit backupPath
  2. Operator: Resolves the Backup CR's status.backendPath and job UUID, renders a per-restore credentials Secret, and spawns the worker pod with a carrier metadata-fetch init container. Init container and worker share an emptyDir at /var/retour/backup-metadata
  3. Init container: Downloads the backup's metadata documents and manifests from the storage backend into the shared volume
  4. Worker: Parses the metadata (filtered by the backup's job UUID, so other backups under the same backend prefix are untouched), recreates PVCs and Kubernetes resources via a resource-kind registry
  5. Worker: Spawns carrier pods to copy volume data from the backend into the new PVCs
  6. Worker: Patches the Restore CR's status with progress and the terminal phase

Because the restore is driven entirely by the metadata stored next to the backup data, it works even when the Backup CR is gone — point spec.backupPath at the backup's directory on the backend.

Restore flow

Key Concepts

VolumeSnapshots

Retour uses CSI VolumeSnapshots for crash-consistent backups. The snapshot is created before rclone copies data, ensuring a point-in-time view of the volume.

Metadata documents

The carrier writes a backup-operation-<id>-metadata.json document (format frozen in pkg/backupmeta, versioned with schemaVersion) and an operation-cluster-metadata-<id>/ directory of manifest YAMLs next to each backup's data. These are the durable record of the backup; restores read them and nothing else.

Job config and secrets

The worker gives each carrier Job its configuration directly: non-secret backend parameters inline in the job config, credentials in a per-operation Kubernetes Secret exposed as RCLONE_SECRET_* environment variables. Both are rendered from the typed StorageBackend CR and the Secret it references.

Status updates

The carrier prints progress as one-line {"retourProgress":{...}} JSON on stdout. The worker tails those logs and patches the Backup/Restore CR status as transfers run, so kubectl get backups shows current per-PV file and byte counts without any intermediate store.