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

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, 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:

  • upgrade (default): upgrade
  • downgrade: downgrade
Object Body No

The request body parameters.

nodeAmount Integer Body No 3

The number of nodes.

nodeSpec NodeSpec Body No

The configuration of the data node.

masterConfiguration MasterNodeConfiguration Body No

The configuration of the dedicated master node.

clientNodeConfiguration ClientNodeConfiguration Body No

Coordination node configuration.

warmNodeConfiguration WarmNodeConfiguration Body No

Configure the cold data node.

kibanaConfiguration KibanaNodeConfiguration Body No

The configuration of the kibana node.

elasticDataNodeConfiguration ElasticDataNodeConfiguration Body No

The configuration of the elastic node.

instanceCategory String Body No advanced

Version type. Valid values:

  • x-pack: Business Edition instance
  • advanced: Enhanced Edition instance
  • IS: Enable an Enhanced Edition instance of Indexing Service
  • community: Basic Edition instance
    Note To create an enhanced instance with OpenStore enabled, you must also enable Indexing Service.
force Boolean Query No false

Whether to forcibly restart:

  • true: enables data encryption
  • false (default): No

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

  • 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 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:

  • cloud_ssd: standard SSD
  • cloud_efficiency: ultra disk
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.