All Products
Search
Document Center

Elastic Compute Service:ModifyInstanceAttribute

Last Updated:Sep 29, 2024

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

Operation description

Usage notes

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

Take note of the following items:

  • If you change the hostname (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 an instance. The new hostname may not take effect if you restart the instance from within the operating system.

  • If you reset the password (Password), take note of the following items:

    • 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 an instance. The new password does not take effect if you restart the instance from within the operating system.
  • If you modify user data (UserData), take note of the following items: The instance must meet the limits for user data. For more information, see Instance user data.

    **

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

  • If you change the security groups (SecurityGroupIds.N), take note of the following items:

    • You can move the instance to a security group of a different type. If you want to move the 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.
  • If you change the number of queues supported by the primary elastic network interface (ENI) (NetworkInterfaceQueueNumber), take note of the following items:

    • 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 query the maximum number of queues per ENI and the queue quota for an instance type, you can call the DescribeInstanceTypes operation and view the values of the MaximumQueueNumberPerEni and TotalEniQueueQuantity response parameters.
    • If you set this parameter to -1, the value is reset to the default value for the instance type. To query the default number of queues supported per primary ENI for an instance type, you can call the DescribeInstanceTypes operation and view the value of the PrimaryEniQueueNumber response parameter.
  • If you enable or disable the Jumbo Frames feature (EnableJumboFrame), take note of the following items. 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.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ecs:ModifyInstanceAttributeupdate
  • Instance
    acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
  • SecurityGroup
    acs:ecs:{#regionId}:{#accountId}:securitygroup/{#SecurityGroupId}
  • ecs:tag
none

Request parameters

ParameterTypeRequiredDescriptionExample
InstanceIdstringYes

The instance ID.

i-bp67acfmxazb4ph****
PasswordstringNo

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. The following special characters are supported:

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

The password of a Windows instance cannot start with a forward slash (/).

Note For security reasons, we recommend that you use HTTPS to send requests if Password is specified.
Test123456
HostNamestringNo

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

  • When you change 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 status of the instance.
  • After you change 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 (-).
testHostName
InstanceNamestringNo

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 (-).

testInstanceName
DescriptionstringNo

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

testInstanceDescription
UserDatastringNo

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

The maximum size of the raw data before encoding is 32 KB. 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.

ZWNobyBoZWxsbyBlY3Mh
RecyclablebooleanNo
Note This parameter is in invitational preview and is not publicly available.
hide
CreditSpecificationstringNo

The performance mode of the burstable instance. Valid values:

  • Standard
  • Unlimited

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

Standard
DeletionProtectionbooleanNo

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.
false
NetworkInterfaceQueueNumberintegerNo

The number of queues supported by the primary ENI.

8
SecurityGroupIdsarrayNo

The IDs of replacement security groups.

  • All security group IDs 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 security groups and the instance must belong to the same VPC.
  • The valid values of N vary based on the maximum number of security groups to which the instance can belong. For more information, see the Security group limits section in the "Limits and quotas" topic.
  • New security groups become valid for the instance after a short delay.
stringNo

The ID of replacement security group N.

  • All security group IDs 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 security groups and the instance must belong to the same VPC.
  • The valid values of N vary based on the maximum number of security groups to which the instance can belong. For more information, see the Security group limits section in the "Limits and quotas" topic.
  • New security groups become valid for the instance after a short delay.
sg-bp15ed6xe1yxeycg7o****
RemoteConnectionOptionsobjectNo
Note This parameter is in invitational preview and is not publicly available.
PasswordstringNo
Note This parameter is in invitational preview and is not publicly available.
hide
TypestringNo
Note This parameter is in invitational preview and is not publicly available.
hide
EnableJumboFramebooleanNo

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 MTU and jumbo frames.

false
CpuOptions.TopologyTypestringNo

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.

By default, this parameter is left empty.

Note
  • This parameter is supported only by specific instance families. For information about the supported instance families, see View and modify CPU topologies.

  • Before you specify this parameter, make sure that the instance is in the Stopped (Stopped) state.

DiscreteCoreToHTMapping
PrivateDnsNameOptionsobjectNo
Note This parameter is in invitational preview and is not publicly available.
EnableInstanceIdDnsARecordbooleanNo
Note This parameter is in invitational preview and is not publicly available.
false
EnableInstanceIdDnsAAAARecordbooleanNo
Note This parameter is in invitational preview and is not publicly available.
false
EnableIpDnsARecordbooleanNo
Note This parameter is in invitational preview and is not publicly available.
false
EnableIpDnsPtrRecordbooleanNo
Note This parameter is in invitational preview and is not publicly available.
false
HostnameTypestringNo
Note This parameter is in invitational preview and is not publicly available.
Custom

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The request ID.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

Examples

Sample success responses

JSONformat

{
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

Error codes

HTTP status codeError codeError messageDescription
400InvalidInstanceName.MalformedThe specified parameter "InstanceName" is not valid.The specified InstanceName parameter is invalid.
400InvalidDescription.MalformedThe specified parameter "Description" is not valid.The source description can be 2 to 256 characters in length. It cannot start with http:// and https://.
400InvalidRemoteConnectionOptions.PasswordThe remote connection password is invalid.-
400InvalidRemoteConnectionOptions.TypeThe remote connection type is invalid.-
400InstanceType.ValueNotSupportedThe instance type not supported.-
400OSType.ValueNotSupportedThe OS type is not supported.-
400InvalidHostPassword.MalformedThe specified parameter "Password" is not valid.-
400InvalidHostName.MalformedThe specified parameter "HostName" is not valid.-
400InvalidPassword.MalformedThe specified parameter "Password" is not valid.-
400InvalidUserData.SizeExceededThe specified parameter "UserData" exceeds the size.-
400InvalidUserData.NotSupportedTThe specified parameter "UserData" only support the vpc and IoOptimized Instance.-
400InvalidUserData.NotSupportedThe specified parameter "UserData" only support the vpc and IoOptimized Instance.-
400ImageNotSupportCloudInitThe specified image does not support cloud-init.-
400ChargeTypeViolationPay-As-You-Go instances do not support this operation.The operation is not supported by pay-as-you-go instances. Check the billing method of the instance.
400InvalidParameter.RecycleBinYou do not have permission to set recyclable properties.You are not authorized to perform the operation.
400InvalidParameter.CreditSpecificationThe specified CreditSpecification is not supported in this region.The running mode of the specified burst performance instance is not supported in this zone.
400InvalidInstanceStatus.CreditSpecRestrictedThe current status of the resource does not support this operation.The resource is in a state that does not support the current operation.
400InvalidInstanceStatus.NotRunningThe current status of the resource is invalid, you can only do this operation when instance is running.The resource is in a state that does not support the operation. Perform the operation when the instance is in the Running state.
400InvalidNetworkType.NotSupportedThe classic networkType does not support to modify security group-
400InvalidOperation.EniCountExceeded=The maximum number of eni in a enterprise security group is exceeded.-
400JoinedGroupLimitExceed%sThe maximum number of security groups to which the specified resource can be added has been reached. For more information, see the return value of the %s placeholder in the error message.
400InvalidParameterThe specified parameter is not valid.A specified parameter is invalid.
400InvalidOperation.InvalidEcsState%s-
400InvalidParam.NotSupportJumboFrameNot support jumbo frame.-
400InvalidOperation.InstanceStatusNotSupportThe instance status is not support modify mtu config.-
400InvalidOperation.InstanceStatusUnsupportedThe specified instance status does not support modification of cpu topology type.The specified instance status does not support modification of cpu topology type.
400InvalidParameter.CpuOptionsTopologyTypeThe specified parameter CpuOptions.TopologyType: %s is not valid.Illegal enumeration value for current CPU topology type
400InvalidInstanceType.NotSupportCpuOptionsTopologyTypeThe specified instance type does not support CpuOptions.TopologyType: %s.The current specification does not support the specified CPU topology type
400InvalidAdditionalInfoPvdConfig.SizeExceededThe specified parameter AdditionalInfo.PvdConfig exceeds the size.-
400InvalidInstanceType.NotSupportHighDensityModeThe specified instance type does not support the use of the high density mode.The current instance type does not support the cloud disk high-density mode.
400InvalidStatus.StoppedRequiredThe current state of the resource does not support this operation, it can only be operated in a stopped state.The current state of the resource does not support this operation, only down state can operate
403IncorrectInstanceStatusThe current status of the resource does not support this operation.The resource is in a state that does not support the current operation.
403InstanceLockedForSecurityThe specified operation is denied as your instance is locked for security reasons.-
403OperationDeniedThe instance amount in the specified SecurityGroup reach its limit.The maximum number of instances in the specified security group has been reached.
403OperationDeniedThe current status of the resource does not support this operation.The resource is in a state that does not support the current operation.
403InvalidUserData.ForbiddenUser not authorized to input the parameter "UserData"please apply for permission "UserData"-
403InvalidUserData.Base64FormatInvalidThe specified UserData is not validAn error occurred when the specified UserData parameter is encoded.
403InvalidChargeType.ValueNotSupportedDeletion protection is only valid for postPaid instance, not for prePaid or spot instance.Release protection can be enabled only for pay-as-you-go instances.
403InvalidUser.UnauthorizedThe user is not authorizedYou are not authorized to perform this operation.
403EnterpriseGroupLimited.MutliGroupTypeThe specified instance can not join multi SecurityGroup types.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 security groups.
403SecurityGroupInstanceLimitExceed%s-
403InstanceNotInSecurityGroupThe instance not in the group.The specified instance does not belong to the security group.
403InvalidOperation.InvalidRegion%sThe specified RegionId parameter is invalid.
403OperationDeniedThe specified Image is disabled or is deleted.The specified image is disabled or deleted.
403InvalidOperation.ResourceManagedByCloudProduct%sYou cannot modify security groups managed by cloud services.
403InvalidParameter.InvalidEniQueueNumber%s-
403InvalidOperation.MaxEniQueueNumberExceeded%s-
403InvalidOperation.ExceedInstanceTypeQueueNumber%sThe maximum number of queues for all ENIs on an instance has been exceeded. For more information, see the return value of the %s placeholder in the error message.
403InvalidOperation.InstanceTypeNotSupportHighPerformanceTrafficMode%s-
403InvalidParameter.InvalidQueuePairNumber%s-
403InvalidOperation.MaxEniQueuePairNumberExceed%s-
403InvalidOperation.EniQueuePairNumberOverflow%s-
403AclLimitExceed%sThe number of ACL rules for an ENI or instance exceeds the upper limit.
404InvalidInstanceId.NotFoundThe specified InstanceId does not exist.The specified instance does not exist.
404InvalidSecurityGroupId.NotFoundThe specified SecurityGroupId does not exist.The specified security group does not exist in this account. Check whether the security group ID is correct.
404Credit.NotFoundThe specified credit information does not exist.The specified burst performance instance credit information does not exist.
404InvalidInstanceStatus.NeedRestartThe current status of the resource is invalid, you can only do this operation after instance is restarted.-
404InvalidParameter.SecurityGroupIdRepeatedThe specified security group ids has repeated.Duplicate security group IDs are specified. Check whether the specified SecurityGroupIds.N parameter is valid.
404InvalidSecurityGroupType.NotSupportClassicThe specified SecurityGroupIds have classic group type.The specified security group is in the classic network. Check whether the specified SecurityGroupIds.N parameter is valid.
404InvalidSecurityGroupVpc.NotBelongToOneVpcThe specified SecurityGroupIds are belong to different vpc.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.
500InternalErrorThe request processing has failed due to some unknown error.An internal error has occurred. Try again later.
500InternalErrorThe request processing has failed due to some unknown error, exception or failure.An internal error has occurred. Try again later.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-08-29The Error code has changedView Change Details
2024-08-08The Error code has changed. The request parameters of the API has changedView Change Details
2024-07-03The Error code has changedView Change Details
2024-05-11The Error code has changedView Change Details
2023-12-14The Error code has changed. The request parameters of the API has changedView Change Details
2023-07-17The Error code has changedView Change Details