You can call this operation to change the cluster configuration.

When you call this operation, take note of the following limits:

  • 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

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 headers

This operation uses only common request headers. For more information, refer to the documentation of 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 make sure that it 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:

  • upgrade (default): upgrade
  • downgrade: downgrade
String Body No { "nodeSpec": { "spec": "elasticsearch.r5.xlarge" } }

The request body parameters.

RequestBody

You must also specify the following parameters in the RequestBody parameter to specify the information of the instance to be upgraded.

Parameter

Type

Required

Example

Description

updateType

String

No

blue_green

The change method. Valid values: blue_green and normal.

nodeAmount

int

No

3

The number of data nodes.

nodeSpec

Map

No

The configuration of the data node.

└spec

String

No

elasticsearch.sn2ne.xlarge

node specifications, the specification information can be viewed by product specifications.

└disk

String

No

20

The storage space of a single node. Unit: GB.

└diskType

String

No

cloud_ssd

The type of the storage. Valid values: cloud_ssd(SSD), cloud_essd (Enhanced SSD), and cloud_efficiency (ultra disk).

└performanceLevel

String

No

PL1

The performance level of the ESSD. This parameter is required when the storage type is cloud_essd. Valid values: PL1, PL2, and PL3.

masterConfiguration

Map

No

The configuration of the dedicated master node.

└spec

String

No

elasticsearch.sn2ne.xlarge

node specifications, the specification information can be viewed by product specifications.

└amount

int

No

3

The number of nodes. Currently, the value is fixed to 3.

└disk

int

No

20

The size of the storage space per node. Currently, only 20 GB is supported.

└diskType

string

No

cloud_ssd

The storage type of the node. Valid values: cloud_ssd(SSD) and cloud_essd (Enhanced SSD).

warmNodeConfiguration

Map

No

Configure the cold data node.

└spec

string

No

elasticsearch.ic5.large

node specifications, the specification information can be viewed by product specifications. The openstore.i2g.4xlarge specification indicates that OpenStore storage is enabled (this specification only applies to China site (aliyun.com)).

└amount

Integer

No

2

The number of nodes.

└disk

Integer

No

500

The storage space of a single node.

clientNodeConfiguration

Map

No

Coordination node configuration.

└spec

string

No

elasticsearch.ic5.large

node specifications, the specification information can be viewed by product specifications.

└amount

Integer

No

2

The number of nodes.

└disk

Integer

No

20

The size of the storage space per node.

elasticDataNodeConfiguration

Map

No

Elastic node configuration (this configuration only applies to China site (aliyun.com)).

└spec

string

No

elasticsearch.ic5.large

node specifications, the specification information can be viewed by product specifications.

└amount

Integer

No

2

The quantity.

└diskType

string

No

cloud_efficiency

The storage type of the node. Valid values: cloud_ssd(SSD), cloud_essd (Enhanced SSD), and cloud_efficiency (ultra disk).

└disk

Integer

No

20

The size of the storage space per node.

└performanceLevel

String

No

PL1

The performance level of the ESSD. This parameter is required when the storage type is cloud_essd. Valid values: PL1, PL2, and PL3.

kibanaConfiguration

Map

No

The configuration of the kibana node.

└spec

String

Yes

elasticsearch.n4.small

node specifications, the specification information can be viewed by product specifications.

dryRun

boolean

No

true

Specifies whether to verify the configurations when you change the configuration of the instance. Valid values: true and false. Valid values: true and false.

Note

An example of the RequestBody is as follows:

Upgrade
Note 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
Note

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 return results.

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 status of the instance. Valid values:

  • active: normal
  • activating: taking effect
  • inactive: frozen
  • invalid: invalid
paymentType String postpaid

The billing method of the instance. Valid values:

  • prepaid: subscription
  • postpaid: pay-as-you-go
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 version of the read-only instance.

instanceId String es-cn-abc

The ID of the instance.

nodeSpec Object

The configuration of data nodes.

spec String elasticsearch.sn2ne.xlarge

The specifications of the node.

disk Integer 40

The storage space of the node. Unit: GB.

diskType String cloud_ssd

The storage type of the node. Valid values:

  • cloud_ssd: standard SSD
  • cloud_efficiency: ultra disk
kibanaConfiguration Object

The configuration of Kibana nodes.

spec String elasticsearch.n4.small

The specifications of the node.

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 specifications of the node.

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 sample responses

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