All Products
Search
Document Center

Elastic Compute Service:ImportImage

Last Updated:Dec 03, 2024

Imports an on-premise 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 by calling the RunInstances operation or replace the system disks of ECS instances by calling the ReplaceSystemDisk operation.

Operation description

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 specific 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 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, verify that the virtio driver is installed on the source server before you import the 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 NoSetRoletoECSServiceAccount or InvalidOperation.CloudBoxImageImportRoleRequired error code is returned when you call the ImportImage operation. The authorization configuration varies based on whether the image files are imported from a cloud box.

    • If the image files are not imported from a cloud box, you can complete the authorization 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 example shows the policies and permissions required for specific steps in the authorization procedure. For more information, see Control access to ECS resources by using RAM users.

      1. Create a RAM 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 RAM 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"
        			}
        	]
        }
        
    • If the image files are imported from a cloud box, you can complete the authorization 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 example shows the policies and permissions required for specific steps in the authorization procedure. For more information, see Control access to ECS resources by using RAM users.

      1. Create a RAM role named AliyunECSCloudBoxImageImportDefaultRole. 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 AliyunECSCloudBoxImageImportRolePolicy system policy to the RAM 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-cloudbox:GetObject",
        				"oss-cloudbox:GetBucketLocation",
        				"oss-cloudbox: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 the CONFIG_FW_CFG_SYSFS 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, 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 Overview of image check.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ecs:ImportImageupdate
*All Resources
*
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID of the source image. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
ImageNamestringNo

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 (-).

ImageTestName
DescriptionstringNo

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

TestDescription
ArchitecturestringNo

The system architecture. Valid values:

  • i386
  • x86_64
  • arm64

Default value: x86_64.

x86_64
OSTypestringNo

The operating system platform. Valid values:

  • windows
  • linux

Default value: linux.

linux
PlatformstringNo

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.

Aliyun
BootModestringNo

The boot mode of the image. Valid values:

  • BIOS
  • UEFI

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

Note Make sure that you are aware of the boot modes supported by the specified image, as thehe modified boot mode needs to be supported by the image. This way, instances that use this image can start.
BIOS
RoleNamestringNo

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

AliyunECSImageImportDefaultRole
LicenseTypestringNo

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

  • Auto: ECS checks 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 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 is eligible for use in Alibaba Cloud.

Default value: Auto.

Auto
ResourceGroupIdstringNo

The ID of the resource group to which to assign the image.

rg-bp67acfmxazb4p****
DiskDeviceMappingarray<object>No

The information of disks from which the custom images are created.

objectNo

The information of disk N from which a custom image is created.

DiskImSizeintegerNo

The size of disk N in the custom image. 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: 1 to 2048.
  • 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: 1 to 2048.

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.
80
DevicestringNo

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.
null
OSSBucketstringNo

The OSS bucket where the image file 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.
ecsimageos
FormatstringNo

The image format. 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.

QCOW2
OSSObjectstringNo

The name (key) of the object that the uploaded image is stored as in the OSS bucket.

CentOS_5.4_32.raw
DiskImageSizeintegerNo

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: 1 to 2048.
  • 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: 1 to 2048.

After the image file is uploaded to an OSS bucket, you can view the size of the image file in the OSS bucket.

80
Tagarray<object>No

The image tags.

objectNo

The information about the tags.

KeystringNo

The key of tag N of the 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.

TestKey
ValuestringNo

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

TestValue
DetectionStrategystringNo

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 operating system versions. For more information about image check items and operating system limits for image check, see Overview and Operating system limits for image check.
Standard
StorageLocationArnstringNo

The Alibaba Cloud Resource Name (ARN) of the cloud box, which is used to uniquely identify a storage location in the cloud.

Note Specify this parameter only if you import an image from OSS on CloudBox. Otherwise, you do not need to specify this parameter. For more information, see What is OSS on CloudBox?

The ARN must be in the following format: arn:acs:cloudbox:{RegionId}:{AliUid}:cloudbox/{CloudBoxId}. Replace {RegionId} with the region ID of the cloud box, {AliUid} with the ID of the Alibaba Cloud account to which the cloud box belongs, and {CloudBoxId} with the ID of the cloud box.

arn:acs:cloudbox:cn-hangzhou:123456:cloudbox/cb-xx***123
DryRunbooleanNo

Specifies whether to perform only a dry run, without performing the actual request. Valid values:

  • true: performs only a dry run. The system checks the request for potential issues, including invalid AccessKey pairs, unauthorized RAM users, and missing parameter values. If the request fails the dry run, an error message is returned. If the request passes the dry run, the DryRunOperation error code is returned.
  • false: performs a dry run and performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.

Default value: false.

false
FeaturesobjectNo

The attributes of the custom image.

NvmeSupportstringNo

Specifies whether the image supports the Non-Volatile Memory Express (NVMe) protocol. Valid values:

  • supported: The image supports the NVMe protocol. Instances created from the image also support the NVMe protocol.
  • unsupported: The image does not support the NVMe protocol. Instances created from the image do not support the NVMe protocol.
supported

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The request ID.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3****
ImageIdstring

The image ID.

m-bp67acfmxazb4p****
TaskIdstring

The image import task ID.

t-bp67acfmxazb4p****
RegionIdstring

The region ID.

cn-hangzhou

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status codeError codeError messageDescription
400UnsupportedSuffix.OSSObjectThe specified OSS object suffix is not supported.-
400MissingParameterAn input parameter "RegionId" that is mandatory for processing the request is not supplied.-
400MissingParameterAn input parameter "DiskDeviceMapping.1.OSSBucket" that is mandatory for processing the request is not supplied.-
400MissingParameterAn input parameter "DiskDeviceMapping.1.OSSObject" that is mandatory for processing the request is not supplied.-
400InvalidImageName.MalformedThe specified Image name is wrongly formed.The specified image name 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 can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-). It cannot contain http:// or https://.
400InvalidOSSObject.MalformedThe specified OSS object is wrongly formed.The specified OSS object is invalid.
400InvalidOSSBucket.MalformedThe specified OSS bucket is wrongly formed.-
400InvalidOSSObject.SizeThe specified OSS object size is zero.-
400InvalidDescription.MalformedThe specified Image description is wrongly formed.The image description is invalid.
400InvalidArchitecture.MalformedThe specified Architecture is wrongly formed.The specified Architecture parameter is invalid.
400InvalidPlatform.MalformedThe specified Platform is wrongly formed.-
400InvalidOSType.MalformedThe specified OSType is wrongly formed.The specified OS type is invalid.
400InvalidImageName.DuplicatedThe destination image is exist.The specified image name already exists.
400InvalidImageSize%sThe specified image size is invalid.
400InvalidDataDiskSizeThe specified DiskDeviceMapping.N.DiskImSize should be in the specified range.The specified DiskDeviceMapping.N.DiskImSize parameter is invalid.
400InvalidImageFormat.MalformedThe specified Image Format is wrongly formed.The specified image format is invalid.
400InvalidRegionId.NotFoundThe specified RegionId does not exist.The specified region ID does not exist.
400InvalidRegion.NotSupportThe specified region does not support image import or export.The specified region does not support the operation.
400InvalidOSSBucket.NotFoundThe specified OSS bucket does not exist in this region.The specified bucket does not exist.
400InvalidOSSObject.NotFoundThe specified OSS object does not exist in this region.The specified OSS object does not exist.
400InvalidOSSObject.NeedRestoreThe specified OSS object is a archive object, need restore first.-
400InvalidOSSBucket.NotMatchedThe specified OSS bucket is incorrect, %s.The specified DiskDeviceMapping.N.OSSBucket parameter is invalid. For more information, see the return value of the %s placeholder in the error message.
400InvalidLicenseType.NotSupportedThe specified LicenseType is not supported.-
400InvalidLicenseType.BYOLOnlyOnly BYOL LicenseType is supported for the current platform provided.-
400InvalidOSSBucket.FlowLimit%s-
400InvalidImageFormat.RegionNotSupportedThe specified image format is not supported in current region.-
400InvalidBootMode.MalformedThe specified parameter "BootMode" is malformed.-
400InvalidParameter.DetectionStrategyThe specified parameter DetectionStrategy is invalid.-
400InvalidBootMode.NotSupportThe specified parameter BootMode is not supported for current image architecture.The current image architecture does not support setting this boot mode.
400DRYRUN.SUCCESSThis request is a dryrun request with successful result.The request is checked and determined as valid.
400InvalidClientToken.MalformedThe specified parameter clientToken is not valid.-
403ImageIsImportingThe specified Image is importing.The specified image is being imported and cannot be managed.
403QuotaExceed.ImageThe Image Quota exceeds.The custom image quota has been used up.
403ImportImageFailedImporting image is failed, Please contact the administrator.The image cannot be imported. Contact your system administrator.
403UserNotInTheWhiteListThe user is not in the white list of importing image.The user is not authorized to import image.
403NoSetRoletoECSServiceAcountECS service account Have no right to access your OSS.please attach a role of access your oss to ECS service account.The official ECS website service account does not have permissions to access your specified OSS bucket and object.
403InvalidParameter.MalformedThe specified parameter "DiskDeviceMapping.n.Device " is not valid.-
403MissingParameter.DiskDeviceMappingThe specified parameter DiskDeviceMapping is not supplied.A parameter that starts with DiskDeviceMapping must be specified.
403InvalidOSS.NotAuthorizedThe specified OSS bucket or object is not allowed to access.-
403InvalidBlockSize.NotSupport%s-
403InvalidImageFormat.Malformed%s-
403ImageCheckUnsupported.WindowsImageImage check is unsupported for windows image.-
403InvalidVHDImage.IncorrectSizeThe 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 header.MaxTableEntries × header.BlockSize size limit.
403InvalidOSSBucket.EncryptUnsupportedAccessing objects from encrypted OSS bucket is not supported.You cannot read objects from encrypted OSS buckets.
403InvalidArchitecture.PlatformUnsupportedThe OS platform you selected does not support the specified architecture.The selected operating system does not support the specified architecture type.
403InvalidAccountStatus.OSSDisabledOSS is disabled due to invalid account status.-
403InvalidStorageLocation.NotFoundThe specified cloud box storage location %s could not be found.The specified cloud box storage location could not be found.
403InvalidOperation.CloudBoxImageImportRoleRequiredThe role for cloud box image import is not set to the ECS service.The role for cloud box image import is not set to the ECS service.
403InvalidOperation.CloudBoxImageImportUnsupportedImporting cloud box images is not supported.Importing cloud box images is not supported.
404InvalidResourceGroup.NotFoundThe ResourceGroup provided does not exist in our records.The specified resource group does not exist.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-11-14The Error code has changedView Change Details
2024-10-09The Error code has changed. The request parameters of the API has changedView Change Details
2024-06-12The Error code has changedView Change Details
2023-08-23The Error code has changedView Change Details
2023-05-26The Error code has changedView Change Details
2023-04-19The Error code has changedView Change Details
2023-04-12The Error code has changedView Change Details
2022-07-11The Error code has changed. The request parameters of the API has changedView Change Details
2021-06-17The Error code has changedView Change Details