Bringing Your Own Images into OCI—Without the Headaches

As more organizations move toward hybrid and multi-cloud setups, one requirement keeps coming up: reuse the same operating system image everywhere.

You might already have a trusted image built on‑premises, or one that comes from a third‑party vendor. Naturally, you want to import that image into Oracle Cloud Infrastructure (OCI) and use it to launch both virtual machines (VMs) and bare metal (BM) instances.

On the surface, this sounds simple. In practice, there’s a catch.

Custom images created outside OCI usually work fine for virtual machines—but they often fail to boot on bare metal. The reason isn’t obvious unless you know how OCI boots bare metal systems.

This post explains why that happens and what you need to change, using plain language and focusing only on what actually matters.

The Reality of Image Portability across Environments

OCI supports importing external images, but those images are typically designed for environments that boot from local disks or paravirtualized storage.

Bare metal in OCI works differently.

If you import an image “as is” and try to launch it on a bare metal shape, you’ll likely see one of the following:

  • The instance never finishes booting
  • The OS can’t find its root disk
  • Networking never comes up

None of these are OCI bugs. They’re simply missing prerequisites inside the image.

The good news: once you understand the requirements, the fix is straightforward—and you can end up with one image that works everywhere.

Why Bare Metal Needs Extra Configuration

Virtual machines and bare metal instances boot in very different ways.

Virtual Machines (VMs)

VMs use paravirtualized storage. From the OS point of view, the boot disk looks like a locally attached device. Most modern Linux images already know how to handle this, so they boot without special tweaks.

Bare Metal (BM)

Bare metal instances in OCI boot using iSCSI. The boot disk is provided over the network, not from local storage.

That difference changes everything during early boot.

For a bare metal instance to start correctly, the operating system must:

  • Bring up networking very early
  • Load iSCSI drivers before the root filesystem is mounted
  • Pass the right kernel parameters during boot
  • Use reliable low‑level network configuration tools

External images usually don’t include this setup because on‑prem and third‑party environments rarely boot from iSCSI.

Without these pieces, a bare metal instance simply has no way to find its boot disk.

Designing One Image That Works for Both VM and Bare Metal

To make a single custom image work across both shapes, you need to focus on three core areas.

Nothing fancy—just the right basics in the right place.

1. Setup iSCSI Boot Support

Since bare metal boots over the network, your image must include everything required to talk iSCSI before the OS is fully running.

At a high level, this means:

  • Installing The iSCSI initiator (e.g.: iscsi-initiator-utils)
  • Include the kernel parameters ( rd.iscsi.ibft=1 rd.iscsi.firmware=1) 
  • Rebuild initramfs

With this in place, the OS can:

  • Discover the boot volume exposed by OCI
  • Bring up networking early enough to reach it
  • Mount the root filesystem and continue booting normally

Once these capabilities exist in the image, the same disk layout works on both VMs and bare metal shapes.

2. Bring Cloud‑Init Up to OCI Standards

Cloud-init is responsible for critical first-boot tasks:

  • applying SSH keys from instance metadata
  • configuring networking
  • using custom start-up configuration

External images frequently ship with older or incompatible cloud-init versions that assume OpenStack or other metadata services.

For OCI compatibility, a custom image must:

  • include cloud-init version 20.3 or later, which supports OCI as a data source
  • remove or replace older versions that may conflict
  • configure Oracle as the authoritative datasource

Once this is done, both VM and bare metal instances initialize the same way every time.

Clean Up the Image Before You Capture It

Before turning your updated system into a reusable image, take a moment to clean it up.

This step prevents hard to debug issues later.

Make sure to:

  • Clear cloud init state (cloud-init clean –logs)
  • Remove old logs and temporary files

The goal is simple: every instance launched from this image should behave as if it’s brand new.

Summary

Using a single custom image for both virtual machines and bare metal instances makes life much easier. It reduces the number of images you need to manage, keeps security and configuration consistent, and simplifies DevOps workflows and hybrid cloud migrations. To make this work in OCI, an external image just needs a few specific updates: support for iSCSI booting, the right modules and kernel settings loaded during boot, and a cloud-init version that works properly with OCI. Once these pieces are in place, the image follows OCI’s provisioning process and behaves reliably, regardless of which type of instance it runs on.

For more information, see the following resources:

To learn more, ask your Oracle Sales Account team to engage the OCI HPC GPU Specialist team.