Document CSI Volume Snapshot requirement for OADP backup/restore

CRITICAL: The staged deployment restore approach requires CSI
Volume Snapshots to work correctly.

Why CSI snapshots are required:
- Staged restore pauses at infrastructure-only (no service pods)
- PVCs must be restored with data BEFORE pods start
- Filesystem backup (Restic/Kopia) requires pods to mount PVCs
  during restore, which breaks the staged approach
- CSI snapshots restore data at storage layer without pods

Changes:
1. docs/dev/backup-restore-storage-volumes.md
   - Add CSI Volume Snapshot as critical requirement
   - List supported vs unsupported StorageClasses
   - Provide VolumeSnapshotClass example for LVM
   - Update "What OADP Provides" to clarify CSI snapshots
   - Update backup strategy table

2. docs/dev/README.md
   - Add CSI Volume Snapshot Support section
   - Link to storage volume prerequisites
   - Clarify supported storage types

3. docs/dev/playbooks/backup-openstack-ctlplane.yaml
   - Change backup spec from filesystem to CSI snapshots:
     - Remove: defaultVolumesToRestic: true
     - Add: snapshotVolumes: true
     - Add: defaultVolumesToFsBackup: false
   - Update backup header message

Supported StorageClasses:
- LVM storage (TopoLVM/LVMS)
- Ceph RBD
- Cloud provider storage (AWS EBS, Azure Disk, GCP PD)

NOT Supported:
- Local storage (node-local directories)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: stuggi

docs/dev/README.md

@@ -42,6 +42,8 @@ oc project openstack
 
 See also: [OADP Setup Playbooks](#oadp-setup-playbooks) for automated installation using Ansible.
 
+**IMPORTANT:** OADP backup/restore requires a StorageClass that supports **CSI Volume Snapshots**. See [Storage Volume Prerequisites](#csi-volume-snapshot-support) below.
+
 ### Restore Prerequisites
 
 #### Operator Version Matching
@@ -63,6 +65,29 @@ The target cluster must have the same storage classes available as the source cl
 
 See [Storage Class Requirements](backup-restore-ctlplane.md#storage-class-requirements) for detailed procedures.
 
+#### CSI Volume Snapshot Support
+
+**CRITICAL REQUIREMENT**: Both source and target clusters must have a StorageClass that supports **CSI Volume Snapshots**.
+
+**Why this is critical:**
+- The staged deployment restore approach requires PVCs to be restored **before** service pods start
+- Filesystem backup (Restic/Kopia) requires pods to mount PVCs during restore, which breaks the staged approach
+- CSI snapshots restore data at the storage layer without needing pods
+
+**Supported StorageClasses:**
+- ✅ LVM storage (TopoLVM/LVMS)
+- ✅ Ceph RBD
+- ✅ Cloud provider storage (AWS EBS, Azure Disk, GCP PD)
+- ❌ Local storage (node-local directories) - **NOT supported**
+
+**Verification:**
+```bash
+# Check if VolumeSnapshotClass exists
+oc get volumesnapshotclass
+```
+
+See [Storage Volume Backup Prerequisites](backup-restore-storage-volumes.md#prerequisites) for detailed setup instructions including VolumeSnapshotClass creation.
+
 ## Core Backup/Restore Procedures
 
 | Document | Description |

docs/dev/backup-restore-storage-volumes.md

@@ -8,12 +8,15 @@ This guide covers backing up and restoring persistent volumes for OpenStack serv
 
 ### What OADP Provides
 
-- ✅ **Automated PVC/PV backups** using Restic for file-level backups
+- ✅ **Automated PVC/PV backups** using CSI Volume Snapshots (requires CSI-capable StorageClass)
+- ✅ **Storage-level snapshots** that restore data before pods start (critical for staged deployment)
 - ✅ **Scheduled backups** (daily, weekly, etc.)
 - ✅ **Label-based selection** for backup filtering
 - ✅ **S3-compatible object storage** integration (MinIO, AWS S3, etc.)
 - ✅ **Retention policies** and automatic cleanup
 
+**Note:** Filesystem backup (Restic/Kopia) is not compatible with the staged deployment restore approach because it requires pods to mount PVCs during restore.
+
 ### What OADP Does NOT Handle
 
 OADP complements, but does not replace, other backup methods:
@@ -26,20 +29,57 @@ OADP complements, but does not replace, other backup methods:
 
 | Component | Backup Method | Reason |
 |-----------|---------------|--------|
-| **MariaDB/Galera** | Dedicated procedure | Ensures transactional consistency |
+| **MariaDB/Galera** | Dedicated procedure + OADP (backup PVCs only) | Ensures transactional consistency via dumps; OADP backs up dump files |
 | **OVN Databases** | Dedicated procedure | Ensures database consistency |
 | **RabbitMQ** | No backup | Ephemeral, recreated on restore |
-| **Glance** | **OADP/Restic** | Image storage needs file-level backup |
-| **Cinder** | **OADP/Restic** | Volume backend storage (depends on backend) |
-| **Swift** | **OADP/Restic** | Object storage (if using PVC backend) |
-| **Manila** | **OADP/Restic** | Share storage (depends on backend) |
+| **Glance** | **OADP/CSI Snapshots** | Image storage PVCs backed up at storage layer |
+| **Cinder** | **OADP/CSI Snapshots** | Volume backend storage PVCs (depends on backend) |
+| **Swift** | **OADP/CSI Snapshots** | Object storage PVCs (if using PVC backend) |
+| **Manila** | **OADP/CSI Snapshots** | Share storage PVCs (depends on backend) |
 
 ## Prerequisites
 
+**CRITICAL REQUIREMENT: CSI Volume Snapshot Support**
+
+The backup/restore procedure with staged deployment requires a StorageClass that supports **CSI Volume Snapshots**. This is because:
+- The restore procedure uses infrastructure-only staging (no service pods running)
+- PVCs must be restored with data **before** pods start
+- Filesystem backup (Restic/Kopia) requires pods to mount PVCs during restore
+- CSI snapshots restore data at the storage layer without needing pods
+
+**Supported StorageClasses:**
+- ✅ LVM storage (TopoLVM/LVMS) - supports CSI snapshots
+- ✅ Ceph RBD - supports CSI snapshots
+- ✅ Most cloud provider storage (AWS EBS, Azure Disk, GCP PD) - support CSI snapshots
+- ❌ Local storage (node-local directories) - **does NOT support CSI snapshots**
+
+**Required Setup:**
 - OADP operator installed and configured (see [setup-oadp-minio.md](setup-oadp-minio.md))
 - MinIO or other S3-compatible storage configured as backup location
+- **VolumeSnapshotClass configured** for your storage provider (see below)
 - PVCs labeled for backup (see labeling section below)
 
+**Verify CSI Snapshot Support:**
+
+```bash
+# Check if VolumeSnapshotClass exists
+oc get volumesnapshotclass
+
+# For LVM storage (TopoLVM/LVMS), create if missing:
+cat <<EOF | oc apply -f -
+apiVersion: snapshot.storage.k8s.io/v1
+kind: VolumeSnapshotClass
+metadata:
+  name: lvms-vsc
+  labels:
+    velero.io/csi-volumesnapshot-class: "true"
+driver: topolvm.io
+deletionPolicy: Delete
+EOF
+```
+
+**Note:** If your storage does not support CSI snapshots, you cannot use the staged deployment restore approach. See [backup-restore-ctlplane.md](backup-restore-ctlplane.md) for alternative restore strategies.
+
 ## Label Convention
 
 Services that need PVC/PV backup should label their PVCs with:

docs/dev/playbooks/backup-openstack-ctlplane.yaml

@@ -512,7 +512,8 @@
           - "Step 10: Backup Storage Volumes (OADP)"
           - "========================================"
           - ""
-          - "Backing up PVCs with label openstack.org/backup=true"
+          - "Backing up PVCs with label openstack.org/backup=true using CSI Volume Snapshots"
+          - "REQUIRES: StorageClass with CSI snapshot support (LVM, Ceph RBD, cloud provider storage)"
           - "See: docs/dev/backup-restore-storage-volumes.md"
       when: not skip_pvc_backup
 
@@ -561,7 +562,8 @@
           labelSelector:
             matchLabels:
               openstack.org/backup: "true"
-          defaultVolumesToRestic: true
+          snapshotVolumes: true
+          defaultVolumesToFsBackup: false
           storageLocation: velero-1
           ttl: 720h
         EOF