ImportImage

Last Updated: Apr 09, 2018

Description

Imports on-premises image files to the Alibaba Cloud ECS. You can use the imported image to create an instance (CreateInstance) or replace the system disk of an instance (ReplaceSystemDisk). When you call this interface, consider the following:

  • You must upload the image file to OSS beforehand.

  • You can only import an image file to a region from OSS in the same region. The image and the OSS must belong to one account.

  • The n in DiskDeviceMapping.n indicates the disk type.

    • When n is set to 1, it represents a system disk.

    • When n is set to [2, 17], it represents a data disk.

  • You cannot delete an image that is being imported. However, you can cancel the image import task (CancelTask).

  • Follow these steps to use RAM allowing ECS to access OSS for your Alibaba Cloud account.

    1. Create a role with a name AliyunECSImageImportDefaultRole (image import fails if a different name is used), and see the following code snippet to set its role policy.

      1. {
      2. "Statement": [
      3. {
      4. "Action": "sts:AssumeRole",
      5. "Effect": "Allow",
      6. "Principal": {
      7. "Service": [
      8. "ecs.aliyuncs.com"
      9. ]
      10. }
      11. }
      12. ],
      13. "Version": "1"
      14. }
    2. Attach the default permission policy AliyunECSImageImportRolePolicy to AliyunECSImageImportDefaultRole. You can also create a custom policy with the following permissions:

      1. {
      2. "Version": "1",
      3. "Statement": [
      4. {
      5. "Action": [
      6. "oss:GetObject",
      7. "oss:GetBucketLocation"
      8. ],
      9. "Resource": "*",
      10. "Effect": "Allow"
      11. }
      12. ]
      13. }

Request parameters

Name Type Required Description
Action String Yes The name of this interface. Value: ImportImage.
RegionId String Yes The region ID. For more information, see DescribeRegions.
ImageName String No The image name.
  • Can be [2, 128] characters in length.
  • Must start with an uppercase or lowercase English letter, or a Chinese character.
  • Can contain digits, underscores (_), or hyphen (-).
  • Cannot start with http:// or https://.
Description String No The image description.
  • Can be [0, 256] characters in length.
  • Cannot start with http:// or https://.
Default value: null.
Architecture String No The system architecture. Optional values:
  • i386
  • x86_64
Default value: x86_64.
OSType String No The type of operating system platform. Optional values:
  • Windows
  • Linux
Default value: Linux.
Platform String No The operating system release edition. Optional values:
  • CentOS
  • Ubuntu
  • SUSE
  • OpenSUSE
  • Debian
  • CoreOS
  • Aliyun
  • Windows Server 2003
  • Windows Server 2008
  • Windows Server 2012
  • Others Linux
  • Customized Linux
Default value: Others Linux.
DiskDeviceMapping.n.Format String No The image format. Optional values:
  • RAW
  • VHD
When you import an image, we automatically scan and check the format of the image, and the checking result is used as the default value of this parameter.
DiskDeviceMapping.n.OSSBucket String Yes The OSS bucket where an image file is stored.
DiskDeviceMapping.n.OSSObject String Yes The name (key) of the OSS object with an image file.
DiskDeviceMapping.n.DiskImageSize String No The size of a custom image. The space of the disk must be larger than or equal to the actual used space of disks. Value range:
  • When n is set to 1: [5, 500] GB.
  • When n is set to [2, 16]: [5, 1000] GB.
When you import an image, the system auto scans and checks the size of the image, and the checking result is used for the default value of this parameter.

Response parameters

Name Type Description
RegionId String The region ID.
ImageId String The image ID.
ImportTaskId String The ID of an image import task.

Examples

Request example

  1. https://ecs.aliyuncs.com/?Action=ImportImage
  2. &RegionId=cn-hangzhou
  3. &DiskDeviceMapping.1.OSSBucket=ecsimageos
  4. &DiskDeviceMapping.1.OSSObject=CentOS_5.4_32.raw
  5. &<Common Request Parameters>

Response example

XML format

  1. <ImportImageResponse>
  2. <RequestId>C8B26B44-0189-443E-9816-D951F59623A9</RequestId>
  3. <ImageId>Img-231234567</ImageId>
  4. <ImportTaskId>123-345-2332-22323</ImportTaskId>
  5. </ImportImageResponse>

JSON format

  1. {
  2. "RequestId": "C8B26B44-0189-443E-9816-D951F59623A9",
  3. "ImageId": "Img-231234567",
  4. "ImportTaskId":"123-345-2332-22323"
  5. }

Error codes

Error code Error message HTTP status code Meaning
Forbidden User not authorized to operate on the specified resource. 400 You cannot import the image now. Submit a ticket to enable the image import feature.
IncorrectImageStatus The specified image is not available. 400 The status of the specified image is incorrect.
InvalidArchitecture.Malformed The specified Architecture is wrongly formed. 400 The specified architecture is invalid.
InvalidDescription.Malformed The specified destination image description is wrongly formed. 400 The specified target image description is invalid.
InvalidFormat.Malformed The specified Image format is wrongly formed. 400 The specified image file format is invalid.
InvalidImageName.Duplicated The destination image is exist. 400 The value of the specified ImageName already exists.
InvalidImageName.Malformed The specified destination Image name is wrongly formed. 400 The specified image name is invalid.
InvalidImageSize The specified DiskDeviceMapping.n.DiskImageSize should be not less than system device size. 400 The value of the specified DiskDeviceMapping.n.DiskImageSize must be larger than or equal to the actual used space of disks.
InvalidOSType.Malformed The specified OSType is wrongly formed. 400 The specified OSType is invalid.
InvalidPlatform.Malformed The specified Platform is wrongly formed. 400 The specified Platform is invalid.
MissingParameter An input parameter RegionId that is mandatory for processing the request is not supplied. 400 You must specify the parameter RegionId.
MissingParameter An input parameter DiskDeviceMapping.n.OSSBucket that is mandatory for processing the request is not supplied. 400 You must specify the parameter OSSBucket.
MissingParameter An input parameter DiskDeviceMapping.n.OSSObject that is mandatory for processing the request is not supplied. 400 You must specify the parameter OSSObject.
RegionId.NotFound The specified region is not found. 400 The region ID of the specified image does not exist.
ImageIsImporting The specified Image is importing. 403 The specified image is being copied. Please try again later.
InvalidRegion.NotSupport The specified region does not support image import or export. 403 The specified region currently does not support image import.
QuotaExceed.Image The Image Quota exceeds. 403 You have exceeded the maximum number of your custom images. No more images can be imported.
QuotaExceed.Snapshot The maximum number of snapshots is exceeded. 403 You have exceeded the maximum number of your snapshot. No more images can be imported.
Thank you! We've received your feedback.