Modifies some attributes of an Elastic Compute Service (ECS) instance, such as the password, name, description, hostname, security group, and user data. If the instance is a burstable instance, you can also change its performance mode.
Description
When you query the instance information and the responses contain {"OperationLocks": {"LockReason" : "security"}}
, the instance is locked for security reasons and all operations cannot take effect
on the instance.
When you call this operation, take note of the following items:
- Modify the hostname (
HostName
): After the hostname is modified, you must restart the instance by performing the operations described in Restart an instance in the ECS console or by calling the RebootInstance operation for the new hostname to take effect. The new hostname does not take effect if you restart the instance from within the operating system. - Reset the password (
Password
):- The instance must not be in the Starting (
Starting
) state. - After the password is reset, you must restart the instance by performing the operations described in Restart an instance in the ECS console or by calling the RebootInstance operation for the new password to take effect. The new password does not take effect if you restart the instance from within the operating system.
- The instance must not be in the Starting (
- Modify user data (
UserData
):- The instance must be in the Stopped (
Stopped
) state. - The instance must meet the limits on user data. For more information, see Prepare user data.
- The instance must be in the Stopped (
- Change the security group (
SecurityGroupIds.N
):-
You can switch an instance to a security group of a different type.
If you want to switch an instance to a security group of a different type, you must understand the differences between the rule configurations of the two security group types to avoid impacts on the instance network.
-
Security groups of instances in the classic network cannot be changed.
For more information, see the description of the
SecurityGroupIds.N
parameter.
-
- Modify the number of queues supported by the primary elastic network interface (ENI)
(
NetworkInterfaceQueueNumber
):- The instance must be in the Stopped (
Stopped
) state. - The value of this parameter cannot exceed the maximum number of queues per ENI allowed for the instance type.
- The total number of queues for all ENIs on the instance cannot exceed the queue quota
for the instance type. To obtain the maximum number of queues per ENI and the queue
quota for an instance type, you can call the DescribeInstanceTypes operation to query the
MaximumQueueNumberPerEni
andTotalEniQueueQuantity
parameters. - If you set this parameter to -1, the value is reset to the default value for the instance
type. To obtain the default number of queues supported by the primary ENI for an instance
type, you can call the DescribeInstanceTypes operation to query the
PrimaryEniQueueNumber
parameter.
- The instance must be in the Stopped (
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | ModifyInstanceAttribute |
The operation that you want to perform. Set the value to ModifyInstanceAttribute. |
InstanceId | String | Yes | i-bp67acfmxazb4ph**** |
The ID of the instance. |
Password | String | No | Test123456 |
The password of the instance. The password must be 8 to 30 characters in length and contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. Special characters include:
For Windows instances, the password cannot start with a forward slash (/). Note For security reasons, we recommend that you use HTTPS to send requests if the
Password parameter is specified.
|
HostName | String | No | testHostName |
The hostname of the instance. Take note of the following items:
The following limits apply to the hostnames of instances that run different operating systems:
|
InstanceName | String | No | testInstanceName |
The name of the instance. The name must be 2 to 128 characters in length. It must
start with a letter and cannot start with |
Description | String | No | testInstanceDescription |
The description of the instance. The description must be 2 to 256 characters in length
and cannot start with This parameter is empty by default. |
UserData | String | No | ZWNobyBoZWxsbyBlY3Mh |
The user data of the instance. User data must be encoded in Base64. The size of the user data must be no greater than 16 KB before it is encoded in Base64. We recommend that you do not pass in confidential information such as passwords and private keys in the plaintext format. If you must pass in confidential information, we recommend that you encrypt and Base64-encode the information before you pass it in. Then you can decode and decrypt the information in the same way within the instance. |
CreditSpecification | String | No | Standard |
The performance mode of the burstable instance. Valid values:
For more information about the performance modes of burstable instances, see Burstable instances. |
DeletionProtection | Boolean | No | false |
The release protection attribute of the instance. This parameter specifies whether you can use the ECS console or call the DeleteInstance operation to release the instance. Note This parameter is applicable only to pay-as-you-go instances. It can protect instances
only against manual releases, but not against automatic releases.
|
NetworkInterfaceQueueNumber | Integer | No | 8 |
The number of queues supported by the primary ENI. |
SecurityGroupIds.N | String | No | sg-bp15ed6xe1yxeycg7o**** |
The IDs of replacement security groups.
|
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
RequestId | String | 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
The ID of the request. |
Examples
Sample requests
https://ecs.aliyuncs.com/?Action=ModifyInstanceAttribute
&InstanceId=i-bp67acfmxazb4ph****
&Action=ModifyInstanceAttribute
&CreditSpecification=Standard
&DeletionProtection=false
&Description=testInstanceDescription
&HostName=testHostName
&InstanceName=testInstanceName
&Password=Test123456
&SecurityGroupIds.1=sg-bp15ed6xe1yxeycg7o****
&SecurityGroupIds.2=sg-bp15ed6xe1yxeycg7p****
&SecurityGroupIds.3=sg-bp15ed6xe1yxeycg7q****
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<ModifyInstanceAttributeResponse>
<RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
</ModifyInstanceAttributeResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}
Error codes
HTTP status code | Error code | Error message | Description |
---|---|---|---|
400 | InvalidInstanceName.Malformed | The specified parameter "InstanceName" is not valid. | The error message returned because the specified InstanceName parameter is invalid. The name must be 2 to 128 characters in length and can contain letters, digits, periods (.), underscores (_), and hyphens (-). It must start with a letter and cannot start with http:// or https://. |
400 | InvalidDescription.Malformed | The specified parameter "Description" is not valid. | The error message returned because the specified Description parameter is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://. |
400 | InvalidHostPassword.Malformed | The specified parameter "Password" is not valid. | The error message returned because the specified Password parameter is invalid. |
400 | InvalidHostName.Malformed | The specified parameter "HostName" is not valid. | The error message returned because the specified HostName parameter is invalid. |
400 | InvalidPassword.Malformed | The specified parameter "Password" is not valid. | The error message returned because the specified Password parameter is invalid. |
400 | InvalidUserData.SizeExceeded | The specified parameter "UserData" exceeds the size. | The error message returned because the size of user data specified by the UserData parameter exceeds the upper limit. |
400 | InvalidUserData.NotSupported | The specified parameter "UserData" only support the vpc and IoOptimized Instance. | The error message returned because the specified UserData parameter is not supported. UserData is supported only by I/O optimized instances of the VPC type. |
400 | ImageNotSupportCloudInit | The specified image does not support cloud-init. | The error message returned because the specified image does not support cloud-init. |
400 | ChargeTypeViolation | Pay-As-You-Go instances do not support this operation. | The error message returned because the pay-as-you-go billing method does not support this operation. |
400 | InvalidParameter.RecycleBin | You do not have permission to set recyclable properties. | The error message returned because you are not authorized to perform this operation. |
400 | InvalidParameter.CreditSpecification | The specified CreditSpecification is not supported in this region. | The error message returned because the specified credit specification is not supported in this region. |
400 | InvalidInstanceStatus.CreditSpecRestricted | 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. |
400 | InvalidInstanceStatus.NotRunning | The current status of the resource is invalid, you can only do this operation when instance is running. | The error message returned because the operation is not supported while the instance is in the current state. Try again when the instance is in the Running state. |
400 | JoinedGroupLimitExceed | %s | The error message returned because the maximum number of security groups to which the specified resource can be assigned has been exceeded. For more information, see the return value of the %s placeholder in the error message. |
400 | InvalidParameter | The specified parameter is not valid. | The error message returned because a specified parameter is invalid. |
400 | InvalidOperation.InvalidEcsState | %s | The error message returned because the operation is not supported while the instance is in the current state. |
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. |
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. |
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 | InstanceLockedForSecurity | The specified operation is denied as your instance is locked for security reasons. | The error message returned because the operation is not supported while the instance is locked for security reasons. |
403 | OperationDenied | The instance amount in the specified SecurityGroup reach its limit. | The error message returned because the maximum number of instances in the specified security group has been reached. |
403 | OperationDenied | 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 | InvalidUserData.Forbidden | User not authorized to input the parameter "UserData"please apply for permission "UserData" | The error message returned because you are not authorized to configure the UserData parameter. Apply for the permissions first. |
403 | InvalidUser.Unauthorized | The user is not authorized | The error message returned because you are not authorized to perform this operation. |
403 | EnterpriseGroupLimited.MutliGroupType | The specified instance can not join multi SecurityGroup types. | The error message returned because the specified instance cannot belong to both a basic and an advanced security group. You can call the DescribeSecurityGroups operation to query the type of a specific security group. |
403 | SecurityGroupInstanceLimitExceed | %s | The error message returned because the maximum number of instances in the specified security group has been reached. |
403 | InstanceNotInSecurityGroup | The instance not in the group. | The error message returned because the specified instance does not belong to the security group. |
403 | InvalidOperation.InvalidRegion | %s | The error message returned because the specified RegionId parameter is invalid. |
403 | OperationDenied | The specified Image is disabled or is deleted. | The error message returned because the specified image is disabled or deleted. |
403 | InvalidOperation.ResourceManagedByCloudProduct | %s | The error message returned because you cannot modify security groups managed by cloud services. |
403 | InvalidParameter.InvalidEniQueueNumber | %s | The error message returned because the specified NetworkInterfaceQueueNumber parameter is invalid. For more information, see the return value of the %s placeholder in the error message. |
403 | InvalidOperation.MaxEniQueueNumberExceeded | %s | The error message returned because the maximum number of queues per 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. |
404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. | The error message returned because the specified InstanceId parameter does not exist. Check whether the instance ID is correct. |
404 | InvalidSecurityGroupId.NotFound | The specified SecurityGroupId does not exist. | The error message returned because the specified security group does not exist within this account. Check whether the security group ID is correct. |
404 | Credit.NotFound | The specified credit information does not exist. | The error message returned because the specified credit information does not exist. |
404 | InvalidParameter.SecurityGroupIdRepeated | The specified security group ids has repeated. | The error message returned because the specified SecurityGroupIds.N parameter already exists. Check whether the specified SecurityGroupIds.N parameter is valid. |
404 | InvalidSecurityGroupType.NotSupportClassic | The specified SecurityGroupIds have classic group type. | The error message returned because the specified security group is in the classic network. Check whether the specified SecurityGroupIds.N parameter is valid. |
404 | InvalidSecurityGroupVpc.NotBelongToOneVpc | The specified SecurityGroupIds are belong to different vpc. | The error message returned because the specified security groups belong to different VPCs. Check whether the specified SecurityGroupIds.N parameter is valid. You can call the DescribeSecurityGroups operation to query the VPCs to which the security groups belong. |
For a list of error codes, visit the API Error Center.