全部产品
Search
文档中心

云服务器 ECS:ReplaceSystemDisk - 更换操作系统

更新时间:Mar 19, 2024

调用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:ReplaceSystemDiskWrite
  • Disk
    acs:ecs:{#regionId}:{#accountId}:disk/{#diskId}
  • Image
    acs:ecs:{#regionId}:{#accountId}:image/{#imageId}
  • Instance
    acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
  • ecs:tag

请求参数

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

指定实例的 ID。

i-bp67acfmxazb4ph****
ImageIdstring

重置系统时使用的镜像 ID。

未设置DiskId参数时,该参数为必选参数。

m-bp67acfmxazb4ph****
SystemDisk.Sizeinteger

新的系统盘容量,单位为 GiB。取值范围:

  • 普通云盘:Max{20, 参数 ImageId 对应的镜像大小}~500。
  • 其他云盘:Max{20, 参数 ImageId 对应的镜像大小}~2048。

默认值:Max{40, 参数 ImageId 对应的镜像大小}

说明 超过Max{20, 更换前的系统盘容量}的云盘容量部分,将收取额外费用。
80
ClientTokenstring

保证请求幂等性。从您的客户端生成一个参数值,确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符,且不能超过 64 个字符。更多信息,请参见如何保证幂等性

123e4567-e89b-12d3-a456-426655440000
UseAdditionalServiceboolean

是否使用阿里云提供的虚拟机系统配置(Windows:NTP、KMS;Linux:NTP、YUM)。

说明 挂载系统盘时(即设备名为/dev/xvda)有效。
true
Passwordstring

是否重置 ECS 实例的用户名密码。长度为 8 至 30 个字符,必须同时包含大小写英文字母、数字和特殊符号中的三类字符。特殊符号可以是:

()`~!@#$%^&*-_+=|{}[]:;'<>,.?/

其中,Windows 实例不能以斜线号(/)为密码首字符。

默认值:保持不变。

说明 如果传入Password参数,建议您使用 HTTPS 协议发送请求,避免密码泄露。
EcsV587!
PasswordInheritboolean

是否使用镜像预设的密码。

默认值:false。

说明 使用该参数时,Password 参数必须为空。同时您需要确保使用的镜像已经设置了密码。
false
KeyPairNamestring

密钥对名称。

说明 该参数仅对 Linux 系统 ECS 实例生效。您可以为 ECS 实例绑定一个 SSH 密钥对,作为登录凭证。使用了 SSH 密钥对后,用户名密码的登录凭证方式将被禁用。
testKeyPairName
DiskIdstring
说明 该参数已废弃,为提高兼容性,建议您使用 ImageId
d-bp67acfmxazb4ph****
Platformstring
说明 已弃用。
CentOS
Architecturestring
说明 已弃用。
i386
SecurityEnhancementStrategystring

更换系统盘后,是否免费使用云安全中心服务。取值范围:

  • Active:使用。该值仅支持公共镜像。

  • Deactive:不使用。该值支持所有镜像。

默认值:Deactive。

Active
Encryptedboolean

是否加密云盘。取值范围:

  • true:是。

  • false:否。

默认值:false。

false
KMSKeyIdstring

系统盘对应的 KMS 密钥 ID。

e522b26d-abf6-4e0d-b5da-04b7******3c
EncryptAlgorithmstring
说明 该参数暂未开放使用。
hide
Arnobject []

该参数暂未开放使用。

RoleTypestring
说明 该参数暂未开放使用。
null
Rolearnstring
说明 该参数暂未开放使用。
null
AssumeRoleForlong
说明 该参数暂未开放使用。
0

返回参数

名称类型描述示例值
object
DiskIdstring

新系统盘的云盘 ID。

d-bp67acfmxazb4ph****
RequestIdstring

请求 ID。

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

示例

正常返回示例

JSON格式

{
  "DiskId": "d-bp67acfmxazb4ph****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

错误码

HTTP status code错误码错误信息描述
400LoginAsNonRoot.ImageNotSupportThe specified image does not support login as non-root.此镜像不支持NonRoot登录。
400InvalidSystemDiskSize.ValueNotSupportedThe specified parameter SystemDisk.Size is invalid.指定的 SystemDisk.Size 不合法。
400InvalidParameter.ConflictThe specified image does not support the specified instance type.指定的镜像不能用于指定的实例规格。
400InvalidSystemDiskSize.ImageNotSupportResizeThe specified image does not support resize.指定的镜像不支持扩容。
400InvalidSystemDiskSizeThe specified parameter SystemDisk.Size is invalid.指定的 SystemDisk.Size 不合法。
400InvalidPassword.MalformedThe specified parameter "Password" is not valid.-
400InvalidPasswordParam.MismatchThe input password should be null when passwdInherit is true.启用 PasswdInherit 后,用户名密码应该设置为空。
400OperationDeniedThe specified image contains the snapshot of the data disk,does not support this operation.包含了数据盘快照的镜像,不支持此操作。
400InvalidDiskCategory.ValueNotSupportedThe specified parameter "DiskCategory" is not valid.-
400InvalidParameter.Conflict%s您输入的参数无效,请检查参数之间是否冲突。%s为变量,将根据调用API的实际情况动态返回错误信息。
400InvalidSystemDiskSize.ValueNotSupported%s当前操作不支持设置的系统盘大小。
400OperationDenied%s拒绝操作。
400InvalidKeyPairName.NotFoundThe specified KeyPairName does not exist.指定的 KeyPairName 不存在。
400DependencyViolation.IoOptimizeThe specified parameter InstanceId is not valid.指定的实例 IO 优化配置不合法。
400MissingParameter.ArchitectureArchitecture should not be null.参数 Architecture 不能为空。
400InvalidArchitecture.MalformedArchitecture is not valid.您输入的参数 Architecture 无效,请查看该参数格式是否正确。
400MissingParameter.PlatformPlatform should not be null.参数 Platform 不能为空。
400InvalidPlatform.MalformedPlatform is not valid.指定的平台无效。
400InvalidParameter.AllEmpty%s您没有输入任何参数,请输入必要的参数。
400InvalidDiskId.NotFoundThe specified disk do not exist.指定的磁盘不存在。
400InvalidDatadisk.DiskStatusViolationThe operation is not permitted due to status of the Datadisk.当前数据盘的状态不支持此操作。
400InvalidDatadisk.DiskCategoryViolationThe operation is not permitted due to category of the Datadisk.该数据盘的类型不支持该操作。
400InvalidDatadisk.ChargeTypeViolationThe operation is not permitted due to charge type of the Datadisk.-
400InvalidSystemDiskSize.ValueNotSupportedThe specified SystemDiskSize is not valid.指定的 SystemDisk.Size 不合法。
400MissingParameterThe input parameter "ImageId" that is mandatory for processing this request is not supplied.-
400InvalidInstance.NotFoundSystemDiskThe specified instance has no system disk.指定的实例没有挂载系统盘。请确保指定的实例已挂载了系统盘。您可以调用 DescribeInstances 查询指定实例的信息。
400InvalidParameter.DiskTypeThe specified disk type which has kms key can't convert to system disk.-
400DISK_IN_DEDICATED_BLOCK_STORAGE_CLUSTERThe disk in dedicated block storage cluster is not allowed to do this operation.-
400IncorrectDiskStatus.ReplicationStatusNotFoundDisk replication status not found.-
400IncorrectDiskStatus.InReplicationDisk already in replication.-
400InvalidInstanceType.NotSupportedThe specified instanceType is not supported by the image architecture.-
400InvalidRegionId.NotSupportReplaceEncryptedSystemDiskThe specified region not support replace encrypted system disk.-
400InvalidStorageClusterId.CapacityNotEnoughThe remaining capacity of the current dedicated storage cluster is less than the size of disk.磁盘所在专属存储集群的可用容量不足
400QuotaExceed.DiskCapacityThe used capacity of disk type has exceeded the quota in the zone, %s.指定磁盘类型的已用容量超出可用区配额限制,您可以前往配额中心查询和申请提升磁盘容量配额。
403LoginAsNonRoot.RegionNotSupportThe specified region does not support login as non-root.-
403InvalidSystemDiskStatus.IsTransferingThe current status of the resource does not support this operation, system disk is transfering.当前资源的状态不支持此操作,请再系统盘停止传输数据后重试。
403IncorrectDiskStatusThe current disk status does not support this operation.当前的磁盘不支持此操作,请您确认磁盘处于正常使用状态,是否欠费。
403IncorrectInstanceStatusThe current status of the resource does not support this operation.该资源目前的状态不支持此操作。
403InstanceLockedForSecurityThe instance is locked due to security.您的资源被安全锁定,拒绝操作。
403ImageNotSubscribedThe specified image has not be subscribed.指定的镜像未在云市场镜像中订阅。
403ImageRemovedInMarketThe 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.指定的市场镜像不可用,或者指定的用户定义镜像包含产品代码,因为它基于从市场订购的镜像,并且市场中包含完全相同的产品代码的镜像已被删除。
403InstanceExpiredOrInArrearsThe specified operation is denied as your prepay instance is expired (prepay mode) or in arrears (afterpay mode).实例已过期或者欠费,请您续费或者结清后再进行操作。
403ChargeTypeViolationThe operation is not permitted due to charge type of the instance.付费方式不支持该操作,请您检查实例的付费类型是否与该操作冲突。
403DiskCreatingSnapshotThe operation is denied due to a snapshot of the specified disk is not completed yet.指定的磁盘正在创建快照。
403IoOptimized.NotSupportedThe specified image is not support IoOptimized Instance.指定的镜像不支持 I/O 优化型实例。
403ImageNotSupportInstanceTypeThe specified image don not support the InstanceType instance.指定的镜像不支持此类实例规格。
403QuotaExceed.BuyImageThe specified image is from the image market,You have not bought it or your quota has been exceeded.您暂时不能使用指定的市场镜像。
403INST_HAS_UNPAID_ORDERThe instance has unpaid order.该实例有未完成的账单。
403OperationDenied.InstanceCreatingThe specified instance is creating.指定的实例已存在。
403DependencyViolation.WindowsInstanceThe instance creating is windows, cannot use ssh key pair to login.-
403InvalidParameter.NotMatch%s您输入的参数无效,请检查参数之间是否冲突。
403ResourcesNotInSameZoneThe specified instance and disk are not in the same zone.指定的实例和磁盘不在同一可用区。
403ImageNotSupportInstanceTypeThe specified instanceType is not supported by instance with marketplace image.指定的市场镜像不支持该实例规格。
403OperationDenied.UnpaidOrderThe specified instance has unpaid order.指定的实例ID已存在未支付订单,您可以登录ECS管理控制台支付。
403InvalidHostname.MismatchImageThe hostname of the current instance can not be applied to the image you choose.-
403OperationDenied.ImageNotValid%s当前镜像不支持此操作。
403HibernationConfigured.InstanceOperationForbiddenThe operation is not permitted due to limit of the hibernation configured instance.不符合开启休眠选项的实例的相关限制,操作不被允许。
403InvalidOperation.MultiAttachDiskMulti attach disk does not support this operation.开启多重挂载特性的云盘不支持该操作。
403InvalidRegionId.NotSupportEncryptAlgorithmThe current region does not support creating encrypted disks with EncryptAlgorithm.-
403InvalidRegionId.NotExistsThe region not exists.-
403InvalidEncryptAlgorithmThe specified parameter EncryptAlgorithm is not valid.-
403InvalidEncrypted.NotMatchKmsKeyIdThe specified parameter Encrypted must be true when KmsKeyId is not empty.-
403InvalidEncrypted.NotMatchEncryptAlgorithmThe specified parameter Encrypted must be true when EncryptAlgorithm is not empty.-
403InvalidParameter.KmsNotEnabledThe specified operation need enable KMS.当前操作需要开启KMS。
403InvalidParameter.DataEncryptedKeyCreateFailedCreate kms data encrypted key fail. If you need further assistance, you can contact the KMS Technical Support.-
403InvalidParameter.KMSKeyId.NotFoundThe specified KMSKeyId does not exist.指定的参数 KMSKeyId 不存在。
403InvalidParameter.KMSKeyId.CMKUnauthorizedThis operation for kmsKeyId is forbidden by KMS. If you need further assistance, you can contact the KMS Technical Support.-
403InvalidParameter.KMSKeyId.CMKNotEnabledThe CMK needs to be enabled.加密云盘设置了 KMSKeyId 后,CMK必须处于启用状态。您可以调用密钥管理服务的 DescribeKey 接口查询指定CMK的相关信息。
403InvalidParameter.KMSKeyId.KMSUnauthorizedECS service have no right to access your KMS.ECS 服务无权访问您的 KMS。
403InvalidKMSKeyId.NotSymmetricThe specified parameter KmsKeyId must be symmetric.-
403InvalidEncrypted.NotMatchKmsKeyIdThe specified parameter Encrypted must be true when kmsKeyId is not null.-
403InvalidDiskId.NotSupportReplaceEncryptedSystemDiskThe specified diskId not support replace encrypted system disk.-
403NotSupportSnapshotEncrypted.DiskCategoryThe 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.该磁盘类型不支持创建加密系统盘或以快照方式创建加密数据盘,请检查您输入的磁盘类型、加密参数,或者检查您是否做过账号云盘默认加密配置。
403InvalidEncrypted.DefaultEncryptionUnsupportedThe specified parameter Encrypted must be true when default encryption is enabled.开启云盘默认加密后新购云盘必须为加密云盘.
404InvalidInstanceId.NotFoundThe specified InstanceId does not exist.指定的实例ID未找到。
404InvalidInstanceId.NotFoundThe specified instance does not exist.指定的实例不存在,请您检查实例 ID 是否正确。
404InvalidImageId.NotFoundThe specified ImageId does not exist.指定的镜像在该用户账号下不存在,请您检查镜像 ID 是否正确。
404InvalidSystemDiskSize.MoreThanMaxSizeThe specified SystemDisk.Size parameter exceeds the maximum size.指定的系统盘大小超出最大容量。
404InvalidSystemDiskSize.LessThanImageSizeThe specified parameter SystemDisk.Size is less than the image size.指定的参数 SystemDisk.Size 小于镜像文件大小数值。
404InvalidSystemDiskSize.LessThanMinSizeThe specified parameter SystemDisk.Size is less than the min size.指定的系统盘小于最低容量。
404NoSuchResourceThe specified resource is not found.指定的资源不存在。
500OperationDeniedInternal Error.内部错误。
500InternalErrorThe request processing has failed due to some unknown error.内部错误,请重试。
500InternalErrorThe request processing has failed due to some unknown error, exception or failure.内部错误,请重试。

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

变更历史

变更时间变更内容概要操作
2024-01-15OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 403 变更
    删除错误码:400
    删除错误码:404
    删除错误码:500
2021-12-06OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 400 变更
    错误码 403 变更
    删除错误码:404
    删除错误码:500