DescribeClustersV1 - 查询集群列表 - 容器服务 Kubernetes 版 ACK

您可以调用DescribeClustersV1接口查看本账号下符合条件的ACK集群（例如指定集群类型、集群规格）列表信息。

调试

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

授权信息

当前API暂无授权信息透出。

请求语法

GET /api/v1/clusters HTTP/1.1

请求参数

名称	类型	必填	描述	示例值
name	string	否	集群名称。命名规则：由数字、汉字、英文字符或短划线（-）组成，长度范围 1~63 个字符，且不能以短划线（-）开头。	cluster-demo
cluster_type	string	否	`Kubernetes`: ACK 专有集群。 `ManagedKubernetes`：ACK 托管类的集群，包括 ACK 托管集群（ACK 集群 Pro 版、ACK 集群基础版）、ACK Serverless 集群（Pro 版、基础版）、ACK Edge 集群（Pro 版、基础版）、ACK 灵骏集群（Pro 版）。 `ExternalKubernetes`：注册集群。	Kubernetes
page_size	long	否	每页显示的记录数。	10
page_number	long	否	当前页码。	3
profile	string	否	当您选择`cluster_type`为`ManagedKubernetes`时，即 ACK 托管类的集群时，您可以进一步指定集群的子类型。 `Default`：ACK 托管集群，包括 ACK 集群 Pro 版和 ACK 集群基础版。 `Edge`：ACK Edge 集群，包括 ACK Edge 集群 Pro 版和 ACK Edge 集群基础版。 `Serverless`：ACK Serverless 集群，包括 ACK Serverless 集群 Pro 版和 ACK Serverless 集群基础版。 `Lingjun`：ACK 灵骏集群，提供 Pro 版。	Default
cluster_spec	string	否	当您选择`cluster_type`为`ManagedKubernetes`并配置`profile`后，您可以进一步指定集群的规格。 `ack.pro.small`：集群 Pro 版。 `ack.standard`：集群基础版（取值为空时默认选择）。	ack.pro.small
region_id	string	否	集群地域。通过指定该字段，可以过滤出该地域下的集群列表。	cn-hangzhou
cluster_id	string	否	集群 ID。	c3fb96524f9274b4495df0f12a6b5****

返回参数

名称	类型	描述	示例值
	object	返回体数据。
clusters	array<object>	集群信息列表。
clusters	object	集群实例。
cluster_id	string	集群 ID。	c3fb96524f9274b4495df0f12a6b5****
cluster_type	string	`Kubernetes`: ACK 专有集群。 `ManagedKubernetes`：ACK 托管类的集群，包括 ACK 托管集群（ACK 集群 Pro 版、ACK 集群基础版）、ACK Serverless 集群（Pro 版、基础版）、ACK Edge 集群（Pro 版、基础版）、ACK 灵骏集群（Pro 版）。 `ExternalKubernetes`：注册集群。	Kubernetes
created	string	集群创建时间。	2020-08-20T10:51:29+08:00
init_version	string	集群版本，与 Kubernetes 社区基线版本保持一致。建议选择最新版本，若不指定，默认使用最新版本。目前 ACK 控制台提供两种最新 Kubernetes 版本的集群。您可以通过 API 创建其他 Kubernetes 版本集群。ACK 支持的 Kubernetes 版本，请参见 Kubernetes 版本发布概览。	1.16.9-aliyun.1
current_version	string	集群当前版本。	1.16.9-aliyun.1
next_version	string	集群可升级版本。	1.18.8-aliyun.1
deletion_protection	boolean	集群删除保护，防止通过控制台或 API 误删除集群。取值： `true`：启用集群删除保护，将不能通过控制台或 API 删除集群。 `false`：不启用集群删除保护，则能通过控制台或 API 删除集群。	true
docker_version	string	集群 Docker 版本。	19.03.5
external_loadbalancer_id	string	集群中 Ingress SLB 实例。默认实例规格：性能保障型（slb.s1.small）。	lb-2vcrbmlevo6kjpgch****
master_url	string	集群 API Server 访问地址，包含内网访问地址以及公网访问地址。	{\"api_server_endpoint\":\"\",\"intranet_api_server_endpoint\":\"https://192.168.0.251:6443\"}
meta_data	string	集群元数据信息。	{\"Addons\":[{\"config\":***}
name	string	集群名称。命名规则：由数字、汉字、英文字符或短划线（-）组成，长度范围 1~63 个字符，且不能以短划线（-）开头。	cluster-demo
network_mode	string	集群网络模式。取值： `classic`：经典网络。 `vpc`：专有网络。 `overlay`：叠加网络。 `calico`：Calico 网络。	vpc
private_zone	boolean	集群 Private Zone 配置。取值： `true`：启用 Private Zone。 `false`：不启用 Private Zone。	false
profile	string	集群标识，取值： `Default`：ACK 托管集群，包括 ACK 集群 Pro 版和 ACK 集群基础版。 `Edge`：ACK Edge 集群，包括 ACK Edge 集群 Pro 版和 ACK Edge 集群基础版。 `Serverless`：ACK Serverless 集群，包括 ACK Serverless 集群 Pro 版和 ACK Serverless 集群基础版。 `Lingjun`：ACK 灵骏集群，提供 Pro 版。	Default
region_id	string	集群所在地域 ID。	cn-beijing
resource_group_id	string	集群资源组 ID。	rg-acfmyvw3wjm****
security_group_id	string	集群安全组 ID。	sg-2vcgwsrwgt5mp0yi****
container_cidr	string	Pod 网络网段，Flannel 网络配置。	172.20.0.0/16
service_cidr	string	服务网络网段。	172.21.0.0/20
proxy_mode	string	kube-proxy 代理模式 `iptables`: 成熟稳定的 kube-proxy 代理模式，Kubernetes Service 的服务发现和负载均衡使用 iptables 规则配置，但是性能一般，受规模影响较大，适用于集群存在少量的 Service。 `ipvs`：高性能的 kube-proxy 代理模式，Kubernetes Service 的服务发现和负载均衡使用 Linux IPVS 模块进行配置，适用于集群存在大量的 Service，对负载均衡有高性能要求的场景。	ipvs
timezone	string	时区。	Asia/Shanghai
ip_stack	string	集群的 IP 协议栈，可取值： ipv4：创建仅支持 IPv4 协议栈的集群； dual：创建支持 IPv4/IPv6 双栈的集群。	ipv4
cluster_domain	string	集群本地域名。	cluster.local
size	long	集群当前节点数量，包含 Master 节点以及 Worker 节点。	5
state	string	集群运行状态，取值： `initial`：集群创建中。 `failed`：集群创建失败。 `running`：集群运行中。 `updating`：集群升级中。 `updating_failed`：集群升级失败。 `scaling`：集群伸缩中。 `stopped`：集群已经停止运行。 `deleting`：集群删除中。 `deleted`：集群已经被删除。 `delete_failed`：集群删除失败。	running
subnet_cidr`deprecated`	string	【该字段已废弃】请使用 container_cidr 获取 Pod 网络网段。 Pod 网络地址段，必须是有效的私有网段，即以下网段及其子网： 10.0.0.0/8 172.16-31.0.0/12-16 192.168.0.0/16 不能与 VPC 及 VPC 内已有 Kubernetes 集群使用的网段重复，创建成功后不能修改。关于集群网络规划，请参见VPC 下 Kubernetes 的网络地址段规划。	172.21.0.0/16
tags	array	集群资源标签。
tags	tag	集群资源标签。
updated	string	集群更新时间。	2020-09-16T11:09:55+08:00
vpc_id	string	集群专有网络 ID，创建集群时必传。	vpc-2vcg932hsxsxuqbgl****
vswitch_id`deprecated`	string	虚拟交换机 ID，创建集群时可选择 1~3 个虚拟交换机。为保证集群高可用，建议选择不同可用区的虚拟交换机。	vsw-2vc41xuumx5z2rdma**,vsw-2vc41xuumx5z2rdma**
vswitch_ids	array	集群控制面虚拟交换机。
控制面交换机	string	集群控制面虚拟交换机。	vsw-2vc41xuumx5z2rdma****
worker_ram_role_name	string	Worker RAM 角色名称，授权 ECS 实例为集群 Woker 节点。	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
zone_id	string	集群所属可用区 ID。	cn-beijing-b
cluster_spec	string	当您选择`cluster_type`为`ManagedKubernetes`并配置`profile`后，您可以进一步指定集群的规格。 `ack.pro.small`：集群 Pro 版。 `ack.standard`：集群基础版（取值为空时默认选择）。	ack.standard
maintenance_window	maintenance_window	集群维护窗口，该功能只在 ACK 托管集群和 ACK Serverless 集群中生效。
operation_policy	object	集群自动运维策略。
cluster_auto_upgrade	object	集群自动升级。
enabled	boolean	是否开启集群自动升级。	true
channel	string	集群自动升级频次。更多信息，请参见升级频次。取值： patch：最新补丁版本。 stable：次新次要版本。 rapid：最新次要版本。	patch
page_info	object	分页信息。
page_number	integer	分页数。	3
page_size	integer	单页大小。	20
total_count	integer	结果总数。	50

示例

正常返回示例

JSON格式

{
  "clusters": [
    {
      "cluster_id": "c3fb96524f9274b4495df0f12a6b5****",
      "cluster_type": "Kubernetes",
      "created": "2020-08-20T10:51:29+08:00",
      "init_version": "1.16.9-aliyun.1",
      "current_version": "1.16.9-aliyun.1",
      "next_version": "1.18.8-aliyun.1",
      "deletion_protection": true,
      "docker_version": "19.03.5",
      "external_loadbalancer_id": "lb-2vcrbmlevo6kjpgch****",
      "master_url": "{\\\"api_server_endpoint\\\":\\\"\\\",\\\"intranet_api_server_endpoint\\\":\\\"https://192.168.0.251:6443\\\"}",
      "meta_data": "{\\\"Addons\\\":[{\\\"config\\\":***}",
      "name": "cluster-demo",
      "network_mode": "vpc",
      "private_zone": false,
      "profile": "Default",
      "region_id": "cn-beijing",
      "resource_group_id": "rg-acfmyvw3wjm****",
      "security_group_id": "sg-2vcgwsrwgt5mp0yi****",
      "container_cidr": "172.20.0.0/16",
      "service_cidr": "172.21.0.0/20",
      "proxy_mode": "ipvs",
      "timezone": "Asia/Shanghai",
      "ip_stack": "ipv4",
      "cluster_domain": "cluster.local",
      "size": 5,
      "state": "running",
      "subnet_cidr": "172.21.0.0/16",
      "tags": [
        {
          "key": "env",
          "value": "prod"
        }
      ],
      "updated": "2020-09-16T11:09:55+08:00",
      "vpc_id": "vpc-2vcg932hsxsxuqbgl****",
      "vswitch_id": "vsw-2vc41xuumx5z2rdma****,vsw-2vc41xuumx5z2rdma****",
      "vswitch_ids": [
        "vsw-2vc41xuumx5z2rdma****"
      ],
      "worker_ram_role_name": "KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****",
      "zone_id": "cn-beijing-b",
      "cluster_spec": "ack.standard",
      "maintenance_window": {
        "enable": false,
        "maintenance_time": "2020-10-15T12:31:00.000+08:00",
        "duration": "3h",
        "weekly_period": "Monday,Thursday",
        "recurrence": "FREQ=WEEKLY;INTERVAL=4;BYDAY=MO,TU"
      },
      "operation_policy": {
        "cluster_auto_upgrade": {
          "enabled": true,
          "channel": "patch"
        }
      }
    }
  ],
  "page_info": {
    "page_number": 3,
    "page_size": 20,
    "total_count": 50
  }
}

错误码

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

变更历史

变更时间	变更内容概要	操作
2024-10-18	OpenAPI 返回结构发生变更	查看变更详情
2024-10-15	OpenAPI 返回结构发生变更	查看变更详情
2023-11-24	OpenAPI 入参发生变更	查看变更详情
2020-09-14	OpenAPI 入参发生变更	查看变更详情