Oracle Cloud Infrastructure Documentation

Importing Custom Linux Images

The Compute service enables you to import Linux-based images that were created outside of Oracle Cloud Infrastructure. For example, you can import images running on your on-premises physical or virtual machines (VMs), or VMs running in Oracle Cloud Infrastructure Classic. You can then launch your imported images on Compute virtual machines.

Supported Operating Systems

You can launch imported Linux VMs in either paravirtualized mode or emulated mode.

Paravirtualized mode offers better performance than emulated mode. We recommend that you use paravirtualized mode if your OS supports it. Linux-based operating systems running the kernel version 3.4 or later support paravirtualized drivers. You can verify your system's kernel version using the uname command.

To verify the kernel version using the uname command

These Linux distributions support custom image import:

Linux Distribution Supported Versions Preferred Launch Mode
RHEL 7 or later Paravirtualized
4.5, 5.9, 5.11, 6.9 Emulated
CentOS 7 or later Paravirtualized
4.0, 4.8, 5.11, 6.9 Emulated
Oracle Linux 7 or later Paravirtualized
4.5, 4.8, 5.8, 5.11, 6.2, 6.5 Emulated
Ubuntu 13.04 or later Paravirtualized
12.04 Emulated
FreeBSD 12 or later Paravirtualized
8, 9, 10, 11 Emulated
Debian 8 or later Paravirtualized
5.0.10, 6.0, 7 Emulated
SUSE 12.2 or later Paravirtualized
11, 12.1 Emulated
    Note

  • Oracle Cloud Infrastructure has tested the operating systems listed in the previous table and will support customers in ensuring that instances launched from these images and built according to the guidelines in this topic are accessible using SSH.
  • For OS versions not listed in the previous table, Oracle Cloud Infrastructure will provide commercially reasonable support to customers in an effort to get instances that are launched from these images accessible via SSH.
  • Support from Oracle Cloud Infrastructure in launching an instance from a custom OS does not ensure that the operating system vendor also supports the instance. Customers running Oracle Linux on Oracle Cloud Infrastructure automatically have access to Oracle Linux Premier Support.

Tip

If your image supports paravirtualized drivers, you can convert your existing emulated mode instances into paravirtualized instances. Create a custom image of your instance, export it to Object Storage, and then reimport it using paravirtualized mode.

Linux Source Image Requirements

Custom images must meet the following requirements:

  • The maximum image size is 300 GB.

  • The image must be set up for BIOS boot.

  • Only one disk is supported, and it must be the boot drive with a valid master boot record (MBR) and boot loader. You can migrate additional data volumes after you import the image's boot volume.

  • The boot process must not require additional data volumes to be present for a successful boot.

  • The boot loader should use LVM or a UUID to locate the boot volume.

  • The disk image cannot be encrypted.

  • The disk image must be a VMDK or QCOW2 file.

    • Create the image file by cloning the source volume, not by creating a snapshot.
    • VMDK files must be either the "single growable" (monolithicSparse) type or the "stream optimized" (streamOptimized) type, both of which consist of a single VMDK file. All other VMDK formats, such as those that use multiple files, split volumes, or contain snapshots, are not supported.
  • The network interface must use DHCP to discover the network settings. When you import a custom image, existing network interfaces are not recreated. Any existing network interfaces are replaced with a single NIC after the import process is complete. You can attach additional VNICs after you launch the imported instance.

  • The network configuration must not hardcode the MAC address for the network interface.

We recommend that you enable certificate-based SSH, however this is optional. If you want your image to automatically use SSH keys supplied from the User Data field when you launch an instance, you can install cloud-init when preparing the image. See Creating an Instance for more information about the User Data field.

Preparing Linux VMs for Import

Before you import a custom Linux image, you must prepare the image to ensure that instances launched from the image can boot correctly and that network connections will work. Do the following:

  1. Optionally, configure your Linux image to support serial console connections. A console connection can help you remotely troubleshoot malfunctioning instances, such as an imported image that does not complete a successful boot.

  2. Create a backup of the root volume.

  3. If the VM has remotely attached storage, such as NFS or block volumes, configure any services that rely on this storage to start manually. Remotely attached storage is not available the first time that an imported instance boots on Oracle Cloud Infrastructure.

  4. Ensure that all network interfaces use DHCP, and that the MAC address and IP addresses are not hardcoded. See your system documentation for steps to perform network configuration for your system.

  5. Stop the VM.

  6. Clone the stopped VM as a VMDK or QCOW2 file, and then export the image from your virtualization environment. See the tools documentation for your virtualization environment for steps.

Importing a Linux-Based VM

After you prepare a Linux image for import, follow these steps to import the image:

  1. Upload the VMDK or QCOW2 file to Oracle Cloud Infrastructure:

    1. Upload the file to an Object Storage bucket. You can upload the file using the Console or using the command line interface (CLI). If you use the CLI, use the following command:

      oci os object put -bn <destination_bucket_name> --file <path_to_the_VMDK_or_QCOW2_file>
    2. Copy the URL of the file that you uploaded: On the Bucket Details page, click the the Actions icon (three dots) next to the file, and then click Details. Copy the URL Path (URI).
  2. Open the navigation menu. Under Core Infrastructure, go to Compute and click Custom Images.

  3. Click Import Image.

  4. In the Create in Compartment list, select the compartment that you want to import the image to.

  5. Enter a name for the image.

  6. For the Operating System, select Linux.

  7. In the Object Storage URL field, paste the URL of the file that you uploaded.

  8. For the Image Type, select the file type of the image, either VMDK or QCOW2.

  9. Depending on your image's version of Linux, in the Launch Mode area, select Paravirtualized Mode or Emulated Mode. If your image supports paravirtualized drivers, we recommend that you select paravirtualized mode.

  10. Tags: Optionally, you can apply tags. If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  11. Click Import Image.

    The imported image appears in the Custom Images list for the compartment, with a status of IMPORTING. When the import completes successfully, the status changes to AVAILABLE.

    If the status doesn't change, or no entry appears in the Custom Images list, the import failed. Ensure that you have read access to the Object Storage object, and that the object contains a supported image.

  12. Complete the post-import tasks.

Post-Import Tasks for Linux Images

After you import a custom Linux-based image, do the following:

  1. Create an instance based on the custom image. For the image source, select Custom Images, and then select the image that you imported.

  2. Connect to the instance using SSH.
  3. If the instance requires any remotely attached storage, such as block volumes or file storage, create and attach it.
  4. Create and attach any required secondary VNICs.
  5. Test that all applications are working as expected.
  6. Reset any services that were set to start manually.
  7. If you enabled serial console access to the image, test it by creating a serial console connection to the instance.

See the current issues and workarounds for known issues with imported custom images.

This topic has moved. Please update your bookmarks.