ImportImage - API Reference| Alibaba Cloud Documentation Center

ImportImage

Edit in GitHub

Last Updated: May 25, 2020 Edit in GitHub

You can call this operation to import a local image to ECS. The local image then appears as a custom image in the corresponding region. The imported image can be used to create ECS instances (RunInstances) or replace system disks of instances (ReplaceSystemDisk).

Description

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

You must upload the image file to Object Storage Service (OSS) bucket before you can import the image file. For more information, see Upload image file.
You must use Resource Access Management (RAM) to authorize ECS to access your OSS buckets before you import an image for the first time. Otherwise, the NoSetRoletoECSServiceAcount error code is returned. For information about the procedure, see Account access control. The following example shows the procedure to configure RAM authorization policies:
1. Create a role named AliyunECSImageImportDefaultRole. You must use this exact name. Otherwise, the image will fail to be imported. Refer to the following code to set the policy for the role:
```
        {
			"Statement": [
			{
				"Action": "sts:AssumeRole",
				"Effect": "Allow",
				"Principal": {
				"Service": [
					"ecs.aliyuncs.com"
				]
				}
			}
        ],
			"Version": "1"
        }
        
```
2. Attach the permission policy AliyunECSImageImportRolePolicy to the role. For more information, see RAM. You can also create your custom policies that must contain the following permissions:
```
        {
			"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 only import an image to the same region as the OSS bucket that the image file is uploaded to.
Valid values of N in the DiskDeviceMapping.N parameter: 1 to 17. When N is 1, the disk is a system disk. When N is 2 to 17, the disk is a data disk.

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	No	ImportImage	The operation that you want to perform. Set the value to ImportImage.
RegionId	String	Yes	cn-hangzhou	The region ID of the source custom image. You can call the DescribeRegions operation to query the most recent region list.
DiskDeviceMapping.N.Format	String	No	qcow2	The format of image. Valid values: RAW VHD qcow2 This parameter is empty by default. When you import an image, the system automatically detects the format of the image, and the checking result is used as the value of this parameter.
DiskDeviceMapping.N.OSSBucket	String	No	ecsimageos	The OSS bucket where the image file is stored. Note Before you import the image file to the OSS bucket for the first time, see "Description" section in this topic to add RAM authorization policies. If you do not add RAM authorization policies, the `NoSetRoletoECSServiceAcount` error code is returned.
DiskDeviceMapping.N.OSSObject	String	No	CentOS_5.4_32.raw	The OSS object where the image file is stored.
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.DiskImageSize	Integer	No	80	The size of the image. The space of the system disk must be greater than or equal to the actual used space of file systems. Valid values: When N is set to 1, the disk is a system disk and the range of the parameter value is 5-500 GiB. When N is set to 2 to 17, the disk is a data disk and the range of the parameter value is 5-1000 GiB. When you import an image, the system automatically scans and checks the size of the image, and the checking result is used as the value of this parameter.
DiskDeviceMapping.N.Device	String	No	null	The 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.
ImageName	String	No	ImageTestName	The name of the image. The name must be 2 to 128 characters in length and can contain letters, digits, colons (:), underscores (_), and hyphens (-). The name must start with a letter and cannot start with http:// or https://. This parameter is empty by default.
Description	String	No	TestDescription	The description of the image. The description must be 2 to 256 characters in length and cannot start with http:// or https://. This parameter is empty by default.
Architecture	String	No	x86_64	The system architecture. Default value: x86_64. Valid values: i386 x86_64
OSType	String	No	linux	The type of the operating system. Default value: linux. Valid values: windows linux
Platform	String	No	Aliyun	The release version of the operating system. Default value: Others Linux. Valid values: CentOS Ubuntu SUSE OpenSUSE Debian CoreOS Aliyun Windows Server 2003 Windows Server 2008 Windows Server 2012 Others Linux Customized Linux
RoleName	String	No	AliyunECSImageImportDefaultRole	The name of the RAM role used to import the image.
LicenseType	String	No	Auto	The type of the license used to activate the operating system after the image is imported. Default value: Auto. Valid values: Auto: Alibaba Cloud detects the source operating system and allocates a license to the system. In this mode, the system first checks whether the specified `Platform` has a license granted by Alibaba Cloud. If yes, ECS allocates the license to the imported image. If not, the license is switched to the bring your own license (BYOL) mode. Aliyun: The license that was granted by Alibaba Cloud to the specified `Platform` is used. BYOL: The license for the source operating system is used. In this mode, ensure that your license key can be used in Alibaba Cloud.
Tag.N.Key	String	No	TestKey	The key of tag N for the image. Valid values of N: 1 to 20. It cannot be an empty string. It can be up to 128 characters in length and cannot contain http:// or https://. It cannot start with acs: or aliyun.
Tag.N.Value	String	No	TestValue	The value of tag N for the image. Valid values of N: 1 to 20. It can be an empty string. It can be up to 128 characters in length and cannot contain http:// or https://. It cannot start with acs:.
ResourceGroupId	String	No	rg-bp67acfmxazb4p****	The ID of the resource group to which the image to be imported belongs.

Response parameters


Parameter	Type	Example	Description
ImageId	String	m-bp67acfmxazb4p****	The ID of the image.
RegionId	String	cn-hangzhou	The region ID of the image.
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E	The ID of the request.
TaskId	String	t-bp67acfmxazb4p****	The ID of the image import task.

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

<ImportImageResponse>
      <RequestId>C8B26B44-0189-443E-9816-D951F59623A9</RequestId>
      <ImageId>m-bp67acfmxazb4p****</ImageId>
      <RegionId>cn-hangzhou</RegionId>
      <ImportTaskId>t-bp67acfmxazb4p****</ImportTaskId>
</ImportImageResponse>

JSON format

{
    "RequestId": "C8B26B44-0189-443E-9816-D951F59623A9",
    "ImageId": "m-bp67acfmxazb4p****",
    "RegionId": "cn-hangzhou",
    "ImportTaskId": "t-bp67acfmxazb4p****"
}

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 OSS bucket of the imported image 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 OSS bucket of the imported image is not specified.
400	InvalidImageName.Malformed	The specified Image name is wrongly formed.	The error message returned because the specified image name is invalid. The name must be 2 to 128 characters in length and can contain letters, digits, periods (.), underscores (_), and hyphens (-). It must start with a letter and cannot start with http:// or https://.
400	InvalidOSSObject.Malformed	The specified OSS object is wrongly formed.	The error message returned because the specified OSS object is invalid.
400	InvalidDescription.Malformed	The specified Image description is wrongly formed.	The error message returned because the format of image description is invalid.
400	InvalidArchitecture.Malformed	The specified Architecture is wrongly formed.	The error message returned because the architecture format is invalid.
400	InvalidPlatform.Malformed	The specified Platform is wrongly formed.	The error message returned because the specified release version of the operating system is invalid.
400	InvalidOSType.Malformed	The specified OSType is wrongly formed.	The error message returned because the format of the operating system 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 value of the DiskDeviceMapping.N.DiskImSize parameter is invalid.
400	InvalidImageFormat.Malformed	The specified Image Format is wrongly formed.	The error message returned because the specified image format is invalid.
400	InvalidRegionId.NotFound	The specified RegionId does not exist.	The error message returned because the specified region ID 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 this operation.
403	ImageIsImporting	The specified Image is importing.	The error message returned because the specified image is being imported and cannot be operated.
403	QuotaExceed.Image	The Image Quota exceeds.	The error message returned because the maximum number of custom images has been reached.
403	ImportImageFailed	Importing image is failed, Please contact the administrator.	The error message returned because the image failed to 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 and object.
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.
403	InvalidParameter.Malformed	The specified parameter "DiskDeviceMapping.n.Device " is not valid.	The error message returned because the specified value of the DiskDeviceMapping.N.Device parameter is invalid.
403	MissingParameter.DiskDeviceMapping	The specified parameter DiskDeviceMapping is not supplied.	The error message returned because the DiskDeviceMapping parameter is not specified.
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 does not exist.
400	InvalidLicenseType.NotSupported	The specified LicenseType is not supported	The error message returned because the specified license type is not supported.
400	InvalidLicenseType.BYOLOnly	Only BYOL LicenseType is supported for the current platform provided	The error message returned because the current platform only supports BYOL-type licenses.

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