Use DescribeClustersV1 to query cluster details - Container Service for Kubernetes - Alibaba Cloud - Container Service for Kubernetes

Call the DescribeClustersV1 API to retrieve a list of ACK clusters in your account based on criteria such as cluster type and cluster specification.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

cs:GetClusters

get

*Cluster

acs:cs:*:{#accountId}:cluster/*

None

Request syntax

GET /api/v1/clusters HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
name	string	No	The cluster name.	cluster-demo
cluster_type	string	No	The cluster type. `Kubernetes`: an ACK dedicated cluster. `ManagedKubernetes`: an ACK managed cluster. This includes ACK managed clusters (Pro and Basic Editions), ACK Serverless clusters (Pro and Basic Editions), ACK Edge clusters (Pro and Basic Editions), and ACK Lingjun clusters (Pro Edition). `ExternalKubernetes`: a registered cluster.	Kubernetes
page_size	integer	No	The number of entries per page.	10
page_number	integer	No	The page number.	1
profile	string	No	The cluster subtype. This parameter applies only when `cluster_type` is set to `ManagedKubernetes`. `Default`: an ACK managed cluster. This includes Pro and Basic Editions. `Edge`: an ACK Edge cluster. This includes Pro and Basic Editions. `Serverless`: an ACK Serverless cluster. This includes Pro and Basic Editions. `Lingjun`: an ACK Lingjun cluster, which is available in Pro Edition.	Default
cluster_spec	string	No	The cluster specification. This parameter applies only when `cluster_type` is set to `ManagedKubernetes` and the `profile` parameter is specified. Valid values: `ack.standard`: Basic Edition `ack.pro.small`: Pro Edition `ack.pro.xlarge`: Pro XL `ack.pro.2xlarge`: Pro 2XL `ack.pro.4xlarge`: Pro 4XL (Contact customer service to add your account to the allowlist.) Pro XL, Pro 2XL, and Pro 4XL are three tiers of the ACK Pro provisioned control plane. These tiers pre-allocate and pin dedicated control plane resources to ensure consistently high performance for API server requests and pod scheduling. They are ideal for AI training and inference, very large clusters, and mission-critical workloads. See cluster management fee for information about costs for Pro Edition clusters and clusters that use a provisioned control plane.	ack.pro.small
region_id	string	No	The cluster region. Use this parameter to filter for clusters in a specific region.	cn-hangzhou
cluster_id	string	No	The cluster ID.	c3fb96524f9274b4495df0f12a6b5****

Response elements

Element	Type	Description	Example
	object	The data returned.
clusters	array<object>	The list of clusters.
	array<object>	The details of a cluster.
cluster_id	string	The ID of the cluster.	c3fb96524f9274b4495df0f12a6b5****
cluster_type	string	The type of the cluster.	Kubernetes
created	string	The time the cluster was created.	2025-04-07T09:57:26+08:00
init_version	string	The initial Kubernetes version of the cluster. For more information about the Kubernetes versions supported by ACK, see Overview of Kubernetes versions.	1.32.1-aliyun.1
current_version	string	The current Kubernetes version of the cluster.	1.32.1-aliyun.1
next_version	string	The version that the cluster can be upgraded to.	1.xx.x-aliyun.1
deletion_protection	boolean	Specifies whether deletion protection is enabled for the cluster. This feature prevents you from accidentally deleting a cluster in the console or by calling an API operation. Valid values: `true`: Deletion protection is enabled. `false`: Deletion protection is disabled.	true
docker_version `deprecated`	string	The Docker version of the cluster.	19.03.5
external_loadbalancer_id `deprecated`	string	The ID of the load balancer instance that is used as the ingress. The default instance type is slb.s1.small (guaranteed-performance).	lb-2vcrbmlevo6kjpgch****
master_url	string	The cluster's API server endpoint, which includes both internal and public endpoints.	{\"api_server_endpoint\":\"\",\"intranet_api_server_endpoint\":\"https://192.168.xx.xx:6443\"}
meta_data	string	The metadata of the cluster.	{\"Addons\":[{\"config\":***}}
name	string	The name of the cluster.	cluster-demo
network_mode `deprecated`	string	The network mode of the cluster. Valid values: `classic`: Classic Network. `vpc`: VPC. `overlay`: Overlay network. `calico`: Calico network.	vpc
private_zone `deprecated`	boolean	Indicates whether PrivateZone is enabled for the cluster. Valid values: `true`: PrivateZone is enabled. `false`: PrivateZone is disabled.	false
profile	string	The subtype of the cluster.	Default
region_id	string	The ID of the region in which the cluster is deployed.	cn-beijing
resource_group_id	string	The ID of the resource group to which the cluster belongs.	rg-acfmyvw3wjm****
security_group_id	string	The ID of the security group to which the cluster belongs.	sg-2vcgwsrwgt5mp0yi****
container_cidr	string	The pod CIDR block. This parameter is used for Flannel network configurations.	172.20.xx.xx/16
service_cidr	string	The service CIDR block.	172.21.xx.xx/20
proxy_mode	string	The proxy mode of kube-proxy. `iptables`: A mature and stable proxy mode for kube-proxy. It uses iptables rules for service discovery and load balancing. The performance is moderate and is affected by the number of services in the cluster. This mode is suitable for clusters that run a small number of services. `ipvs`: A high-performance proxy mode for kube-proxy. It uses the Linux IPVS module for service discovery and load balancing. This mode is suitable for clusters that run a large number of services and require high-performance load balancing.	ipvs
timezone	string	The time zone of the cluster.	Asia/Shanghai
ip_stack	string	The IP stack of the cluster. Valid values: `ipv4`: The cluster uses an IPv4 stack. `dual`: The cluster uses a dual IPv4/IPv6 stack.	ipv4
cluster_domain	string	The domain name of the cluster.	cluster.local
size	integer	The total number of master and worker nodes in the cluster.	5
state	string	The state of the cluster. Valid values: `initial`: The cluster is being created. `failed`: The cluster creation failed. `running`: The cluster is running. `updating`: The cluster is being updated. `upgrading`: The cluster is being upgraded. `removing`: Nodes are being removed from the cluster. `draining`: Nodes in the cluster are being drained. `scaling`: The cluster is being scaled. `inactive`: The cluster is inactive. `unavailable`: The cluster is unavailable. `deleting`: The cluster is being deleted. `deleted`: The cluster is deleted. `delete_failed`: The cluster deletion failed. `waiting`: The cluster is waiting to be connected. `disconnected`: The cluster is disconnected.	running
subnet_cidr `deprecated`	string	Deprecated. Use the container_cidr parameter instead.	null
tags	array	The tags attached to the cluster.
	tag	The details of a tag.
updated	string	The time the cluster was last updated.	2025-04-07T09:57:26+08:00
vpc_id	string	The ID of the VPC in which the cluster is deployed.	vpc-2vcg932hsxsxuqbgl****
vswitch_id `deprecated`	string	The ID of the vSwitch.	vsw-2vc41xuumx5z2rdma**,vsw-2vc41xuumx5z2rdma**
vswitch_ids	array	The IDs of the vSwitches used for the control plane.
	string	The ID of a vSwitch used for the control plane.	vsw-2vc41xuumx5z2rdma****
worker_ram_role_name `deprecated`	string	The name of the worker RAM role that grants permissions to the worker nodes.	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
zone_id `deprecated`	string	The ID of the availability zone in which the cluster is deployed.	cn-beijing-b
cluster_spec	string	The specification of the cluster.	ack.standard
maintenance_window	maintenance_window	The maintenance window of the cluster. This feature is available only in ACK managed clusters and ACK Serverless clusters.
operation_policy	object	The automatic O&M policy of the cluster.
cluster_auto_upgrade	object	The auto-upgrade settings of the cluster.
enabled	boolean	Specifies whether to enable auto-upgrade for the cluster.	true
channel	string	The auto-upgrade channel. For more information, see Upgrade channels. Valid values: `patch`: Upgrades to the latest patch version. `stable`: Upgrades to the second-latest minor version. `rapid`: Upgrades to the latest minor version.	patch
page_info	object	The pagination information.
page_number	integer	The page number.	3
page_size	integer	The number of entries per page.	20
total_count	integer	The total number of entries returned.	50

Examples

Success response

JSON format

{
  "clusters": [
    {
      "cluster_id": "c3fb96524f9274b4495df0f12a6b5****",
      "cluster_type": "Kubernetes",
      "created": "2025-04-07T09:57:26+08:00",
      "init_version": "1.32.1-aliyun.1",
      "current_version": "1.32.1-aliyun.1",
      "next_version": "1.xx.x-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.xx.xx: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.xx.xx/16",
      "service_cidr": "172.21.xx.xx/20",
      "proxy_mode": "ipvs",
      "timezone": "Asia/Shanghai",
      "ip_stack": "ipv4",
      "cluster_domain": "cluster.local",
      "size": 5,
      "state": "running",
      "subnet_cidr": "null",
      "tags": [
        {
          "key": "env",
          "value": "prod"
        }
      ],
      "updated": "2025-04-07T09:57:26+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
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.