Import a local custom image in the Alibaba Cloud ECS console-Elastic Compute Service(ECS)-阿里云帮助中心

Prerequisites

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

Refer to Image import limits and requirements to make sure that the image file meets all import requirements to avoid 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.

Differences between QCOW2, VHD, and RAW formats

Format	Description	Features
QCOW2	A virtual machine image format for QEMU. It uses a single file to represent a block device and supports dynamic disk space allocation.	Uses less disk space. Supports copy-on-write (CoW), where the image file reflects only the changes that are made to the underlying disk. Supports multiple historical snapshots. Supports ZLIB compression and AES encryption.
VHD	A virtual disk file format from Microsoft. A VHD file can be compressed into a single file on the file system of the local host and used for various purposes.	Easy to maintain. You can partition, format, compress, or delete the virtual disk without affecting physical partitions. Easy to back up. You can back up only the VHD file or the entire physical partition that contains the VHD file. Easy to migrate. To use a VHD file on another computer, detach the file from the current computer, copy it to the target computer, and then attach it. Can be used for direct system deployment. You can use the ImageX tool to apply a captured image to a VHD or use a Windows Deployment Services (WDS) server to deploy a system to a VHD.
RAW	A direct read/write file format that does not support dynamic space allocation. This format provides the best I/O performance among all image formats.	Offers simple addressing and high access efficiency. Can be easily converted to other formats by using conversion tools. Can be mounted on a local host. This allows data transfer between the image file and the host without starting the virtual machine.

Grant ECS permissions to access Object Storage Service (OSS) resources. ECS obtains these permissions by assuming the AliyunECSImageImportDefaultRole role.

If this is the first time you import an image, follow the instructions in the wizard on the Images page of the ECS console to grant the required permissions.

To import a custom image as a RAM user, an Alibaba Cloud account must first grant that user the required permissions for the OSS bucket. For more information, see Authorize a RAM user to access an OSS bucket.

Video tutorial

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

Procedure

Step 1: Prepare and upload image file

Before importing an image, you need to upload a compliant image file to Object Storage Service (OSS). Ensure the image file meets the requirements in Image import limits and requirements. Otherwise, the import may fail, or instances created from the image may not function correctly.

Upload your local image file to OSS and obtain the file URL. For more information, see Methods for uploading files to OSS.

Note

To include data disks in the imported image, you must prepare separate image files for the system disk and each data disk and then upload the files to OSS. When you create an ECS instance from the custom image, the instance includes both the system disk and the data disks.

Step 2: Import the custom image

Go to the Images page of the ECS console. In the upper-left corner of the page, select the region and resource group for the target resources. Then, in the top navigation bar, select your project from the Product/Project drop-down list and verify that the correct account is selected in the Account drop-down list on the right.
Important
The selected region must match the region of the OSS bucket where the image file is stored.
Finance Cloud regions

A Finance Cloud region may have different names in ECS and OSS. The following table describes the mappings.

The China (Hangzhou) Finance region in ECS (cn-hangzhou) corresponds to the oss-cn-hzfinance region in OSS.

The China (Shanghai) Finance region in ECS (cn-shanghai-finance-1) corresponds to the oss-cn-shanghai-finance-1-pub region in OSS.

The China (Shenzhen) Finance region in ECS (cn-shenzhen-finance-1) corresponds to the oss-cn-szfinance region in OSS.

The China (Beijing) Finance region in ECS (cn-beijing-finance-1) corresponds to the oss-cn-beijing-finance-1 region in OSS.
On the Images page, click Import Image > Import Image in the upper-right corner.
On the Prepare Before Import page of the wizard, confirm that the preparations are complete, click Next, and then click Confirm.

On the Import Image File page of the wizard, configure the following parameters.

Parameter	Required	Description
Image File URL	Yes	Enter the URL of the image file that you obtained in Step 1. The region of the OSS image file must match the currently selected region. To change the region, select a new region from the top menu bar and then reopen the Import Image dialog box.
Image Name	Yes	Enter a name for the image that will be displayed after it is imported. 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 (-).
OS Type	Yes	Select the OS type of the image file to import. This must match the actual OS type of the image file. Valid values: Windows and linux. If the operating system of the image is not in the supported platform list, select linux.
OS Version	Yes	Select the OS version of the image file to import. This must match the actual OS version of the image file. If your operating system is not on the list of supported platforms, you have the following options: Select Aliyun Customized Linux: Make sure that you have manually added parsing scripts to ensure that the image is available. For more information, see Customize a Linux image. Select Others Linux: ECS performs no processing on the instance created from this image. After the instance is created, you must manually configure the IP address, routes, and password within the instance. If your operating system is a custom version based on the Linux kernel, submit a ticket.
System Architecture	Yes	Select the system architecture of the image file. Supported architectures: i386 (32-bit) x86_64 (64-bit) arm64 (64-bit)
License Type	This parameter is required when OS Type is set to Windows.	The license type used to activate the 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, and the OS is automatically activated by Alibaba Cloud's activation servers. For more information about billing, see Image billing. BYOL: When you create an instance from the imported image, Alibaba Cloud does not charge an OS license fee or automatically activate Windows Server. You must provide a valid license and manually activate the OS.
Detect Image	No	The image check feature verifies whether a custom image is valid and can be used to create fully functional ECS instances. By default, Check After Import is selected. The image check runs immediately after the image import is complete. After the check is complete, you can view the details in the Check Result column of the custom image list. If any items need to be fixed, you can use the Fix feature or manually apply the repairs suggested in the image details. Note The image check feature is available only for specific operating systems. For a list of unsupported operating systems, see OS limits for image check.
Boot Mode	No	Select the boot mode of the image. Valid values: BIOS and UEFI. The boot mode specifies the method used to start the system disk when an ECS instance is created. This setting should match the boot mode of your image file. Otherwise, instances created from the custom image may fail to start.
Image Format	No	You can select Auto (default), or specify the format as RAW, QCOW2, VHD, or VMDK. We recommend that this setting match the format of your image file. If you are unsure of the image format, select Auto. The system automatically detects and sets the image format to match your image file. Note ECS does not support importing ISO image files directly. You must convert the ISO file to a supported image format before you import it. For more information, see How do I convert an ISO file to an ECS-supported image format?
Disk Configuration	No	Set the system disk capacity and add data disk images. Select Configure Disk Properties. The system disk parameters are pre-filled. You only need to specify the system disk capacity. The size must be between 1 GiB and 2,048 GiB and be at least as large as the image file. Note The image file size is the size of the image file in OSS, which you can view in the OSS console. Click Add Data Disk and configure the parameters. Image File URL: Enter the URL of the data disk image file that you obtained in Step 1. The method for obtaining the URL is the same as that for the system disk. Mount Point: Automatically assigned by the system. Image Format: You can select Auto, or specify the format as RAW, QCOW2, VHD, or VMDK. The setting must match the format of your image file. Disk Capacity (GiB): The size must be between 1 GiB and 2,048 GiB and be at least as large as the image file. Note The image file size is the size of the image file in OSS, which you can view in the OSS console.
Image Description	No	Enter a description for the image to facilitate future management.
Tag	No	Add tags to the image to categorize it for easier searching and batch operations.
Resource Group	No	You can assign the image to a resource group for hierarchical management. Important If an Alibaba Cloud account grants a RAM user permissions that are scoped to a specific resource group, make sure that you select the same resource group here.

After you confirm that the information is correct, click OK.

The system creates a task to import the custom image.

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

View the import task

You can check the progress of the import task in the custom image list for the target 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.

When you import a custom image, a snapshot is automatically created. You can view its information in the Snapshots list. Before the import task is complete, the snapshot status is displayed as Failed. After the task is complete, the snapshot status changes to Completed, and the image status changes to Available. The capacity of the snapshot is equal to the size of the imported custom image file, regardless of the system disk size that you specified during the import. Snapshots are a paid service. For more information, see Snapshot billing.
If you enabled the image check feature, you can view the results in the Check Result column of the custom image list after the check is complete. If any items need to be fixed, you can use the Fix feature or manually apply the repairs suggested in the image details. For more information about the check items and repair suggestions, see Check and repair a custom image.

An import task can fail due to an unexpected error during file validation. Such errors may affect subsequent operations such as instance creation. You can follow these steps to identify and fix the issue.

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

Use the error code to identify and fix the issue.

Error codes

Error code	Cause	Troubleshooting	Solution
UNKNOWN_IMAGE_FORMAT	The image file format is not supported.	Run the `qemu-img check` command to check the image file 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 with default parameters to convert the image file format. For more information, see Convert image formats.
IMAGE_SIZE_EXCEEDS_LIMIT	The image file is too large.	Run the `qemu-img info` command to check the image file size.	Reduce the image file size. Convert the image format. We recommend that you use the RAW or VHD format. Note We recommend that you use the qemu-img tool with default parameters to convert the image file format. For more information, see Convert image formats.
INVALID_IMAGE_SIZE	The image size could not be retrieved.	Call the OSS API operation GetObject to verify that the object exists and is accessible.	Try re-uploading the image file to a new OSS object.
IMAGE_FILE_NOT_FOUND	The source of the image file cannot be found.	Call the OSS API operation GetObject to verify that the object exists and is accessible.	Do not delete the OSS object before the import task is complete. Avoid using special characters in OSS file names. For more information, see Object naming conventions. Try re-uploading the image file to a new OSS object.
INVALID_IMAGE_FORMAT	Invalid image format.	The format declared in the file header is not supported.	Check the image file format. For formats other than RAW or VHD, we recommend that you convert the image to the RAW or VHD format. Note We recommend that you use the qemu-img tool with default parameters to convert the image file format. For more information, see Convert image formats.

Cancel the import task
You can cancel an in-progress import task in one of two ways:
- Method 1: In the image list, click Cancel Import.
- Method 2: On the Task Management page, cancel the image import task.
  1. In the left-side navigation pane, choose Maintenance & Monitoring > Tasks.
  2. Find the custom image import task and click Cancel in the Actions column.

Billing details

Importing a custom image incurs the following fees:

Before you import a custom image, you must upload the local image file to OSS. This operation incurs OSS storage fees.
During the import process, the image file is uploaded to and downloaded from OSS. These operations incur OSS data transfer fees.
The import process calls OSS APIs. This operation incurs OSS API request fees.
When you import a custom image into ECS, a snapshot is created by default. This incurs snapshot storage fees, which are billed on a pay-as-you-go basis. For more information, see Snapshot billing.

FAQ

What do I do if I selected the wrong license type when I imported a Windows Server image, which resulted in extra charges?

If you accidentally set the license type to Alibaba Cloud License when you imported a Windows Server image, instances that are created from this image will be charged a license fee and automatically activated. You can call the ModifyImageAttribute API operation to change the LicenseType attribute to BYOL.

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

For new ECS instances: If you change the LicenseType value of the imported image to BYOL, new instances that are created from the image will no longer incur Windows Server license fees and are not automatically activated.
For existing ECS instances: For instances already created from the original image, changing the image's LicenseType to BYOL does not stop Windows Server billing. To stop the billing, contact customer service to request a data correction.