This is an automated email from the ASF dual-hosted git repository.
dahn pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new 77e21b27 Create new Instance from VM backup documentation (#474)
77e21b27 is described below
commit 77e21b2702b66c55242ece1d1f157704e345d0b0
Author: Abhisar Sinha <63767682+abh1...@users.noreply.github.com>
AuthorDate: Wed Aug 6 15:07:38 2025 +0530
Create new Instance from VM backup documentation (#474)
---
source/_static/images/B&R-ConfigureInstance.png | Bin 0 -> 530948 bytes
.../images/B&R-CreateInstanceFromBackup.png | Bin 0 -> 81849 bytes
source/_static/images/NASB&R-quiesceInstance.png | Bin 0 -> 27795 bytes
source/adminguide/backup_and_recovery.rst | 42 ++++++++++++++++++++
source/adminguide/nas_plugin.rst | 44 ++++++++++++++++-----
5 files changed, 76 insertions(+), 10 deletions(-)
diff --git a/source/_static/images/B&R-ConfigureInstance.png
b/source/_static/images/B&R-ConfigureInstance.png
new file mode 100644
index 00000000..8712c899
Binary files /dev/null and b/source/_static/images/B&R-ConfigureInstance.png
differ
diff --git a/source/_static/images/B&R-CreateInstanceFromBackup.png
b/source/_static/images/B&R-CreateInstanceFromBackup.png
new file mode 100644
index 00000000..18ce3856
Binary files /dev/null and
b/source/_static/images/B&R-CreateInstanceFromBackup.png differ
diff --git a/source/_static/images/NASB&R-quiesceInstance.png
b/source/_static/images/NASB&R-quiesceInstance.png
new file mode 100644
index 00000000..3ba79e9c
Binary files /dev/null and b/source/_static/images/NASB&R-quiesceInstance.png
differ
diff --git a/source/adminguide/backup_and_recovery.rst
b/source/adminguide/backup_and_recovery.rst
index ee06d8d5..1ae73d37 100644
--- a/source/adminguide/backup_and_recovery.rst
+++ b/source/adminguide/backup_and_recovery.rst
@@ -161,6 +161,41 @@ of an expunged Instance will not restore nics and recovery
any network which may
not exist. User may however restore a specific volume from an Instance backup
and attach
that volume to a specified Instance.
+Creating a new Instance from Backup
+-----------------------------------
+
+Since CloudStack 4.21, users can now remove the backup offering and expunge or
unmanage an instance
+that has existing backups, for the supported backup providers — Dummy, NAS,
and Veeam.
+Additionally, users can create a new instance from a backup using any of these
providers.
+
+Each backup now includes metadata that captures the instance’s configuration
at the time of backup including service offering,
+template, disk offerings for all data volumes, attached networks, and
instance-specific settings.
+The new instance will be created with the same configuration and data as the
original instance at the time the backup was taken.
+
+.. warning::
+ Users should ensure that the entry for the expunged or unmanaged instance
is not purged from the database, as the backup framework relies on it to
function correctly.
+
+|B&R-CreateInstanceFromBackup.png|
+
+Users also have the option to customize the configuration of the new instance,
similar to deploying a new instance from scratch.
+The deployment form will be pre-filled with the values captured in the backup,
but users can modify them as needed.
+However, the number of volumes in the new instance must match the number of
volumes in the backup.
+If volume sizes are customized, users must ensure that each volume is at least
as large as the corresponding volume in the backup.
+Advanced settings are not pre-filled in the form by default, but if left
unset, they will automatically be retrieved from the backup metadata.
+The Template and ISO can only be updated via the UI if the UUID stored in the
backup is no longer available in the environment.
+
+If the original instance from which the backup was created has been expunged,
users will be presented with an option to reuse thesame IP address and
+MAC address stored in the backup metadata. The new instance will be assigned
the same IP and MAC address, provided they are still available in the network.
+
+|B&R-ConfigureInstance.png|
+
+If one or few of the resources stored in the backup such as template, networks
etc are no longer available
+in the system, the user will be prompted to reconfigure the Instance before
creating it from backup.
+
+.. note::
+ If the backup was created in a release prior to 4.21, the backup metadata
won't contain the instance configuration details,
+ so users would have to fill in the required details by clicking on the
Configure Instance button.
+
Supported APIs:
~~~~~~~~~~~~~~~~
@@ -176,6 +211,7 @@ Supported APIs:
- **listBackups**: lists backups.
- **restoreBackup**: restore a previous Instance backup in-place of a stopped
or destroyed Instance.
- **restoreVolumeFromBackupAndAttachToVM**: restore and attach a backed-up
volume (of an Instance backup) to a specified Instance.
+- **createInstanceFromBackup**: create a new Instance from a backup.
Configuring resource limits on Backups
@@ -211,3 +247,9 @@ the backup size, although the actual backup size may be
less than the size use t
.. |B&R-BackupScheduleEntry.png| image::
/_static/images/B&R-BackupScheduleEntry.png
:alt: Creating a backup schedule for an Instance.
:width: 400px
+.. |B&R-CreateInstanceFromBackup.png| image::
/_static/images/B&R-CreateInstanceFromBackup.png
+ :alt: Creating a new Instance from a backup.
+ :width: 400px
+.. |B&R-ConfigureInstance.png| image::
/_static/images/B&R-ConfigureInstance.png
+ :alt: Configure Instance parameters before creating it from backup.
+ :width: 700px
diff --git a/source/adminguide/nas_plugin.rst b/source/adminguide/nas_plugin.rst
index 454e8d2a..3304a3b5 100644
--- a/source/adminguide/nas_plugin.rst
+++ b/source/adminguide/nas_plugin.rst
@@ -31,14 +31,13 @@ Currently, only backup of VMs from the NFS-based Primary
Storage are tested to w
You can also make backups of CEPH-based VMs, but restoring is not possible yet.
The NAS B&R plugin requires admin to first add backup repositories which are
-network-attached storage (shared storage). Currently it supports NFS, and may
-support other shared storage such as CephFS and CIFS/Samba in future.
+network-attached storage (shared storage). It supports NFS, CIFS/Samba and
CephFS.
When initiating B&R operations on KVM instance, the assigned backup offering
is used to infer backup repository (NAS) details which are then used to mount
the shared storage temporarily on the KVM host to perform instance
backup/restore
disks operations. This also requires that admin installs NAS-storage specific
-utilities on the KVM hosts such as nfs-utils/nfs-common (ceph-common,
cifs-utils).
+utilities on the KVM hosts such as nfs-utils/nfs-common, ceph-common and
cifs-utils.
Consider the following mount, typically performed on a KVM/Linux host to mount
storage:
@@ -71,15 +70,15 @@ backup.framework.provider.plugin nas
================================= ========================
Once the above two configurations are set, restart the cloudstack-management
service. After restart check the Settings of the Zone where you want to enable
NAS backups - make sure that the "backup.framework.enabled"="true" on the
Setting tab of the Zone. Once this is done, we can add the backup repository
for the 'nas' Backup and Recovery plugin.
-Navigate to the Configuration -> Backup Repository. Click on 'Add Backup
Repository' and fill the form.
+Navigate to the Configuration -> Backup Repository. Click on 'Add Backup
Repository' and fill the form.
=================== ========================
Field Value
=================== ========================
Name A suitable name to represent the Backup Repository
Address URL, in case of NFS <server IP>:/path
-Type NFS ( only NFS type in 4.20)
-label.mountopts Any mount point options to be passed while mounting this
storage on the hypervisor.
+Type NFS / CIFS / CEPH
+Mount options Any mount point options to be passed while mouting this
storage on the hypervisor.
Zone The zone in CloudStack with which this Backup Repository
must be associated.
=================== ========================
@@ -89,7 +88,7 @@ Zone The zone in CloudStack with which this
Backup Repository mus
Pay attention to the "Name" given to this repository, as you will have to
specify this in the "External ID" field when creating Backup Offerings
(Importing backup offering)
-Once the Backup Repository is created, we need to add a Backup Offering, in
this plugin the Backup offering is a placeholder to associate an instance to a
Backup Repository. While creating the Backup Offering, select the desired
Backup Repository. Associate the Backup Offering on an instance to create an
Adhoc or scheduled backup.
+Once the Backup Repository is created, we need to add a Backup Offering, in
this plugin the Backup offering is a placeholder to associate an instance to a
Backup Repository. While creating the Backup Offering, select the desired
Backup Repository. Associate the Backup Offering on an instance to create an
Adhoc or scheduled backup.
For the "External ID", please specify the name of the previously created
backup repository.
@@ -99,6 +98,28 @@ For the "External ID", please specify the name of the
previously created backup
After this has been done, you can go to any Instance view and there will be
buttons available for either ad-hoc backup or a scheduled backup of the VM
+Quiesce (Filesystem Freeze and Thaw)
+------------------------------------
+
+Users can set quiesce to true while creating a backup or a backup schedule.
+When a backup is initiated with quiesce enabled, CloudStack uses QEMU guest
agent
+to freeze the filesystem before starting backup. This operation flushes all
dirty
+filesystem buffers to disk and quiesces new writes. The filesystem is then
thawed
+immediately after the backup process starts, keeping the freezing window very
short.
+
+|NASB&R-quiesceInstance.png|
+
+This enhancement brings the NAS backup plugin from crash-consistent backups
closer to
+application-consistent backups.
+
+Points to note:
+
+#. The feature requires qemu-guest-agent to be installed and running on the
guest instance.
+#. This method does not capture the memory state of the guest. Any data held
in application memory
+ that hasn’t been flushed to disk prior to the filesystem freeze will not be
captured.
+#. For fully application-consistent backups, guest applications must implement
pre-freeze hooks
+ to flush their internal state to disk before the filesystem is frozen.
+
Support Information and Limitation
----------------------------------
@@ -121,9 +142,12 @@ in qcow2 format to the backup repository.
For restore operations, the KVM instance must be stopped in CloudStack.
Currently, only volume(s) restoration is supported only to NFS and local
storage
-based primary storage pools, and restored volumes are fully baked disks (i.e.
+based primary storage pools, and restored volumes are fully backed disks (i.e.
not using any backing template file).
-Restoring fully expunged and unmanaged instances are not supported. Backup and
-restore operations are not fully supported for CKS cluster instances and should
+Backup and restore operations are not fully supported for CKS cluster
instances and should
be avoided.
+
+.. |NASB&R-quiesceInstance.png| image::
/_static/images/NASB&R-quiesceInstance.png
+ :alt: Quiesce option while creating backups.
+ :width: 400 px
