From c8fbe5a473d7de5db8bc462b6246fbebd345d958 Mon Sep 17 00:00:00 2001 From: Rohit Yadav Date: Thu, 29 Aug 2024 15:52:06 +0530 Subject: [PATCH 1/4] NAS B&R docs Signed-off-by: Rohit Yadav --- source/adminguide/backup_and_recovery.rst | 6 +- source/adminguide/nas_plugin.rst | 80 +++++++++++++++++++++++ 2 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 source/adminguide/nas_plugin.rst diff --git a/source/adminguide/backup_and_recovery.rst b/source/adminguide/backup_and_recovery.rst index 2fc82d19da..2df0a1f653 100644 --- a/source/adminguide/backup_and_recovery.rst +++ b/source/adminguide/backup_and_recovery.rst @@ -28,6 +28,7 @@ The following providers are currently supported: - VMware with Veeam Backup and Recovery - KVM with DELL EMC Networker +- KVM with NAS B&R Plugin (4.20 onwards) See the Veeam Backup and Recovery plugin documentation for plugin specific information. :ref:`Veeam Backup and Recovery Plugin` @@ -35,6 +36,9 @@ See the Veeam Backup and Recovery plugin documentation for plugin specific infor See the DELL EMC Networker Backup and Recovery plugin documentation for plugin specific information. :ref:`DELL EMC Networker Backup and Recovery Plugin` +See the Veeam Backup and Recovery plugin documentation for plugin specific information. +:ref:`NAS Backup and Recovery Plugin` + Backup and Recovery Concepts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -73,7 +77,7 @@ the Global Settings area of the CloudStack UI. Configuration Description ================================= ======================== backup.framework.enabled Setting to enable or disable the feature. Default: false. -backup.framework.provider.plugin The backup provider (plugin) name. For example: 'dummy', 'veeam' and 'networker'. This is a zone specific setting. Default: dummy. +backup.framework.provider.plugin The backup provider (plugin) name. For example: 'dummy', 'veeam', 'networker' and 'nas'. This is a zone specific setting. Default: dummy. backup.framework.sync.interval Background sync task internal in seconds that performs metrics/usage stats collection, backup reconciliation and backup scheduling. Default: 300. ================================= ======================== diff --git a/source/adminguide/nas_plugin.rst b/source/adminguide/nas_plugin.rst new file mode 100644 index 0000000000..499a2087b0 --- /dev/null +++ b/source/adminguide/nas_plugin.rst @@ -0,0 +1,80 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information# + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _NAS Backup and Recovery Plugin: + +NAS Backup and Recovery Plugin +============================== + +About the NAS Backup and Recovery Plugin +---------------------------------------- + +The NAS Backup and Recovery Plugin provider simple B&R operations for KVM +instances to any shared storage (NAS). It is based on `libvirt push backup mode +`_ +to take full instance backups (qcow2) and requires libvirt-7.2.0 and QEMU-4.2, +or high versions on the KVM hosts. + +The NAS B&R plugin requires admin to first add backup repositories which are +network-attached storage (shared storage) such as NFS, CephFS and CIFS/Samba. +This plugin currently supports NFS, CephFS and CIFS (Samba) based NAS storage +pools. 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 them temporarily on the KVM host to peform 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 +etc. + +Consider the following mount, typically performed on a KVM/Linux host to mount storage: + + mount -t -o
+ +For example, for CephFS, this can be: + + mount -t ceph 10.10.1.10,10.10.1.11,10.10.1.12:/ /target -o name=user,secret=xyz,defaults + +The backup repository is designed to accept these parameters (type, address and +mount options) as configurations to be used to execute mount operations such as +illustrated above. + +With 'nas' B&R plugin enabled, after a backup repositories are added, root +admins can create new backup offerings by selecting the zone and the backup +repository. These backup offerings are then assigned and used with KVM instances +to perform support B&R actions and operations. + +Support Information and Limitation +---------------------------------- + +The NAS B&R plugin has been tested with EL8, EL9, Ubuntu 22.04 and 24.04. Older +KVM distros such as EL7 etc may not work due to libvirt/qemu version +requirements. Other supported KVM-distros are not tested but may work such as +Ubuntu 20.04, OpenSUSE 15, Debian 11 and Debian 12. + +Instance backups are full disk backups and limited by libvirt's ability to +initiate and handle backup. All such backups are exported and stored in qcow2 +format. Due to this, restore operation are supported for volumes of type qcow2 +and limited to NFS and local storage based primary storage pools. + +For running instances, their disks (of any format/storage type) are backed up by +libvirtd's push based efficient-backup mechanism exported as qcow2 disks on the +backup repository. + +For stopped instances, `qemu-img` is used to convert and export full-disk backup +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. +not using any backing template file). From f7916a9944d9fd4b68ce1a442d58655ac0b66adf Mon Sep 17 00:00:00 2001 From: Rohit Yadav Date: Thu, 29 Aug 2024 15:56:05 +0530 Subject: [PATCH 2/4] Update source/adminguide/backup_and_recovery.rst --- source/adminguide/backup_and_recovery.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/adminguide/backup_and_recovery.rst b/source/adminguide/backup_and_recovery.rst index 2df0a1f653..bf657b89d8 100644 --- a/source/adminguide/backup_and_recovery.rst +++ b/source/adminguide/backup_and_recovery.rst @@ -36,7 +36,7 @@ See the Veeam Backup and Recovery plugin documentation for plugin specific infor See the DELL EMC Networker Backup and Recovery plugin documentation for plugin specific information. :ref:`DELL EMC Networker Backup and Recovery Plugin` -See the Veeam Backup and Recovery plugin documentation for plugin specific information. +See the NAS Backup and Recovery plugin documentation for plugin specific information. :ref:`NAS Backup and Recovery Plugin` From ec3f14edadedd2e61c52e6182b4b60e9045eacd0 Mon Sep 17 00:00:00 2001 From: Rohit Yadav Date: Thu, 5 Sep 2024 18:42:14 +0530 Subject: [PATCH 3/4] Update nas_plugin.rst --- source/adminguide/nas_plugin.rst | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/source/adminguide/nas_plugin.rst b/source/adminguide/nas_plugin.rst index 499a2087b0..4b66f3a906 100644 --- a/source/adminguide/nas_plugin.rst +++ b/source/adminguide/nas_plugin.rst @@ -28,21 +28,22 @@ to take full instance backups (qcow2) and requires libvirt-7.2.0 and QEMU-4.2, or high versions on the KVM hosts. The NAS B&R plugin requires admin to first add backup repositories which are -network-attached storage (shared storage) such as NFS, CephFS and CIFS/Samba. -This plugin currently supports NFS, CephFS and CIFS (Samba) based NAS storage -pools. 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 them temporarily on the KVM host to peform 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 -etc. +network-attached storage (shared storage). Currently it supports NFS, and may +support other shared storage such as CephFS and CIFS/Samba in future. + +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 peform 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). Consider the following mount, typically performed on a KVM/Linux host to mount storage: mount -t -o
-For example, for CephFS, this can be: +Some examples for variety of shared storage can be: + mount -t nfs 10.10.1.10:/export /target -o vers=4.2,defaults mount -t ceph 10.10.1.10,10.10.1.11,10.10.1.12:/ /target -o name=user,secret=xyz,defaults The backup repository is designed to accept these parameters (type, address and @@ -58,9 +59,9 @@ Support Information and Limitation ---------------------------------- The NAS B&R plugin has been tested with EL8, EL9, Ubuntu 22.04 and 24.04. Older -KVM distros such as EL7 etc may not work due to libvirt/qemu version -requirements. Other supported KVM-distros are not tested but may work such as -Ubuntu 20.04, OpenSUSE 15, Debian 11 and Debian 12. +KVM distros such as EL7, Ubuntu 20.04 etc may not work due to libvirt/qemu +version requirements. Other supported KVM-distros are not tested but may work +such as OpenSUSE 15, Debian 11 and Debian 12. Instance backups are full disk backups and limited by libvirt's ability to initiate and handle backup. All such backups are exported and stored in qcow2 @@ -78,3 +79,7 @@ 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. 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 +be avoided. From 79cde86ea736daafeff729f5f12e938cc352cf35 Mon Sep 17 00:00:00 2001 From: Rohit Yadav Date: Thu, 5 Sep 2024 18:46:28 +0530 Subject: [PATCH 4/4] Update nas_plugin.rst --- source/adminguide/nas_plugin.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/adminguide/nas_plugin.rst b/source/adminguide/nas_plugin.rst index 4b66f3a906..9c17802e15 100644 --- a/source/adminguide/nas_plugin.rst +++ b/source/adminguide/nas_plugin.rst @@ -44,6 +44,7 @@ Consider the following mount, typically performed on a KVM/Linux host to mount s Some examples for variety of shared storage can be: mount -t nfs 10.10.1.10:/export /target -o vers=4.2,defaults + mount -t ceph 10.10.1.10,10.10.1.11,10.10.1.12:/ /target -o name=user,secret=xyz,defaults The backup repository is designed to accept these parameters (type, address and