创建集群V2
功能介绍
该接口用于创建拥有多种不同节点类型组合的集群。支持创建的集群引擎类型为Elasticsearch、Opensearch和Logstash。
-
Elasticsearch集群支持创建以下节点:
-
数据节点(ess):必选节点,数据节点用于存储集群数据。当集群未启用Client节点时,数据节点将额外提供接入集群和分析数据的功能;当集群未启用Master节点时,数据节点将额外提供集群管理功能。
-
Master节点(ess-master):可选节点,Master节点负责管理集群中所有节点任务,如集群元数据、索引及分片分配,保障大规模集群稳定运行,适用于需高可用性与集中管控的场景。
-
Client节点(ess-client):Client节点负责接收并协调外部请求(如搜索和写入),优化高负载查询和集群扩展性,适用于处理复杂查询和大规模分片场景。
-
冷数据节点(ess-cold):冷数据节点用于存储查询时延要求不高且数据量大的历史数据,适用于大规模数据集存储,有利于优化存储成本和查询性能。
-
-
Opensearch集群支持的节点与Elasticsearch集群支持的节点一致。
-
Logstash集群支持创建Logstash节点(lgs),该节点用于收集、解析、处理和传输数据。
接口约束
-
在创建集群之前,需确保已完成集群规划,包括集群规模、节点配置、存储容量等方面的规划。
-
已申请虚拟私有云VPC、子网和安全组,您也可以在创建集群的过程中申请。
调用方法
请参见如何调用API。
URI
POST /v2.0/{project_id}/clusters
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
project_id |
是 |
String |
参数解释: 项目ID。获取方法请参见获取项目ID和名称。 约束限制: 不涉及 取值范围: 账号的项目ID。 默认取值: 不涉及 |
请求参数
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
cluster |
是 |
CreateClusterBody object |
参数解释: 集群对象。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
name |
是 |
String |
参数解释: 集群名称。 约束限制: 不涉及 取值范围: 4~32个字符,只能包含数字、字母、中划线和下划线,且必须以字母开头。 默认取值: 不涉及 |
backupStrategy |
否 |
参数解释: 开启自动创建快照策略。 约束限制: 当backupStrategy参数配置不为空时,才会开启自动创建快照策略。 取值范围: 不涉及 默认取值: 不涉及 |
|
roles |
是 |
Array of CreateClusterRolesBody objects |
参数解释: 集群节点信息。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
nics |
是 |
参数解释: 网络配置信息。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
|
enterprise_project_id |
否 |
String |
参数解释: 企业项目ID。创建集群时,给集群绑定企业项目ID。 约束限制: 不涉及 取值范围: 最大长度36个字符,带"-"连字符的UUID格式,或者是字符串"0"。 默认取值: "0"表示企业项目。 |
tags |
否 |
Array of CreateClusterTagsBody objects |
参数解释: 集群标签。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
availability_zone |
是 |
String |
参数解释: 节点所在的可用区,需要指定可用区的名称(可用分区名称)。 约束限制: 选择多个可用区时,各个可用区名称不能重复输入,并且要求节点个数大于等于可用区个数。 若节点个数为可用区个数的倍数,节点将会均匀分布于各个可用区。 若节点个数非可用区个数的倍数,各可用区分布的节点数量之差的绝对值不大于1。 请参考CSS使用前必读中基本概念,了解可用区。 取值范围: 指定节点所在的可用区时,各个可用区名称需要使用英文逗号(,)分隔,以“通用可用区”为例,选择多可用区时,availability_zone取值为region-1a,region-1b,region-1c。 默认取值: 不涉及 |
datastore |
是 |
CreateClusterDatastoreBody object |
参数解释: 要创建的集群的引擎类型。 约束限制: 不涉及 取值范围: 支持elasticsearch、opensearch和logstash。 默认取值: 不涉及 |
authorityEnable |
否 |
Boolean |
参数解释: 集群是否开启安全认证。 约束限制: 此参数仅支持Elasticsearch集群和OpenSearch集群。
取值范围: 默认取值: false |
httpsEnable |
否 |
Boolean |
参数解释: 设置是否进行通信加密。 约束限制: 当httpsEnable设置为true时,authorityEnable字段需要设置为true。 Elasticsearch安全集群只有6.5.4及之后版本支持。 OpenSearch安全集群只有1.3.6和2.19.0版本支持关闭HTTPS访问,其他版本均强制启用HTTPS访问,不可关闭。 取值范围:
默认取值: false |
adminPwd |
否 |
String |
参数解释: 安全模式下集群管理员admin的密码。 约束限制: 只有在创建集群时authorityEnable设置为true时需要设置此参数。 取值范围: 8~32个字符,密码至少包含大写字母,小写字母,数字、特殊字符四类中的三类,其中可输入的特殊字符为:~!@#$%&*()-_=|[{}];:,<.>/?。 默认取值: 不涉及 |
publicIPReq |
否 |
CreateClusterPublicIpReq object |
参数解释: 公网访问信息。 约束限制: 只有在httpsEnable设置为true时该参数配置生效。 取值范围: 不涉及 默认取值: 不涉及 |
loadBalance |
否 |
CreateClusterLoadBalance object |
参数解释: 终端节点服务信息。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
publicKibanaReq |
否 |
CreateClusterPublicKibanaReq object |
参数解释: Kibana公网访问信息。 约束限制: 只有在authorityEnable设置为true时该参数配置生效。 取值范围: 不涉及 默认取值: 不涉及 |
payInfo |
否 |
PayInfoBody object |
参数解释: 包周期集群相关参数,订购包周期集群时使用。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
ipv6_enable |
否 |
Boolean |
参数解释: 集群是否开启自动分配IPv6地址。 约束限制: 不涉及 取值范围:
默认取值: false |
diskEncryption |
否 |
diskEncryptionInfo object |
参数解释: 磁盘加密信息。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
period |
是 |
String |
参数解释: 每天创建快照的时刻。 约束限制: 只支持整点,后面需加上时区,格式为HH:mm z,HH:mm表示整点时间,z表示时区。比如00:00 GMT+08:00、01:00 GMT+08:00等。 取值范围: 不涉及 默认取值: 00:00 GMT+08:00。
说明:
当frequency取值HOUR时,无需指定period值,默认从设置成功的下一整点创建。
|
frequency |
否 |
String |
参数解释: 自动创建快照的执行频次。 约束限制: 保留快照个数与自动创建快照策略中设置的执行频次和索引有关。当执行频次间隔时间短或索引数据量大,保留自动快照可能会达不到设置的个数,请谨慎选择! 取值范围:
默认取值: DAY |
prefix |
是 |
String |
参数解释: 自动创建的快照的前缀,需要用户自己手动输入。 约束限制: 只能包含1~32位小写字母、数字、中划线或者下划线,并且以小写字母开头。 取值范围: 不涉及 默认取值: 不涉及 |
keepday |
是 |
Integer |
参数解释: 自定义设置快照保留的个数。 约束限制: 系统在半点时刻会自动删除超过保留个数的快照。过期删除策略只针对与当前自动创建快照策略相同执行频次的自动快照。 取值范围: 1~90 默认取值: 不涉及 |
bucket |
否 |
String |
参数解释: 备份使用的OBS桶名称。 约束限制: 选择的OBS桶需要满足如下条件:
取值范围: 不涉及 默认取值: 不涉及 |
basePath |
否 |
String |
参数解释: 快照在OBS桶中的存放路径。 约束限制: 备份路径配置规则:
取值范围: 不涉及 默认取值: 不涉及 |
agency |
否 |
String |
参数解释: 选择IAM委托,授权当前账号访问和使用OBS的权限。 约束限制: 不涉及 取值范围: 委托名称必须仅包含字符a-z、A-Z、0-9、下划线(_)和短横线(-)。 默认取值: 不涉及
说明:
如果bucket、basePath和agency三个参数同时为空,则系统会自动创建OBS桶和IAM代理(若创建失败,则需要手工配置正确的参数)。
|
maxSnapshotBytesPerSeconds |
否 |
String |
参数解释: 配置每个节点的最大备份速率(每秒),即当备份的速率超过该值时会被限流,避免速率太大导致资源占用过高,影响系统稳定性。实际备份速率不一定能达到该值,会受OBS、磁盘等影响。 约束限制: 不涉及 取值范围: 有以下3种填写规则:
默认取值: 40mb |
maxRestoreBytesPerSeconds |
否 |
String |
参数解释: 配置每个节点的最大恢复速率(每秒),即当恢复的速率超过该值时会被限流,避免速率太大导致资源占用过高,影响系统稳定性。实际恢复速率不一定能达到该值,会受OBS、磁盘等影响。 约束限制: OpenSearch集群和版本是7.6.2以后的Elasticsearch集群,恢复速率还受限于“indices.recovery.max_bytes_per_sec”参数。当“最大恢复速率(每秒)”小于“indices.recovery.max_bytes_per_sec”的参数值时,恢复速率达到“最大恢复速率(每秒)”参数值时就会被限流。当“最大恢复速率(每秒)”大于“indices.recovery.max_bytes_per_sec”的参数值时,恢复速率达到“indices.recovery.max_bytes_per_sec”参数值时就会被限流。 取值范围: 有以下3种填写规则:
默认取值: 7.6.2及以下版本的Elasticsearch集群,默认值是40mb。 OpenSearch集群和7.6.2以上版本的Elasticsearch集群,默认值是不限制,但还受限于“indices.recovery.max_bytes_per_sec”参数。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
flavorRef |
是 |
String |
参数解释: 实例规格名称。可以使用获取实例规格列表的name属性确认当前拥有的规格信息。 约束限制: 可以使用获取实例规格列表的name属性确认当前拥有的规格信息。 取值范围: 不涉及 默认取值: 不涉及 |
volume |
是 |
参数解释: volume信息。 约束限制: 当flavorRef选择的是本地盘规格时不需要填写,本地盘规格可以通过获取实例规格列表中diskrange属性获得,如果diskrange中两个数值相等,则为本地盘。 取值范围: 不涉及 默认取值: 不涉及 |
|
type |
是 |
String |
参数解释: 节点类型。 约束限制: 不涉及 取值范围:
默认取值: 不涉及 |
instanceNum |
是 |
Integer |
参数解释: 实例个数。 约束限制: 见取值范围。 取值范围:
默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
volume_type |
是 |
String |
参数解释: 磁盘类型。 约束限制: 不涉及 取值范围:
默认取值: 不涉及 |
size |
是 |
Integer |
参数解释: 磁盘大小。 约束限制: 必须为大于0且为4和10的公倍数,单位:GB。 取值范围: 磁盘规格大小可以通过获取实例规格列表中diskrange属性获得。 默认取值:
说明:
推荐大于100G。
|
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
vpcId |
是 |
String |
参数解释: 指定虚拟私有云ID,用于集群网络配置。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
netId |
是 |
String |
参数解释: 子网ID(网络ID)。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
securityGroupId |
是 |
String |
参数解释: 安全组ID。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
ips |
否 |
Array of strings |
参数解释: 节点IP信息,在指定IP创建集群时配置。 约束限制: 不涉及 取值范围: 只有Elasticsearch和OpenSearch支持。
默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
key |
是 |
String |
参数解释: 集群标签的key值。 约束限制: 可输入的字符串长度为1~36个字符。只能包含数字、字母、中划线"-"和下划线"_"。 取值范围: 不涉及 默认取值: 不涉及 |
value |
是 |
String |
参数解释: 集群标签的value值。 约束限制: 可输入的字符串长度为0~43个字符。只能包含数字、字母、中划线"-"和下划线"_"。 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
version |
是 |
String |
参数解释: CSS集群引擎版本号。详细请参考CSS使用前必读中支持的版本。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
type |
是 |
String |
参数解释: 要创建的集群的引擎类型。 约束限制: 不涉及 取值范围:
默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
eip |
是 |
CreateClusterPublicEip object |
参数解释: 公网带宽信息。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
elbWhiteListReq |
是 |
CreateClusterElbWhiteList object |
参数解释: 弹性IP白名单。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
publicBindType |
是 |
String |
参数解释: 是否自动绑定弹性公网IP。 约束限制: 不涉及 取值范围: 当前仅支持auto_assign为自动分配参数。 默认取值: 不涉及 |
eipId |
否 |
String |
参数解释: 弹性公网IP的ID。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
bandWidth |
是 |
CreateClusterPublicEipSize object |
参数解释: 设置公网带宽大小。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
size |
是 |
Integer |
参数解释: 带宽大小,单位Mbit/s。 约束限制: 不涉及 取值范围: 1-200 默认取值: 1 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
enableWhiteList |
是 |
Boolean |
参数解释: 是否开启公网访问控制。 约束限制: 不涉及 取值范围:
单击“设置访问白名单”,输入允许公网访问集群的IP地址或网段(CIDR格式),以英文逗号分隔,不可重复。例如输入“192.168.1.1,10.0.0.0/24”,不支持“0.0.0.0”、“x.x.x.x0”、“172.16.0.0-172.16.255.255”、非标准格式(如“192.168.1”)或重复项。 -false:不设置访问白名单,则表示所有公网IP地址都可以访问集群。 默认取值: false |
whiteList |
否 |
String |
参数解释: 公网访问控制白名单。 约束限制: 需要添加白名单的网段或IP,以逗号隔开,不可重复。 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
endpointWithDnsName |
是 |
Boolean |
参数解释: 终端节点的内网域名。 约束限制: 不涉及 取值范围:
默认取值: false |
vpcPermissions |
否 |
Array of strings |
参数解释: 访问控制。 约束限制: 不涉及 取值范围: 不涉及。 默认取值: 不涉及 |
professionVpcep |
否 |
Boolean |
参数解释: 创建专业型终端节点。 约束限制: 不涉及 取值范围:
默认取值: fasle |
dualstackEnable |
否 |
Boolean |
参数解释: 是否开启IPv4/IPv6双栈网络。 约束限制: 仅支持在创建专业型终端节点时开启双栈网络,且集群的VPC子网支持IPv6。 取值范围:
默认取值: fasle |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
eipSize |
是 |
Integer |
参数解释: 带宽大小,单位Mbit/s。 约束限制: 不涉及 取值范围: 1-200 默认取值: 1 |
elbWhiteList |
是 |
参数解释: Kibana白名单信息。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
whiteList |
是 |
String |
参数解释: 白名单 约束限制: 需要添加白名单的网段或IP,以逗号隔开,不可重复。 取值范围: 不涉及 默认取值: 不涉及 |
enableWhiteList |
是 |
Boolean |
参数解释: 是否开启kibana访问控制。 约束限制: 不涉及 取值范围: -true:设置访问白名单,则表示只允许白名单列表中的IP地址或网段通过公网访问集群Kibana。 单击“设置访问白名单”,输入允许公网访问集群Kibana的IP地址或网段(CIDR格式),以英文逗号分隔,不可重复。例如输入“192.168.1.1,10.0.0.0/24”,不支持“0.0.0.0”、“x.x.x.x0”、“172.16.0.0-172.16.255.255”、非标准格式(如“192.168.1”)或重复项。 -false:不设置访问白名单,则表示所有公网IP地址都可以访问集群Kibana。 默认取值: false |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
payModel |
是 |
Integer |
参数解释: 集群订购周期类型。 约束限制: 不涉及 取值范围:
默认取值: 不涉及 |
period |
是 |
Integer |
参数解释: 集群订购周期数。 约束限制: 不涉及 取值范围:
默认取值: 不涉及 |
isAutoRenew |
否 |
Integer |
参数解释: 是否自动续订,为空时表示不自动续订。 约束限制: 不涉及 取值范围:
默认取值: 0 |
isAutoPay |
否 |
Integer |
参数解释: 是否自动支付。下单订购后,是否自动从客户的华为云账户中支付,而不需要客户手动去进行支付。该参数适用于包周期集群。 约束限制: 不涉及 取值范围:
默认取值: 0 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
systemEncrypted |
否 |
String |
参数解释: 是否开启磁盘加密。通过磁盘加密对集群节点的数据盘进行KMS加密,保障数据存储的安全性。 约束限制: 磁盘加密不会改变集群的管理和运维操作流程,但数据加解密环节会增加系统处理开销,可能会对操作性能产生一定的影响。 取值范围:
默认取值: 0 |
systemCmkid |
否 |
String |
参数解释: 磁盘密钥ID。 约束限制: systemEncrypted为1时有效。 在下拉框中选择KMS密钥名称,下拉框中不可见的KMS密钥表示集群不支持。选择的密钥必须满足以下条件:
集群创建成功后不支持修改密钥。 当集群使用的KMS密钥处于非启用状态时,集群扩容、升级、节点规格变更、指定节点替换及可用区切换的操作将失败,需通过新建集群并完成数据迁移实现业务变更。 取值范围: 不涉及 默认取值: 不涉及 |
响应参数
状态码:200
参数 |
参数类型 |
描述 |
---|---|---|
cluster |
CreateClusterResp object |
参数解释: 集群对象。若创建的是按需集群,则只返回cluster参数。 取值范围: 不涉及。 |
orderId |
String |
参数解释: 订单号。只有创建包周期集群时才会返回orderld参数。 取值范围: 不涉及。 |
请求示例
-
创建包周期的Elasticsearch集群请求示例。
POST https://{Endpoint}/v2.0/{project_id}/clusters { "cluster" : { "name" : "css-cluster", "backupStrategy" : { "period" : "16:00 GMT+08:00", "prefix" : "snapshot", "keepday" : 7, "frequency" : "DAY", "bucket" : "OBS-obsName", "basePath" : "css_repository/obs-path", "agency" : "css_obs_agency", "maxSnapshotBytesPerSeconds" : 40, "maxRestoreBytesPerSeconds" : 40 }, "roles" : [ { "flavorRef" : "ess.spec-4u8g", "volume" : { "volume_type" : "COMMON", "size" : 100 }, "type" : "ess", "instanceNum" : 1 } ], "nics" : { "vpcId" : "{VPC ID}", "netId" : "{NET ID}", "securityGroupId" : "{Security group ID}" }, "enterprise_project_id" : 0, "tags" : [ { "key" : "k1", "value" : "v1" }, { "key" : "k2", "value" : "v2" } ], "availability_zone" : "{Az code}", "datastore" : { "version" : "{cluster-version}", "type" : "elasticsearch" }, "authorityEnable" : true, "httpsEnable" : true, "adminPwd" : "{password}", "publicIPReq" : { "eip" : { "bandWidth" : { "size" : 5 } }, "elbWhiteListReq" : { "enableWhiteList" : true, "whiteList" : "127.0.0.1" }, "publicBindType" : "auto_assign", "eipId" : null }, "loadBalance" : { "endpointWithDnsName" : false, "vpcPermissions" : [ "{Account ID}" ] }, "publicKibanaReq" : { "eipSize" : 5, "elbWhiteList" : { "whiteList" : "127.0.0.1", "enableWhiteList" : true } }, "payInfo" : { "payModel" : 2, "period" : 1, "isAutoRenew" : 1, "isAutoPay" : null } } }
-
创建按需的Elasticsearch集群请求示例。
POST https://{Endpoint}/v2.0/{project_id}/clusters { "cluster" : { "name" : "css-cluster", "backupStrategy" : { "period" : "16:00 GMT+08:00", "prefix" : "snapshot", "keepday" : 7, "frequency" : "DAY", "bucket" : "OBS-obsName", "basePath" : "css_repository/obs-path", "agency" : "css_obs_agency", "maxSnapshotBytesPerSeconds" : 40, "maxRestoreBytesPerSeconds" : 40 }, "roles" : [ { "flavorRef" : "ess.spec-4u8g", "volume" : { "volume_type" : "COMMON", "size" : 100 }, "type" : "ess", "instanceNum" : 1 } ], "nics" : { "vpcId" : "{VPC ID}", "netId" : "{NET ID}", "securityGroupId" : "{Security group ID}" }, "enterprise_project_id" : 0, "tags" : [ { "key" : "k1", "value" : "v1" }, { "key" : "k2", "value" : "v2" } ], "availability_zone" : "{Az code}", "datastore" : { "version" : "{cluster-version}", "type" : "elasticsearch" }, "authorityEnable" : true, "httpsEnable" : true, "adminPwd" : "{password}", "publicIPReq" : { "eip" : { "bandWidth" : { "size" : 5 } }, "elbWhiteListReq" : { "enableWhiteList" : true, "whiteList" : "127.0.0.1" }, "publicBindType" : "auto_assign", "eipId" : null }, "loadBalance" : { "endpointWithDnsName" : false, "vpcPermissions" : [ "{Account ID}" ] }, "publicKibanaReq" : { "eipSize" : 5, "elbWhiteList" : { "whiteList" : "127.0.0.1", "enableWhiteList" : true } } } }
响应示例
状态码:200
请求已成功
-
创建按需期集群响应示例。
{ "cluster" : { "id" : "ef683016-871e-48bc-bf93-74a29d60d214", "name" : "ES-Test" } }
-
创建包周期集群响应示例。
{ "orderId" : "CS2208241141LY94J", "cluster" : { "id" : "ef683016-871e-48bc-bf93-74a29d60d214", "name" : "ES-Test" } }
状态码
状态码 |
描述 |
---|---|
200 |
请求已成功 |
400 |
非法请求。 建议直接修改该请求,不要重试该请求。 |
409 |
服务器在完成请求时发生冲突。 返回该状态码,表明客户端尝试创建的资源已经存在,或者由于冲突请求的更新操作不能被完成。 |
412 |
未满足前提条件,服务器未满足请求者在请求中设置的其中一个前提条件。 |
错误码
请参见错误码。