Existing virtual machine images from other platforms or hypervisors may require changes to function on top of Catalyst Cloud. The changes may require specialised knowledge of the operating system the image is based on.
Note
Catalyst Cloud does not provide support for images you upload or modify to run in Catalyst Cloud. We do not guarantee any compatibility with any other platform for images.
The minimum requirements for an existing virtual machine image to be used in Catalyst Cloud is:
Intel or AMD “x86” architecture (for c1 compute instances)
Supports KVM/QEMU virtio storage and network drivers, and is
configured to use these for storage and networking
Uses DHCP on each network interface
Has cloud-init or an equivalent package installed
Linux-based operating system, Windows is not supported for import
Has the whole boot and OS components in a single disk image, not spread over multiple disk images
The following steps are suggestions on steps needed to allow a machine image to be imported and successfully used to start an instance, but may not be all steps required to support a given application or workload.
You will need to check that the virtio drivers are able to be loaded
during boot. By default, these should be available without any need to
modify the system.
However, you can check they are present with the following commands on the running machine:
grep VIRTIO_BLK /boot/config-`uname -r`
grep VIRTIO_NET /boot/config-`uname -r`
These should return lines like:
CONFIG_VIRTIO_BLK=m
CONFIG_VIRTIO_NET=m
If no lines are reported, or they have n instead of m or y.
Then the kernel has no support for virtio drivers and must be changed
to a kernel that does. Changing and selection of a new kernel is outside
the scope of this document.
If the lines end in m as above, then we need to check the modules are
included in the bootstrap environment used during boot, called initrd.
The following command will check if the virtio drivers are present
in the bootstrap environment:
lsinitramfs /boot/initrd.img-`uname -r` | grep virtio
This should output a number of references including virtio_blk and
virtio_net, the most important two entries to see.
Your machine should have /boot and the root filesystem in the same
disk image. Although it is possible to create machines with multiple disks
making up different parts of the system, this is an advanced configuration
that requires careful planning and can be very difficult to create and
launch systems in this way.
cloud-init provides tools to query the metadata exposed by Catalyst
Cloud to the server, and is required to ensure features such as
“user data scripts” are picked up and executed by the server. Recent
versions should detect the metadata source provided by Catalyst Cloud
without configuration.
However, if this does need to be configured, the OpenStack datasource
is the preferred one to use.
Installation of cloud-init depends on the distribution of Linux your
image uses:
sudo apt-get install cloud-init
sudo dnf -y install cloud-init
Compute instances receive their network configuration from our cloud metadata agent and DHCP servers. As such, we recommend you configure the network interfaces to use DHCP instead of a static IP.
Note
Using DHCP does not mean your compute instance will get a different IP every time you boot it up. On our cloud, an IP is allocated for your compute instance by our compute and network services. This IP will remain the same throughout the life-cycle of the compute instance (until it is terminated). Each virtual network created by you runs its own DHCP agent that is used to lease IPs directed by the compute and network services.
You may also need to remove any persistence rules for network interfaces. In Debian/Ubuntu, for example, this will purge the persistence rules:
sudo echo > /etc/udev/rules.d/70-persistent-net.rules
Block devices on our cloud are named /dev/vd[a,b,c…]. If your /etc/fstab is using UUIDs, this should not be an issue, as the UUIDs will be preserved in the migration. However, if your fstab is specifying the block device (eg: /dev/sda1) like the example below, your compute instance will fail to boot complaining it could not find its boot device or root file-system. You should use UUIDs or rename the devices to /dev/vd[a,b,c,…] instead.
# /etc/fstab: static file system information.
# <file system> <mount point> <type> <options> <dump> <pass>
proc /proc proc defaults 0 0
# The device below should be /dev/vda1 instead of /dev/sda1
/dev/sda1 / ext3 errors=remount-ro 0 1
Renaming the file system on the original virtual machine will probably prevent you from booting it. To safely rename the devices, you should mount the image on a loop-back device and then change it as required.
sudo losetup /dev/loop1 image.raw
sudo mount /dev/mapper/loop1p1 /mnt
Warning
If you rename a device in fstab to vda, remember you probably need to apply the same changes to the boot loader. Don’t forget to run update-grub.
Follow the instructions of the next sections (converting the machine image, uploading an image to the cloud and launching a VM based on a custom image) to conclude the process.