调用ReplaceSystemDisk更换一台ECS实例的操作系统。系统盘的云盘ID会发生变化,原云盘会被释放。
接口说明
更换系统盘时,您需要注意:
-
不支持更换系统盘的云盘类型。
-
不支持变更系统盘计费方式。
-
实例的状态必须为已停止(
Stopped
)状态。说明 仅适用于专有网络 VPC 类型实例。如果 ECS 实例为按量付费计费模式,且开启默认启用节省停机模式,为防止地域范围内的 ECS 实例库存不足,引起的更换系统盘后无法重启实例。您需要在停止该实例时设置为普通停机模式。具体操作,请参见 StopInstance 。 -
ECS 实例不能被安全锁定,即实例的
OperationLocks
参数值包含"LockReason": "security"
。更多信息,请参见安全锁定时的 API 行为。 -
系统盘挂载的 ECS 实例不能有未支付的订单。
-
您可以通过参数
SystemDisk.Size
重新指定系统盘的容量大小。
更换系统盘后,建议您通过以下任一方式验证是否更换成功:
-
通过 DescribeDisks 接口查询新系统盘的状态。如果已挂载实例,则表示更换系统盘的操作已完成。
-
通过 DescribeInstances 接口查询更换系统盘的实例的状态。如果返回值
OperationLocks
为空,则表示更换系统盘的操作已完成。
调试
您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
下表是API对应的授权信息,可以在RAM权限策略语句的Action
元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:
- 操作:是指具体的权限点。
- 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
- 资源类型:是指操作中支持授权的资源类型。具体说明如下:
- 对于必选的资源类型,用背景高亮的方式表示。
- 对于不支持资源级授权的操作,用
全部资源
表示。
- 条件关键字:是指云产品自身定义的条件关键字。
- 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
---|---|---|---|---|
ecs:ReplaceSystemDisk | update | *Disk acs:ecs:{#regionId}:{#accountId}:disk/{#diskId} *Image acs:ecs:{#regionId}:{#accountId}:image/{#imageId} *Instance acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId} |
| 无 |
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
InstanceId | string | 是 | 指定实例的 ID。 | i-bp67acfmxazb4ph**** |
ImageId | string | 否 | 重置系统时使用的镜像 ID。 未设置 | m-bp67acfmxazb4ph**** |
SystemDisk.Size | integer | 否 | 新的系统盘容量,单位为 GiB。取值范围:
默认值:Max{40, 参数 ImageId 对应的镜像大小} 说明
超过 Max{20, 更换前的系统盘容量} 的云盘容量部分,将收取额外费用。
| 80 |
ClientToken | string | 否 | 保证请求幂等性。从您的客户端生成一个参数值,确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符,且不能超过 64 个字符。更多信息,请参见如何保证幂等性。 | 123e4567-e89b-12d3-a456-426655440000 |
UseAdditionalService | boolean | 否 | 是否使用阿里云提供的虚拟机系统配置(Windows:NTP、KMS;Linux:NTP、YUM)。 说明
挂载系统盘时(即设备名为/dev/xvda)有效。
| true |
Password | string | 否 | 是否重置 ECS 实例的用户名密码。长度为 8 至 30 个字符,必须同时包含大小写英文字母、数字和特殊符号中的三类字符。特殊符号可以是:
其中,Windows 实例不能以斜线号(/)为密码首字符。 默认值:保持不变。 说明
如果传入 Password 参数,建议您使用 HTTPS 协议发送请求,避免密码泄露。
| EcsV587! |
PasswordInherit | boolean | 否 | 是否使用镜像预设的密码。 默认值:false。 说明
使用该参数时,Password 参数必须为空。同时您需要确保使用的镜像已经设置了密码。
| false |
KeyPairName | string | 否 | 密钥对名称。 说明
该参数仅对 Linux 系统 ECS 实例生效。您可以为 ECS 实例绑定一个 SSH 密钥对,作为登录凭证。使用了 SSH 密钥对后,用户名密码的登录凭证方式将被禁用。
| testKeyPairName |
DiskId | string | 否 | 说明
该参数已废弃,为提高兼容性,建议您使用 ImageId 。
| d-bp67acfmxazb4ph**** |
Platform | string | 否 | 说明
已弃用。
| CentOS |
Architecture | string | 否 | 说明
已弃用。
| i386 |
SecurityEnhancementStrategy | string | 否 | 更换系统盘后,是否免费使用云安全中心服务。取值范围:
默认值:Deactive。 | Active |
Encrypted | boolean | 否 | 是否加密云盘。取值范围:
默认值:false。 | false |
KMSKeyId | string | 否 | 系统盘对应的 KMS 密钥 ID。 | e522b26d-abf6-4e0d-b5da-04b7******3c |
EncryptAlgorithm | string | 否 | 说明
该参数暂未开放使用。
| hide |
Arn | array<object> | 否 | 该参数暂未开放使用。 | |
object | 否 | |||
RoleType | string | 否 | 说明
该参数暂未开放使用。
| null |
Rolearn | string | 否 | 说明
该参数暂未开放使用。
| null |
AssumeRoleFor | long | 否 | 说明
该参数暂未开放使用。
| 0 |
返回参数
示例
正常返回示例
JSON
格式
{
"DiskId": "d-bp67acfmxazb4ph****",
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}
错误码
HTTP status code | 错误码 | 错误信息 | 描述 |
---|---|---|---|
400 | LoginAsNonRoot.ImageNotSupport | The specified image does not support login as non-root. | 此镜像不支持NonRoot登录。 |
400 | InvalidSystemDiskSize.ValueNotSupported | The specified parameter SystemDisk.Size is invalid. | 指定的 SystemDisk.Size 不合法。 |
400 | InvalidParameter.Conflict | The specified image does not support the specified instance type. | 指定的镜像不能用于指定的实例规格。 |
400 | InvalidSystemDiskSize.ImageNotSupportResize | The specified image does not support resize. | 指定的镜像不支持扩容。 |
400 | InvalidSystemDiskSize | The specified parameter SystemDisk.Size is invalid. | 指定的 SystemDisk.Size 不合法。 |
400 | InvalidPassword.Malformed | The specified parameter "Password" is not valid. | - |
400 | InvalidPasswordParam.Mismatch | The input password should be null when passwdInherit is true. | 启用 PasswdInherit 后,用户名密码应该设置为空。 |
400 | OperationDenied | The specified image contains the snapshot of the data disk,does not support this operation. | 包含了数据盘快照的镜像,不支持此操作。 |
400 | InvalidDiskCategory.ValueNotSupported | The specified parameter "DiskCategory" is not valid. | - |
400 | InvalidParameter.Conflict | %s | 您输入的参数无效,请检查参数之间是否冲突。%s为变量,将根据调用API的实际情况动态返回错误信息。 |
400 | InvalidSystemDiskSize.ValueNotSupported | %s | 当前操作不支持设置的系统盘大小。 |
400 | OperationDenied | %s | 拒绝操作。 |
400 | InvalidKeyPairName.NotFound | The specified KeyPairName does not exist. | 指定的 KeyPairName 不存在。 |
400 | DependencyViolation.IoOptimize | The specified parameter InstanceId is not valid. | 指定的实例 IO 优化配置不合法。 |
400 | MissingParameter.Architecture | Architecture should not be null. | 参数 Architecture 不能为空。 |
400 | InvalidArchitecture.Malformed | Architecture is not valid. | 您输入的参数 Architecture 无效,请查看该参数格式是否正确。 |
400 | MissingParameter.Platform | Platform should not be null. | 参数 Platform 不能为空。 |
400 | InvalidPlatform.Malformed | Platform is not valid. | 指定的平台无效。 |
400 | InvalidParameter.AllEmpty | %s | 您没有输入任何参数,请输入必要的参数。 |
400 | InvalidDiskId.NotFound | The specified disk do not exist. | 指定的磁盘不存在。 |
400 | InvalidDatadisk.DiskStatusViolation | The operation is not permitted due to status of the Datadisk. | 当前数据盘的状态不支持此操作。 |
400 | InvalidDatadisk.DiskCategoryViolation | The operation is not permitted due to category of the Datadisk. | 该数据盘的类型不支持该操作。 |
400 | InvalidDatadisk.ChargeTypeViolation | The operation is not permitted due to charge type of the Datadisk. | - |
400 | InvalidSystemDiskSize.ValueNotSupported | The specified SystemDiskSize is not valid. | 指定的 SystemDisk.Size 不合法。 |
400 | MissingParameter | The input parameter "ImageId" that is mandatory for processing this request is not supplied. | - |
400 | InvalidInstance.NotFoundSystemDisk | The specified instance has no system disk. | 指定的实例没有挂载系统盘。请确保指定的实例已挂载了系统盘。您可以调用 DescribeInstances 查询指定实例的信息。 |
400 | InvalidParameter.DiskType | The specified disk type which has kms key can't convert to system disk. | - |
400 | DISK_IN_DEDICATED_BLOCK_STORAGE_CLUSTER | The disk in dedicated block storage cluster is not allowed to do this operation. | - |
400 | IncorrectDiskStatus.ReplicationStatusNotFound | Disk replication status not found. | - |
400 | IncorrectDiskStatus.InReplication | Disk already in replication. | - |
400 | InvalidInstanceType.NotSupported | The specified instanceType is not supported by the image architecture. | - |
400 | InvalidRegionId.NotSupportReplaceEncryptedSystemDisk | The specified region not support replace encrypted system disk. | - |
400 | InvalidStorageClusterId.CapacityNotEnough | The remaining capacity of the current dedicated storage cluster is less than the size of disk. | 磁盘所在专属存储集群的可用容量不足 |
400 | QuotaExceed.DiskCapacity | The used capacity of disk type has exceeded the quota in the zone, %s. | 指定磁盘类型的已用容量超出可用区配额限制,您可以前往配额中心查询和申请提升磁盘容量配额。 |
403 | LoginAsNonRoot.RegionNotSupport | The specified region does not support login as non-root. | - |
403 | InvalidSystemDiskStatus.IsTransfering | The current status of the resource does not support this operation, system disk is transfering. | 当前资源的状态不支持此操作,请再系统盘停止传输数据后重试。 |
403 | IncorrectDiskStatus | The current disk status does not support this operation. | 当前的磁盘不支持此操作,请您确认磁盘处于正常使用状态,是否欠费。 |
403 | IncorrectInstanceStatus | The current status of the resource does not support this operation. | 该资源目前的状态不支持此操作。 |
403 | InstanceLockedForSecurity | The instance is locked due to security. | 您的资源被安全锁定,拒绝操作。 |
403 | ImageNotSubscribed | The specified image has not be subscribed. | 指定的镜像未在云市场镜像中订阅。 |
403 | ImageRemovedInMarket | The specified market image is not available, Or the specified user defined image includes product code because it is based on an image subscribed from marketplace, and that image in marketplace includeing exact the same product code has been removed. | 指定的市场镜像不可用,或者指定的用户定义镜像包含产品代码,因为它基于从市场订购的镜像,并且市场中包含完全相同的产品代码的镜像已被删除。 |
403 | InstanceExpiredOrInArrears | The specified operation is denied as your prepay instance is expired (prepay mode) or in arrears (afterpay mode). | 实例已过期或者欠费,请您续费或者结清后再进行操作。 |
403 | ChargeTypeViolation | The operation is not permitted due to charge type of the instance. | 付费方式不支持该操作,请您检查实例的付费类型是否与该操作冲突。 |
403 | DiskCreatingSnapshot | The operation is denied due to a snapshot of the specified disk is not completed yet. | 指定的磁盘正在创建快照。 |
403 | IoOptimized.NotSupported | The specified image is not support IoOptimized Instance. | 指定的镜像不支持 I/O 优化型实例。 |
403 | ImageNotSupportInstanceType | The specified image don not support the InstanceType instance. | 指定的镜像不支持此类实例规格。 |
403 | QuotaExceed.BuyImage | The specified image is from the image market,You have not bought it or your quota has been exceeded. | 您暂时不能使用指定的市场镜像。 |
403 | INST_HAS_UNPAID_ORDER | The instance has unpaid order. | 该实例有未完成的账单。 |
403 | OperationDenied.InstanceCreating | The specified instance is creating. | 指定的实例已存在。 |
403 | DependencyViolation.WindowsInstance | The instance creating is windows, cannot use ssh key pair to login. | - |
403 | InvalidParameter.NotMatch | %s | 您输入的参数无效,请检查参数之间是否冲突。 |
403 | ResourcesNotInSameZone | The specified instance and disk are not in the same zone. | 指定的实例和磁盘不在同一可用区。 |
403 | ImageNotSupportInstanceType | The specified instanceType is not supported by instance with marketplace image. | 指定的市场镜像不支持该实例规格。 |
403 | OperationDenied.UnpaidOrder | The specified instance has unpaid order. | 指定的实例ID已存在未支付订单,您可以登录ECS管理控制台支付。 |
403 | InvalidHostname.MismatchImage | The hostname of the current instance can not be applied to the image you choose. | - |
403 | OperationDenied.ImageNotValid | %s | 当前镜像不支持此操作。 |
403 | HibernationConfigured.InstanceOperationForbidden | The operation is not permitted due to limit of the hibernation configured instance. | 不符合开启休眠选项的实例的相关限制,操作不被允许。 |
403 | InvalidOperation.MultiAttachDisk | Multi attach disk does not support this operation. | 开启多重挂载特性的云盘不支持该操作。 |
403 | InvalidRegionId.NotSupportEncryptAlgorithm | The current region does not support creating encrypted disks with EncryptAlgorithm. | - |
403 | InvalidRegionId.NotExists | The region not exists. | - |
403 | InvalidEncryptAlgorithm | The specified parameter EncryptAlgorithm is not valid. | - |
403 | InvalidEncrypted.NotMatchKmsKeyId | The specified parameter Encrypted must be true when KmsKeyId is not empty. | - |
403 | InvalidEncrypted.NotMatchEncryptAlgorithm | The specified parameter Encrypted must be true when EncryptAlgorithm is not empty. | - |
403 | InvalidParameter.KmsNotEnabled | The specified operation need enable KMS. | 当前操作需要开启KMS。 |
403 | InvalidParameter.DataEncryptedKeyCreateFailed | Create kms data encrypted key fail. If you need further assistance, you can contact the KMS Technical Support. | - |
403 | InvalidParameter.KMSKeyId.NotFound | The specified KMSKeyId does not exist. | 指定的参数 KMSKeyId 不存在。 |
403 | InvalidParameter.KMSKeyId.CMKUnauthorized | This operation for kmsKeyId is forbidden by KMS. If you need further assistance, you can contact the KMS Technical Support. | - |
403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | 加密云盘设置了 KMSKeyId 后,CMK必须处于启用状态。您可以调用密钥管理服务的 DescribeKey 接口查询指定CMK的相关信息。 |
403 | InvalidParameter.KMSKeyId.KMSUnauthorized | ECS service have no right to access your KMS. | ECS 服务无权访问您的 KMS。 |
403 | InvalidKMSKeyId.NotSymmetric | The specified parameter KmsKeyId must be symmetric. | - |
403 | InvalidEncrypted.NotMatchKmsKeyId | The specified parameter Encrypted must be true when kmsKeyId is not null. | - |
403 | InvalidDiskId.NotSupportReplaceEncryptedSystemDisk | The specified diskId not support replace encrypted system disk. | - |
403 | NotSupportSnapshotEncrypted.DiskCategory | The specified disk category does not support creating encrypted system disks or creating encrypted data disks from snapshots. Check the DiskCategory or Encrypted parameter, or check your account for default encryption settings. | 该磁盘类型不支持创建加密系统盘或以快照方式创建加密数据盘,请检查您输入的磁盘类型、加密参数,或者检查您是否做过账号云盘默认加密配置。 |
403 | InvalidEncrypted.DefaultEncryptionUnsupported | The specified parameter Encrypted must be true when default encryption is enabled. | 开启云盘默认加密后新购云盘必须为加密云盘. |
404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. | 指定的实例ID未找到。 |
404 | InvalidInstanceId.NotFound | The specified instance does not exist. | 指定的实例不存在,请您检查实例 ID 是否正确。 |
404 | InvalidImageId.NotFound | The specified ImageId does not exist. | 指定的镜像在该用户账号下不存在,请您检查镜像 ID 是否正确。 |
404 | InvalidSystemDiskSize.MoreThanMaxSize | The specified SystemDisk.Size parameter exceeds the maximum size. | 指定的系统盘大小超出最大容量。 |
404 | InvalidSystemDiskSize.LessThanImageSize | The specified parameter SystemDisk.Size is less than the image size. | 指定的参数 SystemDisk.Size 小于镜像文件大小数值。 |
404 | InvalidSystemDiskSize.LessThanMinSize | The specified parameter SystemDisk.Size is less than the min size. | 指定的系统盘小于最低容量。 |
404 | NoSuchResource | The specified resource is not found. | 指定的资源不存在。 |
500 | OperationDenied | Internal Error. | 内部错误。 |
500 | InternalError | The request processing has failed due to some unknown error. | 内部错误,请重试。 |
500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | 内部错误,请重试。 |
500 | OperationDenied | The specified InstanceType or Zone is not available or not authorized. | 指定的实例规格或可用区不可用或者未授权。 |
访问错误中心查看更多错误码。
变更历史
变更时间 | 变更内容概要 | 操作 |
---|---|---|
2024-06-27 | OpenAPI 错误码发生变更 | 查看变更详情 |
2024-05-08 | OpenAPI 错误码发生变更 | 查看变更详情 |
2024-01-15 | OpenAPI 错误码发生变更 | 查看变更详情 |
2021-12-06 | OpenAPI 错误码发生变更 | 查看变更详情 |