:ImportImage

Usage notes

Take note of the following items:

• Before you 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 an image based on operating system data of a source server, import the image to ECS, and then create an ECS instance from the imported 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 verify that the virtio driver is installed on the source server before you import an image. 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 the authorization with 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 file is uploaded.
• The valid values of N in DiskDeviceMapping.N 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 N is set to a value greater than 17, parameters prefixed with DiskDeviceMapping.N are ignored.
• When you set Architecture to arm64 or when you set Platform to CentOS Stream, Anolis, AlmaLinux, UOS, Kylin, 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, make sure that the image meets the following requirements before you import it:
    • The kernel of the operating system 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 kernel of the image supports the CONFIG_FW_CFG_SYSFS feature.
    • Alibaba Cloud cloud-init of the latest version is installed on the operating system. If the version of cloud-init is 19.1, the minor version must be 19.1.3 or later. If the version of cloud-init is 0.7.6a in some early versions of operating systems, the minor version 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 operating systems. For more information, see Extend the partitions and file systems of disks on a Linux instance.
    • The image supports the resize2fs command. To support this command, you must install the e2fsprogs package. By default, the package is installed on the operating system. If the package is not installed, install it.
    • Alibaba Cloud cloud-init of the latest version is installed on the operating system. If the version of cloud-init is 19.1, the minor version must be 19.1.3 or later. If the version of cloud-init is 0.7.6a in some early versions of operating systems, the minor version 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 configure the real-time clock (RTC) to use the Coordinated Universal Time (UTC) time standard. For more information, see Linux time and time zones.
• When you import images, we recommend that you specify DetectionStrategy. This way, you can optimize the images based on the image check results. For more information, see Image check items.

Request parameters

Response parameters

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

For a list of error codes, see Service error codes.