文档首页/ 弹性内存存储 EMS/ API参考/ API/ 生命周期管理/ 查询集群列表 - ListClusters
更新时间：2026-05-25 GMT+08:00
查看PDF
分享

查询集群列表 - ListClusters

功能介绍

查询集群列表接口。

URI

GET /v1/clusters

表1 Query参数

参数

是否必选

参数类型

描述

limit

否

Integer

参数解释

返回结果个数限制。

约束限制

不涉及。

取值范围

值为大于0的整数。

默认取值

1000

offset

否

Integer

参数解释

偏移量。分页查询集群时使用，与limit配合使用，从第offset+1条记录开始返回结果。

约束限制

不涉及。

取值范围

值为大于等于0的整数。

默认取值

0

请求参数

无

响应参数

状态码：200

表2 响应Body参数

参数

参数类型

描述

clusters

Array of Cluster objects

参数解释

集群列表信息。

取值范围

集群对象数组，最多1000个元素。
表3 Cluster

参数

参数类型

描述

cluster_metadata

ClusterMetadata object

参数解释

集群基本信息。

取值范围

不涉及。

cluster_specification

ClusterSpecification object

参数解释

创建时指定的集群配置信息。

取值范围

不涉及。
表4 ClusterMetadata

参数

参数类型

描述

id

String

参数解释

集群ID，资源唯一标识，创建后自动生成。

取值范围

不涉及。

status

String

参数解释

集群状态。

取值范围

  • CREATING：创建中。

  • RUNNING：运行中。

  • FREEZE：已冻结。

  • UPGRADING：升级中。

  • EXPANDING：扩容中。

  • SHRINKING：缩容中

  • DELETING：删除中。

  • DELETED：已删除。

reason

String

参数解释

集群变为当前状态的原因，在集群在非“Available”状态下时，会返回此参数。

取值范围

不涉及。

project_id

String

参数解释

所属租户项目ID。

取值范围

不涉及。

created_at

String

参数解释

集群创建时间。

取值范围

不涉及。

updated_at

String

参数解释

集群信息更新时间。

取值范围

不涉及。

k8s_name

String

参数解释

关联的CCE集群名称。

取值范围

不涉及。

available_node_count

Integer

参数解释

业务集群当前可用节点数。

取值范围

3-512
表5 ClusterSpecification

参数

参数类型

描述

name

String

参数解释

集群名称。

取值范围

以小写字母开头，由字母、数字、中划线(-)组成，长度范围4-128位，且不能以中划线(-)结尾。

description

String

参数解释

集群描述。

取值范围

不涉及。

charge_mode

Integer

参数解释

付费模式。

取值范围

0：按需付费。

k8s_cluster_specification

K8sClusterSpecification object

参数解释

业务k8s集群部署配置。

取值范围

不涉及。

memory_specification

MemorySpecification object

参数解释

EMS集群内存配置。

取值范围

不涉及。
表6 K8sClusterSpecification

参数

参数类型

描述

k8s_cluster_id

String

参数解释

CCE集群ID。

约束限制

必须为UUID格式。

取值范围

不涉及。

默认取值

不涉及。

namespace

String

参数解释

CCE集群中部署ems服务的命名空间。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。

label

K8sLabel object

参数解释

指定CCE集群中的安装范围，当前支持指定标签。Map对象，key为标签名，value为标签值。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。

node_count

Integer

参数解释

CCE集群节点数。

约束限制

不涉及。

取值范围

3-512。

默认取值

不涉及。

flavor

String

参数解释

集群实例规格。

约束限制

不涉及。

取值范围

由一个或多个字母开始，后面跟随一个或多个由点分隔的字母段的字符串组成。且长度为1-64个字符。

默认取值

不涉及。

version

String

参数解释

集群版本，发放的集群版本。

约束限制

不涉及。

取值范围

不涉及。

默认取值空

lts_enable

Boolean

参数解释

是否安装云原生日志采集插件用LTS采集日志，安装前请提前创建LTS的转储委托。

约束限制

不涉及。

取值范围

  • true: 开启日志采集。

  • false: 关闭日志采集。

默认取值

true。

lts_connect_type

Integer

参数解释

日志接入方式。

约束限制

不涉及。

取值范围

  • 0: logagent。

  • 1: icagent。

默认取值

0。

monitor_enable

Boolean

参数解释

是否安装云原生监控插件。

约束限制

不涉及。

取值范围

  • true: 已安装云原生监控插件。

  • false: 未安装云原生监控插件。

默认取值

true。

node_type

Integer

参数解释

节点类型。

约束限制

不涉及。

取值范围

  • 0: 自动检测。

  • 1: A3节点。

  • 2: 其他。

默认取值

0。

node_list

Array of NodeInfo objects

参数解释

集群节点信息列表，包含每个节点上运行的Pod信息，仅在查询集群详情响应体中出现。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。
表7 K8sLabel

参数

参数类型

描述

key

String

参数解释

标签的键。

约束限制

不涉及。

取值范围

以字母或者数字开头和结尾，由字母、数字、连接符(-)、下划线(_)、点号(.)组成，且长度范围不超过63个字符。

默认取值

ems。

value

String

参数解释

标签的值。

约束限制

不涉及。

取值范围

以字母或者数字开头和结尾，由字母、数字、连接符(-)、下划线(_)、点号(.)组成，且长度范围不超过63个字符。

默认取值

true。
表8 NodeInfo

参数

参数类型

描述

node_name

String

参数解释

主机名称，即为节点的IP地址。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。

pod_list

Array of PodInfo objects

参数解释

该节点上运行的Pod信息列表。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。
表9 PodInfo

参数

参数类型

描述

pod_type

String

参数解释

Pod类型，用于标识Pod的用途。

约束限制

不涉及。

取值范围

  • ems-zookeeper：ems-zookeeper

  • ems-controller：ems-controller

  • ems-server：ems-server

  • ems-agent：ems-agent

默认取值

不涉及。

pod_name

String

参数解释

Pod名称，Kubernetes中Pod的资源名称。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。
表10 MemorySpecification

参数

参数类型

描述

huge_page_num

Integer

参数解释

大页数。

约束限制

不涉及。

取值范围

131072-2147483647。

默认取值

默认256GB，对应数量是131072。

huge_page_flavor

Integer

参数解释

大页规格（即大页大小，单位MB）。

约束限制

不涉及。

取值范围

不涉及。

默认取值

默认2MB。

状态码：400

表11 响应Body参数

参数

参数类型

描述

error_code

String

参数解释

错误码，用于标识具体的错误类型。

取值范围

不涉及。

error_msg

String

参数解释

错误描述，用于说明具体的错误信息。

取值范围

不涉及。

请求示例

获取当前租户集群列表。每页返回10个记录，从第2条（offset+1）条记录开始。

GET https://{endpoint}/v1/clusters?offset=1&limit=10

响应示例

状态码：200

参数解释

查询集群列表成功返回响应体。

取值范围

不涉及。

{
  "clusters" : [ {
    "cluster_metadata" : {
      "id" : "471e7fbe-1e55-4a5f-90a5-f0b9a4badf30",
      "status" : "RUNNING",
      "reason" : null,
      "project_id" : "2d29ce239ba24d759bb37e624b0a6e06",
      "created_at" : "2026-04-28 11:30:34",
      "updated_at" : "2026-04-28 11:30:34",
      "k8s_name" : null,
      "available_node_count" : null
    },
    "cluster_specification" : {
      "name" : "test-cluster-mzm-24",
      "description" : "test-description",
      "charge_mode" : "0",
      "k8s_cluster_specification" : {
        "k8s_cluster_id" : "c51900cc-c9fa-11f0-88fb-0255ac100b0a",
        "namespace" : "ems-471e7fbe-1e55-4a5f-90a5-f0b9a4badf30",
        "label" : {
          "key" : "ems",
          "value" : "true"
        },
        "node_count" : null,
        "flavor" : "xms.storage.pro.nodeCount",
        "version" : "v3.0",
        "lts_enable" : true,
        "lts_connect_type" : "0",
        "monitor_enable" : true,
        "node_type" : "0"
      },
      "memory_specification" : {
        "huge_page_num" : 1536,
        "huge_page_flavor" : 2
      }
    }
  } ]
}

状态码：400

参数解释

错误响应体。

取值范围

不涉及。

{
  "error_code" : "EMS.00004000",
  "error_msg" : "invalid parameter"
}

状态码

状态码

描述

200

参数解释

查询集群列表成功返回响应体。

取值范围

不涉及。

400

参数解释

错误响应体。

取值范围

不涉及。

错误码

请参见错误码。

父主题： 生命周期管理

相关文档