You can call this operation to change the cluster configuration.
When you call this operation, take note of the following items:
If the instance is in the Activating, Invalid, or Inactive state, you cannot change the configurations.
If the indexes of your cluster do not have replica shards, the load of the cluster is excessively high, and large amounts of data are written to or queried in your cluster, access to the cluster may time out during a cluster configuration upgrade or downgrade. We recommend that you configure an access retry mechanism for your client before you upgrade the configuration of your cluster. This reduces the impact on your business.
You can change the configurations of only one type of node at a time (data node, dedicated master node, cold data node, coordinator node, Kibana node, and elastic node).
Due to the health and stability of your cluster, Alibaba Cloud Elasticsearch does not support the purchase of 1-core 2 GB instances, 2-core 2 GB instances for dedicated master nodes, and 7.4 instances since May 2021. If you have confirmed that the purchased specifications are no longer available for sale, you must perform the following operations:
For the 1-core 2 GB and 2-core 2 GB specifications, we recommend that you upgrade to the stable sales specifications that are available on the buy page in advance. For more information about the sales specifications available on the buy page, see Purchase page parameters.
If your cluster is of V7.4, purchase a V7.10 cluster and migrate data from the original cluster to the V7.10 cluster.
For more information, see Upgrade a cluster and Downgrade a cluster.
Debugging
Request headers
This operation uses only common request headers. For more information, see Common request parameters.
Request syntax
PUT /openapi/instances/{InstanceId} HTTP/1.1
Request parameters
Parameter | Type | Position | Required | Example | Description |
InstanceId | String | Path | Yes | es-cn-n6w1ptcb30009**** | The ID of the instance. |
clientToken | String | Query | No | 5A2CFF0E-5718-45B5-9D4D-70B3FF**** | The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must ensure that the value is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length. |
orderActionType | String | Query | No | upgrade | The type of the configuration change. Valid values:
|
Object | Body | No | The request body parameters. | ||
nodeAmount | Integer | Body | No | 3 | The number of nodes. |
nodeSpec | Body | No | The configuration of the data node. | ||
masterConfiguration | Body | No | The configuration of the dedicated master node. | ||
clientNodeConfiguration | Body | No | Coordination node configuration. | ||
warmNodeConfiguration | Body | No | Configure the cold data node. | ||
kibanaConfiguration | Body | No | The configuration of the kibana node. | ||
elasticDataNodeConfiguration | Body | No | The configuration of the elastic node. | ||
instanceCategory | String | Body | No | advanced | Version type. Valid values:
|
force | Boolean | Query | No | false | Whether to forcibly restart:
|
For a list of Elasticsearch supported node specifications, see Alibaba Cloud Elasticsearch Elasticsearch pricing information and product specifications.
The following example shows the request body parameters:
Upgrade
You cannot reduce the storage space value, storage type configuration, number of nodes, number of CPU cores of specifications, or memory value when you upgrade the configuration.
Upgrade storage space
Currently, you can upgrade storage space only for data nodes, cold data nodes, and elastic data nodes.
Upgrade the storage space of cold data nodes to 1000 GiB.
{ "warmNodeConfiguration": { "disk": 1000 } }
Upgrade storage type
Currently, you can upgrade storage types only for data nodes, elastic data nodes, and dedicated master nodes.
Upgrade the storage type of the dedicated master node to the Enhanced SSD type.
{ "masterConfiguration": { "diskType": "cloud_essd" } }
If the storage type of a dedicated master node is Enhanced SSD, upgrade the node storage performance level to PL3.
After the performanceLevel is specified, the diskType is populated as cloud_essd by default.
After you specify the cloud_essd, the performanceLevel defaults to PL1.
{ "masterConfiguration": { "performanceLevel": "PL3" } }
Number of Upgraded Nodes
Currently, only data nodes, cold data nodes, elastic data nodes, and coordinator nodes are supported.
The method of increasing the number of nodes for a data node is different from that for other nodes. For more information, see the following example.
Increase the number of data nodes to 12.
{ "nodeAmount": 12 }
Increase the number of nodes of other types (for example, cold data nodes) to 12.
{ "warmNodeConfiguration": { "amount": 12 } }
Upgrade node specifications
Upgrade the specifications of data nodes to 4 cores and 32 GB.
{ "nodeSpec": { "spec": "elasticsearch.r5.xlarge" } }
Several configurations of the same node are upgraded at the same time
To upgrade several configurations of the same node at the same time, you must write the request body of the upgraded resource at the same time.
The number of nodes of the coordinator node is increased to 8, and the specification is increased to 4 cores and 8 GB.
{ "clientNodeConfiguration": { "amount": 8, "spec": "elasticsearch.sn1ne.xlarge" } }
Increase the number of data nodes to 12 and the storage type to Enhanced SSD.
{ "nodeAmount": 12, "nodeSpec": { "diskType": "cloud_essd" } }
Enable a node
For more information about how to configure a complete node resource, see Configure a createInstance port.
Enable the coordination node and set the coordination node configuration.
{ "clientNodeConfiguration": { "amount": 5, "disk": 20, "spec": "elasticsearch.sn1ne.xlarge" } }
Enable the elastic data node and set the elastic data node configuration (this configuration only applies to China site (aliyun.com)).
{ "elasticNodeConfiguration": { "disk": 200, "amount": 5, "diskType": "cloud_essd", "spec": "elasticsearch.sn1ne.xlarge" } }
Enable the cold data node and set the cold data node configuration.
{ "warmNodeConfiguration": { "disk": 1000, "amount": 3, "spec": "elasticsearch.sn1ne.xlarge" } }
Upgrade OpenStore (this configuration only applies to China site (aliyun.com))
Instances that have cold data nodes enabled and instances whose data node storage type is Enhanced SSD cannot be upgraded to open OpenStore.
If the instance type is Standard Business Edition, the instance type is upgraded from Standard Business Edition to Log Enhanced Edition with Indexing Service enabled after OpenStore is enabled.
Open OpenStore on a cold data node.
{ "warmNodeConfiguration": { "amount": 5, "spec": "openstore.i2g.4xlarge" } }
Data is node specifications converted to OpenStore.
{ "nodeAmount": 6, "nodeSpec": { "spec": "openstore.i2g.4xlarge", "diskType": "cloud_ssd", "disk": 100 } }
Specify the change method
The default change mode is intelligent change, which is specified as blue-green change (blue_green) or in-situ change (normal).
{ "nodeSpec": { "spec": "elasticsearch.r5.xlarge" }, "updateType": "blue_green" ## Change the value to normal. }
Enforce changes are enabled.
{ "nodeSpec": { "spec": "elasticsearch.r5.xlarge" }, "force": true }
Use the dryRun interface to upgrade the configuration precheck
Add the dryRun field to the request body.
{ "nodeSpec": { "spec": "elasticsearch.r5.xlarge" }, "dryRun": true }
Downgrade
When you downgrade the configuration, you cannot upgrade the storage space value, storage type, number of nodes, number of CPU cores of specifications, or memory value.
The UpdateInstance interface cannot reduce the number of nodes. Use the ShrinkNode interface if necessary.
You cannot downgrade the storage space of a node. Enabled nodes cannot be disabled.
You cannot select a forced change or specify a change type. By default, smart changes are used.
If you downgrade the configuration, you must set the orderActionType parameter to Downgrade.
You can downgrade multiple resource configurations at the same time, or perform dryRun pre-verification.
Downgrade the storage type
When you downgrade the configuration, you cannot change the storage types of cold data nodes, coordinator nodes, and Kibana nodes.
Change the storage type of the dedicated master node to SSD.
{ "masterConfiguration": { "diskType": "cloud_ssd" } }
Downgrade specifications
Downgrade the specifications of data nodes to 4 cores and 32 GB.
{ "nodeSpec": { "spec": "elasticsearch.r5.xlarge" } }
Response parameters
Parameter | Type | Example | Description |
RequestId | String | 5FFD9ED4-C2EC-4E89-B22B-1ACB6FE1**** | The ID of the request. |
Result | Object | The result of the request. | |
nodeAmount | Integer | 2 | The number of data nodes. |
createdAt | String | 2018-07-13T03:58:07.253Z | The time when the instance was created. |
status | String | active | The state of the instance. Valid values:
|
paymentType | String | postpaid | The billing method of the instance. Valid values:
|
domain | String | es-cn-abc.elasticsearch.aliyuncs.com | The private domain name of the instance. |
description | String | test | The name of the instance. |
esVersion | String | 5.5.3_with_X-Pack | The edition of the dedicated KMS instance. |
instanceId | String | es-cn-abc | The ID of the instance. |
nodeSpec | Object | The configuration of data nodes. | |
spec | String | elasticsearch.sn2ne.xlarge | The node specifications. |
disk | Integer | 40 | The storage space of the node. Unit: GB. |
diskType | String | cloud_ssd | The storage type of the node. Valid values:
|
kibanaConfiguration | Object | The configuration of Kibana nodes. | |
spec | String | elasticsearch.n4.small | The node specifications. |
amount | Integer | 1 | The number of nodes. |
disk | Integer | 20 | The size of the node storage space. |
diskType | String | cloud_ssd | The storage type of the node. This parameter can be ignored. |
masterConfiguration | Object | The configuration of dedicated master nodes. | |
spec | String | elasticsearch.sn2ne.large | The node specifications. |
amount | Integer | 3 | The number of nodes. |
disk | Integer | 20 | The storage space of the node. Unit: GB. |
diskType | String | cloud_ssd | The storage type of the node. Only cloud_ssd(SSD cloud disk) is supported. |
Examples
Sample requests
PUT /openapi/instances/es-cn-n6w1ptcb30009****?clientToken=5A2CFF0E-5718-45B5-9D4D-70B3FF****&orderActionType=upgrade HTTP/1.1
Host:elasticsearch.aliyuncs.com
Content-Type:application/json
{
"nodeSpec": {
"spec": "elasticsearch.r5.xlarge"
}
}
Sample success responses
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"Result" : {
"instanceId" : "es-cn-n6w1ptcb30009****",
"version" : "5.5.3_with_X-Pack",
"nodeAmount" : 3,
"paymentType" : "postpaid",
"status" : "active",
"nodeSpec" : {
"spec" : "elasticsearch.n4.small",
"disk" : 40,
"diskType" : "cloud_ssd",
"diskEncryption" : false
},
"createdAt" : "2020-06-28T08:25:52.895Z",
"zoneCount" : 1,
"instanceCategory" : "x-pack",
"kibanaConfiguration" : {
"spec" : "elasticsearch.n4.small",
"amount" : 1,
"disk" : 0
}
},
"RequestId" : "B5246080-9C30-4B6A-8F8A-8C705405****"
}
Description of the sample response
> In the return example, this article only guarantees that the parameters in the return data list are included, and the parameters not mentioned are for reference only. The program cannot force to rely on obtaining these parameters.
Error codes
For a list of error codes, visit the API Error Center.