ImportImage - Elastic Compute Service - Alibaba Cloud Documentation Center

Imports an image to Elastic Compute Service (ECS). The imported image appears as a custom image in the destination region. You can use the imported image to create ECS instances (RunInstances) or replace the system disks of ECS instances (ReplaceSystemDisk).

Description

Before you call this operation, take note of the following items:

Before you can import an image, you must upload the image to an Object Storage Service (OSS) bucket. For more information, see Upload objects.
In some scenarios, you may want to create a custom image based on operating system data of a source server, import the image to Alibaba Cloud ECS, and then create an ECS instance from the image. The source server can be a physical server, a virtual machine, or a cloud host. If the virtio driver is not installed on the source server, the created ECS instance may be unable to start. To prevent this issue, you must check that the virtio driver is installed on the source server before you import an image to Alibaba Cloud. For more information, see Install the virtio driver.
Before you import images for the first time, you must use Resource Access Management (RAM) to authorize ECS to access your OSS buckets. If ECS is not authorized to access your OSS buckets, the NoSetRoletoECSServiceAcount error code is returned when you call the ImportImage operation. You can complete this authorization in one click on the Cloud Resource Access Authorization page of the RAM console. You can also complete the authorization by using a RAM role and RAM policies. The following examples show the policies and permissions required for some steps in the authorization procedure. For more information, see Control access to resources by using RAM users.
1. Create a role named AliyunECSImageImportDefaultRole. You must use this exact role name. Otherwise, the image cannot be imported. Configure the following trust policy for the role:
```
        {
            "Statement": [
            {
                "Action": "sts:AssumeRole",
                "Effect": "Allow",
                "Principal": {
                "Service": [
                    "ecs.aliyuncs.com"
                ]
                }
            }
        ],
            "Version": "1"
        }
        
```
2. Attach the AliyunECSImageImportRolePolicy system policy to the role. You can also create a custom policy that contains the following content and attach the policy to the role:
```
        {
            "Version": "1",
            "Statement": [
            {
                "Action": [
                        "oss:GetObject",
                        "oss:GetBucketLocation",
                        "oss:GetBucketInfo"
            ],
                    "Resource": "*",
                    "Effect": "Allow"
                    }
            ]
        }
        
        
```
You cannot delete an image that is being imported. However, you can call the CancelTask operation to cancel the image import task.
You can import an image only to the same region as the OSS bucket to which the image was uploaded.
The valid values of N in the DiskDeviceMapping.N parameter range from 1 to 17. When N is set to 1, the disk is a system disk. When N is set to a value from 2 to 17, the disk is a data disk.
When you set the Architecture parameter to arm64 or when you set the Platform parameter to CentOS Stream, Anolis, AlmaLinux, UOS, Kylin, or Rocky Linux, take note of the following items:
- To allow the password to be set or the key pair to be modified for an imported image, make sure that the image meets the following requirements before you import it:
  - The operating system kernel supports the CONFIG_FW_CFG_SYSFS feature. By default, Linux community kernel 4.6 and later and CentOS kernel 3.10.0-826.el7 and later support this feature. You can run the grep -nr CONFIG_FW_CFG_SYSFS /boot/config-$(uname -r) command on the source server of the image. If the command output contains CONFIG_FW_CFG_SYSFS=y, the operating system kernel in this image supports the CONFIG_FW_CFG_SYSFS feature.
  - Alibaba Cloud cloud-init of the latest version is installed on the operating system. The version of cloud-init 19.1 must be 19.1.3 or later. The version of cloud-init 0.7.6a in some early versions of operating systems must be 0.7.6a15 or later. For more information, see Install cloud-init.
  - The operating system supports the SHA-512 encryption algorithm.
- If you want an imported image to support the resizing of disks and file systems, make sure that the image meets the following requirements before you import it:
  - The kernel version of the operating system is later than 3.6.
  - The image supports the growpart command. To support this command, you must install the cloud-utils-growpart package. The methods of installing the package vary based on the operating systems. For more information, see Resize partitions and file systems of Linux system disks.
  - The image supports the resize2fs command. To support this command, you must install thee2fsprogs package. By default, the package is installed on the operating system. If the package is not installed, install it on your own.
  - Alibaba Cloud cloud-init of the latest version is installed on the operating system. The version of cloud-init 19.1 must be 19.1.3 or later. The version of cloud-init 0.7.6a in some early versions of operating systems must be 0.7.6a15 or later. For more information, see Install cloud-init.
If the image that you want to import uses the ARM64 architecture, you must set the real-time clock (RTC) to use the Coordinated Universal Time (UTC) time standard. For more information, see Linux time and time zones.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	ImportImage	The operation that you want to perform. Set the value to ImportImage.
RegionId	String	Yes	cn-hangzhou	The region ID of the source custom image. You can call the DescribeRegions operation to query the most recent region list.
ImageName	String	No	ImageTestName	The name of the custom image. The name must be 2 to 128 characters in length. It must start with a letter and cannot start with `acs:` or `aliyun`. It cannot contain `http://` or `https://`. It can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-).
Description	String	No	TestDescription	The description of the custom image. The description must be 2 to 256 characters in length and cannot start with `http://` or `https://`.
Architecture	String	No	x86_64	The system architecture. Valid values: i386 x86_64 arm64 Default value: x86_64.
OSType	String	No	linux	The operating system platform. Valid values: windows linux Default value: linux.
Platform	String	No	Aliyun	The operating system distribution. Valid values: CentOS CentOS Stream Ubuntu SUSE openSUSE Debian CoreOS Aliyun Anolis AlmaLinux FreeBSD Fedora Rocky Linux UOS Kylin Others Linux Customized Linux Windows Server 2022 Windows Server 2019 Windows Server 2016 Windows Server 2012 Windows Server 2008 Windows Server 2003 Default value: Others Linux.
BootMode	String	No	BIOS	The boot mode of the custom image. Valid values: BIOS (default value) UEFI Note You must be aware of the boot modes supported by the specified image. When you use this parameter to change the boot mode of the image, specify a boot mode supported by the image to ensure that instances that use this image can start normally.
RoleName	String	No	AliyunECSImageImportDefaultRole	The name of the RAM role to use to import the source image.
LicenseType	String	No	Auto	The type of the license to use to activate the operating system after the source image is imported. Valid values: Auto: ECS checks the operating system of the source image and allocates a license to the operating system. ECS first checks whether the operating system distribution specified by `Platform` has a license allocated through an official Alibaba Cloud channel. If yes, the allocated license is used. If not, the license that comes with the source operating system is used. Aliyun: The license allocated through an official Alibaba Cloud channel is used for the operating system distribution specified by `Platform`. BYOL: The license that comes with the source operating system is used. In this case, make sure that your license key can be used in Alibaba Cloud. Default value: Auto.
ResourceGroupId	String	No	rg-bp67acfmxazb4p****	The ID of the resource group to which to assign the custom image.
DiskDeviceMapping.N.DiskImSize	Integer	No	80	The size of the custom image. Note This parameter will be removed in the future. To ensure future compatibility, we recommend that you use the `DiskDeviceMapping.N.DiskImageSize` parameter.
DiskDeviceMapping.N.Device	String	No	null	The device name of disk N in the custom image. Note This parameter will be removed in the future. To ensure future compatibility, we recommend that you do not use this parameter.
DiskDeviceMapping.N.OSSBucket	String	No	ecsimageos	The OSS bucket in which the source image is stored. Note Before you import images for the first time, you must use RAM to authorize ECS to access your OSS buckets. If ECS is not authorized to access your OSS buckets, the NoSetRoletoECSServiceAcount error code is returned when you call the ImportImage operation. For more information, see the `Description` section of this topic.
DiskDeviceMapping.N.Format	String	No	QCOW2	The format of the custom image. Valid values: RAW VHD QCOW2 This parameter is empty by default, which indicates that the system checks the format of the custom image and uses the check result as the value of this parameter.
DiskDeviceMapping.N.OSSObject	String	No	CentOS_5.4_32.raw	The name (key) of the object that the uploaded source image is stored as in the OSS bucket.
DiskDeviceMapping.N.DiskImageSize	Integer	No	80	The size of disk N in the custom image. You can use this parameter to specify the sizes of the system disk and data disks in the custom image. When you specify the size of the system disk, make sure that the specified size is greater than or equal to the size of the custom image file. Unit: GiB. Valid values: When the N value is 1, this parameter specifies the size of the system disk in the custom image. Valid values: 5 to 500. When the N value is an integer in the range of 2 to 17, this parameter specifies the size of a data disk in the custom image. Valid values: 5 to 2000. After the source image is uploaded to an OSS bucket, you can view the size of the image in the OSS bucket.
Tag.N.Key	String	No	TestKey	The key of tag N to add to the custom image. Valid values of N: 1 to 20. The tag key cannot be an empty string. It can be up to 128 characters in length and cannot contain `http://` or `https://`. It cannot start with `aliyun` or `acs:`.
Tag.N.Value	String	No	TestValue	The value of tag N to add to the custom image. Valid values of N: 1 to 20. The tag value can be an empty string. It can be up to 128 characters in length and cannot start with `acs:`. It cannot contain `http://` or `https://`.
DetectionStrategy	String	No	Standard	The mode in which to check the source image. If you do not specify this parameter, the source image is not checked. Only Linux images can be checked. Set the value to Standard, which indicates standard check mode. The following items are checked in standard check mode: Virtio: whether the virtio driver is installed. Fstab: whether mounting configurations in the fstab file are correct. Grub: whether GRUB configurations are correct. SystemImage: whether the image is valid. Do not import images that are in the ISO format or empty. CloudInit: whether cloud-init is installed. NVMe: whether the NVMe driver is installed. Selinux: whether SElinux is enabled. OnlineResizeFS: whether the root partition can be automatically resized. Dhcp: whether Dynamic Host Configuration Protocol (DHCP) is enabled for network interface controllers (NICs). RtcTimeMode: the RTC time mode. Platform: the platform. Example: Linux or Windows. OSVersion: the operating system version. Example: Centos 7.9. Architecture: the architecture. Example: ARM or x86_64. BootMode: the boot mode. Example: UEFI or Legacy. KernelVersion: the kernel version. CloudAssistant: whether the Cloud Assistant client is installed. SecurityCenterAgent: whether the Security Center agent is installed.

Response parameters


Parameter	Type	Example	Description
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****	The ID of the request.
ImageId	String	m-bp67acfmxazb4p****	The ID of the custom image.
TaskId	String	t-bp67acfmxazb4p****	The ID of the image import task.
RegionId	String	cn-hangzhou	The region ID of the image.

Examples

Sample requests

http(s)://ecs.aliyuncs.com/?Action=ImportImage
&RegionId=cn-hangzhou
&DiskDeviceMapping.1.Format=QCOW2
&DiskDeviceMapping.1.OSSBucket=ecsimageos
&DiskDeviceMapping.1.OSSObject=CentOS_5.4_32.raw
&DiskDeviceMapping.1.DiskImageSize=80
&ImageName=Test
&Description=Test
&Architecture=x86_64
&OSType=linux
&Platform=Aliyun
&LicenseType=Aliyun
&DetectionStrategy=Standard
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<ImportImageResponse>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3****</RequestId>
    <ImageId>m-bp67acfmxazb4p****</ImageId>
    <TaskId>t-bp67acfmxazb4p****</TaskId>
    <RegionId>cn-hangzhou</RegionId>
</ImportImageResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
  "ImageId" : "m-bp67acfmxazb4p****",
  "TaskId" : "t-bp67acfmxazb4p****",
  "RegionId" : "cn-hangzhou"
}

Error codes


HTTP status code	Error code	Error message	Description
400	InvalidImageName.Malformed	The specified Image name is wrongly formed.	The error message returned because the specified ImageName parameter is invalid. The name must be 2 to 128 characters in length. It must start with a letter and cannot start with acs: or aliyun. It cannot contain http:// or https://. It can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-).
400	InvalidOSSObject.Malformed	The specified OSS object is wrongly formed.	The error message returned because the specified DiskDeviceMapping.N.OSSObject parameter is invalid.
400	InvalidDescription.Malformed	The specified Image description is wrongly formed.	The error message returned because the specified Description parameter is invalid.
400	InvalidArchitecture.Malformed	The specified Architecture is wrongly formed.	The error message returned because the specified Architecture parameter is invalid.
400	InvalidPlatform.Malformed	The specified Platform is wrongly formed.	The error message returned because the specified Platform parameter is invalid.
400	InvalidOSType.Malformed	The specified OSType is wrongly formed.	The error message returned because the specified OSType parameter is invalid.
400	InvalidImageName.Duplicated	The destination image is exist.	The error message returned because the specified image name already exists.
400	InvalidImageSize	%s	The error message returned because the specified image size is invalid.
400	InvalidDataDiskSize	The specified DiskDeviceMapping.N.DiskImSize should be in the specified range.	The error message returned because the specified DiskDeviceMapping.N.DiskImSize parameter is invalid.
400	InvalidImageFormat.Malformed	The specified Image Format is wrongly formed.	The error message returned because the specified ImageFormat parameter is invalid.
400	InvalidRegionId.NotFound	The specified RegionId does not exist.	The error message returned because the specified RegionId parameter is invalid.
400	InvalidRegion.NotSupport	The specified region does not support image import or export.	The error message returned because the specified region does not support the operation.
400	InvalidOSSBucket.NotFound	The specified OSS bucket does not exist in this region.	The error message returned because the specified OSS bucket does not exist.
400	InvalidOSSObject.NotFound	The specified OSS object does not exist in this region.	The error message returned because the specified OSS object does not exist.
400	InvalidOSSObject.NotFound	The specified OSS object cannot be retrieved.	The error message returned because the specified OSS object cannot be found.
400	InvalidOSSBucket.NotMatched	The specified OSS bucket is incorrect, %s.	The error message returned because the specified DiskDeviceMapping.N.OSSBucket parameter is invalid. For more information, see the return value of the %s placeholder in the error message.
400	InvalidLicenseType.NotSupported	The specified LicenseType is not supported	The error message returned because the specified LicenseType parameter is invalid.
400	InvalidLicenseType.BYOLOnly	Only BYOL LicenseType is supported for the current platform provided	The error message returned because the current platform supports only BYOL licenses.
403	ImageIsImporting	The specified Image is importing.	The error message returned because the specified image is being imported and cannot be managed.
403	QuotaExceed.Image	The Image Quota exceeds.	The error message returned because the quota for custom images has been used up.
403	ImportImageFailed	Importing image is failed, Please contact the administrator.	The error message returned because the image cannot be imported. Contact a system administrator.
403	UserNotInTheWhiteList	The user is not in the white list of importing image.	The error message returned because you are not authorized to import images.
403	NoSetRoletoECSServiceAcount	ECS service account Have no right to access your OSS.please attach a role of access your oss to ECS service account.	The error message returned because ECS is not authorized to access the specified OSS bucket or object.
403	MissingParameter.DiskDeviceMapping	The specified parameter DiskDeviceMapping is not supplied.	The error message returned because a parameter that starts with DiskDeviceMapping is not specified.
403	InvalidOSS.NotAuthorized	The specified OSS bucket or object is not allowed to access	The error message returned because you do not have permissions to access the specified OSS bucket or object.

For a list of error codes, visit the API Error Center.