Home / OCI

OCIHow-toIntermediate

OCI custom images - creating, exporting and importing images across regions and tenancies

Build a golden image from a prepared instance, export it to Object Storage, and import it in another region or tenancy. Includes preparation steps, CLI commands and checks for images that won't boot.

Deepak Bhardwaj4 min read

Applies toOCI Compute custom images (Oracle Linux, other Linux, Windows); OCI CLI 3.x; Object Storage pre-authenticated requests

When you need this

  • A golden image for consistent builds (hardened OS, agents, base packages).
  • Copying a server build to another region for DR or expansion.
  • Moving an image to another tenancy (for example from a partner, or between dev and prod tenancies).

1. Prepare the source instance

Do this on a copy if the instance is in use.

Linux:

sudo dnf -y update          # or apt-get
sudo cloud-init clean --logs
sudo rm -f /etc/ssh/ssh_host_*        # regenerated on first boot
sudo truncate -s0 /etc/machine-id
history -c

Windows: run Sysprep with generalise if you need unique SIDs (the OCI documentation has the steps for OCI Windows images). Sysprep is final: the instance shuts down and is not usable afterwards.

Warning

Remove secrets, API keys, application credentials and SSH authorised keys you don't want in every copy. An image carries everything on the boot volume.

2. Create the custom image

oci compute image create --compartment-id $COMP \
  --instance-id ocid1.instance.oc1..xxxx \
  --display-name "ol9-golden-2026-10" --wait-for-state AVAILABLE

The instance is briefly unavailable while the image is taken. Plan a short window.

3. Same tenancy, another region: export and import

Export to Object Storage:

NS=$(oci os ns get --query data --raw-output)

oci compute image export to-object --image-id ocid1.image.oc1..xxxx \
  --namespace $NS --bucket-name images --name ol9-golden-2026-10.oci \
  --export-format OCI
oci work-requests work-request get --work-request-id <id>

The OCI export format includes image metadata and is the easiest to import back into OCI. QCOW2 and VMDK are for use outside OCI. Check the CLI help for the formats your version supports.

Copy the object to the target region, or create a PAR on it, then import:

oci os object copy -bn images --source-object-name ol9-golden-2026-10.oci \
  --destination-region eu-frankfurt-1 --destination-bucket images

oci compute image import from-object --region eu-frankfurt-1 \
  --compartment-id $COMP --namespace $NS --bucket-name images \
  --name ol9-golden-2026-10.oci --display-name ol9-golden-2026-10

For .oci files the metadata already contains the image type and launch mode. For QCOW2/VMDK files exported elsewhere, add --source-image-type QCOW2 (or VMDK) and --launch-mode PARAVIRTUALIZED (or EMULATED for images without paravirtualised drivers).

4. Another tenancy: pre-authenticated request

In the source tenancy, create a read PAR on the exported object:

oci os preauth-request create -bn images --name share-golden \
  --access-type ObjectRead --object-name ol9-golden-2026-10.oci \
  --time-expires 2026-11-02T00:00:00Z --query "data.\"full-path\"" --raw-output

In the target tenancy, import from the PAR URL:

oci compute image import from-object-uri --compartment-id $TARGET_COMP \
  --uri "https://objectstorage.eu-frankfurt-1.oraclecloud.com/p/....../o/ol9-golden-2026-10.oci" \
  --display-name ol9-golden-2026-10

Caution

Anyone with the PAR URL can download the image until it expires. Use a short expiry and delete the PAR after the import.

oci os preauth-request delete -bn images --par-id <par-id> --force

5. Shape compatibility

Images record which shapes they are compatible with. A custom image from a VM shape may not allow bare metal or a different processor architecture.

oci compute image-shape-compatibility-entry list --image-id ocid1.image.oc1..yyyy --all \
  --query "data[].shape" -o table

oci compute image-shape-compatibility-entry add --image-id ocid1.image.oc1..yyyy --shape-name VM.Standard.E5.Flex

x86 images don't run on Ampere (Arm) shapes. Build separate Arm images.

6. Test boot

oci compute instance launch --compartment-id $COMP --availability-domain "$AD" \
  --shape VM.Standard.E5.Flex --shape-config '{"ocpus":1,"memoryInGBs":8}' \
  --subnet-id $SUBNET --image-id ocid1.image.oc1..yyyy \
  --display-name img-test --ssh-authorized-keys-file ~/.ssh/id_rsa.pub --wait-for-state RUNNING
Problem Check
Import fails Object name/namespace, PAR expired, unsupported format
Instance won't boot Launch mode (paravirtualised vs emulated) or missing drivers for imported non-OCI images; use the serial console
No network Old persistent NIC rules or static network config baked in; use DHCP
SSH keys not applied cloud-init missing or disabled in the image
Shape not allowed Add the shape compatibility entry

Housekeeping

  • Name images with OS and date, and keep the last two or three versions only.
  • Delete exported .oci files from Object Storage once they're imported, or put them in Archive.
  • Rebuild golden images monthly with patches instead of patching every instance from an old base.

Checklist

  • Source instance cleaned and free of secrets
  • Image created and exported in OCI format
  • Copied by object copy or PAR (with short expiry)
  • Imported and shape compatibility set
  • Test instance boots, network and SSH work
  • Old exports and PARs removed

Related fixes