Imports an image to Elastic Compute Service (ECS).
Operation description
When you call this operation, take note of the following items:
-
Before you can 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 the 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, make sure that the virtio driver is installed on the source server before you import an 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
NoSetRoletoECSServiceAcount
error code is returned when you call the ImportImage operation. The Cloud Resource Access Authorization page in the RAM console provides a convenient push-button authorization feature for this operation. You can also perform 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.-
Create a role named
AliyunECSImageImportDefaultRole
. You must use this exact 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" }
-
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 was uploaded.
-
The valid values of N in the
DiskDeviceMapping.N
parameter 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 you set
Architecture
toarm64
or when you setPlatform
toCentOS Stream
,Anolis
,AlmaLinux
,UOS
,Kylin
, orRocky Linux
, take note of the following items:-
To ensure that the password can be set, or that the key pair can be modified for an imported image, the image must meet the following requirements:
- The operating system kernel supports the
CONFIG_FW_CFG_SYSFS
feature. By default, Linux community kernel 4.6 and later, as well as CentOS kernel 3.10.0-826.el7 and later, support this feature. You can run thegrep -nr CONFIG_FW_CFG_SYSFS /boot/config-$(uname -r)
command in the source server of the image. If the command output containsCONFIG_FW_CFG_SYSFS=y
, the kernel of this image supports theCONFIG_FW_CFG_SYSFS
feature. - The latest version of Alibaba Cloud cloud-init is installed on the operating system. If the installed version of cloud-init is 19.1, make sure that the minor version is 19.1.3 or later. If the installed version of cloud-init is 0.7.6a as in some early versions of operating systems, make sure that the minor version is 0.7.6a15 or later. For more information, see Install cloud-init.
- The operating system supports the SHA-512 encryption algorithm.
- The operating system kernel supports the
-
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. Package installation methods vary based on operating systems. For more information, see Resize partitions and file systems of Linux system disks. - 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, you must install it. - The latest version of Alibaba Cloud cloud-init is installed on the operating system. If the installed version of cloud-init is 19.1, make sure that the minor version is 19.1.3 or later. If the installed version of cloud-init is 0.7.6a as in some early versions of operating systems, make sure that the minor version is 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.
Debugging
Authorization information
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
RegionId | string | Yes | The region ID of the source image. You can call the DescribeRegions operation to query the most recent region list. | cn-hangzhou |
ImageName | string | No | The name of the custom image. The name must be 2 to 128 characters in length. It must start with a letter and cannot start with | ImageTestName |
Description | string | No | The image description. The description must be 2 to 256 characters in length and cannot start with | TestDescription |
Architecture | string | No | The system architecture. Valid values:
Default value: x86_64. | x86_64 |
OSType | string | No | The operating system platform. Valid values:
Default value: linux. | linux |
Platform | string | No | The operating system distribution. Valid values:
Default value: Others Linux. | Aliyun |
BootMode | string | No | The boot mode of the image. Valid values:
Default value: BIOS. If you set 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 |
RoleName | string | No | The name of the RAM role used to import the image. | AliyunECSImageImportDefaultRole |
LicenseType | string | No | The type of the license used to activate the operating system after the image is imported. Valid values:
Default value: Auto. | Auto |
ResourceGroupId | string | No | The ID of the resource group to which to assign the image. | rg-bp67acfmxazb4p**** |
DiskDeviceMapping | object [] | No | The custom images. | |
DiskImSize | integer | No | The size of the custom image. Note
This parameter will be deprecated in the future. We recommend that you use the DiskDeviceMapping.N.DiskImageSize parameter to ensure future compatibility.
| 80 |
Device | string | No | The device name of disk N in the custom image. Note
This parameter will be removed in the future. To ensure future compatibility, we recommend that you do not use this parameter.
| null |
OSSBucket | string | No | The OSS bucket where the image is stored. Note
If this is the first time that you import images to ECS, you must use RAM to authorize ECS to access your OSS buckets. Otherwise, the NoSetRoletoECSServiceAcount error code is returned. For more information, see the Description section of this topic.
| ecsimageos |
Format | string | No | The image format. Valid values:
This parameter is empty by default, which indicates that the system checks the format of the image and uses the result as the value of this parameter. | QCOW2 |
OSSObject | string | No | The name (key) of the object that the uploaded image is stored as in the OSS bucket. | CentOS_5.4_32.raw |
DiskImageSize | integer | No | 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 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:
After the image is uploaded to an OSS bucket, you can view the size of the image file in the OSS bucket. | 80 |
Tag | object [] | No | The image tags. | |
Key | string | No | 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 | TestKey |
Value | string | No | 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 | TestValue |
DetectionStrategy | string | No | The mode that you want to use to check the source image. If you do not specify this parameter, the source image is not checked. Only Linux images can be checked. Set the value to Standard, which indicates standard check mode. The following items are checked in standard check mode:
| Standard |
Response parameters
Examples
Sample success responses
JSON
format
{
"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. | - |
400 | InvalidBootMode.NotSupport | The specified parameter BootMode can not be BIOS for arm image. | - |
400 | MissingParameter | An input parameter "RegionId" that is mandatory for processing the request is not supplied. | - |
400 | MissingParameter | An input parameter "DiskDeviceMapping.1.OSSBucket" that is mandatory for processing the request is not supplied. | - |
400 | MissingParameter | An input parameter "DiskDeviceMapping.1.OSSObject" that is mandatory for processing the request is not supplied. | - |
400 | InvalidImageName.Malformed | The 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://. |
400 | InvalidOSSObject.Malformed | The specified OSS object is wrongly formed. | The specified OSS object is invalid. |
400 | InvalidOSSBucket.Malformed | The specified OSS bucket is wrongly formed. | - |
400 | InvalidOSSObject.Size | The specified OSS object size is zero. | - |
400 | InvalidDescription.Malformed | The specified Image description is wrongly formed. | The image description is invalid. |
400 | InvalidArchitecture.Malformed | The specified Architecture is wrongly formed. | The specified Architecture parameter is invalid. |
400 | InvalidPlatform.Malformed | The specified Platform is wrongly formed. | - |
400 | InvalidOSType.Malformed | The specified OSType is wrongly formed. | The specified OS type is invalid. |
400 | InvalidImageName.Duplicated | The destination image is exist. | The specified image name already exists. |
400 | InvalidImageSize | %s | The specified image size is invalid. |
400 | InvalidDataDiskSize | The specified DiskDeviceMapping.N.DiskImSize should be in the specified range. | The specified DiskDeviceMapping.N.DiskImSize parameter is invalid. |
400 | InvalidImageFormat.Malformed | The specified Image Format is wrongly formed. | The specified image format is invalid. |
400 | InvalidRegionId.NotFound | The specified RegionId does not exist. | The specified region ID does not exist. |
400 | InvalidRegion.NotSupport | The specified region does not support image import or export. | The specified region does not support the operation. |
400 | InvalidOSSBucket.NotFound | The specified OSS bucket does not exist in this region. | The specified bucket does not exist. |
400 | InvalidOSSObject.NotFound | The specified OSS object does not exist in this region. | The specified OSS object does not exist. |
400 | InvalidOSSObject.NeedRestore | The specified OSS object is a archive object, need restore first. | - |
400 | InvalidOSSBucket.NotMatched | The 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. |
400 | InvalidLicenseType.NotSupported | The specified LicenseType is not supported. | - |
400 | InvalidLicenseType.BYOLOnly | Only BYOL LicenseType is supported for the current platform provided. | - |
400 | InvalidOSSBucket.FlowLimit | %s | - |
400 | InvalidImageFormat.RegionNotSupported | The specified image format is not supported in current region. | - |
400 | InvalidBootMode.Malformed | The specified parameter "BootMode" is malformed. | - |
400 | InvalidParameter.DetectionStrategy | The specified parameter DetectionStrategy is invalid. | - |
403 | ImageIsImporting | The specified Image is importing. | The specified image is being imported and cannot be managed. |
403 | QuotaExceed.Image | The Image Quota exceeds. | The custom image quota has been used up. |
403 | ImportImageFailed | Importing image is failed, Please contact the administrator. | The image cannot be imported. Contact your system administrator. |
403 | UserNotInTheWhiteList | The user is not in the white list of importing image. | The user is not authorized to import image. |
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 official ECS website service account does not have permissions to access your specified OSS bucket and object. |
403 | InvalidParameter.Malformed | The specified parameter "DiskDeviceMapping.n.Device " is not valid. | - |
403 | MissingParameter.DiskDeviceMapping | The specified parameter DiskDeviceMapping is not supplied. | A parameter that starts with DiskDeviceMapping must be specified. |
403 | InvalidOSS.NotAuthorized | The specified OSS bucket or object is not allowed to access. | - |
403 | InvalidBlockSize.NotSupport | %s | - |
403 | InvalidImageFormat.Malformed | %s | - |
403 | ImageCheckUnsupported.WindowsImage | Image check is unsupported for windows image. | - |
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 header.MaxTableEntries × header.BlockSize size limit. |
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. | - |
404 | InvalidResourceGroup.NotFound | The 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 time | Summary of changes | Operation | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
2023-08-23 | The Error code has changed | see changesets | ||||||||||
| ||||||||||||
2023-05-26 | The Error code has changed | see changesets | ||||||||||
| ||||||||||||
2023-04-19 | The Error code has changed | see changesets | ||||||||||
| ||||||||||||
2023-04-12 | The Error code has changed | see changesets | ||||||||||
| ||||||||||||
2022-07-11 | The Error code has changed. The request parameters of the API has changed | see changesets | ||||||||||
| ||||||||||||
2021-06-17 | The Error code has changed | see changesets | ||||||||||
|