# 查询集群列表 - ListClusters #### 功能介绍 查询集群列表接口。 #### URI GET /v1/clusters 表1Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | limit | 否 | Integer | **参数解释** 返回结果个数限制。 **约束限制** 不涉及。 **取值范围** 值为大于0的整数。 **默认取值** 1000 | | offset | 否 | Integer | **参数解释** 偏移量。分页查询集群时使用，与limit配合使用，从第offset+1条记录开始返回结果。 **约束限制** 不涉及。 **取值范围** 值为大于等于0的整数。 **默认取值** 0 | #### 请求参数 无 #### 响应参数 **状态码：200** 表2响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | clusters | Array of [Cluster] objects | **参数解释** 集群列表信息。 **取值范围** 集群对象数组，最多1000个元素。 | 表3Cluster | 参数 | 参数类型 | 描述 | |:---|:---|:---| | cluster_metadata | [ClusterMetadata] object | **参数解释** 集群基本信息。 **取值范围** 不涉及。 | | cluster_specification | [ClusterSpecification] object | **参数解释** 创建时指定的集群配置信息。 **取值范围** 不涉及。 | 表4ClusterMetadata | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | 表5ClusterSpecification | 参数 | 参数类型 | 描述 | |:---|:---|:---| | name | String | **参数解释** 集群名称。 **取值范围** 以小写字母开头，由字母、数字、中划线(-)组成，长度范围4-128位，且不能以中划线(-)结尾。 | | description | String | **参数解释** 集群描述。 **取值范围** 不涉及。 | | charge_mode | Integer | **参数解释** 付费模式。 **取值范围** 0：按需付费。 | | k8s_cluster_specification | [K8sClusterSpecification] object | **参数解释** 业务k8s集群部署配置。 **取值范围** 不涉及。 | | memory_specification | [MemorySpecification] object | **参数解释** EMS集群内存配置。 **取值范围** 不涉及。 | 表6K8sClusterSpecification | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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信息，仅在查询集群详情响应体中出现。 **约束限制** 不涉及。 **取值范围** 不涉及。 **默认取值** 不涉及。 | 表7K8sLabel | 参数 | 参数类型 | 描述 | |:---|:---|:---| | key | String | **参数解释** 标签的键。 **约束限制** 不涉及。 **取值范围** 以字母或者数字开头和结尾，由字母、数字、连接符(-)、下划线(_)、点号(.)组成，且长度范围不超过63个字符。 **默认取值** ems。 | | value | String | **参数解释** 标签的值。 **约束限制** 不涉及。 **取值范围** 以字母或者数字开头和结尾，由字母、数字、连接符(-)、下划线(_)、点号(.)组成，且长度范围不超过63个字符。 **默认取值** true。 | 表8NodeInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | node_name | String | **参数解释** 主机名称，即为节点的IP地址。 **约束限制** 不涉及。 **取值范围** 不涉及。 **默认取值** 不涉及。 | | pod_list | Array of [PodInfo] objects | **参数解释** 该节点上运行的Pod信息列表。 **约束限制** 不涉及。 **取值范围** 不涉及。 **默认取值** 不涉及。 | 表9PodInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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的资源名称。 **约束限制** 不涉及。 **取值范围** 不涉及。 **默认取值** 不涉及。 | 表10MemorySpecification | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | **参数解释** 错误响应体。 **取值范围** 不涉及。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-ems/ems_04_0031.html)。