All Products
Search
Document Center

:ImportImage

最終更新日:Dec 25, 2023

Imports an image to Elastic Compute Service (ECS). The imported image exists 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).

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.

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 image name. The name must be 2 to 128 characters in length. The name must start with a letter and cannot start with acs: or aliyun. The name cannot contain http:// or https://. The name can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-).

Description String No TestDescription

The image description. The description must be 2 to 256 characters in length, and cannot start with http:// or https://.

Architecture String No x86_64

The operating 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:

  • Aliyun
  • Anolis
  • CentOS
  • Ubuntu
  • CoreOS
  • SUSE
  • Debian
  • OpenSUSE
  • FreeBSD
  • RedHat
  • Kylin
  • UOS
  • Fedora
  • Fedora CoreOS
  • CentOS Stream
  • AlmaLinux
  • Rocky Linux
  • Gentoo
  • Customized Linux
  • Others 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 image. Valid values:

  • BIOS
  • UEFI

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

Note You must be familiar with 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 image.

LicenseType String No Auto

The type of the license to use to activate the operating system after the image is imported. Valid values:

  • Auto: ECS detects the operating system of the 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 image.

DiskDeviceMapping.N.DiskImSize Integer No 80

The size of disk N in the custom image after the image is imported. Unit: GiB.

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 imported 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 image file is uploaded to an OSS bucket, you can view the size of the image file in the OSS bucket.

Note This parameter will be removed in the future. We recommend that you use DiskDeviceMapping.N.DiskImageSize 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 do not use this parameter to ensure future compatibility.
DiskDeviceMapping.N.OSSBucket String No ecsimageos

The OSS bucket where the 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 "Usage notes" section in this topic.
DiskDeviceMapping.N.Format String No QCOW2

The format of the image. Valid values:

  • RAW
  • VHD
  • QCOW2

This parameter is empty by default, which indicates that the system checks the format of the 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 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.

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 imported 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 image file is uploaded to an OSS bucket, you can view the size of the image file 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. The tag key can be up to 128 characters in length and cannot contain http:// or https://. The tag key cannot start with acs: or aliyun.

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. The tag value can be up to 128 characters in length and cannot contain http:// or https://. The tag value cannot start with acs:.

DetectionStrategy String No Standard

The mode in which to check the image. If you do not specify this parameter, the image is not checked. Only the standard check mode is supported.

Note This parameter is supported for most Linux and Windows images. For more information about image check items and operating system limits for image check, see Overview of image check and Operating system limits for image check.

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 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 UnsupportedSuffix.OSSObject The specified OSS object suffix is not supported. The specified OSS object suffix is not supported.
400 InvalidImageName.Malformed The specified Image name is wrongly formed. Invalid ImageName format. The name must be 2 to 128 characters in length. The name must start with a letter and cannot start with acs: or aliyun. It cannot contain http:// or https://. The name can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-).
400 InvalidOSSObject.Malformed The specified OSS object is wrongly formed. Invalid DiskDeviceMapping.N.OSSObject value.
400 InvalidDescription.Malformed The specified Image description is wrongly formed. Invalid Description format.
400 InvalidArchitecture.Malformed The specified Architecture is wrongly formed. Invalid Architecture format.
400 InvalidPlatform.Malformed The specified Platform is wrongly formed. Invalid Platform value.
400 InvalidOSType.Malformed The specified OSType is wrongly formed. Invalid OSType format.
400 InvalidImageName.Duplicated The destination image is exist. The image name already exists.
400 InvalidImageSize %s Invalid image size.
400 InvalidDataDiskSize The specified DiskDeviceMapping.N.DiskImSize should be in the specified range. Invalid DiskDeviceMapping.N.DiskImSize value.
400 InvalidImageFormat.Malformed The specified Image Format is wrongly formed. Invalid ImageFormat value.
400 InvalidRegionId.NotFound The specified RegionId does not exist. Invalid RegionId value.
400 InvalidRegion.NotSupport The specified region does not support image import or export. This operation cannot be performed on the image in the specified region.
400 InvalidOSSBucket.NotFound The specified OSS bucket does not exist in this region. The OSS bucket is not found.
400 InvalidOSSObject.NotFound The specified OSS object does not exist in this region. The OSS object is not found.
400 InvalidOSSBucket.NotMatched The specified OSS bucket is incorrect, %s. Invalid DiskDeviceMapping.N.OSSBucket value. For more information, see the return value of the %s placeholder in the error message.
403 ImageIsImporting The specified Image is importing. The specified image is being imported. The operation cannot be performed.
403 QuotaExceed.Image The Image Quota exceeds. The custom image quota has been exhausted.
403 ImportImageFailed Importing image is failed, Please contact the administrator. The image cannot be imported. Contact a system administrator.
403 UserNotInTheWhiteList The user is not in the white list of importing image. 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. ECS is not authorized to access the specified OSS bucket or object.
403 MissingParameter.DiskDeviceMapping The specified parameter DiskDeviceMapping is not supplied. A parameter that starts with DiskDeviceMapping is required.
403 InvalidVHDImage.IncorrectSize The specified size of the VHD image does not meet the 'header.MaxTableEntries * header.BlockSize' specification. The size of the specified VHD image does not meet the limit of header.MaxTableEntries multiplied by header.BlockSize.
403 InvalidOSSBucket.EncryptUnsupported Accessing objects from encrypted OSS bucket is not supported. You cannot read objects from encrypted OSS buckets.
403 InvalidArchitecture.PlatformUnsupported The OS platform you selected does not support the specified architecture. The selected operating system does not support the specified architecture type.
403 InvalidAccountStatus.OSSDisabled OSS is disabled due to invalid account status. OSS is deactivated because the account is invalid.
404 InvalidResourceGroup.NotFound The ResourceGroup provided does not exist in our records. The resource group is not found.

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