All Products
Search
Document Center

:ModifyInstanceAttribute

更新时间:Jan 15, 2024

Modifies the attributes of an Elastic Compute Service (ECS) instance, such as the password, name, description, hostname, security group, maximum transmission unit (MTU), and user data. If the instance is a burstable instance, you can also change its performance mode.

Usage notes

If the response contains {"OperationLocks": {"LockReason" : "security"}} when you query the information of an instance, the instance is locked for security reasons. No operations are allowed on the instance.

Take note of the following items:

  • Modify the hostname (HostName): After you modify the hostname, restart the instance in the ECS console or by calling the RebootInstance operation for the new hostname to take effect. For information about how to restart an instance in the ECS console, see Restart instances. The new hostname does not take effect if you restart the instance from within the operating system.
  • Reset the password (Password):
    • The instance cannot be in the Starting (Starting) state.
    • After you reset the password, restart the instance in the ECS console or by calling the RebootInstance operation for the new password to take effect. For information about how to restart an instance in the ECS console, see Restart instances. The new password does not take effect if you restart the instance from within the operating system.
  • Modify user data (UserData):
    • The instance must be in the Stopped (Stopped) state.
    • The instance must meet the limits for user data. For more information, see Prepare user data.

      Note After you restart the instance, the new user data is displayed but not run as scripts.

  • Change the security groups (SecurityGroupIds.N):
    • You can move an instance to a security group of a different type.

      If you want to move an instance to a security group of a different type, you must familiarize yourself with the differences between the rule configurations of the two security group types to prevent impacts on the instance network.

    • Security groups of instances in the classic network cannot be changed.

      For more information, see the description of SecurityGroupIds.N.

  • 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 allowed per ENI.
    • 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 MaximumQueueNumberPerEni and TotalEniQueueQuantity.
    • 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 value.
  • Enable or disable the Jumbo Frames feature (EnableJumboFrame): For more information, see MTUs.
    • The instance must be in the Running (Running) or Stopped (Stopped) state.
    • The instance must reside in a virtual private cloud (VPC).
    • After the Jumbo Frames feature is enabled, the MTU value of the instance is set to 8500. After the Jumbo Frames feature is disabled, the MTU value of the instance is set to 1500.

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 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, passwords cannot start with a forward slash (/).

Note For security reasons, we recommend that you use HTTPS to send requests if Password is specified.
HostName String No testHostName

The hostname of the instance. Take note of the following items:

  • When you modify the hostname of the instance, the instance cannot be in the Creating (Pending) or Starting (Starting) state. Otherwise, the new hostname and the configurations in /etc/hosts may not take effect. You can call the DescribeInstances operation to query the state of the instance.
  • After you modify the hostname, you must call the RebootInstance operation for the new hostname to take effect.

The following limits apply to the hostnames of instances that run different operating systems:

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

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

Description String No testInstanceDescription

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

UserData String No ZWNobyBoZWxsbyBlY3Mh

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

The size of the user data cannot exceed 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 plaintext. 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.

Recyclable Boolean No hide
Note This parameter is in invitational preview and is not publicly available.
CreditSpecification String No Standard

The performance mode of the burstable instance. Valid values:

  • Standard
  • Unlimited

For more information about the performance modes of burstable instances, see Overview.

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. The release protection attribute can protect instances 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.

  • The security group ID must be unique.
  • The instance is moved from the current security groups to the replacement security groups. If you want the instance to remain in the current security groups, add the IDs of the current security groups to the list.
  • You can move the instance to security groups of a different type. However, the list cannot contain the IDs of both basic and advanced security groups.
  • 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 the instance can belong. For more information, see Limits.
  • New security groups become valid for the instance after a short latency.
RemoteConnectionOptions.Password String No hide
Note This parameter is in invitational preview and is not publicly available.
RemoteConnectionOptions.Type String No hide
Note This parameter is in invitational preview and is not publicly available.
EnableJumboFrame Boolean No false

Specifies whether to enable the Jumbo Frames feature for the instance. Valid values:

true

false

You can enable the Jumbo Frames feature only for specific instance types. For more information, see MTUs.

CpuOptions.TopologyType String No DiscreteCoreToHTMapping

The CPU topology type of the instance. Valid values:

  • ContinuousCoreToHTMapping: The Hyper-Threading (HT) technology allows continuous threads to run on the same core in the CPU topology of the instance.
  • DiscreteCoreToHTMapping: The HT technology allows discrete threads to run on the same core in the CPU topology of the instance.

This parameter is empty by default.

Note
  • This parameter is supported only by specific instance families. For more information about the supported instance families, see View and modify the CPU topology.
  • Before you specify this parameter, make sure that the instance is in the Stopped (Stopped) state.

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. Invalid InstanceName value.
400 InvalidDescription.Malformed The specified parameter "Description" is not valid. Invalid Description format. The name must be 2 to 256 characters in length and cannot start with http:// or https://.
400 ImageNotSupportCloudInit The specified image does not support cloud-init. The specified image does not support cloud-init.
400 ChargeTypeViolation Pay-As-You-Go instances do not support this operation. The operation cannot be performed on pay-as-you-go instances. Check the billing method of the instance.
400 InvalidParameter.RecycleBin You do not have permission to set recyclable properties. You are not authorized to perform the operation.
400 InvalidParameter.CreditSpecification The specified CreditSpecification is not supported in this region. The specified credit specification is not supported in this region.
400 InvalidInstanceStatus.CreditSpecRestricted The current status of the resource does not support this operation. This operation cannot be performed on the resource 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. This operation cannot be performed on the instance in the current state. Try again when the instance is in the Running state.
400 JoinedGroupLimitExceed %s The maximum number of security groups to which the specified resource can be assigned is exceeded. For more information, see the return value of the %s placeholder in the error message.
400 InvalidParameter The specified parameter is not valid. A specified parameter is invalid.
400 InvalidOperation.InvalidEcsState %s This operation cannot be performed on the instance in the current state.
400 InvalidOperation.InstanceStatusUnsupported The specified instance status does not support modification of cpu topology type. The CPU topology cannot be modified for the instance in the current state.
400 InvalidParameter.CpuOptionsTopologyType The specified parameter CpuOptions.TopologyType: %s is not valid. The enumeration value of the current CPU topology type is invalid.
400 InvalidInstanceType.NotSupportCpuOptionsTopologyType The specified instance type does not support CpuOptions.TopologyType: %s. The instance type does not support the specified CPU topology.
403 IncorrectInstanceStatus The current status of the resource does not support this operation. This operation cannot be performed on the resource in the current state.
403 InstanceLockedForSecurity The specified operation is denied as your instance is locked for security reasons. The instance is locked for security reasons.
403 OperationDenied The instance amount in the specified SecurityGroup reach its limit. The maximum number of instances in the specified security group is exceeded.
403 OperationDenied The current status of the resource does not support this operation. This operation cannot be performed on the resource in the current state.
403 InvalidUserData.Base64FormatInvalid The specified UserData is not valid Invalid UserData value.
403 InvalidChargeType.ValueNotSupported Deletion protection is only valid for postPaid instance, not for prePaid or spot instance. The release protection feature can be used only on pay-as-you-go resources.
403 InvalidUser.Unauthorized The user is not authorized You are not authorized to perform this operation.
403 EnterpriseGroupLimited.MutliGroupType The specified instance can not join multi SecurityGroup types. The specified instance cannot belong to both a basic security group and an advanced security group. You can call the DescribeSecurityGroups operation to query the type of a specific security group.
403 SecurityGroupInstanceLimitExceed %s The maximum number of instances in the specified security group is exceeded.
403 InstanceNotInSecurityGroup The instance not in the group. The specified instance does not belong to the security group.
403 InvalidOperation.InvalidRegion %s Invalid RegionId value.
403 OperationDenied The specified Image is disabled or is deleted. The specified image is disabled or deleted.
403 InvalidOperation.ResourceManagedByCloudProduct %s You cannot modify security groups managed by cloud services.
403 InvalidParameter.InvalidEniQueueNumber %s Invalid QueueNumber value. For more information, see the return value of the %s placeholder in the error message.
403 InvalidOperation.MaxEniQueueNumberExceeded %s The maximum number of queues per ENI is exceeded. For more information, see the return value of the %s placeholder in the error message.
403 InvalidOperation.ExceedInstanceTypeQueueNumber %s The maximum number of queues for all ENIs on an instance is exceeded. For more information, see the return value of the %s placeholder in the error message.
404 InvalidSecurityGroupId.NotFound The specified SecurityGroupId does not exist. The specified security group is not found in this account. Check whether the security group ID is correct.
404 Credit.NotFound The specified credit information does not exist. The specified credit information does not exist.
404 InvalidParameter.SecurityGroupIdRepeated The specified security group ids has repeated. Duplicate security group IDs are found. Check whether the SecurityGroupIds.N value is valid.
404 InvalidSecurityGroupType.NotSupportClassic The specified SecurityGroupIds have classic group type. The specified security group is in the classic network. Check whether the SecurityGroupId.N value is valid.
404 InvalidSecurityGroupVpc.NotBelongToOneVpc The specified SecurityGroupIds are belong to different vpc. The specified security groups belong to different VPCs. Check whether the SecurityGroupIds.N value is valid. You can call the DescribeSecurityGroups operation to query the VPCs to which the security groups belong.
500 InternalError The request processing has failed due to some unknown error. An internal error occurred. Try again later.
500 InternalError The request processing has failed due to some unknown error, exception or failure. An internal error occurred. Try again later.

For a list of error codes, see Service error codes.