You can call this operation to modify the information of an 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 burst mode.

Description

If the response message contains {"OperationLocks": {"LockReason" : "security"}} when you query ECS instance information, the instance is locked for security reasons and all operations are prohibited on the instance.

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

  • Modify the hostname (HostName): You must restart the instance by using the ECS console or by calling the RebootInstance operation for the new hostname to take effect. For more information, see Restart instances from the ECS console and RebootInstance. The modification will not take effect if you restart the instance within the operating system.
  • Reset password ( Password):
    • The instance cannot be in the Starting( Starting) state.
    • You must restart the instance by using the ECS console or by calling the RebootInstance operation for the new password to take effect. For more information, see Restart instances from the ECS console and RebootInstance. The modification will not take effect if you restart the instance within the operating system.
  • Modify user data ( UserData):
    • The ECS instances must be in the Stopped (Stopped) state.
    • The instance must meet the limits of user data. For more information, see Generate user data.
  • Change security group (SecurityGroupIds.N):
    • You can switch an ECS instance to a security group of a different type.

      When you switch an ECS 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 affecting the instance network.

    • Instances in the classic network do not support this operation.

      For more information, see the description for the SecurityGroupIds.N parameter.

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 No ModifyInstanceAttribute

The operation that you want to perform. If you use a custom HTTP URL or HTTPS URL to make an API request, you must specify the Action parameter. Set the value to ModifyInstanceAttribute.

InstanceId String Yes i-bp67acfmxazb4ph***

The ID of the instance.

Password String No EcsV587!

The password of the instance. The password must be 8 to 30 characters in length and contain characters from at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. Special characters include:



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

Passwords of Windows instances 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 LocalHost

The hostname of the instance. After the hostname is modified, call the RebootInstance operation for the new hostname to take effect.

  • Windows Server: The hostname must be 2 to 15 characters in length and can contain letters, digits, and hyphens (-). It cannot start or end with a hyphen (-), contain consecutive hyphens (-), or contain only digits.
  • Other operating systems such as Linux: The hostname must be 2 to 64 characters in length. You can use periods (.) to separate a name into multiple segments. Each segment can contain letters, digits, and hyphens (-). However, the hostname cannot contain consecutive periods (.) or hyphens (-). It cannot start or end with a period (.) or a hyphen (-).
InstanceName String No EcsInstance

The name of the instance. The name must be 2 to 128 characters in length. It can contain letters, digits, colons (:), underscores (_), and hyphens (-). It must start with a letter but cannot start with http:// or https://.

Description String No InstanceAttribute

The description of the instance. The description must be 2 to 256 characters in length and cannot start with http:// or https://.

This parameter is empty by default.

UserData String No ZWNobyBoZWxsbyBlY3Mh

The user data of the instance, which must be encoded in Base64.

The size of your user data must be no greater than 16 KB before Base64 encoding. Because user data is imported in plaintext, we recommend that you do not contain confidential information such as passwords and private keys in the user data. If confidential information is required, we recommend that you encrypt it and encode it in Base64 before you import it. You can decrypt the information within your ECS instance in the same mode after the information is transmitted.

Recyclable Boolean No false

Specifies whether the instance can be recycled.

CreditSpecification String No Standard

The running mode of the burstable instance. Valid values:

  • Standard: the standard mode. For more information, see the "Standard mode" section in Burstable instances.
  • Unlimited: the unlimited mode. For more information, see the "Unlimited mode" section in Burstable instances.

This parameter is empty by default.

DeletionProtection Boolean No false

The release protection property of the instance. It specifies whether you can use the ECS console or call the DeleteInstance operation to release the instance.

This parameter is empty by default.

Note This parameter is applicable only to pay-as-you-go instances. It can only protect against manual releases and not against automatic releases.
SecurityGroupIds.N RepeatList No sg-bp15ed6xe1yxeycg7o***

The ID of replacement security group N.

  • All security group IDs must be unique.
  • The instance is removed from the current security group. If you want to retain the ECS instance in the current group, you must add the current security group ID to the list.
  • You can switch the ECS instance to security groups of a different type. However, the security group list cannot contain both basic security groups and advanced security groups at the same time.
  • The specified security group and instance must belong to the same VPC.
  • The valid values of N are based on the maximum number of security groups to which an instance can belong. For more information, see the Security groups section in Limits.
  • New security groups will become valid for corresponding instances after a short delay.

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=InstanceAttribute
&HostName=LocalHost
&InstanceName=EcsInstance
&Password=EcsV587!
&SecurityGroupIds.1=sg-bp15ed6xe1yxeycg7o***
&SecurityGroupIds.2=sg-bp15ed6xe1yxeycg7p***
&SecurityGroupIds.3=sg-bp15ed6xe1yxeycg7q***
&<Common request parameters>

Sample success responses

XML format

<ModifyInstanceAttributeResponse>
      <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
</ModifyInstanceAttributeResponse>

JSON format

{
    "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 instance name is invalid. The name must be 2 to 128 characters in length and can contain letters, digits, periods (.), underscores (_), and hyphens (-). The name must start with a letter but cannot start with http:// or https://.
400 InvalidDescription.Malformed The specified parameter "Description" is not valid. The error message returned because the specified description 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.
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 instance 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.
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 ID does not exist in this account. Check whether the security group ID is correct.
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.
400 InvalidPassword.Malformed The specified parameter "Password" is not valid. The error message returned because the specified Password parameter is invalid.
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 problem persists, submit a ticket.
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.
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 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 in VPC-type instances and I/O optimized instances.
400 ImageNotSupportCloudInit The specified image does not support cloud-init. The error message returned because cloud-init is not supported by the specified image.
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 policy is not supported in the region.
400 InvalidInstanceStatus.CreditSpecRestricted The current status of the resource does not support this operation. The error message returned because this operation is not supported while the instance 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 this operation is not supported while the instance is in the current state. Try again when the instance is in the Running state.
404 Credit.NotFound The specified credit information does not exist. The error message returned because the specified credit information does not exist.
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 problem persists, submit a ticket.
403 InvalidUser.Unauthorized The user is not authorized The error message returned because you are not authorized to modify the instance information.
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 specified security group.
403 InvalidOperation.InvalidRegion %s The error message returned because the specified RegionId parameter is invalid.

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