All Products
Search
Document Center

Elasticsearch:UpdateInstance

更新時間:Sep 10, 2024

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.