OCI Image Migrate Utilities
You can migrate on-premises Oracle Linux images to Oracle Cloud Infrastructure with the oci-image-migrate
utilities.
The
oci-image-migrate
utilities aren't part of the preinstalled OCI Utilities, but are available from the addons
repository. You must manually install the oci-image-migrate
utilities on the on-premises image.Compatibility
You can use the utilities to migrate both virtual machines and physical hosts to Oracle Cloud Infrastructure. To migrate, you must create a compatible disk image and save it in a shared location where an Oracle Linux host can access it. The migration utilities work with the default Oracle VM VirtualBox disk image format (VMDK), or the QEMU copy-on-write disk image format (QCOW2) that's commonly used with Oracle Linux KVM.
How the Utilities Alter the Image
The utilities verify the virtual machine's OS is supported, and perform necessary changes to ensure it runs correctly as a compute instance on Oracle Cloud Infrastructure. To learn more about the changes that these utilities automate, see Bring Your Own Device (BYOI).
Migrating an Image with oci-image-migrate
Install the oci-image-migrate
utilities, convert any physical installations to a virtual disk image, and migrate the virtual disk image to Oracle Cloud Infrastructure.
Installing the Migration Utilities
Install the utilities on the host system before migrating.
Oracle Linux 10
-
Enable the
ol10_addons
yum repository for Oracle Linux 10:sudo dnf config-manager --enable ol10_addons
-
Update the system by using the
dnf update
command, then install the required packages:sudo dnf update -y sudo dnf install -y python3-oci-sdk python3-oci-cli oci-utils-migrate
-
If you intend to migrate a physical installation, install the qemu-img package:
sudo dnf install -y qemu-img
Oracle Linux 9
-
Enable the
ol9_addons
yum repository for Oracle Linux 9:sudo dnf config-manager --enable ol9_addons
-
Update your system by using the
dnf update
command, then install the required packages:sudo dnf update -y sudo dnf install -y python36-oci-sdk python36-oci-cli oci-utils-migrate
-
If you intend to migrate a physical installation, install the qemu-img package:
sudo dnf install -y qemu-img
Oracle Linux 8
-
Enable the
ol8_addons
yum repository for Oracle Linux 8:sudo dnf config-manager --enable ol8_addons
-
Update your system by using the
dnf update
command, then install the required packages:sudo dnf update -y sudo dnf install -y python36-oci-sdk python36-oci-cli oci-utils-migrate
-
If you intend to migrate a physical installation, install the qemu-img package:
sudo dnf install -y qemu-img
Oracle Linux 7 (extended support)
-
Enable the
ol7_addons
and theol7_kvm_utils
repositories for Oracle Linux 7:sudo yum-config-manager --enable ol7_addons ol7_kvm_utils
-
Update your system by using the
yum update
command, then install the required packages:sudo yum update -y sudo yum install -y python36-oci-sdk python36-oci-cli oci-utils-migrate
-
If you intend to migrate a physical installation, install the
qemu-img
package:sudo yum install -y qemu-img
Converting a Physical Installation to a Virtual Disk Image
To migrate a physical installation, create a raw disk image and then convert it into a virtual hard disk format (either VMDK or QCOW2). You can then follow the instructions in Migrating a Virtual Disk Image.
Create the Raw Disk Image
-
Before shutting down the physical machine to create the image, temporarily include all device drivers in the initial ramdisk (
initramfs
):sudo dracut --force --no-hostonly
-
After powering down the physical machine, use a recovery system to create a disk image to an external location:
sudo dd if=device_or_volume of=path_to_image bs=4M status=progress conv=sync,noerror
- Select a disk format VMDK (compatible with Oracle VM Virtualbox) or QCOW2 (compatible with Oracle Linux KVM), and then convert the disk image.
Option 1: Convert to Virtual Machine Disk Format (VMDK)
-
Convert your raw disk image to Virtual Machine Disk (VMDK) format. This file format is used for virtual hard disks that are compatible with Oracle VM Virtualbox.
qemu-img convert -f raw -p -O vmdk raw_disk_image exported_file.vmdk
-
Optionally test the virtual hard disk before packaging and importing it into Oracle Cloud Infrastructure.
For more information, see the Disk Image Files section in the Oracle VM VirtualBox documentation. For more information about the
qemu-img
command, see theqemu-img(1)
man page. - Proceed to Migrating a Virtual Disk Image to Oracle Cloud Infrastructure.
Option 2: Convert to QEMU Copy-on-Write Format (QCOW2)
-
Convert your raw disk image to QEMU copy-on-write (QCOW2). This storage format is used for virtual hard disks that are compatible with Oracle Linux KVM.
qemu-img convert -f raw -p -c -O qcow2 raw_disk_image exported_file.qcow2
-
Optionally test the virtual hard disk before packaging and importing it into Oracle Cloud Infrastructure.
For more information, see the Working with Storage for KVM Guests chapter in the Oracle Linux KVM User's Guide.
- Proceed to Migrating a Virtual Disk Image to Oracle Cloud Infrastructure.
Migrating a Virtual Disk Image to Oracle Cloud Infrastructure
Use the oci-image-migrate
utilities to migrate a virtual disk image to an Oracle Cloud Infrastructure (OCI)instance.
Prerequisites
Before migrating, ensure you have already:
- Configured Identity and Access Management.
- Created a bucket for Object Storage in the OCI tenancy.
- Configured the OCI SDK with the credentials for API access. See Setup and Prerequisites.
- Completed Converting a Physical Installation to a Virtual Disk Image (if migrating a physical host).
If you're new to OCI, see the Getting Started section in the OCI documentation.
Use the Utilities to Migrate the Image
- Complete the prerequisites.
- Verify and preprocess the virtual hard disk in either VMDK or QCOW2 format:
sudo oci-image-migrate -y -i unprocessed_virtual_hard_disk
- Upload the preprocessed virtual hard disk to an OCI
Object Storage bucket as a custom image:
oci-image-migrate-upload -y -i processed_virtual_hard_disk -b bucket_name -o image_name
- Import the image file from the Object Storage bucket to your custom images repository:
oci-image-migrate-import -y -i image_name -b bucket_name -c compartment_name
- If you migrated from a physical host, regenerate
initramfs
on each new instance by using the imported custom image:sudo dracut --force
Migration Utilities Reference
Details about each utility including a description, options, and usage examples.
Prepares an on-premises image for importing into Oracle Cloud Infrastructure. You must run this command as root.
The oci-image-migrate
utility can migrate image files in qcow2
and vmdk
format.
The utility does the following to prepare the image for migration:
- Verifies the prerequisites for importing the image.
- Disables the network interfaces except the primary network interface, which is set up as a DHCP client.
- Installs recommended packages, such as the
cloud-init
package. The list of packages that are installed are displayed in/etc/oci-utils/oci-migrate-conf.yaml
file. - Tries to access remote servers hosting software repositories for the image being processed. The Domain Name Server (DNS) names servers and proxy settings must be able to reach the software repositories.
- Sets the default cloud user to
opc
.
- Usage
oci-image-migrate [-i unprocessed_virtual_hard_disk | --input-image unprocessed_virtual_hard_disk] [-y | --yes] [-v | --verbose] [-h | --help}
- Options
-i unprocessed_virtual_hard_disk | --input-image unprocessed_virtual_hard_disk
Specify the full path for the unprocessed virtual hard disk. This option is mandatory.
- Example
-
$ sudo oci-image-migrate /omv/data/images/ol79.vmdk -v 2021-03-30 20:38:38,177 - oci-utils.migrate-tools - DEBUG(migrate_tools:223) - __ Get config data: helpers_list 2021-03-30 20:38:38,205 - oci-utils.migrate-tools - DEBUG(migrate_tools:223) - __ Get config data: lc_all ...
Uploads an on-premises image file to an Object Storage bucket in Oracle Cloud Infrastructure. This command doesn't require root privileges, provided you can access the Object Storage bucket in Oracle Cloud Infrastructure and have write privileges to the directories where the log and results files are written (/var/tmp/
).
- Usage
oci-image-migrate-upload [-i processed_virtual_hard_disk | --input-image processed_virtual_hard_disk] [-b bucket_name | --bucket-name bucket_name] [-o output_name | --output-name output_name] [-y | --yes] [-v | --verbose] [-h | --help}
- Options
-i processed_virtual_hard_disk | --input-image processed_virtual_hard_disk
Specify the full path for processed virtual hard disk. This option is mandatory.
- Example
-
$ oci-image-migrate-upload -v -i /omv/data/images/ol79.vmdk -b test_bucket_001 -o ol79_demo.qcow2 Uploading ol79.vmdk -b test_bucket_001 -o ol79_demo.qcow2 at Thu Mar 25 20:44:16 2021 Uploading /omv/data/images/ol79.vmdk to object storage test_bucket_001 in the Oracle Cloud Infrastructure as ol79_demo.qcow2 Object storage test_bucket_001 present. Agree to proceed uploading /omv/data/images/ol79.vmdk to test_bucket_001 as ol79_demo.qcow2? (y/N) y Uploading /omv/data/images/ol79.vmdk, this may take a while.... 00:03:12 [ uploading ol79_demo.qcow2
Imports an image from Object Storage to a custom images repository in Oracle Cloud Infrastructure. This command doesn't require root privileges, provided you can access the Object Storage bucket in Oracle Cloud Infrastructure and have write privileges to the directories where the log and results files are written (/var/tmp/
).
- Usage
oci-image-migrate-import[-i image_name | --input-image image_name] [-b bucket_name | --bucket-name bucket_name] [-c compartment_name | --compartment_name compartment_name] [-d display_name | display-name display_name] [-l launch_mode | launch-mode launch_mode] [-y | --yes] [-v | --verbose] [-h | --help}
- Options
-i image_name | --input-image image_name
Specify the name of the image to import as a custom image. This option is mandatory.
- Example
-
$ oci-image-migrate-import -v -y -i ol79_demo.qcow2 -b test_bucket_001 -c OLimages -d ol79_demo Importing ol79_demo.qcow2 from test_bucket_001 into test_bucket_001 as ol79_demo and setting launch mode as PARAVIRTUALIZED Object storage namespace: IMAGETEST Compartment: OLimages Object storage test_bucket_001 present. Import ol79_demo.qcow2 to OLimages as ol79_demo y 00:00:05 [ importing ol79_demo
Additional Migration Information
- To discover how to create and configure new instances with a custom image, see Post-Import Tasks for Linux Images.
- To migrate on-premises servers to dedicated bare metal instances, see Bring Your Own Image (BYOI).
- To migrate Oracle VM VirtualBox virtual machines, see Exporting an Appliance to Oracle Cloud Infrastructure.