调用UpdateInstance,变更集群配置。

调用该接口时,请注意:

  • 当实例状态为生效中(activating)、失效(invalid)和冻结(inactive)时,无法变更配置。
  • 如果集群负载过高且索引没有副本,同时在升配或者降配过程中存在大量的写入或查询等情况,业务可能会出现偶发的访问超时现象。建议在集群变更前,在客户端访问机制中配置重试机制,以减小对业务的影响。
  • 每次只能变更一种类型的节点(数据节点、专有主节点、冷数据节点、协调节点、Kibana节点、弹性节点)的配置。
  • 出于您的集群健康和稳定性的考虑,自2021年5月起,阿里云Elasticsearch已不支持购买1核2 GB规格、专有主节点的2核2 GB规格和7.4版本实例,如果您已确认已购规格不再支持售卖,那么您需要先完成以下操作:

更多注意事项,请参见升配集群降配集群

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求头

该接口使用公共请求头,无特殊请求头。请参见公共请求参数文档。

请求语法

PUT /openapi/instances/{InstanceId} HTTP/1.1

请求参数

名称 类型 位置 是否必选 示例值 描述
InstanceId String Path es-cn-n6w1ptcb30009****

实例ID。

clientToken String Query 5A2CFF0E-5718-45B5-9D4D-70B3FF****

用于保证请求的幂等性。由客户端生成该参数值,要保证在不同请求间唯一,最大不超过64个ASCII字符。

orderActionType String Query upgrade

配置变更类型,可选值:

  • upgrade(默认):升配
  • downgrade:降配
Object Body

请求体参数。

nodeAmount Integer Body 3

节点数量。

nodeSpec NodeSpec Body

数据节点配置。

masterConfiguration MasterNodeConfiguration Body

专有主节点配置。

clientNodeConfiguration ClientNodeConfiguration Body

协调节点配置。

warmNodeConfiguration WarmNodeConfiguration Body

冷数据节点配置。

kibanaConfiguration KibanaNodeConfiguration Body

kibana节点配置。

elasticDataNodeConfiguration ElasticDataNodeConfiguration Body

弹性节点配置。

instanceCategory String Body advanced

版本类型。可选值:

  • x-pack:商业版实例
  • advanced:增强版实例
  • IS:开启Indexing Service的增强版实例
  • community:基础版实例
    说明 创建增强版开启OpenStore的实例需要同时开启Indexing Service。
force Boolean Query false

是否强制重启:

  • true:是
  • false(默认):否

Elasticsearch支持的节点规格列表,请参见阿里云Elasticsearch定价信息产品规格

请求体参数示例如下:

升配
说明 升配时,不支持降低存储空间数值、存储类型配置、节点数量、规格的CPU核数或内存值。
  • 升配存储空间

    目前仅支持数据节点、冷数据节点和弹性数据节点升配存储空间。

    将冷数据节点的存储空间升配至1000 GiB。
    
    {
      "warmNodeConfiguration": {
       "disk": 1000
      }
    }
    
  • 升配存储类型

    目前仅支持数据节点、弹性数据节点和专有主节点升配存储类型。

    • 将专有主节点的存储类型升配为ESSD云盘类型。
      
      {
        "masterConfiguration": {
          "diskType": "cloud_essd"
        }
      }
      
    • 当专有主节点的存储类型为ESSD云盘类型时,将节点存储性能级别升配为PL3。

      指定performanceLevel后,diskType会默认填充为cloud_essd

      指定cloud_essd后,performanceLevel默认为PL1
      
      	{
      	  "masterConfiguration": {
      		"performanceLevel": "PL3"
      	  }
      	}
      	
  • 升配节点数量

    目前仅支持数据节点、冷数据节点、弹性数据节点和协调节点升配节点数量。

    数据节点升配节点数量的方式与其他节点不同,具体参见下文示例。

    • 将数据节点的节点数量升至12个。
      
      {
        "nodeAmount": 12
      }
      
    • 将其他类型节点(以冷数据节点为例)的节点数量升至12个。
      
      {
        "warmNodeConfiguration": {
          "amount": 12
        }
      }
      
  • 升配节点规格

    将数据节点的规格升至4核32 GB。
    
    {
      "nodeSpec": {
        "spec": "elasticsearch.r5.xlarge"
      }
    }
    
  • 同时升配同一节点的几种配置

    同时升配同一节点的几种配置,需要您同时写入升配资源RequestBody。

    • 将协调节点的节点数量升至8,规格升至4核8 GB。
      
      {
        "clientNodeConfiguration": {
          "amount": 8,
          "spec": "elasticsearch.sn1ne.xlarge"
        }
      }
      
    • 将数据节点的节点数量升至12,存储类型升至ESSD云盘。
      
      {
        "nodeAmount": 12,
        "nodeSpec": {
          "diskType": "cloud_essd"
        }
      }
      
  • 启用节点

    您可以参见createInstance接口设置完整的节点资源配置。

    • 启用协调节点,同时设置协调节点配置。
      
      {
        "clientNodeConfiguration": {
          "amount": 5,
          "disk": 20,
          "spec": "elasticsearch.sn1ne.xlarge"
        }
      }
      
    • 启用弹性数据节点,同时设置弹性数据节点配置(此配置只适用于中国站)。
      
      {
        "elasticNodeConfiguration": {
          "disk": 200,
          "amount": 5,
          "diskType": "cloud_essd",
          "spec": "elasticsearch.sn1ne.xlarge"
        }
      }
      
    • 启用冷数据节点,同时设置冷数据节点配置。
      
      {
        "warmNodeConfiguration": {
          "disk": 1000,
          "amount": 3,
          "spec": "elasticsearch.sn1ne.xlarge"
        }
      }
      
  • 升配开启OpenStore(此配置只适用于中国站)

    已启用冷数据节点的实例以及数据节点存储类型为ESSD云盘的实例,目前不支持升配开启OpenStore。

    如果实例类型为普通商业版,升配开启OpenStore后,实例类型同时由普通商业版升配至开启Indexing Service的日志增强版。

    • 冷数据节点打开OpenStore。
      
      {
        "warmNodeConfiguration": {
          "amount": 5,
          "spec": "openstore.i2g.4xlarge"
        }
      }
      
    • 数据节点规格转换为OpenStore。
      
      {
        "nodeAmount": 6,
        "nodeSpec": {
          "spec": "openstore.i2g.4xlarge",
          "diskType": "cloud_ssd",
          "disk": 100
        }
      }
      
  • 指定变更方式
    • 变更方式默认为智能变更,将其指定为蓝绿变更(blue_green)或原地变更(normal)。
      
      {
        "nodeSpec": {
          "spec": "elasticsearch.r5.xlarge"
        },
        "updateType": "blue_green"  ## 原地变更为normal。
      }
      
    • 开启强制变更。
      
      {
        "nodeSpec": {
          "spec": "elasticsearch.r5.xlarge"
        },
        "force": true
      }
      
  • 使用dryRun接口进行升配预校验

    在RequestBody中添加dryRun字段。
    
    {
      "nodeSpec": {
        "spec": "elasticsearch.r5.xlarge"
      },
      "dryRun": true
    }
    
降配
说明

降配时,不支持升级存储空间数值、存储类型、节点数量、规格的CPU核数或内存值。

UpdateInstance接口无法降低节点数量,如有需求请使用ShrinkNode接口。

不支持降配节点存储空间大小,启用的节点不支持关闭。

不支持选择强制变更,不支持指定变更类型,默认使用智能变更。

降配时,orderActionType参数需要设置为Downgrade

您可以同时降配多个资源配置,也可以进行dryRun预校验。

  • 降配存储类型

    降配时,不支持变更冷数据节点(不变更实例类型)、协调节点、Kibana节点的存储类型。

    将专有主节点的存储类型变更为SSD云盘。
    
    {
      "masterConfiguration": {
        "diskType": "cloud_ssd"
      }
    }
    
  • 降配规格

    将数据节点的规格降配至4核32 GB。
    
    {
      "nodeSpec": {
        "spec": "elasticsearch.r5.xlarge"
      }
    }
    

返回数据

名称 类型 示例值 描述
RequestId String 5FFD9ED4-C2EC-4E89-B22B-1ACB6FE1****

请求ID。

Result Object

返回结果。

nodeAmount Integer 2

数据节点的数量。

createdAt String 2018-07-13T03:58:07.253Z

实例创建时间。

status String active

实例的状态。支持:

  • active:正常
  • activating:生效中
  • inactive:冻结
  • invalid:失效
paymentType String postpaid

实例的付费方式。支持:

  • prepaid:包年包月
  • postpaid:按量付费
domain String es-cn-abc.elasticsearch.aliyuncs.com

实例的私网访问域名。

description String test

实例名称。

esVersion String 5.5.3_with_X-Pack

实例版本。

instanceId String es-cn-abc

实例ID。

nodeSpec Object

数据节点配置信息。

spec String elasticsearch.sn2ne.xlarge

节点规格。

disk Integer 40

节点存储空间大小,单位:GB。

diskType String cloud_ssd

节点存储类型。支持:

  • cloud_ssd:SSD云盘
  • cloud_efficiency:高效云盘
kibanaConfiguration Object

Kibana节点配置。

spec String elasticsearch.n4.small

节点规格。

amount Integer 1

节点数量。

disk Integer 20

节点存储空间大小。

diskType String cloud_ssd

节点存储类型(可忽略该参数)。

masterConfiguration Object

Master节点配置。

spec String elasticsearch.sn2ne.large

节点规格。

amount Integer 3

节点数量。

disk Integer 20

节点的存储空间大小,单位:GB。

diskType String cloud_ssd

节点的存储类型。只支持cloud_ssd(SSD云盘)。

示例

请求示例

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"
  }
}

正常返回示例

JSON格式

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****"
}

返回示例补充说明

> 返回示例中,本文只保证包含返回数据列表中的参数,而未提到的参数仅供参考,程序中不能强制依赖获取这些参数。

错误码

访问错误中心查看更多错误码。