---
name: vpc-vsi_is_about_custom_images
title: Getting started with custom images
description: A custom image contains an operating system image with specific configurations that you customize. You can manage the lifecycle, share the custom image, and use it to create virtual servers or bare metal servers with your own settings and configurations. You can create a Linux® custom image, a Windows® custom image, a z/OS Wazi aaS custom image, or a generic operating system custom image.
last-updated: 2025-11-06
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/vpc?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Getting started with custom images
{: #planning-custom-images}

A custom image contains an operating system image with specific configurations that you customize. You can manage the lifecycle, share the custom image, and use it to create virtual servers or bare metal servers with your own settings and configurations. You can create a Linux® custom image, a Windows® custom image, a z/OS Wazi aaS custom image, or a generic operating system custom image.
{: shortdesc}

You have a few options to create a custom image.

* You can import your custom image directly into IBM Cloud® Virtual Private Cloud from IBM Cloud® Object Storage. For more information, see [Importing your custom image into IBM Cloud VPC](https://cloud.ibm.com/docs/vpc?topic=vpc-custom-image-using-COS&interface=ui&format=markdown).
* You can create a custom image from an existing VPC virtual server boot volume. For more information, see [About creating an image from a volume](https://cloud.ibm.com/docs/vpc?topic=vpc-image-from-volume-vpc&interface=ui&format=markdown).
* If you have virtual servers that are running on the Classic Infrastructure, you can create an image template to migrate to a VPC virtual server. For more information, see [Migrating a virtual server from the Classic infrastructure](https://cloud.ibm.com/docs/vpc?topic=vpc-migrate-vsi-to-vpc&format=markdown).

When you create a custom image, you can plan and manage the lifecycle of the image by using three statuses: available, deprecated, or obsolete. For more information about statuses and how to manage them, see [Custom image lifecycle](https://cloud.ibm.com/docs/vpc?topic=vpc-planning-custom-images&interface=ui&format=markdown#custom-image-lifecycle).

You can also share your custom images with other accounts by using a private catalog. For more information on using custom images in a private catalog, see [Getting started with Catalog Images on VPC](https://cloud.ibm.com/docs/vpc?topic=vpc-getting-started-images-on-vpc-catalog&interface=ui&format=markdown).

On the console, you can find custom images by clicking **Menu icon ![Menu icon](../icons/icon_hamburger.svg) > VPC Infrastructure ![VPC icon](../../icons/vpc.svg) > Compute > Images > Custom images**. Images that are from a volume are part of the custom images tab.

## Creating a custom image
{: #create-custom-image}

To create a custom image, see one of the following links.

* [Creating an image from a volume](https://cloud.ibm.com/docs/vpc?topic=vpc-create-ifv&format=markdown)
* [Creating a custom Linux image](https://cloud.ibm.com/docs/vpc?topic=vpc-create-linux-custom-image&format=markdown)
* [Creating a custom Windows image](https://cloud.ibm.com/docs/vpc?topic=vpc-create-windows-custom-image&format=markdown)
* [Creating a z/OS Wazi aaS custom image](https://cloud.ibm.com/docs/vpc?topic=vpc-create-zos-custom-image&format=markdown)
* [Creating a generic operating system custom image](https://cloud.ibm.com/docs/vpc?topic=vpc-create-generic-os-custom-image&interface=ui&format=markdown)

## Sharing a custom image
{: #sharing-custom-image}

After you create a custom image, you can import it into a private catalog, and share it with other accounts with some limitations. For more information about the limitations, see [VPC considerations when you use custom images in a private catalog](https://cloud.ibm.com/docs/vpc?topic=vpc-custom-image-cloud-private-catalog&interface=ui&format=markdown).

## Using a custom image to create a server
{: #custom-image-create-vsi}

To create a virtual server by using a custom image, see one of the following links.

* [Creating a virtual server instance with the UI](https://cloud.ibm.com/docs/vpc?topic=vpc-creating-virtual-servers&interface=ui&format=markdown#creating-virtual-servers-ui)
* [Creating a virtual server instance with the CLI - provision with a stock or custom image](https://cloud.ibm.com/docs/vpc?topic=vpc-creating-virtual-servers&interface=cli&format=markdown#instance-create-from-image-cli)
* [Creating a virtual server instance with the API - provision from a stock or custom image](https://cloud.ibm.com/docs/vpc?topic=vpc-creating-virtual-servers&interface=api&format=markdown#create-instance-stock-custom-image-api)
* [Creating an instance by using Terraform](https://cloud.ibm.com/docs/vpc?topic=vpc-creating-virtual-servers&interface=terraform&format=markdown#create-instance-using-terraform)

## Prerequisites and limitations
{: #custom-image-prerequisites}

Before you create a custom image, you must verify that your custom image meets the custom image requirements and that the operating system is supported.

### Custom image considerations
{: #custom-image-considerations}


For more information about custom images, see [Getting started with custom images](https://cloud.ibm.com/docs/vpc?topic=vpc-planning-custom-images&format=markdown).

### Operating system considerations
{: #custom-image-operating-systems}

* Make sure that the selected operating system specifies the correct user data format type. For more information, see [User data format considerations](#custom-image-user-data-format).
* If you choose to create a custom image with your own license, specify the appropriate operating system version that appends `-byol` to the name when you import the image. For more information, see [Bring your own license](https://cloud.ibm.com/docs/vpc?topic=vpc-byol-vpc-about&format=markdown).
* ISO images of licensed operating systems, such as Windows® and Linux®, and open source operating systems, such as CentOS and Ubuntu, aren't provided by IBM Cloud®. If you need these ISO images, you can download them from the respective vendor website.

### IBM Cloud Object Storage considerations
{: #custom-image-cloud-object-storage}

If you plan to import an image from a file, you must provision an instance of IBM Cloud Object Storage if you don't have one. You can then upload the file to a bucket there. You must also create an IAM authorization between the Image Service for VPC and IBM Cloud Object Storage. For more information, see [Granting access to IBM Cloud Object Storage to import images](https://cloud.ibm.com/docs/vpc?topic=vpc-object-storage-prereq&interface=cli&format=markdown).

## Custom image lifecycle
{: #custom-image-lifecycle}




You can use the UI, CLI, API, and Terraform to manage the lifecycle of your custom images with three statuses. You can move the image back and forth through all the statuses and set dates to automatically change an image status. All status changes are tracked as an IBM Cloud Activity Tracker Event Routing event. You can filter your list of images based on status to aid in clean-up or tracking of your images. For more information about making status changes, see [Managing custom images](https://cloud.ibm.com/docs/vpc?topic=vpc-managing-custom-images&interface=ui&format=markdown).

| Image status | Description |
| -------------- | -------------- |
| `available` | You can use the `available` status to indicate an operating system image is `available` and provisionable in all zones.  \n  \n You might see an image in `partially_available` status. This status is a temporary status that indicates an image was imported into at least one zone but is not yet available in all zones. These images eventually reach `available` status without any additional user action. An image in `partially_available` status can be used to create virtual server instances or bare metal servers in available zones listed in that image's zones array. These images can also be exported into IBM Cloud Object Storage. |
| `deprecated` | You can use the `deprected` status to indicate the image can be used, but it is not recommended. For example, with a stock image, when a new version of an operating system is made `available`, the older version image of that guest operating system changes to `deprecated`. You can still create virtual server instances or bare metal servers with these images.|
| `obsolete` | You can use the `obsolete` status to indicate images must not be used, such as an operating system image that has reached EOS. You can't create virtual server instances or bare metal servers with these images. If you try to use an obsolete image to create an instance, you receive a message that states that you can't use the image to create an instance. This status allows a reversible disabling of an image before you delete the image. |
{: caption="Image lifecycle status" caption-side="bottom"}

Any image that is in `deprecated` or `obsolete` status is still billed. If you don't want to be billed for the image, you must delete it.
{: note}


IBM Cloud VPC managed images can be managed only this way. Custom images that are published to a private catalog must be in `available` status and their statuses are maintained in the private catalog. If you try to change or schedule a change to their status in IBM Cloud VPC, the attempt fails. If a custom image is removed from a private catalog, that image retains its original private catalog status until the status is changed in IBM Cloud VPC.

| Private catalog image status | Corresponding VPC image status |
|------------------------|----------------------------|
| `published/verified`   | `available`                |
| `deprecated`           | `deprecated`               |
| `archived`             | `obsolete`                 |
{: caption="Catalog image lifecycle status and the corresponding VPC status" caption-side="bottom"}

## Red Hat Enterprise Linux AI BYOL custom images
{: #rhel-ai-byol-custom-images}

You can import the Red Hat Enterprise Linux AI (RHEL AI) operating system as bring your own license (BYOL). An RHEL AI qcow2 file is available directly from Red Hat. The operating system name to use when you import the image into IBM Cloud VPC is`red-ai-9-amd64-nvidia-byol`. For more information, see [Red Hat Enterprise Linux AI](https://www.redhat.com/en/products/ai/enterprise-linux-ai){: external}. To download the RHEL AI image, see [Download Red Hat Enterprise Linux AI](https://access.redhat.com/downloads/content/932){: external}. You need a Red Hat account to view the documentation and download the image.

For information about the supported profiles and use cases, see [Red Hat Enterprise Linux AI hardware requirements](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux_ai/1.5#hardware_requirements_rhelai){: external}.
{: note}

For more information about support for Red Hat, see [FAQs about Red Hat and IBM Cloud® infrastructure](https://cloud.ibm.com/docs/infrastructure-hub?topic=infrastructure-hub-faqs-for-red-hat-ibm-cloud&format=markdown).

For more information about importing the image into IBM Cloud VPC, see [Bring your own license](https://cloud.ibm.com/docs/vpc?topic=vpc-byol-vpc-about&format=markdown) and [Importing and validating custom images into VPC](https://cloud.ibm.com/docs/vpc?topic=vpc-importing-custom-images-vpc&interface=ui&format=markdown). For more information on the GPU profiles, see the [x86 GPU profiles](https://cloud.ibm.com/docs/vpc?topic=vpc-profiles&interface=ui&format=markdown#gpu).

## Generic operating system custom images
{: #generic-os-custom-images}

You can use a specific operating system that is not listed in IBM Cloud by specifying a generic operating system when you import a custom image. You can choose from multiple generic operating system options. You can select a generic operating system that is based on the CPU architecture and initialization strategy that is appropriate for your custom image operating system.

Generic operating system custom images are supported for x86 (amd64) architecture. These images are listed in the custom images list. Bare metal server generic operating system custom images must follow requirements for all bare metal server custom images. For more information, see [Bare metal server custom images](https://cloud.ibm.com/docs/vpc?topic=vpc-planning-custom-images&format=markdown#bare-metal-server-custom-images-considerations).

The generic operating systems use a generic value for some of their properties, such as `generic` for the `vendor` property and `Generic` for the `family` property. When you create a generic operating system custom image, select the generic operating system based on the initialization type of the actual operating system. For more information, see [User data format considerations](https://cloud.ibm.com/docs/vpc?topic=vpc-planning-custom-images&format=markdown#custom-image-user-data-format).

When you provision a server by using a generic operating system custom image, most operating system-specific provisioning steps aren't performed, such as console setup and automatic registration. You must provide the appropriate user data if you want your generic operating system custom image to perform these steps. You are also responsible for handling licensing and related costs because IBM is not aware of the actual operating system installed.

## User data format considerations
{: #custom-image-user-data-format}

When you create a server that specifies your custom image, the initialization strategy determines how the user data is used. The `user_data_format` property of an image specifies this initialization strategy. This property is set from the image operating system `user_data_format` property, which contains one of the following values.

* `cloud_init`
* `esxi_kickstart` (This value works only for bare metal servers.)

* For cloud-init, user data and SSH keys are provided to the operating system on a cloud-init disk. A default user account is not created. You must use your SSH key to log in unless you set up another login mechanism through cloud-init. For virtual server instances, you might need to set up networking during initialization. For example,

   See [Creating a custom Linux image](https://cloud.ibm.com/docs/vpc?topic=vpc-create-linux-custom-image&format=markdown) or [Creating a custom Windows image](https://cloud.ibm.com/docs/vpc?topic=vpc-create-windows-custom-image&format=markdown) documentation for details about using cloud-init data.

* For ESXi kickstart, user data is provided to the operating system in a kickstart script. A default user account is created. Retrieve the server's initialization data to obtain the generated password. See VMware documentation for details of kickstart scripts.

Use security best practices to limit access to any files that you expose on the internet.
{: important}

## Bare metal server custom images
{: #bare-metal-server-custom-images-considerations}

Bare metal servers have some limitations that you need to be aware of.

* Encrypted images aren't supported.

To create a custom image for bare metal servers, the custom image must support the following information:

* UEFI boot
   - UEFI boot requires a dedicated EFI partition that contains EFI firmware. Traditional BIOS boot isn't supported.
* Pensando iconic network device drivers
* Intel chip set device drivers
   - These device drivers are usually part of the default kernel build options. Windows requires extra device drivers, but you can install these drivers later.

For more information, see [Custom Linux kernel build options for bare metal servers](https://cloud.ibm.com/docs/vpc?topic=vpc-configuration-requirements-for-custom-linux-kernels&format=markdown#custom-linux-kernel-linuxone-options).

For more information about bare metal server images, see [Bare metal server images](https://cloud.ibm.com/docs/vpc?topic=vpc-bare-metal-image&format=markdown).

## Secure boot-supported custom images
{: #bare-metal-server-custom-images-secure-boot-considerations}

[Select availability]{: tag-green}

Secure boot helps make sure that the system runs only authentic software by verifying the digital signature of all boot components. Secure boot stops the boot process if the signature verification fails. Secure boot prevents the loading of unsigned or malicious code during boot.

Custom images that support secure boot have some requirements that you need to be aware of.

* UEFI boot
   - UEFI boot requires a dedicated EFI partition that contains EFI firmware. Traditional BIOS boot isn't supported.
* GPT partitioned disk

You can verify that the image successfully booted in secure boot mode by using the following mokutil command.

```text
mokutil --sb-state
```
{: codeblock}

For more information about secure boot, see [Secure boot for Virtual Servers for VPC](https://cloud.ibm.com/docs/vpc?topic=vpc-confidential-computing-with-secure-boot-vpc&format=markdown).

## z/OS Wazi aaS custom images
{: #custom-image-zos}

You can use IBM Wazi Image Builder to create your own custom z/OS-based IBM Wazi as a Service (Wazi aaS) image and import the custom image into IBM Cloud® Virtual Private Cloud.

IBM Wazi Image Builder is a separately orderable product from [IBM Passport Advantage](https://www.ibm.com/software/passportadvantage/){: external}. Extra requirements are needed to use Wazi Image Builder. The image cost is the premium that covers the cost of technologies that allows for z/OS dev and test images to run on IBM Z hardware on IBM Cloud as a service layer.

The z/OS Wazi aaS custom image must meet the following requirements:

* qcow2 format
* z/OS 2.4 or z/OS 2.5 operating system

For more information, see [Bringing your own image with Wazi Image Builder](https://www.ibm.com/docs/en/wazi-aas/1.1.0?topic=bringing-your-own-image-wazi-image-builder){: external}.

## More information about custom images
{: #custom-image-additional-information}

You can review the blog [How to create and distribute IBM Cloud® Virtual Private Cloud (VPC) instances from custom images](https://www.ibm.com/products/tutorials/vpc-custom-image-creation-and-distribution){: external} for detailed view, including graphics, on the various custom image options. Or you can review the following links for specific tasks.

* [Using granular RBAC permissions for custom images](https://cloud.ibm.com/docs/vpc?topic=vpc-using-granular-RBAC-permissions-for-custom-images&format=markdown)
* [Configuration requirements for custom Linux kernel](https://cloud.ibm.com/docs/vpc?topic=vpc-configuration-requirements-for-custom-linux-kernels&format=markdown)
* [About creating an image from a volume](https://cloud.ibm.com/docs/vpc?topic=vpc-image-from-volume-vpc&interface=ui&format=markdown)
* [Importing and validating custom images into VPC](https://cloud.ibm.com/docs/vpc?topic=vpc-importing-custom-images-vpc&format=markdown).
* [Managing custom images](https://cloud.ibm.com/docs/vpc?topic=vpc-managing-custom-images&interface=ui&format=markdown)
* [Managing image from a volume](https://cloud.ibm.com/docs/vpc?topic=vpc-image-from-volume-vpc-manage&interface=ui&format=markdown)