From 94f284e2c5f44271e5a1241ca33093c03c81cf7b Mon Sep 17 00:00:00 2001 From: Manoj Kumar Date: Fri, 12 Sep 2025 12:54:03 +0530 Subject: [PATCH 1/7] Documentation related to Persistent domainXML --- .../importing_unmanaging_vms.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst index b15c9db653..991c746845 100644 --- a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst +++ b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst @@ -362,6 +362,22 @@ Preserving unmanaged Instance NICs The zone setting: unmanage.vm.preserve.nics can be used to preserve Instance NICs and its MAC addresses after unmanaging them. If set to true, the Instance NICs (and their MAC addresses) are preserved when unmanaging it. Otherwise, NICs are removed and MAC addresses can be reassigned. +KVM Specific: Persistent Domain XML when unmanaging Instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since 4.22, domain XML will be made persistent when Instance is unmanaged from CloudStack. This will allow to manage the Instance outside of CloudStack using virsh or other libvirt tools. The domain XML will be stored in directory /etc/libvirt/qemu. + +Domain XML is taken from Instance but varies based on their state: + +- Running Instance + - Domain XML is contructed from the Instance and persisted on the Host where the Instance is running +- Stopped Instance + - Domain XML is constructed from the Instance details available in CloudStack database + - Domain XML will pe persisted on the last host where the Instance was running before stopping it + +.. note:: We recommend Unmanaging Instance in Running state to preserve the exact domain XML. There is potential to loose some information when unmanaging in Stopped state. + + Unmanaging Instance actions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 109a3cf9948832813bd35905851dc2f2180951b9 Mon Sep 17 00:00:00 2001 From: Manoj Kumar Date: Fri, 12 Sep 2025 14:12:24 +0530 Subject: [PATCH 2/7] address review comments --- .../virtual_machines/importing_unmanaging_vms.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst index 991c746845..2df0682c54 100644 --- a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst +++ b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst @@ -362,20 +362,21 @@ Preserving unmanaged Instance NICs The zone setting: unmanage.vm.preserve.nics can be used to preserve Instance NICs and its MAC addresses after unmanaging them. If set to true, the Instance NICs (and their MAC addresses) are preserved when unmanaging it. Otherwise, NICs are removed and MAC addresses can be reassigned. -KVM Specific: Persistent Domain XML when unmanaging Instances -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Persistent KVM Domain XML for Unmanaged Instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Since 4.22, domain XML will be made persistent when Instance is unmanaged from CloudStack. This will allow to manage the Instance outside of CloudStack using virsh or other libvirt tools. The domain XML will be stored in directory /etc/libvirt/qemu. +Since 4.22, the domain XML of an Instance is made persistent when it is unmanaged from CloudStack. This allows the Instance to be managed directly outside of CloudStack using `virsh` or other libvirt tools. The domain XML will be stored in the directory `/etc/libvirt/qemu` on the relevant KVM host. Domain XML is taken from Instance but varies based on their state: - Running Instance - - Domain XML is contructed from the Instance and persisted on the Host where the Instance is running + - The existing domain XML is retrieved from the Instance and persisted on the host where the Instance is running. - Stopped Instance - - Domain XML is constructed from the Instance details available in CloudStack database - - Domain XML will pe persisted on the last host where the Instance was running before stopping it + - The domain XML is reconstructed from the Instance details available in the CloudStack database. + - The reconstructed domain XML is persisted on the last host where the Instance was running before is was stopped. -.. note:: We recommend Unmanaging Instance in Running state to preserve the exact domain XML. There is potential to loose some information when unmanaging in Stopped state. +.. note:: + It is recommended to unmanage Instances while they are in the **Running** state to ensure that the exact domain XML is preserved. When unmanaged in the **Stopped** state, some information may be lost due to reconstruction. Unmanaging Instance actions From 22bafc86915010e068277d9ba0dab6db2eea5889 Mon Sep 17 00:00:00 2001 From: Manoj Kumar Date: Mon, 15 Sep 2025 15:42:11 +0530 Subject: [PATCH 3/7] update host selection for stopped instance --- source/adminguide/virtual_machines/importing_unmanaging_vms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst index 2df0682c54..ac1dd0824c 100644 --- a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst +++ b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst @@ -373,7 +373,7 @@ Domain XML is taken from Instance but varies based on their state: - The existing domain XML is retrieved from the Instance and persisted on the host where the Instance is running. - Stopped Instance - The domain XML is reconstructed from the Instance details available in the CloudStack database. - - The reconstructed domain XML is persisted on the last host where the Instance was running before is was stopped. + - The reconstructed domain XML is persisted on the last host where the Instance was running before it was stopped. If the host is no longer available, the domain XML is persisted on any other host available in the Zone. .. note:: It is recommended to unmanage Instances while they are in the **Running** state to ensure that the exact domain XML is preserved. When unmanaged in the **Stopped** state, some information may be lost due to reconstruction. From c6a3f6bd73fb109cd13c9ff99301fe72f99c6260 Mon Sep 17 00:00:00 2001 From: Manoj Kumar Date: Mon, 15 Sep 2025 17:54:25 +0530 Subject: [PATCH 4/7] use cluster scope for host lookup --- source/adminguide/virtual_machines/importing_unmanaging_vms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst index ac1dd0824c..d5bc3af2f8 100644 --- a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst +++ b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst @@ -373,7 +373,7 @@ Domain XML is taken from Instance but varies based on their state: - The existing domain XML is retrieved from the Instance and persisted on the host where the Instance is running. - Stopped Instance - The domain XML is reconstructed from the Instance details available in the CloudStack database. - - The reconstructed domain XML is persisted on the last host where the Instance was running before it was stopped. If the host is no longer available, the domain XML is persisted on any other host available in the Zone. + - The reconstructed domain XML is persisted on the last host where the Instance was running before it was stopped. If that host is no longer available, the domain XML is saved on any other available host within the cluster. .. note:: It is recommended to unmanage Instances while they are in the **Running** state to ensure that the exact domain XML is preserved. When unmanaged in the **Stopped** state, some information may be lost due to reconstruction. From 03efeaca7bf33ad12e213593da0a1227f799156b Mon Sep 17 00:00:00 2001 From: Manoj Kumar Date: Wed, 17 Sep 2025 16:48:49 +0530 Subject: [PATCH 5/7] add hostid param for unmanageVirtualMachine API --- .../virtual_machines/importing_unmanaging_vms.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst index d5bc3af2f8..395c240427 100644 --- a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst +++ b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst @@ -339,7 +339,19 @@ Unmanaging Instances Administrators can unmanage guest Instances from CloudStack. Once unmanaged, CloudStack can no longer monitor, control or administer the provisioning and orchestration-related operations on an Instance. -To unmanage a guest Instance, an administrator must either use the UI or invoke the unmanageVirtualMachine API passing the ID of the Instance to unmanage. The API has the following preconditions: +To unmanage a guest Instance, an administrator must either use the UI or invoke the unmanageVirtualMachine API passing the ID of the Instance to unmanage. + +.. code:: bash + + cmk unmanage virtualmachine id= + +The API supports the `hostid` parameter for stopped instances on the KVM hypervisor, allowing the domain XML to be persisted on the specified host. + +.. code:: bash + + cmk unmanage virtualmachine id= hostid= + +The API has the following preconditions: - The Instance must not be destroyed - The Instance state must be 'Running’ or ‘Stopped’ From 6403daab35eaa683c08a576b16ee0a6dbd78d7a7 Mon Sep 17 00:00:00 2001 From: Manoj Kumar Date: Thu, 25 Sep 2025 20:34:16 +0530 Subject: [PATCH 6/7] allocation nic note --- source/adminguide/virtual_machines/importing_unmanaging_vms.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst index 395c240427..6203e68a4a 100644 --- a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst +++ b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst @@ -455,6 +455,8 @@ Prerequisites - Currently, it's supported to only use NFS and Local storage as the destination Primary Storage pools in CloudStack - Currently, only libvirt-based instances can be migrated +.. note:: Allocate a NIC to any instance without one immediately after importing it into CloudStack. + listVmsForImport API ~~~~~~~~~~~~~~~~~~~~ From 58e00155caf44b121088926a5e9e297f4a0587a7 Mon Sep 17 00:00:00 2001 From: Manoj Kumar Date: Mon, 29 Sep 2025 12:27:10 +0530 Subject: [PATCH 7/7] config drive related doc --- .../virtual_machines/importing_unmanaging_vms.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst index 6203e68a4a..bc197da889 100644 --- a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst +++ b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst @@ -351,6 +351,9 @@ The API supports the `hostid` parameter for stopped instances on the KVM hypervi cmk unmanage virtualmachine id= hostid= +.. note:: + Instances with Config Drive cannot be unmanaged by default, as the Config Drive ISO will be removed during the unmanage operation. To unmanage such instances via the API, use the forced=true parameter. + The API has the following preconditions: - The Instance must not be destroyed @@ -455,7 +458,9 @@ Prerequisites - Currently, it's supported to only use NFS and Local storage as the destination Primary Storage pools in CloudStack - Currently, only libvirt-based instances can be migrated -.. note:: Allocate a NIC to any instance without one immediately after importing it into CloudStack. +.. note:: + - Allocate a NIC to any instance without one immediately after importing it into CloudStack. + - Instances imported on a Config Drive network must be stopped and started after import to properly attach the Config Drive ISO. listVmsForImport API ~~~~~~~~~~~~~~~~~~~~