ModifyInstancesAttribute

Download PDF

Last updated: 2025-10-30 21:38:00

ModifyInstancesAttribute

Last updated: 2025-10-30 21:38:00

Download PDF

1. API Description

Domain name for API request: cvm.intl.tencentcloudapi.com.

This API is used to modify instance attributes.

This API is used to modify one attribute of the instance per request. The attribute must be specified.
The instance name is only for user convenience in management. Tencent Cloud does not use this name as the basis for online support or to perform instance management operations.
This API is used to support batch operations. The maximum of 100 batch instances per request is supported.
This API is used to modify the security group association. The originally associated security group of the instance will be unbound.

You can query the result of the instance operation by calling the API DescribeInstances. If the latest operation status (LatestOperationState) of the instance is SUCCESS, the operation is successful.
This API is used to modify the hostname. The instance restarts immediately after hostname modification, and the new hostname takes effect after restart.

A maximum of 10 requests can be initiated per second for this API.

We recommend you to use API Explorer

Try it

API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name	Required	Type	Description
Action	Yes	String	Common Params. The value used for this API: ModifyInstancesAttribute.
Version	Yes	String	Common Params. The value used for this API: 2017-03-12.
Region	Yes	String	Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-bangkok, ap-beijing, ap-chengdu, ap-chongqing, ap-guangzhou, ap-hongkong, ap-jakarta, ap-nanjing, ap-seoul, ap-shanghai, ap-shanghai-fsi, ap-shenzhen-fsi, ap-singapore, ap-tokyo, eu-frankfurt, na-ashburn, na-siliconvalley, sa-saopaulo.
InstanceIds.N	Yes	Array of String	Instance ID(s). To obtain the instance IDs, you can call `DescribeInstances` and look for `InstanceId` in the response. The maximum number of instances in each request is 100.
InstanceName	No	String	Modified instance name. can be named as required but should not exceed 128 characters.
UserData	No	String	User data provided to an instance, which needs to be encoded in Base64 format with a maximum size of 16 KB. For details on obtaining this parameter, refer to the startup commands for Windows and Linux.
SecurityGroups.N	No	Array of String	Specifies the security group Id list of the specified instance after modification. the instance will reassociate with the security groups in the specified list, and the associated security group will be unbound.
CamRoleName	No	String	The role bound with the instance. If it is not specified, it indicates to unbind the current role of the CVM.
HostName	No	String	Modified hostname of an instance. Period (.) and hyphen (-) should not be used as the first or last character of the hostname, and should not be used consecutively. Windows instances: The hostname should contain 2 to 15 characters, including letters (case insensitive), digits, and hyphens (-), does not support periods (.), and should not be all digits. Instances of other types (such as Linux instances): The hostname should contain 2 to 60 characters, including multiple periods (.), with each segment between periods considered as one section. Each section can contain letters (case insensitive), digits, and hyphens (-). Note: After the hostname is modified, the instance will restart immediately, and the new hostname will take effect after the restart.
DisableApiTermination	No	Boolean	Instance termination protection flag, indicating whether an instance is allowed to be deleted through an API. Valid values: true: Instance protection is enabled, and the instance is not allowed to be deleted through the API. false: Instance protection is disabled, and the instance is allowed to be deleted through the API. Default value: false.
CamRoleType	No	String	Role type, used in conjunction with CamRoleName. this value can be obtained from the RoleType field in the API response of CAM DescribeRoleList or GetRole. currently, only user, system, and service_linked types are accepted. For example, when CamRoleName contains "LinkedRoleIn" (such as TKE_QCSLinkedRoleInPrometheusService), DescribeRoleList and GetRole return RoleType as service_linked, this parameter must also transmit service_linked. The parameter default value is user. this parameter can be omitted if CameRoleName is not of the service_linked kind.
AutoReboot	No	Boolean	Whether to automatically restart an instance when modifying a hostname. If not specified, the instance will automatically restart by default. - true: Modify the hostname and automatically restart the instance. - false: Modify the hostname without automatically restarting the instance. A manual restart is required for the new hostname to take effect. Note: This parameter is valid only when a hostname is modified.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Renaming instances

This example shows you how to rename two instances.

Input Example

POST / HTTP/1.1
Host: cvm.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyInstancesAttribute
<Common request parameters>

{
    "InstanceName": "Mysql_Server",
    "InstanceIds": [
        "ins-5d8a23rs",
        "ins-r8hr2upy"
    ]
}

Output Example

{
    "Response": {
        "RequestId": "6ef60bec-0242-43af-bb20-270359fb54a7"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

Tencent Cloud CLI 3.0

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code	Description
AuthFailure.CamRoleNameAuthenticateFailed	Role name authentication failed.
FailedOperation.InvalidInstanceApplicationRole	The applicationRole instance does not support the operation.
FailedOperation.SecurityGroupActionFailed	Security group operation failed.
InternalServerError	Internal error.
InvalidInstance.NotSupported	This instance is not supported.
InvalidInstanceId.Malformed	Invalid instance `ID`. The specified instance `ID` has an invalid format. For example, `ins-1122` has an invalid `ID` length.
InvalidInstanceId.NotFound	No instance found.
InvalidInstanceName.TooLong	The specified InstanceName exceeds the maximum length of 128 bytes.
InvalidParameter.HostNameIllegal	The specified HostName is invalid.
InvalidParameterValue	Incorrect parameter value.
InvalidParameterValue.CamRoleNameMalformed	Invalid `CamRoleName`. This parameter must contain only letters, numbers and symbols (`+`, `=`, `,`, `.`, `@`, `_`, `-`).
InvalidParameterValue.IllegalHostName	The value of HostName is invalid.
InvalidParameterValue.InstanceIdMalformed	Invalid instance ID. Please enter a valid ID, such as ins-xxxxxxxx (“x” represents a lower-case letter or a number).
InvalidParameterValue.InvalidUserDataFormat	Incorrect UserData format. Use the Base64-encoded format.
InvalidParameterValue.LimitExceeded	The number of parameter values exceeds the limit.
InvalidSecurityGroupId.NotFound	The specified `security group ID` does not exist.
LimitExceeded.AssociateUSGLimitExceeded	An instance can be bound with up to 5 security groups.
LimitExceeded.CvmsVifsPerSecGroupLimitExceeded	The CVM ENIs associated with the security group has exceeded the limit.
LimitExceeded.SingleUSGQuota	The number of security groups exceeds the quota limit.
MissingParameter	Missing parameter.
MutexOperation.TaskRunning	An identical job is running.
OperationDenied.InstanceOperationInProgress	The instance has an operation in progress. Please try again later.
UnauthorizedOperation.MFANotFound	Unauthorized operation. Make sure Multi-Factor Authentication (MFA) exists.
UnsupportedOperation.InstanceReinstallFailed	The current instance is in a failed OS reinstallation state and does not support this operation. We recommend reinstalling the operating system again. Alternatively, you may terminate/return the instance or submit a support ticket.
UnsupportedOperation.InstanceStateEnterRescueMode	Instances are entering the rescue mode, and this operation is not supported.
UnsupportedOperation.InstanceStateEnterServiceLiveMigrate	The instance `ins-xxxxxx` in the `ENTER_SERVICE_LIVE_MIGRATE` status is not supported.
UnsupportedOperation.InstanceStateExitRescueMode	Instances are exiting from the rescue mode, and this operation is not supported.
UnsupportedOperation.InstanceStateExitServiceLiveMigrate	The instance `ins-xxxxxx` in the `EXIT_SERVICE_LIVE_MIGRATE` status is not supported.
UnsupportedOperation.InstanceStateFreezing	The operation is not supported for the frozen instances.
UnsupportedOperation.InstanceStateIsolating	Unable to isolate: the instance is isolated
UnsupportedOperation.InstanceStatePending	The instances are being created, and this operation is not supported.
UnsupportedOperation.InstanceStateRebooting	The instances are being restarted, and this operation is not supported.
UnsupportedOperation.InstanceStateRescueMode	Instances in the rescue mode are not available for this operation.
UnsupportedOperation.InstanceStateServiceLiveMigrate	The instances are being migrated, and this operation is not supported.
UnsupportedOperation.InstanceStateShutdown	Isolated instances do not support this operation.
UnsupportedOperation.InstanceStateStarting	The instance is starting up, and this operation is not supported.
UnsupportedOperation.InstanceStateStopping	The instance is being shut down, and this operation is not supported.
UnsupportedOperation.InstanceStateTerminated	Terminated instances are not supported.
UnsupportedOperation.InstanceStateTerminating	The instance is being terminated, and the operation is not supported.
UnsupportedOperation.InstanceTypeNotSupportHighDensityModeSetting	The instance type does not support setting the HighDensityMode status.
UnsupportedOperation.InstanceTypeNotSupportJumboFrame	The instance type does not support setting the `EnableJumboFrame` status.
UnsupportedOperation.InstancesEnableJumboWithoutReboot	Modifying Jumbo Frame status without a restart is not supported.
UnsupportedOperation.InvalidInstanceNotSupportedProtectedInstance	This operation is not supported for the instance with a termination schedule. Please cancel the scheduled termination time in the instance details page and try again.
UnsupportedOperation.StoppedModeStopCharging	The instance does not support the no charges when shut down feature.

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

Feedback

tencent cloud