cloudstack kvm import

KVM Import | CloudStack Feature Deep Dive

Among hypervisors chosen by organisations, KVM stands out as a popular open-source option. While standalone KVM setups and those coupled with virtualization management tools serve many purposes effectively, there’s a growing interest in self-service, multi-tenant IaaS cloud orchestration solutions like Apache CloudStack. This trend is driven by the enhanced features, scalability, and the overall cloud experience they offer to users. The latest release of Apache CloudStack (4.19) introduces a new feature: ‘KVM Import’. This feature enable Administrators to seamlessly import existing KVM hypervisor infrastructure and qcow2 file images into Apache CloudStack.

Feature description

‘KVM import’ provides a tool for Administrators to import KVM Virtual Machines using the UI or API from the sources listed below:

• Managed KVM Hosts
• Unmanaged KVM Hosts with libvirt
• Existing CloudStack Primary Storage QCOW2 disk images
• Unmanaged instances in existing KVM hosts (only Instances that were previously unmanaged)


When importing KVM hypervisor infrastructure from existing external KVM hosts, you need to ensure that:

• The external KVM host is running libvirtd.
• TCP libvirt connections (listen_tcp=1) are allowed on these external KVM hosts with the CloudStack Management Server.
• Virtual Machines on the external hosts have to be in a stopped state, as Instance live migration is not supported.
• Libvirtd listens on TCP port 16509, and the destination KVM hosts can communicate with this port.
• The selected Isolated Guest Network is in the ‘Implemented’ state.

Import Process Overview

External KVM Hosts

import kvm process

1. The process starts with Cloudstack checking its capacity in the destination Zone to deploy the selected Instance for import based on the selected Compute Offering.
2. Using one of the KVM hosts in the cluster, the existing list of Instances on the source KVM host is retrieved.
3. Once the selected Instance is confirmed as available in the source Host, the Instance’s disk Volumes are converted to a QCOW2 file on the remote Host, and then copied via SSH to the CloudStack Primary Storage.
4. When converting disk volumes to a QCOW2 image in the remote Host, qemu-img is used. Administrators can choose the temporary storage directory on the external host to store the QCOW2 image. The default location is /tmp.

Existing KVM Cluster in CloudStack

Considering existing KVM Clusters, CloudStack checks the available capacity in the selected destination Zone to deploy the Instance.

The Instance will be created with a fresh disk volume using the current QCOW2 image file.

Importing KVM Instances

External Host
1. In the left menu in the UI, navigate to “Tools” > “Import-Export Instances”.

cloudstack ui

2. Select the Source hypervisor type “KVM” and, in the action drop-down list, select “Import Instance from remote KVM host” inserting the host IP Address or hostname, username and password.

import kvm cloudstack

3. In “Destination”, select the “Zone”, “Pod” and “Cluster” and then, click on the “Fetch instances” button:

import instance kvm

4. A list of Instances on the external KVM host will be shown. Select the Instance you want to import and then click on “Import Instance” button:

unmanaged instances cloudstack

5. The import form will be displayed. Add Instance details as follows:
• Display name
• Host name
• Compute Offering
• Guest Network

cloudstack import instance

Clicking on ‘OK’ starts the import process using one of the KVM hosts in the CloudStack and the instance is imported.

cloudstack zone

The instance is imported in the ‘Stopped’ state, make sure to update the guest OS type to the appropriate one before starting. This process can be repeated via the UI for the remaining instances, and API / CMK can be explored for batch operations. Since the source instance is left intact you could delete it after performing sufficient verifications on the imported instance.

Importing Existing QCOW2 Image File

Importing an instance using an existing QCOW2 image on either a shared NFS primary storage or local storage is a faster operation within CloudStack as it doesn’t involve a data transfer.

1. In the left menu in the UI, navigate to “Tools” > “Import-Export Instances”.

cloudstack menu

2. Select the Source hypervisor type “KVM” and, in the action drop-down list, select “Import QCOW2 image from shared storage” or “Import QCOW2 image from Local storage” depending on where you have placed the qcow2 image file:

import hypersvisor

3. In “Destination” area, select the “Scope”, “Zone”, “Pod” and “Cluster” and then, select the “Primary Storage” for the image and fill in the QCOW2 image filename in the “Disk” field exactly as it is in the filesystem and then, click on “Import Instance” button to proceed:

destination cloudstack

4. The “Import Instance” form will be displayed. Add the Instance details and click on “OK” button:

cloudstack import instance

5. After the import process is finished, the Instance will be shown in a Stopped state.

cloudstack default view

Manage Unmanaged Instances

Similar to the “Manage / Unmanage existing Instance” feature for VMware hypervisor, this new feature has been extended to the KVM hypervisor, enabling Administrators to perform the following operations:
• List unmanaged Instances that are present in KVM but not managed by CloudStack.
• Import unmanaged Instances, populating the CloudStack database with the corresponding Instance data.

• Unmanage Instances existing in CloudStack, updating the database records as removed in CloudStack but not removing them on the KVM hypervisor.

1. To manage / unmanage Instances, in the left menu in the UI, navigate to “Tools” > “Import-Export Instances”.

cloudstack ui menu

2. Select the Source hypervisor type “KVM” and, in the action drop-down list, select “Manage / Unmanage existing instances”:

import kvm hypervisor

3. In “Destination” area, select the “Zone”, “Pod” and “Cluster”:

cloudstack zone

4. The managed / unmanaged instances will be shown as follows:

cloudstack unmanaged instance

5. In the “Unmanage Instances” list, select the unmanaged Instance you want to manage and then click on “Import Instance” button:

unmanaged acs instance

6. The “Import Instance” form will be displayed. Fill it in with the Instance details and click on “OK” button:

import instance apache cloudstack

7. Once the Instance is managed by Cloudstack, it will be shown in the Instance list.

default view cloudstack

Note: If the ‘destination’ Network’s VLAN(s) and the requested service offerings match the existing VLAN and the CPU / RAM profile of the Instance on the hypervisor level, then the Instance can be imported while it is running. If the VLANs or service offerings do not match, then the Instance to be imported must be stopped.

8. There are scenarios where we may want to unmanage an Instance, this can be done in a similar method for a managed Instance by selecting an Instance on the “Managed Instances” list and clicking on “Unmanage Instance” button:

unmanaged instance cloudstack


The KVM Import feature significantly enhances the hypervisor capabilities in Apache CloudStack, enabling organisations to integrate multi-tenant features into existing KVM infrastructure. This extension brings KVM to the same level as VMware within the CloudStack ecosystem, providing a seamless experience for managing and importing Instances. By facilitating the import of KVM Virtual Machines and QCOW2 file images, CloudStack 4.19 enable Administrators to leverage their existing infrastructure efficiently while offering robust cloud orchestration solutions. This new feature follows the growing trend of self-service multi-tenant IaaS cloud environments, reflecting the evolving needs of modern organisations for resource-rich, scalable cloud experiences.


Related Posts:

Download a step-by-step guide to migrate your existing vSphere environment to a robust IaaS cloud environment based on Apache CloudStack and the KVM Hypervisor, ensuring a smooth, low-friction migration journey.