Elasticsearch:UpdateInstance

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.

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

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

• 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

• 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

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.