Upgrades or downgrades the instance type of a subscription Elastic Compute Service (ECS) instance. The new instance type takes effect for the remaining lifecycle of the instance.

Description

Before you call this operation, make sure that you understand the billing methods, pricing schedule, and refund rules of Elastic Compute Service. For more information, see Refund rules for real-time configuration downgrade.

Before you change the instance type of a subscription instance, you can call the DescribeResourcesModification operation to query the instance types to which you can change. You can use ECS SDK for Python to query the instance types to which you can change. For more information, see Query available resources for configuration changes.

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

  • You cannot change the instance type of an expired instance. You can renew the instance and try again.
  • When you downgrade the instance type of an instance, take note of the following items:
    • The instance must be in the Stopped (Stopped) state.
    • You must specify the operation type by setting OperatorType to downgrade.
    • You can downgrade the configurations of an instance a maximum of three times. Therefore, a maximum of three refunds for price difference can be made for an instance. Downgrade operations include instance type downgrades, bandwidth configuration downgrades, and the change of the disk billing method from subscription to pay-as-you-go.
    • The price difference is refunded to the payment account you used. Vouchers that have been redeemed are not refundable.
  • This operation is asynchronous. It takes 5 to 10 seconds for the instance type of an instance to change. Then, you must restart the instance by calling the RebootInstance operation or by using the ECS console for the instance type change to take effect. If you restart only the operating system of the instance, the instance type change does not take effect.
    • If the instance is in the Stopped state, you need only to start the instance. You do not need to restart the instance after it enters the Running state.
    • If RebootWhenFinished is set to true for the instance, you do not need to manually restart the instance.

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 Yes ModifyPrepayInstanceSpec

The operation that you want to perform. Set the value to ModifyPrepayInstanceSpec.

InstanceId String Yes i-bp67acfmxazb4ph****

The ID of the instance.

RegionId String Yes cn-hangzhou

The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.

InstanceType String Yes ecs.g5.xlarge

The new instance type. For information about available instance types, see Instance families or call the DescribeInstanceTypes operation.

OperatorType String No upgrade

The operation type. Valid values:

  • upgrade: upgrades the instance type. Make sure that the balance in your account is sufficient.
  • downgrade: downgrades the instance type. When the new instance type specified by the InstanceType parameter has lower specifications than the current instance type, you must set OperatorType to downgrade.

Default value: upgrade.

Note For more information about the precautions on upgrading or downgrading instance types, see the preceding "Description" section in this topic.
ClientToken String No 123e4567-e89b-12d3-a456-426655440000

The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must make sure that the value is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.

AutoPay Boolean No true

Specifies whether to enable automatic payment when you upgrade the instance type. Valid values:

  • true: enables automatic payment.
    Note Make sure that your payment account has sufficient balance. Otherwise, your order becomes invalid and is canceled. If your account balance is insufficient, you can set the AutoPay parameter to false to generate an unpaid order. Then, you can log on to the ECS console to pay for the order.
  • false: An order is generated but no payment is made.

Default value: true.

When OperatorType is set to downgrade, AutoPay is ignored.

MigrateAcrossZone Boolean No false

Specifies whether to support cross-cluster instance type upgrades.

Default value: false.

When the MigrateAcrossZone parameter is set to true and you upgrade the instance based on the returned information, take note of the following items:

Instances of the classic network type:

  • For retired instance types, when a non-I/O optimized instance is upgraded to an I/O optimized instance, the private IP address, disk device names, and software license codes of the instance are changed. For more information, see Retired instance types. For Linux instances, basic disks (cloud) are identified as xvd* such as xvda and xvdb. Ultra disks (cloud_efficiency) and standard SSDs (cloud_ssd) are identified as vd* such as vda and vdb.
  • For instance families available for purchase, when the instance type of an instance is changed, the private IP address of the instance is also changed. For more information, see Instance families.

Instances of the Virtual Private Cloud (VPC) type: For retired instance types, when a non-I/O optimized instance is upgraded to an I/O optimized instance, the disk device names and software license codes of the instance are changed. For Linux instances, basic disks (cloud) are identified as xvd* such as xvda and xvdb. Ultra disks (cloud_efficiency) and standard SSDs (cloud_ssd) are identified as vd* such as vda and vdb.

SystemDisk.Category String No cloud_efficiency

The new category of the system disk. This parameter is valid only when you upgrade an instance from a retired instance type to an available instance type or upgrade a non-I/O optimized instance to an I/O optimized instance. For more information, see Retired instance types and Instance families. Valid values:

  • cloud_efficiency: ultra disk
  • cloud_ssd: standard SSD
RebootTime String No 2018-01-01T12:05Z

The restart time of the instance. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

EndTime String No 2018-01-01T12:05Z

The end time of the temporary change. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

RebootWhenFinished Boolean No false

Specifies whether to restart the instance immediately after the instance type is changed. Valid values:

  • true
  • false

Default value: false.

Note If the instance is in the Stopping state, the instance state remains unchanged and no operations are performed regardless of whether the RebootWhenFinished parameter is set to true.

Response parameters

Parameter Type Example Description
OrderId String 1234567890

The ID of the order.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=ModifyPrepayInstanceSpec
&RegionId=cn-hangzhou
&InstanceId=i-bp67acfmxazb4ph****
&InstanceType=ecs.g5.xlarge
&AutoPay=true
&OperatorType=upgrade
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<ModifyPrepayInstanceSpecResponse>
    <RequestId>04F0F334-1335-436C-A1D7-6C044FE73368</RequestId>
    <OrderId>1234567890</OrderId>
</ModifyPrepayInstanceSpecResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "04F0F334-1335-436C-A1D7-6C044FE73368",
  "OrderId" : "1234567890"
}

Error codes

HTTP status code Error code Error message Description
400 InvalidInstanceType.ValueUnauthorized The specified InstanceType is not authorized. The error message returned because you are not authorized to use the specified instance type.
400 InvalidInstanceType.ValueNotSupported The specified InstanceType does not exist or beyond the permitted range. The error message returned because the specified InstanceType parameter does not exist or because you are not authorized to manage instances of this instance type.
400 InvalidBillingMethod.ValueNotSupported The operation is not permitted due to an invalid billing method of the instance. The error message returned because the operation is not supported due to the invalid billing method of the instance.
400 InvalidInstance.PurchaseNotFound The specified instance has no purchase history. The error message returned because the order record for the instance does not exist.
400 InvalidInstanceType.NotSupported The specified InstanceType is not Supported. The error message returned because the specified InstanceType parameter is invalid.
400 OrderCreationFailed Order creation failed, please check your params and try it again later. The error message returned because the order fails to be created. Check your parameters and try again.
400 Throttling You have made too many requests within a short time; your request is denied due to request throttling. The error message returned because your request is denied due to throttling. Try again later.
400 Account.Arrearage Your account has an outstanding payment. The error message returned because you have overdue payments in your account.
400 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified instance does not exist.
400 InvalidRebootTime.MalFormed The specified rebootTime is not valid. The error message returned because the specified RebootTime parameter is invalid.
400 InvalidRebootTime.ValueNotSupported The specified RebootTime is not valid. The error message returned because the specified RebootTime parameter is invalid.
400 IdempotenceParamNotMatch Request uses a client token in a previous request but is not identical to that request. The error message returned because the ClientToken value in this request is identical to that in the previous request but some other parameters in this request are different from those in the previous request.
400 IdempotenceParamNotMatch %s The error message returned because the idempotent parameters do not match.
400 InvalidInstanceChargeType.ValueNotSupported %s The error message returned because the specified InstanceChargeType parameter is not supported.
400 InvalidStatus.NotStopped Instance status must be stopped. The error message returned because the instance is not in the Stopped state. The operation can be performed only when the instance is in the Stopped state.
400 InvalidAction %s The error message returned because the operation is invalid.
400 InstanceDowngrade.QuotaExceed Quota of instance downgrade is exceed. The error message returned because the maximum number of configuration downgrades allowed for the instance has been reached.
400 InvalidInstanceType.ValueNotSupported %s The error message returned because the operation is not supported by the specified instance type.
400 InvalidParameter %s The error message returned because a specified parameter is invalid.
400 OperationDenied The current user does not support this operation. The error message returned because your account does not support the operation.
400 LastOrderProcessing The previous order is still processing, please try again later. The error message returned because the order is being processed. Try again later.
400 InvalidOperation.VpcHasEnabledAdvancedNetworkFeature The specified vpc has enabled advanced network feature. The error message returned because advanced features are enabled for the specified VPC. You cannot create low-specification instances in the VPC.
400 InvalidAction.WithActiveElasticUpgrade The instance has active Elastic Upgrade. The error message returned because the operation is not supported while the configurations of the instance are being temporarily upgraded. The configurations of the instance go through a temporary upgrade if the EndTime parameter is specified to call the ModifyPrepayInstanceSpec operation.
403 OperationDenied.NoStock The specified instance is out of usage. The error message returned because the resources of the specified instance type are insufficient.
403 InvalidUser.PassRoleForbidden The RAM user does not have privilege to pass a role. The error message returned because RAM users are not authorized to assign RAM roles.
403 ImageNotSupportInstanceType The specified image does not support the specified InstanceType. The error message returned because the specified image does not support the specified instance type.
403 InstanceType.Offline %s The error message returned because the operation is not supported while the instance type is retired or while resources of the instance type are insufficient.
403 IncorrectInstanceStatus The current status of the resource does not support this operation. The error message returned because the operation is not supported while the resource is in the current state.
403 InvalidParameter.InstanceId %s The error message returned because the specified InstanceId parameter is invalid.
403 OperationDenied %s The error message returned because the operation is denied.
403 ImageNotSupportInstanceType The specified instanceType is not supported by instance with marketplace image. The error message returned because the specified Alibaba Cloud Marketplace image does not support the instance type.
403 InvalidInstanceStatus The current status of the instance does not support this operation. The error message returned because the operation is not supported while the instance is in the current state.
403 InvalidInstance.PreInstanceExpired Instance business status is not Expired The error message returned because the instance has expired.
403 InvalidInstance.EipNotSupport The special instance with eip not support operate, please unassociate eip first. The error message returned because the operation is not supported while an elastic IP address (EIP) is associated with this instance. Disassociate the EIP first.
403 OperationDenied.LocalDiskUnsupported The configuration change is not allowed when the specified instance has local disks mounted. The error message returned because the instance types of instances that have local disks attached cannot be changed.
403 OperationDenied.NoStock The resource is out of stock in the specified zone. Please try other types, or choose other regions and zones. The error message returned because the specified resource is unavailable in the specified zone. Try another resource type or select another region or zone.
403 InvalidOperation.Ipv4CountExceeded %s The error message returned because the maximum number of IPv4 addresses has been reached.
403 InvalidOperation.Ipv6CountExceeded %s The error message returned because the maximum number of IPv6 addresses has been reached.
403 InvalidOperation.Ipv6NotSupport %s The error message returned because IPv6 addresses do not support this operation.
403 InvalidInstance.NotFoundSystemDisk The specified instance has no system disk. The error message returned because the specified instance does not have a system disk attached. Make sure that the specified instance has a system disk attached. You can call the DescribeInstances operation to query the details of the specified instance.
403 InvalidInstanceType.NotSupportDiskCategory The instanceType of the specified instance does not support this disk category. The error message returned because the instance type specified by the InstanceType parameter does not support the disk category of the instance. Try another instance type. For information about the disk categories supported by instance types, see the instance family documentation.
403 QuotaExceed.ElasticQuota No additional quota is available for the specified ECS instance type. The error message returned because the maximum number of instances of the specified instance type in the region has been reached. Try another region or instance type, or reduce the purchase quantity. You can go to the ECS console or Quota Center to request a quota increase.
403 QuotaExceed.ElasticQuota The number of the specified ECS instances has exceeded the quota of the specified instance type. The error message returned because the maximum number of instances of the specified instance type in the region has been reached. Try another region or instance type, or reduce the purchase quantity. You can go to the ECS console or Quota Center to request a quota increase.
403 QuotaExceed.ElasticQuota The number of vCPUs assigned to the ECS instances has exceeded the quota in the zone. The error message returned because the maximum number of vCPUs for all instance types in the zone has been reached. You can go to the ECS console or Quota Center to request a quota increase.
403 QuotaExceed.ElasticQuota The number of the specified ECS instances has exceeded the quota of the specified instance type, or the number of vCPUs assigned to the ECS instances has exceeded the quota in the zone. The error message returned because the maximum number of instances of the specified instance type in the region has been reached or because the maximum number of vCPUs for all instance types has been reached. You can go to the ECS console or Quota Center to request a quota increase.
403 InvalidOperation.MaxEniQueueNumberExceeded %s The error message returned because the maximum number of queues per elastic network interface (ENI) has been reached. For more information, see the return value of the %s placeholder in the error message.
403 InvalidOperation.ExceedInstanceTypeQueueNumber %s The error message returned because the maximum number of queues for all ENIs on an instance has been reached. For more information, see the return value of the %s placeholder in the error message.
403 InvalidParameter.InvalidEniQueueNumber %s The error message returned because the specified number of queues per ENI is invalid. For more information, see the return value of the %s placeholder in the error message.
404 InvalidRegionId.NotFound The specified RegionId does not exist. The error message returned because the specified RegionId parameter does not exist.
404 BillingMethodNotFound The account has not chosen any billing method. The error message returned because no billing method is selected for the Alibaba Cloud account.
500 InternalError The request processing has failed due to some unknown error, exception or failure. The error message returned because an internal error has occurred. Try again later. If the error persists, submit a ticket.
500 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later. If the error persists, submit a ticket.

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