文档

ImportImage - 导入本地镜像文件

更新时间:

调用ImportImage导入一份您的本地镜像文件到云服务器ECS,作为自定义镜像出现在相应地域中。您可以使用导入的镜像创建ECS实例(RunInstances),或者更换实例的系统盘(ReplaceSystemDisk)。

接口说明

调用该接口时,您需要注意:

  • 您必须提前上传镜像文件到对象存储 OSS。具体操作,请参见上传文件

  • 为避免部分服务器、虚拟机或者云主机的操作系统在导入自定义镜像后,创建的 ECS 实例无法启动,您需要在导入镜像前检查是否需要在源服务器中安装 virtio 驱动。具体操作,请参见安装 virtio 驱动

  • 首次导入镜像时,您必须提前通过访问控制 RAM 授权 ECS 访问您的 OSS Bucket,否则会报错NoSetRoletoECSServiceAccountInvalidOperation.CloudBoxImageImportRoleRequired。分为以下两种场景情况:

    • 不通过云盒导入镜像文件:您可以通过 RAM 管理控制台一键完成授权操作,具体的授权页面,请参见云资源访问授权。您也可以手动完成授权操作,部分操作中策略与权限如下所示。具体操作,请参见账号访问控制

      1. 创建角色AliyunECSImageImportDefaultRole(必须是这个名称,否则导入镜像会失败),角色的策略为:

        {
        	"Statement": [
        	{
        		"Action": "sts:AssumeRole",
        		"Effect": "Allow",
        		"Principal": {
        		"Service": [
        			"ecs.aliyuncs.com"
        		]
        		}
        	}
        ],
        	"Version": "1"
        }
        
      2. 在该角色下,添加系统策略AliyunECSImageImportRolePolicy。您也可以创建自定义策略,权限必须包含:

        
        {
        	"Version": "1",
        	"Statement": [
        	{
        		"Action": [
        				"oss:GetObject",
        				"oss:GetBucketLocation",
        				"oss:GetBucketInfo"
        	],
        			"Resource": "*",
        			"Effect": "Allow"
        			}
        	]
        }
        
        
    • 通过云盒导入镜像文件:您可以通过 RAM 管理控制台一键完成授权操作,具体的授权页面,请参见云资源访问授权。您也可以手动完成授权操作,部分操作中策略与权限如下所示。具体操作,请参见账号访问控制

      1. 创建角色AliyunECSCloudBoxImageImportDefaultRole(必须是这个名称,否则导入镜像会失败),角色的策略为:

        {
        	"Statement": [
        	{
        		"Action": "sts:AssumeRole",
        		"Effect": "Allow",
        		"Principal": {
        		"Service": [
        			"ecs.aliyuncs.com"
        		]
        		}
        	}
        ],
        	"Version": "1"
        }
        
      2. 在该角色下,添加系统策略AliyunECSCloudBoxImageImportRolePolicy。您也可以创建自定义策略,权限必须包含:

        
        {
        	"Version": "1",
        	"Statement": [
        	{
        		"Action": [
        				"oss-cloudbox:GetObject",
        				"oss-cloudbox:GetBucketLocation",
        				"oss-cloudbox:GetBucketInfo"
        	],
        			"Resource": "*",
        			"Effect": "Allow"
        			}
        	]
        }
        
        
  • 不能删除正在导入的镜像,只能调用 CancelTask 取消导入镜像任务。

  • 导入镜像的地域必须跟镜像文件上传的 OSS Bucket 的地域相同。

  • 参数DiskDeviceMapping.N中 N 的取值范围为 1~17。N 为 1 时表示系统盘,N 为 2~17 时表示数据盘,当 N 大于 17 时系统会自动忽略。

  • 当参数Architecture取值为arm64,或者参数Platform取值为CentOS StreamAnolisAlmaLinuxUOSKylinRocky Linux时,您需要注意:

    • 为了使导入后的镜像支持配置密码或者支持修改密钥对,镜像必须满足以下条件:

      • 操作系统的内核需要支持CONFIG_FW_CFG_SYSFS特性。Linux 社区内核 4.6 版本之后默认支持该特性,CentOS 的内核在 3.10.0-826.el7 版本之后默认支持该特性。您可以在该镜像对应的服务器内运行grep -nr CONFIG_FW_CFG_SYSFS /boot/config-$(uname -r)命令,如果回显结果中包含CONFIG_FW_CFG_SYSFS=y信息,则说明该镜像中的内核已支持CONFIG_FW_CFG_SYSFS特性。

      • 操作系统中已安装阿里云最新版本 cloud-init。其中,19.1 版本 cloud-init 必须在 19.1.3 版本及以上,部分低版本操作系统中的 0.7.6a 版本 cloud-init 必须在 0.7.6a15 版本及以上。具体操作,请参见安装 cloud-init

      • 操作系统需要支持 SHA-512 加密算法。

    • 为了使导入后的镜像支持扩容云盘与扩容文件系统,镜像必须满足以下条件:

      • 操作系统的内核版本需要高于 3.6 版本。

      • 支持 growpart 命令。支持该命令需要安装cloud-utils-growpart包,不同操作系统安装方式有所不同。具体操作,请参见扩展分区和文件系统(Linux)

      • 支持 resize2fs 命令。支持该命令需要安装e2fsprogs包,该包在操作系统中默认已安装,如果没有安装您需要自行安装。

      • 操作系统中已安装阿里云最新版本 cloud-init。其中,19.1 版本 cloud-init 必须在 19.1.3 版本及以上,部分低版本操作系统中的 0.7.6a 版本 cloud-init 必须在 0.7.6a15 版本及以上。具体操作,请参见安装 cloud-init

  • 如果您待导入的自定义镜像对应的系统架构为 arm64 时,您需要设置其 RTC 时钟使用 UTC 时间标准。具体操作,请参见 Linux 时间和时区说明

  • 强烈建议在导入镜像时配置镜像检测参数,有助于系统帮助优化您的镜像。更多信息,请参见镜像检测概述

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
ecs:ImportImageWrite
  • Image
    acs:ecs:{#regionId}:{#accountId}:image/*

请求参数

名称类型必填描述示例值
RegionIdstring

源自定义镜像的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。

cn-hangzhou
ImageNamestring

镜像名称。长度为 2~128 个字符。必须以大小写字母或中文开头,不能以aliyunacs:开头,不能包含http://或者https://。可以包含数字、半角句号(.)、半角冒号(:)、下划线(_)或者短划线(-)。

ImageTestName
Descriptionstring

镜像的描述信息。长度为 2~256 个英文或中文字符,不能以http://https://开头。

TestDescription
Architecturestring

系统架构。取值范围:

  • i386。
  • x86_64。
  • arm64。

默认值:x86_64。

x86_64
OSTypestring

操作系统平台类型。取值范围:

  • windows。
  • linux。

默认值:linux。

linux
Platformstring

操作系统发行版。取值范围:

  • 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

默认值:Others Linux。

Aliyun
BootModestring

修改镜像的启动模式。取值范围:

  • BIOS:BIOS 启动模式。
  • UEFI:UEFI 启动模式。

默认值:BIOS。如果Architecture=arm64,则该参数默认值为 UEFI,且只能设置为 UEFI。

说明 您需要了解指定的镜像支持的启动模式,当通过该参数修改启动模式后,必须与镜像本身支持的启动模式匹配,实例才能正常启动。
BIOS
RoleNamestring

导入镜像时,使用的 RAM 角色名称。

AliyunECSImageImportDefaultRole
LicenseTypestring

导入镜像后,激活操作系统采用的许可证类型。取值范围:

  • Auto:由阿里云检测源操作系统并分配许可证。自动模式下,系统优先搜索您设置的Platform是否有阿里云官方渠道的许可证并分配给导入的镜像,如果缺乏该类许可,会切换成 BYOL(Bring Your Own License)方式。
  • Aliyun:根据您设置的Platform采用阿里云官方渠道的许可证。
  • BYOL:源操作系统自带的许可证。采用 BYOL 时,您必须确保您的许可证密钥支持在阿里云使用。

默认值:Auto。

Auto
ResourceGroupIdstring

导入镜像所在的企业资源组 ID。

rg-bp67acfmxazb4p****
DiskDeviceMappingobject []

创建的自定义镜像信息列表。

DiskImSizeinteger

自定义镜像大小。单位:GiB。

该空间由系统盘和数据盘组成,您必须保证系统盘的空间大小大于等于导入的镜像文件大小。取值范围:

  • N=1 时,表示系统盘,取值范围:5 GiB~500 GiB。
  • N=2~17 时,表示数据盘。取值范围:5 GiB~2000 GiB。

当您将源镜像文件上传至 OSS 后,可以在 OSS Bucket 中查看镜像文件的大小。

说明 该参数即将被弃用,为提高兼容性,请尽量使用DiskDeviceMapping.N.DiskImageSize参数。
80
Devicestring

指定 DiskDeviceMapping.N.Device 在自定义镜像中的设备名。

说明 该参数即将停止使用,为提高代码兼容性,建议您尽量不要使用该参数。
null
OSSBucketstring

镜像文件所在的 OSS Bucket。

说明 首次导入镜像到该 OSS Bucket 前,请参见本文档的接口说明添加 RAM 授权策略,否则会报错NoSetRoletoECSServiceAccount
ecsimageos
Formatstring

镜像格式。取值范围:

  • RAW。
  • VHD。
  • QCOW2。

默认值:无,表示阿里云自动检测镜像格式,以检测格式为准。

QCOW2
OSSObjectstring

镜像上传至 OSS Bucket 后,保存在 Bucket 中的镜像文件的文件名(key)。

CentOS_5.4_32.raw
DiskImageSizeinteger

导入镜像后,自定义镜像的空间大小。

该空间由系统盘和数据盘组成,您必须保证系统盘的空间大小大于等于导入的镜像文件大小。取值范围:

  • N=1 时,表示系统盘,取值范围:5 GiB~500 GiB。
  • N=2~17 时,表示数据盘。取值范围:5 GiB~2000 GiB。

当您将源镜像文件上传至 OSS 后,可以在 OSS Bucket 中查看镜像文件的大小。

80
Tagobject []

镜像的标签列表。

Keystring

镜像的标签键。N 的取值范围:1~20。一旦传入该值,则不允许为空字符串。最多支持 128 个字符,不能以aliyun或者acs:开头,不能包含http://或者https://

TestKey
Valuestring

镜像的标签值。N 的取值范围:1~20。一旦传入该值,允许为空字符串。最多支持 128 个字符,不能以acs:开头,不能包含http://或者https://

TestValue
DetectionStrategystring

镜像检测策略,不配置此参数时不触发检测。仅支持标准(Standard)检测模式。

说明 目前已支持大部分的 Linux/Windows 版本,关于镜像检测项与操作系统限制说明,请参见镜像检测概述镜像检测操作系统限制
Standard
StorageLocationArnstring

指定云盒的资源名称(ARN),用于唯一标识云端存储位置。

说明 仅当您需要从 OSS ON 云盒中导入镜像文件时,才需提供此参数的值。如果您使用的存储服务不是 OSS ON 云盒,则无需设置此参数。更多信息,请参见什么是 OSS ON 云盒

正确的 ARN 格式应遵循:arn:acs:cloudbox:{RegionId}:{AliUid}:cloudbox/{CloudBoxId}的模式,其中{RegionId}应替换为云盒实际所在的地域 ID,{AliUid}是阿里云账号(主账号)ID,而{CloudBoxId}是云盒 ID。

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

返回参数

名称类型描述示例值
object
RequestIdstring

请求 ID。

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

镜像 ID。

m-bp67acfmxazb4p****
TaskIdstring

导入镜像任务 ID。

t-bp67acfmxazb4p****
RegionIdstring

地域 ID。

cn-hangzhou

示例

正常返回示例

JSON格式

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

错误码

HTTP status code错误码错误信息描述
400UnsupportedSuffix.OSSObjectThe specified OSS object suffix is not supported.不支持指定的OSS对象后缀。
400InvalidBootMode.NotSupportThe specified parameter BootMode can not be BIOS for arm image.-
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.镜像名称格式错误。长度为2~128个字符。必须以大小字母或中文开头,不能以aliyun和acs:开头,不能包含http://或者https://。可以包含数字、半角句号(.)、半角冒号(:)、下划线(_)或者短划线(-)。
400InvalidOSSObject.MalformedThe specified OSS object is wrongly formed.指定的 OSS Object 不合法。
400InvalidOSSBucket.MalformedThe specified OSS bucket is wrongly formed.-
400InvalidOSSObject.SizeThe specified OSS object size is zero.-
400InvalidDescription.MalformedThe specified Image description is wrongly formed.镜像描述格式错误。
400InvalidArchitecture.MalformedThe specified Architecture is wrongly formed.参数 Architecture 格式错误。
400InvalidPlatform.MalformedThe specified Platform is wrongly formed.指定的镜像操作系统发行版不合法。
400InvalidOSType.MalformedThe specified OSType is wrongly formed.格式不对。
400InvalidImageName.DuplicatedThe destination image is exist.指定的镜像名已存在。
400InvalidImageSize%s镜像大小不符合要求。
400InvalidDataDiskSizeThe specified DiskDeviceMapping.N.DiskImSize should be in the specified range.指定的 DiskDeviceMapping.N.DiskImSize 超出取值范围。
400InvalidImageFormat.MalformedThe specified Image Format is wrongly formed.指定的镜像格式错误。
400InvalidRegionId.NotFoundThe specified RegionId does not exist.指定的地域 ID 不存在。
400InvalidRegion.NotSupportThe specified region does not support image import or export.指定的地域暂时不支持此操作。
400InvalidOSSBucket.NotFoundThe specified OSS bucket does not exist in this region.指定的 bucket 不存在。
400InvalidOSSObject.NotFoundThe specified OSS object does not exist in this region.指定的 OSS object 不存在。
400InvalidOSSObject.NeedRestoreThe specified OSS object is a archive object, need restore first.-
400InvalidOSSBucket.NotMatchedThe specified OSS bucket is incorrect, %s.指定的 OSS Bucket 有误,具体信息请参见错误信息的实际返回结果。
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.-
403ImageIsImportingThe specified Image is importing.指定镜像正在导入,无法执行操作。
403QuotaExceed.ImageThe Image Quota exceeds.自定义镜像额度已用完。
403ImportImageFailedImporting image is failed, Please contact the administrator.导入镜像失败,请联系系统管理员排查。
403UserNotInTheWhiteListThe user is not in the white list of importing image.用户未被授权导入镜像。
403NoSetRoletoECSServiceAcountECS service account Have no right to access your OSS.please attach a role of access your oss to ECS service account.ECS 官网服务账号没有权限访问您指定的 OSS 的 bucket 和 Object。
403InvalidParameter.MalformedThe specified parameter "DiskDeviceMapping.n.Device " is not valid.-
403MissingParameter.DiskDeviceMappingThe specified parameter DiskDeviceMapping is not supplied.参数 DiskDeviceMapping 不能为空。
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.指定的VHD镜像大小不符合 'header.MaxTableEntries * header.BlockSize' 的规范。
403InvalidOSSBucket.EncryptUnsupportedAccessing objects from encrypted OSS bucket is not supported.不支持从加密的OSS bucket读取对象。
403InvalidArchitecture.PlatformUnsupportedThe OS platform you selected does not support the specified architecture.您选择的操作系统平台不支持指定的架构类型。
403InvalidAccountStatus.OSSDisabledOSS is disabled due to invalid account status.由于帐户状态无效,OSS被禁用。
403InvalidStorageLocation.NotFoundThe specified cloud box storage location %s could not be found.找不到指定的云盒存储位置。
403InvalidOperation.CloudBoxImageImportRoleRequiredThe role for cloud box image import is not set to the ECS service.没有设置用于云盒镜像导入的角色给ECS服务。
403InvalidOperation.CloudBoxImageImportUnsupportedImporting cloud box images is not supported.不支持导入云盒镜像。
404InvalidResourceGroup.NotFoundThe ResourceGroup provided does not exist in our records.资源组并不在记录中。

访问错误中心查看更多错误码。

变更历史

变更时间变更内容概要操作
2023-08-23OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 403 变更
    删除错误码:400
    新增错误码:404
2023-05-26OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 403 变更
    删除错误码:400
2023-04-19OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 403 变更
    删除错误码:400
2023-04-12OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 400 变更
    删除错误码:403
2022-07-11OpenAPI 错误码发生变更、OpenAPI 入参发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 400 变更
    错误码 403 变更
入参OpenAPI 入参发生变更
    新增入参:DetectionStrategy
2021-06-17OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 400 变更
    删除错误码:403
  • 本页导读 (1)