Import a local custom image in the Alibaba Cloud ECS console - Elastic Compute Service

You can import a custom image to quickly create Elastic Compute Service (ECS) instances that match your on-premises development environment or existing server setup. This saves you from manually installing applications and configuring each new instance. This method is ideal for standardized deployments and large-scale delivery. This topic describes how to prepare an image file and import it into Alibaba Cloud to create a custom image.

You can also use Server Migration Center (SMC) to migrate servers from self-managed data centers, on-premises virtual machines, or third-party cloud service providers to Alibaba Cloud. Then, you can generate custom images from these servers and use the custom images to create ECS instances. For more information, see Migrate servers to Elastic Compute Service (ECS).

Prerequisites

Before you import an image file in the ECS console, complete the following preparations:

Review the Instructions for importing images to ensure that your image file meets all import requirements. This helps prevent compatibility issues.

ECS supports importing image files only in QCOW2, VHD, RAW, and VMDK formats. If your image file is in another format, you must convert the image format before you upload the file.

Comparison of QCOW2, VHD, and RAW formats

Image format	Description	Characteristics
QCOW2	QCOW2 is a virtual machine (VM) image format implemented by QEMU. It uses a single file to represent a block device disk and supports dynamic disk space allocation.	Requires less disk space. Supports Copy-On-Write (CoW). An image file reflects only underlying disk changes. Supports snapshots. An image file can contain multiple historical snapshots. Supports ZLIB compression and AES encryption.
VHD	VHD is a virtual disk file format provided by Microsoft. A VHD file can be compressed into a single file and stored in the file system of a local physical host. This format is suitable for multiple purposes.	Simple maintenance. You can partition, format, compress, and delete a VHD file without affecting physical partitions. Easy backup. You need only to back up the created VHD file. You can also use a backup tool to back up the entire physical partition where the VHD file is stored. Easy migration. To use a VHD file on multiple computers, detach the file from the current computer, copy it to the destination computer, and then attach it. Direct system deployment. You can use the ImageX tool to release a captured image to a VHD virtual disk, or use a WDS server to deploy a system to a VHD virtual disk.
RAW	The RAW format is a file format that supports direct read and write operations. It does not support dynamic space extension and provides the best I/O performance among all image formats.	Simple addressing and high access efficiency. Can be easily converted to other formats using a format conversion tool. Can be easily attached to a local physical host. Data can be transmitted between the image and the host without the need to start a VM.

Grant ECS the required permissions to access Object Storage Service (OSS) resources. ECS obtains these permissions by assuming the AliyunECSImageImportDefaultRole role.
If you are importing an image for the first time, follow the on-screen instructions in the wizard on the Images page of the ECS console to grant the permissions.
If you use a Resource Access Management (RAM) user to import a custom image, you must first use your Alibaba Cloud account to grant the RAM user the required permissions to perform operations on the OSS bucket. For more information, see Grant a RAM user read and write permissions on an OSS bucket.

Video tutorial

The following video shows how to import a custom image in the ECS console.

Procedure

Step 1: Prepare and upload the image file to OSS

Before you import an image, you must have a compliant image file and upload it to an Object Storage Service (OSS) bucket. Check the image file against the requirements in Instructions for importing images to ensure that the file is compliant. Otherwise, the import may fail, or instances created from the image may not run as expected.

Upload an on-premises image file to an OSS bucket and obtain the URL of the file. For more information, see Multiple ways to upload files to OSS.

Note

If you want the imported image to include data disks, prepare separate image files for the system disk and data disks and upload them to OSS. When you create an ECS instance from the resulting custom image, the instance will include both a system disk and data disks.

Step 2: Import a custom image in the ECS console

Go to the Images page in the ECS console. In the upper-left corner of the page, select the resource group and region for your resources.
Important
The selected region must be the same as the region of the OSS bucket in which the image file is stored.
On the Images page, in the upper-right corner, choose Import Image > Import Image.
On the Prepare Before Import wizard page, confirm that you have completed the necessary preparations, click Next, and then click Continue To Import.

In the Import Image File wizard, configure the following settings.

Parameter	Required	Description
Image File URL	Yes	Enter the URL of the image file that you obtained in Step 1. The OSS image file must be in the current region. To change the region, select a new region from the top navigation bar and reopen the Import Image dialog box.
Image Name	Yes	Enter a name for the custom image. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character and can contain digits, periods (.), underscores (_), colons (:), and hyphens (-).
Operating System Type	Yes	Select the operating system type of the image file to import. The operating system type must be the same as that of the image file. Valid values: windows and linux. If the operating system of the image that you want to import is not on the list of platforms supported by Alibaba Cloud, select linux.
Operating System Version	Yes	Select the operating system version of the image file to import. The operating system version must be the same as that of the image file. If the operating system is not on the list of platforms supported by Alibaba Cloud, you can select one of the following options: Select Customized Linux. Make sure that you have manually added the parsing script to ensure that the image is usable. For more information, see Customize Linux images. Select Others Linux. ECS does not process the instances that are created from the imported image. After you create an instance from the imported image, you must configure the IP address, route, and password in the instance. If your operating system is developed based on the Linux kernel, submit a ticket to contact us.
System Architecture	Yes	The system architecture must be the same as that of the local image file. The following system architectures are supported: 32-bit operating system 64-bit operating system Arm 64-bit operating system
License Type	Required if the operating system is Windows.	The license type used to activate the original operating system after the image is imported. Valid values: Alibaba Cloud License: When you create an instance from the imported image, you are charged a license fee for Windows Server. The operating system is automatically activated using an Alibaba Cloud activation server. For more information about billing, see Image fees. Bring Your Own License (BYOL): When you create an instance from the imported image, Alibaba Cloud does not charge you an operating system license fee and does not automatically activate Windows Server. You must prepare a valid license and manually activate the operating system.
Image Check	No	Optional. The image check feature checks whether imported custom images are valid and whether the images can be used to create full-featured ECS instances. By default, Check After Import is selected. The image check feature checks the custom image immediately after the image is imported. After the check is complete, you can view the detailed check result in the Check Result column of the custom image list. If an item needs to be fixed, you can use the One-click Fix feature or manually fix the item based on the suggestions in the image details. Note The image check feature is supported only for some operating systems. For a list of operating systems that do not support this feature, see Operating system limits for image check.
Boot Mode	No	Select the boot mode of the image. Valid values: BIOS and UEFI. The boot mode specifies how the system disk is started when an ECS instance is created. We recommend that you select the same boot mode as the boot mode of the image file. Otherwise, the ECS instance created from the custom image may fail to start.
Image Format	No	Valid values: Auto-detect (default), RAW, QCOW2, VHD, and VMDK. We recommend that you select the same format as the image file. If you do not know the image format, select Auto-detect. The system automatically sets the image format to be the same as the format of your local image file. Note ECS does not support importing ISO image files directly. You must convert the ISO image file to a format supported by ECS before you import it. For more information, see How do I convert an ISO image file to an image format supported by ECS?.
Disk Configurations	No	Set the system disk capacity and add data disk images. Select Configure Disk Attributes. The system disk parameters are pre-filled. You need only to specify the system disk capacity. The system disk size must be in the range of 1 GiB to 2,048 GiB and cannot be smaller than the image file size. Note The image file size is the size of the OSS image file. You can view the size in the OSS console. Click Add Data Disk and then configure the parameters. Image File URL: Enter the URL of the data disk image file that you obtained in Step 1. The method to obtain the URL is the same as that for the system disk. Mount Point: The system automatically assigns a mount point. You do not need to configure this parameter. Image Format: Select Auto-detect, RAW, QCOW2, VHD, or VMDK. The format must be the same as that of the image file. Disk Capacity (GiB): The disk size must be in the range of 1 GiB to 2,048 GiB and cannot be smaller than the image file size. Note The image file size is the size of the OSS image file. You can view the size in the OSS console.
Image Description	No	Enter a description for the image to facilitate subsequent management.
Tag	No	You can add tags to classify images for easy search and batch operations.
Resource Group	No	You can add the image to a resource group for tiered management. Important When you use an Alibaba Cloud account to add a permission policy to a RAM user, if the authorization scope is Specified Resource Group, make sure that you select the same resource group here.

Confirm the information and click OK.
The system creates a task to import the custom image.

(Optional) Step 3: View or cancel an import task

View an import task

You can view the progress of the import task in the custom image list of the destination region or on the Task Management page.

Note

The time required to import a custom image varies based on the image file size and the number of concurrent import tasks. Wait for the task to complete.

When you import a custom image, a snapshot is automatically generated. You can view information about the snapshot in the Snapshots list. The snapshot status is Failed during the import process. After the import is complete, the snapshot status changes to Completed and the image status changes to Available. The snapshot size corresponds to the size of the imported custom image file and is independent of the system disk size specified when you import the custom image. You are charged for snapshot capacity. For more information, see Snapshot billing.
If you enabled the image check feature, you can view the detailed check result in the Check Result column of the custom image list after the check is complete. If an item requires a fix, you can use the One-click Fix feature or manually fix the item based on the suggestions provided in the image details. For more information about the check items and recommended fixes, see Check and fix a custom image.

An import task may fail due to unexpected errors that occur when the image file is checked during the import process. These errors may affect subsequent operations, such as instance creation. You can identify and fix the issues as follows:

View the error code on the Task Management page or by calling the DescribeTaskAttribute API operation.

Check the error code details and fix the issue.

Error code details

Error code	Cause	Cause identification	Recommended solution
UNKNOWN_IMAGE_FORMAT	The image format is not supported.	Run the `qemu-img check` command to check the image format.	Convert the image format. We recommend that you use the RAW or VHD format. Note We recommend that you use the qemu-img tool to convert the image format and use the default parameters during the conversion. For more information, see Convert the format of an image.
IMAGE_SIZE_EXCEEDS_LIMIT	The image file is too large.	Run the `qemu-img info` command to check the image file size.	Reduce the size of the image file. Convert the image format. We recommend that you use the RAW or VHD format. Note We recommend that you use the qemu-img tool to convert the image format and use the default parameters during the conversion. For more information, see Convert the format of an image.
INVALID_IMAGE_SIZE	The image size cannot be retrieved.	Call the GetObject API operation to check whether information about the object can be returned.	Re-upload the image file to a new OSS object.
IMAGE_FILE_NOT_FOUND	The source of the image file cannot be found.	Call the GetObject API operation to check whether information about the object can be returned.	Do not delete the OSS object before the import task is complete. Do not use special characters in the names of OSS objects. For more information, see Object naming. Re-upload the image file to a new OSS object.
INVALID_IMAGE_FORMAT	The image format is invalid.	The format declared in the file header is not supported.	Check the image format. If the file is not in RAW or VHD format, we recommend that you convert the image to the RAW or VHD format. Note We recommend that you use the qemu-img tool to convert the image format and use the default parameters during the conversion. For more information, see Convert the format of an image.

Cancel an import task
Before the import task is complete, you can cancel the task in one of the following ways:
- Method 1: In the image list, click Cancel Import.
- Method 2: On the Task Management page, cancel the import task.
  1. In the navigation pane on the left, choose O&M and Monitoring > Task Management.
  2. Find the import task and click Cancel Task in the Actions column.

Billing

Importing a custom image incurs the following fees:

Before you import a custom image, you must upload the on-premises image file to OSS. This incurs OSS storage fees.
During the import process, uploading and downloading the image file in OSS incurs OSS traffic fees.
Importing a custom image involves calling OSS API operations. This incurs OSS request fees.
When you import a custom image into ECS, a snapshot is created by default. This incurs snapshot storage fees. By default, the pay-as-you-go billing method is used. For more information, see Snapshot billing.

FAQ

What do I do if I selected the wrong license type when importing a Windows Server image and incurred extra charges?

If you selected Alibaba Cloud License for the License Type parameter by mistake when you imported a Windows Server image, you are charged a license fee and the operating system is automatically activated when you use the image to create an ECS instance. You can call the ModifyImageAttribute API operation to change the license type to Bring Your Own License (BYOL).

You can call the DescribeImages operation to query the license type of the imported Windows Server image.

For new ECS instances: If you change the LicenseType of the imported image to BYOL, you are no longer charged a license fee for Windows Server and the operating system is not automatically activated when you create new ECS instances from the image.
For existing ECS instances: For ECS instances that were created from the original image, changing the image's LicenseType to BYOL does not stop the billing for Windows Server on those instances. To stop the billing, contact customer service to request a data correction.