Operators: INSTALL.md. This file is the product map (what shipped, what is later).
Sidecar BackupProvider alletramp for ACS 4.22.1.1. Volume create/attach stays in cloudstack-primera_alletraMP-iscsi. Do not fold this JAR into that one.
| Stage | Status | What |
|---|---|---|
| A | Shipped | ACS BackupProvider: Alletra Virtual Copy CG snapshots replace NAS in the zone (take / list / delete / schedule / in-place restore) |
| A+ | Shipped | Clone restore into ACS (restoreBackedUpVolume / create-instance-from-backup) |
| C | Not started | Veeam off-array copy: CG snap → export snap VVs to a Veeam proxy → repository → delete copy-snaps |
Not in this plan: forking ACS 4.23 UHAPI/Veeam-KVM to swap the NBD data path (qcow2-only, not iSCSI/Alletra). Stock ACS provider=veeam on 4.22 is VMware-only.
- v1 in-place restore is promote/revert onto the same VVs. Clone paths are A+, not a different array API.
- One synthetic offering (“Alletra Virtual Copy”, external id
alletra-virtual-copy). The array is implied by the VM’s Primera/AlletraMP disks. - This repo owns two ACS-core overlays (
jar uf, rolling MS restart, never a Python zip rewrite of the fat JAR):BackupManager.validateBackupProviderConfig— addalletrampor the zone setting will not save.BackupManagerImplVOLUME_INFO_GSON— FiberChannel=inbacked_volumes.
- Crash-consistent CG is the bar. qemu-ga quiesce is out (ACS hardcodes it to
"nas"). - Stage C uses A’s VV-set client. Do not re-implement snap/reconcile for Veeam. C is extra: export-to-proxy, copy, unexport, delete copy-snaps.
- C is not stock Veeam HPE “Backup from Storage Snapshots.” That feature is VMware + VMFS + CBT. CloudStack Alletra is one RAW VV per disk. C is custom glue plus Veeam as the repository.
- A is a backup method on the same array, not off-site backup. Array snapshot lock / retention is not a disaster copy. C (or any separate cold/immutable tier) is what survives the array.
NAS dumps /dev/mapper/3<wwn> to NFS. That was a separate tier (TrueNAS) but a bad method for raw Alletra LUNs (full allocated dump). A is the honest ACS replacement: array CG snap, UI unchanged, seconds not hours.
A is a solid operational recovery method. The generations stay on the same array as the VM disks (same controllers, same snap CPG, same site). Array HA is not a second copy. Snapshot lock on the array only protects snaps while that array is still there; if the array is gone, locked snaps are gone with it.
| Need | Stage A (this plugin) | Traditional / Stage C |
|---|---|---|
| Bad guest write, bad patch, restore yesterday | Yes — promote/clone on the array | Unneeded if A is healthy |
| Ransomware that wipes the VM, not the array | Yes, stronger if snaps are locked | Extra |
| Array or site disaster | No | Yes — cold/immutable other storage |
| Snap CPG full | Can hurt live writes | Off-array repo does not share that CPG |
C is the off-array complement (separate repository, retention, immutability that is not bound to this array). Together:
ACS createBackup / schedule Veeam backup job (later)
│ │
▼ ▼
AlletraBackupProvider same AlletraVolumeSetClient
│ │
├─ CG snap (generation) ─────────────┤
│ │
├─ keep snaps on array ├─ export snap VVs to proxy host
│ (A restore = promote) ├─ proxy reads raw LUNs → Veeam repo
│ └─ unexport + delete array copy-snaps
▼
live I/O unchanged: QEMU → /dev/mapper/3<wwn> → per-host VLUN
ACS still allows one BackupProvider per zone. A occupies that slot (alletramp). C is Veeam-driven and does not need to be a second BackupProvider.
ACS UI / API (offering, createBackup, listBackups, restore, schedule)
│
▼
AlletraBackupProvider (sidecar JAR on management nodes)
│ WSAPI v1 — take / delete / in-place restore / clone restore
▼
Alletra MP / Primera / Alletra 9000
VV — one ACS volume (unchanged create/attach)
VV-set — one per VM on the offering; NEVER exported
Virtual Copy (snaps) — one generation = one CG snapshot of the set
- One VV-set per VM on the offering. Members = Ready ROOT + DATADISK VVs. Not ISOs.
- Create VVs as today (
POST /volumesvia the storage plugin). Then add them to the set. - Do not export the VV-set. Export stays per-VV, per-host so live migrate works. Set membership is metadata. HPE will auto-export members if the set is exported.
- The backup plugin owns the set. Do not teach
PrimeraAdapter.create()to put every new VV in a VM set. - At
takeBackup, ACS disk list is source of truth → reconcile set → snap. Stale or extra members is a bug. - Mixed pools (NFS/Ceph + Alletra) or different WSAPI URLs → fail the take.
- Names ~31 characters. Persist
{vvset, snaps[]}on the backup row (externalId). Set-snapshot APIs name members with a-@count@pattern; a literal name returns WSAPI 137.
WSAPI:
POST /volumesets/<vvset>
{ "action": "createSnapshot", "parameters": { "name": "…" } }Credentials from storage_pool_details (same as the storage plugin). VV name from volume details external_name, WWN fallback GET /volumes?query="wwn EQ …". Do not reuse the KVM host-set for backup metadata.
Sequential per-VV createSnapshot on a running multi-disk VM is not one point in time. VV-set CG snap is the requirement.
| Method | Behaviour |
|---|---|
getName() |
alletramp |
listBackupOfferings / isValidProviderOffering |
One synthetic offering |
assignVMToBackupOffering |
KVM only; all Ready disks on Primera/AlletraMP same array; create empty vvset |
removeVMFromBackupOffering |
Do not delete snaps unless none remain; then delete empty vvset |
willDeleteBackupsOnOfferingRemoval |
false |
takeBackup |
Reconcile → CG snap → BackupVO BackedUp. Ignore quiesceVM. |
deleteBackup |
Delete all snaps of that generation; fail if any remain |
restoreVMFromBackup |
VM Stopped; revert every snap onto parent VVs; all-or-nothing |
restoreBackupToVM / restoreBackedUpVolume |
Clone to new VVs (A+). Never promote the original VM. |
supportsInstanceFromBackup |
true |
crossZoneInstanceCreationEnabled |
false |
| Metrics | Backup size = snap CoW if WSAPI gives it, else 0. Never provisioned TiB. Protected size = sum of disk sizes. Stats = snap CPG used/limit. |
In-place restore: promote (PUT /volumes/{snap} action 4). If revert N of M fails: do not start the VM. Never leave disk 1 at T0 and disk 2 at Tnow. Revert while Running is forbidden in code.
Framework restore requires matching disk count. Add/remove a disk and that older point cannot restore in place; it must still be deletable.
Throwaway two-disk Alletra VM, linked writes on both, VM Running. WSAPI via scripts/phase0-array-proof.sh, not ACS APIs.
- Create vvset; add both VVs; do not export the set.
- Existing per-host VLUNs and
/dev/mapper/3<wwn>unchanged; guest I/O clean. - Add/remove a member while I/O runs — still running, same mapper paths.
- Sequential per-VV snap then restore — show the app can be torn.
- VV-set
createSnapshotthen revert both — crash-consistent bar. Record the name contract (-@count@). - Fake sequential partial failure — leftover snap deleted; no half backup.
- Revert disk 1, fail disk 2 — do not start the VM; compensating rollback.
- Confirm promote with VLUNs still mapped and VM Stopped.
Do not: iscsiadm logout, export the vvset, revert while Running, fill snap CPG, restart cloudstack-agent.
Go/no-go for production. If CG snap or live membership fails, stop.
| Safe | Not safe |
|---|---|
| Non-exported vvset; add/remove members | Export vvset to host or host-set |
| CG snapshot of a running throwaway | Revert while Running |
| Rolling MS restart + backup JAR + overlays | Restart KVM agents for this work |
| Throwaway Alletra VMs first | Prod VMs before Phase 0 + scheduled retention are boring |
jar uf overlays |
Python zipfile rewrite of the fat JAR |
Complements A. Does not replace A. A remains the ACS self-service on-array restore. C is the copy that survives the array: a generation is copied off into a Veeam (or other) repository on a separate cold or immutable tier, then the temporary array snaps used for the copy are deleted (A’s retained generations are a separate policy). Array-side snapshot lock is not a substitute for C.
- Not stock Veeam HPE Backup from Storage Snapshots (VMware VMFS + CBT + vCenter).
- Not a fork of ACS 4.23 UHAPI (libvirt NBD / qcow2 / not iSCSI).
- Not a second ACS
BackupProviderin the same zone. - Not Remote Copy / Peer Persistence.
Veeam job (or ACS hook that starts C after A take)
│
▼
C orchestrator (same sidecar, or small companion)
│ reuses AlletraVolumeSetClient
├─ dedicated short-lived CG snap for the copy
├─ VLUN-export of *snap* VVs — not production VVs —
│ to a dedicated array host object = Veeam proxy (iSCSI)
├─ proxy reads raw LUNs into Veeam repository
└─ unexport + delete the copy-snaps
Proxy is an array host (IQN registered, like KVM nodes). Per-VV VLUNs only. Never export the VV-set. Never iscsiadm logout of the Alletra target on the proxy if it holds multiple VLUNs.
Recommend a dedicated copy snap so A retention and C copy cannot delete each other’s snaps. First C ship is full (Primera does not give Veeam CBT for CloudStack raw VVs). Restore from Veeam writes into new VVs (A+ clone path). Do not promote A snaps from a Veeam restore. Do not overwrite production VVs from the proxy while the VM is mapped to KVM.
- NAS / libvirt
backup-begin/ qemu-img to NFS (A replaces this for Alletra VMs). - Forking ACS 4.23 UHAPI to inject Alletra snaps.
- Stock Veeam HPE+VMware BfSS as-is.
- Off-array DR via Remote Copy.
- API-wide
disableHtmlEscaping. - Instance (memory) snapshots / qemu-ga quiesce.
- Primera volume plugin rewrite; changing live
volumes.path. - Multi-provider in one zone.
- Alletra 5000/6000 (Nimble OS).
- Dropping Adaptive/
ProviderAdapterfor a full DataStoreDriver. - WSAPI v3 as a prerequisite for A (v1 is the block API this plugin uses).
Apache PRs: provider, allow-list, Gson volume-info. Until the distro package contains them, sidecar JAR + overlays, same as the storage plugin.