Preparing and importing images

You use the Image Templates screen in the IBM Cloud® console to import an image from an IBM Cloud Object Storage service instance. You can import images to Classic infrastructure that are in a virtual hard disk (VHD), virtual machine disk (VMDK), or custom ISO 9660 format. After you upload an image to a bucket in an IBM Cloud Object Storage service instance, you can import it to the image templates repository in the IBM Cloud console. VMDK images are converted to VHD after the import.

You must have an upgraded account to import images from IBM Cloud Object Storage. For more information, see Switching to IBMid and linking accounts.

These instructions are specific to importing images to the image templates repository for Classic infrastructure. These instructions do not apply to IBM Cloud VPC infrastructure.

You must have an IBM Cloud Object Storage instance that was ordered through the IBM Cloud console to use this import feature. IBM Cloud Object Storage from control.softlayer.com is not supported.

Supported operating systems

After images are imported as an image template, they can be used to provision or start an existing virtual server. VHD and VMDK image imports are restricted to the following 64-bit operating systems:

CentOS Stream 9
Debian 11 and 12
Windows Server Standard 2016, 2019, and 2022
RHEL 8 and 9
Ubuntu 20.04 (EOS April 2025), Ubuntu 22.04, and Ubuntu 24.04

Imports are limited to 100 GB disks. Only the boot volume is imported, not secondary disks. Imported images must be named according to the following example: filename.vhd-0.vhd or filename.vmdk-0.vmdk

ISO templates

IBM Cloud Supported operating systems can be used only to load an ISO Template onto a virtual server instance. For a list of supported operating systems, see Supported operating systems for IBM Cloud virtual servers

ISOs that are imported by using this tool must be bootable in order for the image to be eligible for import.

Configuring unencrypted custom images for Virtual Servers

Use the following information to configure an unencrypted custom image for Virtual Servers.

Configuring a custom Linux image

To make sure that an image can be successfully deployed in the IBM Cloud infrastructure environment, virtual server images must be configured to the following specifications:

/boot must be mounted to the first partition
/boot and / must be mounted to separate partitions, and each must be formatted with the ext3 or ext4 file system
/etc and /root must be on the same partition as /
/etc/fstab -> LABEL=SWAP-xvdb1 swap swap : to mount the swap disk that is attached to the system

The Linux boot volume does not support LVM.
wget must be installed

Guest additions are used for reporting performance and health of virtual server instances. Without performance and health information, virtual server instances might be marked for offline migrations when a critical maintenance is needed.

Don't disable or remove the default guest additions that are installed on IBM Cloud supplied images.

The latest supported guest tools must be installed. Complete the following steps to install guest tools.
1. Download the Linux Guest Tool package.
2. Extract the package and follow the directions that are in the README.txt.
Make sure that your image is cloud-init enabled.
- For more information about cloud-init, see the cloud-init documentation.
- For more information about cloud-init enabled images, see Provisioning with a cloud-init enabled image.
- For more information about cloud-init data sources, see Data sources. IBM Cloud cloud-init images are created for the environment by using the Config drive Version 2 data source to supply the metadata.
- Linux images require Cloud-init version 0.7.7 or greater.

Next steps

If you want to make sure that the guest additions are working from the hypervisor point of view, you can create a support case and ask for XenTools virtual server validation.

Configuring a custom Windows image

Complete the following steps to make sure that your own Windows custom image can be successfully deployed in the IBM Cloud infrastructure environment.

Begin with a single image file in VHD format. Disable its firewall so that it moves smoothly through provisioning.
Install the latest supported guest tools by using the following steps.
- Log in to the IBM Cloud VPN by using your IBM Cloud® credentials and download the latest supported guest tools here.
- Extract the compressed file.
- Go to the Windows Installer, for example, managementagent64, and double-click to open the Citrix XenServer Windows Management Agent set up wizard. Complete the installation wizard to install XenServer Tools.
Guest additions are important for reporting the performance and health of virtual server instances. Without performance and health information, virtual server instances might be marked for offline migrations when a critical maintenance is needed.

Don't disable or remove the default guest additions that are installed on IBM Cloud supplied images.

If you want to make sure that the guest additions are working from the hypervisor point of view, you can create a support case and ask for XenTools virtual server validation.
Make sure that your image is cloud-init enabled.
- For more information, see cloudbase-init’s documentation.
- For more information about data sources, see Data sources. IBM Cloud cloud-init images are created for the environment by using the Config Drive Version 2 data source to supply the metadata.
Windows images require the Cloudbase-init metadata service for public and private network support in IBM Cloud infrastructure. You can access the service from the bluemix cloudbase init GitHub repo.

Preparing to import an encrypted image

If you plan to import a VHD image that's encrypted with your own data encryption key, make sure that you complete the prerequisites and instructions for encryption that are described in Using end to end (E2E) encryption to provision an encrypted instance.

You must use the vhd-util tool to encrypt your image, which must be in VHD format. For more information, see Encrypting VHD images.

Uploading an image to IBM Cloud Object Storage

When your image is ready, you can upload it to IBM Cloud Object Storage. Make sure to use a bucket in a regional location.

In IBM Cloud Object Storage, go to your bucket and select Upload > Files to upload the image.
Use the Aspera high-speed transfer plug-in for the fastest upload speeds of your image.

You can use Cloud Object Storage SDK with Aspera to initiate high-speed transfer within your custom applications when you use Java, Python, or NodeJS. For more information, see Using Libraries and SDKs.

Importing an image from IBM Cloud Object Storage

Complete the following steps to import an image from IBM Cloud Object Storage.

Go to the device menu and make sure that you have the correct account permissions to complete the tasks.
- Go to your console's device menu. For more information, see Navigating to devices.
- Make sure that you have any necessary account permissions and device access. Only the account owner, or a user with the Manage Users Classic infrastructure permission, can adjust the permissions.
For more information about permissions, see Classic infrastructure permissions and Managing device access.

You might need to check your Windows firewall settings to make sure that you can import an image from IBM Cloud Object Storage.
Access the Image templates page by selecting Devices > Manage > Images.
Click the Import custom image link to open the Import tool.

Complete the required fields that are in Table 1.

Values for importing a custom image from IBM Cloud Object Storage
Field	Value
Image name	Specify a descriptive name for your new image. This image is the image that you use to provision your virtual server instances.
IBM Cloud API Key	Specify the API key that gives access to your IBM Cloud Object Storage service instance. This key is the object storage service Service Credentials API key. When you import an encrypted image, the API Key must also have access to your key management service instance. The API key is only available to be copied or downloaded at the time of creation. If the API key is lost, you must create a new API key. For more information, see Working with API keys.
Notes	Add any notes that are related to the image that might be helpful to users.
Cloud Object Storage service instance	Select the IBM Cloud Object Storage service instance where the image that you want to import is stored.
Location	Select the specific geographic region where your image is stored. You can import images into the following regions and associated data centers: US-South (DAL13), US-East (WDC07), EU-Great Britain (LON02), EU-Germany (FRA02), AP-Japan, and AU-Sydney. After the image is imported to one of the data centers that are listed, you can move it to another data center.
Bucket	Select the IBM Cloud Object Storage bucket where your image is stored. Only buckets that exist in the regional location that you selected are valid. You receive an error message if you select a bucket that doesn't exist in the selected location.
Name	Select the image file in the IBM Cloud Object Storage service instance that you want to import. Supported file types are VHD (virtual hard disk), VMDK (virtual machine disk), and ISO. If you are importing an encrypted image, the image must be in the VHD file format and encrypted with the vhd-util tool.
Operating System	Select the operating system that is included in your image.
Boot Mode	Select the boot mode for your image. If a default boot mode is set for the operating system that you specify, that boot mode is selected here automatically.
Your license	If you plan to provide your own operating system license, select this checkbox. If you are importing an image with a Windows operating system, you can select this option if you plan to use the image to provision dedicated host instances. If your version of Windows does not support the use your own license option, this option is disabled. For Windows images, you cannot select Cloud Init if you specify that you use your own license. If you are importing an encrypted image with Red Hat Enterprise Linux as your operating system, this option is selected by default and not editable because your encrypted image must include its own operating system license.
Cloud-init	If the image that you are importing is cloud-init enabled, select this checkbox. If you are importing an image that is on a cloud-init enabled Windows operating system and you select this option, you cannot concurrently select Your License. If you are importing an encrypted image, this option is selected by default and not editable because your encrypted image must be cloud-init enabled.
Encryption	If you are importing an image that you have encrypted with your own data encryption key by using the vhd-util tool, select this checkbox.

When the import is complete from IBM Cloud Object Storage, the image appears on the Image templates page.

The following table shows extra fields that are applicable only to importing encrypted images by using the IBM Cloud console. For more information about encrypted images, see Using end to end (E2E) encryption to provision an encrypted instance.

Values for importing an encrypted image from IBM Cloud Object Storage
Field	Value
Wrapped Data Encryption Key	When you import an encrypted image, specify the ciphertext that is associated with the wrapped data encryption key (DEK) that is produced by wrapping the DEK you used to encrypt your image. For more information, see Wrapping keys by using either the IBM® Key Protect API or the IBM Cloud® Hyper Protect Crypto Services API.
Key Management Service Instance	Select a key management service instance in your account from the drop-down list (either the Key Protect service or the Hyper Protect Crypto service). The key management service instance must include the customer root key that you used to wrap your data encryption key.
Key name	Select the name of the root key within the key management service instance that you used to wrap your data encryption key. For more information, see Viewing keys in Key Protect or Viewing keys in Hyper Protect Crypto.

Next Steps

After the import begins, the system locates the image file in the IBM Cloud Object Storage service instance in the specified bucket. The image file is imported as an image template that is then accessible on the Image Templates page. After the import completes, the image can be used to order a new device or to start an existing device. Additionally, you can delete an image template at any time. Image import times vary based on file size, but generally take several minutes to an hour.

The information that you provided to import encrypted image files from IBM Cloud Object Storage is stored along with the image file. Your information is then used to create an encrypted image template that you can use when you order a new device. You don't need to reenter this information when you order new devices from encrypted image templates.

After an image is imported into the image template repository, you can delete it from IBM Cloud Object Storage. You can continue accessing the image template from your Image templates page and by using it to provision virtual server instances.