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

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

  • You must upload an image to an Object Storage Service (OSS) bucket before you can import the image. For more information, see Upload objects.
  • In some scenarios, you may want to create a custom image based on the operating system data of a source server, import the image to Alibaba Cloud, and then create an Elastic Compute Service (ECS) instance from the image. The source server can be a physical server, a virtual machine, or a cloud host. If the source server is not installed with the virtio driver, the created ECS instance may not be able to start. To prevent this issue, you must check whether the virtio driver is installed on the source server before you import a custom image to Alibaba Cloud. For more information, see Install the virtio driver.
  • The first time you import an image, 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 perform one-click authorization on the Cloud Resource Access Authorization page in the RAM console. You can also manually complete the authorization. The following examples show the policies and permissions required for some operations: 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 ranges 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 the Architecture parameter is set to arm64, or when the Platform parameter is set to CentOS Stream, Anolis, AlmaLinux, or Rocky Linux, take note of the following items:
    • To ensure that the password can be set or the key pair can be modified for an imported image, the image must meet the following requirements:
      • The kernel of the operating system must support the CONFIG_FW_CFG_SYSFS feature. By default, the 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 in the server corresponding to the image. If the command output contains CONFIG_FW_CFG_SYSFS=y, the kernel of this image supports the CONFIG_FW_CFG_SYSFS feature.
      • The operating system is installed with the latest version of Alibaba Cloud cloud-init. 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 must support the SHA-512 encryption algorithm.
    • To ensure that the imported image supports resizing of disks and file systems, the image must meet the following requirements:
      • The kernel version of the operating system must be later than 3.6.
      • The image must support 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 must support the resize2fs command. To support this command, you must install thee2fsprogs package. The package is installed in the operating system by default. If the package is not installed, install it on your own.
      • The operating system is installed with the latest version of Alibaba Cloud cloud-init. 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.

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 OSS bucket to which the image to be imported was uploaded. 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 type. Valid values:

  • windows
  • linux

Default value: linux.

Platform String No Aliyun

The distribution of the operating system. Valid values:

  • CentOS
  • CentOS Stream
  • Ubuntu
  • SUSE
  • OpenSUSE
  • Debian
  • CoreOS
  • Aliyun
  • Anolis
  • AlmaLinux
  • Rocky Linux
  • 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
  • UEFI

Default value: BIOS. If the Architecture parameter is set to arm64, set this parameter to UEFI.

Note You must know which boot modes the specified image supports. 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 which use this image can be started normally.
RoleName String No AliyunECSImageImportDefaultRole

The name of the RAM role used to import the source image.

LicenseType String No Auto

The type of the license used 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 by an official Alibaba Cloud channel. If yes, the allocated license is used. If no, 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. We recommend that you use the DiskDeviceMapping.N.DiskImageSize parameter to ensure future compatibility.
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. We recommend that you use other parameters to ensure future compatibility.
DiskDeviceMapping.N.OSSBucket String No ecsimageos

The OSS bucket where the source image is stored.

Note The first time you import an image, 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.
DiskDeviceMapping.N.Format String No QCOW2

The format of the source 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 after the image is imported.

The value may be the size of the system disk or that of the data disk. When N is 1, the disk is a system disk. When N is a value in the range of 2 to 17, the disk is a data disk. The size of the system disk must be greater than or equal to the size of the imported image. Valid values:

  • Valid values when the N value is 1: 5 GiB to 500 GiB.
  • Valid values when the N value ranges from 2 to 17: 5 GiB to 1000 GiB.

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 of 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 must not start with acs: or aliyun.

Tag.N.Value String No TestValue

The value of tag N of 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://.

Response parameters

Parameter Type Example Description
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

ImageId String m-bp67acfmxazb4p****

The ID of the 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

https://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
&<Common request parameters>

Sample success responses

XML format

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

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

JSON format

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

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

Error codes

HTTP status code Error code Error message Description
400 MissingParameter An input parameter "RegionId" that is mandatory for processing the request is not supplied. The error message returned because the RegionId parameter is not specified.
400 MissingParameter An input parameter "DiskDeviceMapping.1.OSSBucket" that is mandatory for processing the request is not supplied. The error message returned because the DiskDeviceMapping.N.OSSBucket parameter is not specified.
400 MissingParameter An input parameter "DiskDeviceMapping.1.OSSObject" that is mandatory for processing the request is not supplied. The error message returned because the DiskDeviceMapping.N.OSSBucket parameter is not specified.
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 does not exist.
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 custom image quota 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 InvalidParameter.Malformed The specified parameter "DiskDeviceMapping.n.Device " is not valid. The error message returned because the specified DiskDeviceMapping.N.Device parameter is invalid.
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 the permissions to access the specified OSS bucket or object.

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