Help Center/ GeminiDB/ API Reference/ APIs v3 (Recommended)/ Instances/ Configuring an Automatic Scale-out Policy

Updated on 2025-11-17 GMT+08:00

View PDF

Configuring an Automatic Scale-out Policy

Function

This API is used to configure an automatic scale-out policy.

Constraints

This API can be used for GeminiDB Cassandra instances.

This API supports both pay-per-use and yearly/monthly instances.

By default, fees are automatically deducted for yearly/monthly instances.

Autoscaling is available only when your account balance is sufficient.

If the instance status is not normal, the policy for automatically adding nodes cannot be configured.

Authorization

Each account is authorized to call all APIs, but its IAM users must be granted necessary permissions. For details, see Permission Policies and Supported Actions.

URI

PUT /v3/{project_id}/instances/{instance_id}/node-auto-expansion-policy

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Explanation: Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID. Constraints: N/A Values: N/A Default value: N/A
instance_id	Yes	String	Explanation: Instance ID Constraints: N/A Values: N/A Default value: N/A

Request Parameters

**Table 2** Request header parameter
Parameter	Mandatory	Type	Description
X-Auth-token	No	String	Explanation: User token To obtain this value, call the IAM API for obtaining a user token. Constraints: N/A Values: N/A Default value: N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
switch_option	Yes	Boolean	Explanation: Whether the switch for automatically adding nodes is enabled Constraints: N/A Values: true: enabled false: disabled Default value: N/A
overload_node_threshold	No	Integer	Explanation: Percentage of overloaded nodes. For example, if there are three nodes in the current instance and the policy needs to be triggered when a threshold is reached for two of them, the value can be 67% (= 2/3; rounded up). Constraints: N/A Values: An integer ranging from 1 to 100 Default value: N/A
cpu_threshold	No	Integer	Explanation: CPU usage of nodes for which autoscaling is triggered Constraints: N/A Values: An integer ranging from 1 to 100 Default value: 80
mem_threshold	No	Integer	Explanation: Memory usage of nodes for which autoscaling is triggered Constraints: N/A Values: An integer ranging from 1 to 100 Default value: 80
step	No	Integer	Explanation: Number of nodes to be added each time Constraints: N/A Values: The value is a positive integer greater than or equal to 1. The maximum value cannot exceed the upper limit of nodes that can be added. Default value: 3
node_limit	No	Integer	Explanation: Maximum number of nodes that can be automatically added Constraints: N/A Values: The value is a positive integer greater than or equal to 1. The maximum value cannot exceed the upper limit of nodes that can be added to the current instance. Default value: The default value is the maximum number of nodes that can be added to the current instance.

Response Parameters

Status code: 200

Example Request

Configuring a policy for automatically adding nodes

PUT https://{endpoint}/v3/054e292c9880d4992f02c0196d3ea468/instances/3d39c18788b54a919bab633874c159dfin02/auto-node-expansion-policy    
{    
  "switch_option" : "true", 
  "overload_node_threshold" : "50",  
  "cpu_threshold" : "80",  
  "mem_threshold" : "80",  
  "step" : "3",  
  "node_limit" : "10" 
 }