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

The DescribeClustersV1 API lists ACK clusters in your account that match specific 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 general type covers several subtypes, such as ACK Serverless and ACK Edge clusters. Use the `profile` parameter to specify a subtype. `ExternalKubernetes`: A registered cluster.	Kubernetes
page_size	integer	No	The number of entries to return per page.	10
page_number	integer	No	The page number.	1
profile	string	No	Specifies the subtype of an ACK managed cluster. This parameter is used only when `cluster_type` is set to `ManagedKubernetes`. `Default`: An ACK managed cluster (Pro and Basic Editions). `Edge`: An ACK Edge cluster (Pro and Basic Editions). `Serverless`: An ACK Serverless cluster (Pro and Basic Editions). `Lingjun`: An ACK Lingjun cluster (Pro Edition).	Default
cluster_spec	string	No	The cluster edition. This parameter applies only when `cluster_type` is set to `ManagedKubernetes` and `profile` is also 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. To use this specification, you must be on the allowlist. To apply, contact customer service. Pro XL, Pro 2XL, and Pro 4XL are three tiers available for the ACK Pro provisioned control plane. This feature provides a dedicated control plane to ensure consistent high performance for API concurrency and pod scheduling. Ideal for AI training and inference, ultra-large-scale clusters, and mission-critical applications. For information about the cluster management fees for Pro Edition and provisioned control plane clusters, see Cluster management fee.	ack.pro.small
region_id	string	No	The cluster's region ID. Use this to filter results by a specific region.	cn-hangzhou
cluster_id	string	No	The cluster ID.	c3fb96524f9274b4495df0f12a6b5****

Response elements

Element	Type	Description	Example
	object	The response body.
clusters	array<object>	A list of clusters.
	array<object>	The 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 version of the cluster. For information about the Kubernetes versions that are supported by Container Service for Kubernetes (ACK), see Kubernetes release overview.	1.32.1-aliyun.1
current_version	string	The current version of the cluster.	1.32.1-aliyun.1
next_version	string	The version to which the cluster can be upgraded.	1.xx.x-aliyun.1
deletion_protection	boolean	Indicates whether deletion protection is enabled for the cluster. This feature prevents you from accidentally deleting the cluster by using the console or calling an API. Valid values: `true`: Deletion protection is enabled. The cluster cannot be deleted through the console or by an API call. `false`: Deletion protection is disabled. The cluster can be deleted through the console or by an API call.	true
docker_version `deprecated`	string	The Docker version of the cluster.	19.03.5
external_loadbalancer_id `deprecated`	string	The ID of the Ingress Server Load Balancer (SLB) instance in the cluster. The default instance type is slb.s1.small (performance-guaranteed).	lb-2vcrbmlevo6kjpgch****
master_url	string	The API server endpoints of the cluster, which include 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`: the classic network. `vpc`: a VPC network. `overlay`: an overlay network. `calico`: a Calico network.	vpc
private_zone `deprecated`	boolean	Indicates whether PrivateZone is enabled. 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 where 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 CIDR block of pods. This parameter is returned only if the cluster uses the Flannel network plug-in.	172.20.xx.xx/16
service_cidr	string	The CIDR block for services.	172.21.xx.xx/20
proxy_mode	string	The proxy mode of kube-proxy. `iptables`: a stable and mature proxy mode. It uses iptables rules for service discovery and load balancing. This mode offers moderate performance that is affected by the cluster size. It is suitable for clusters with a small number of services. `ipvs`: a high-performance proxy mode. It uses the Linux IPVS module for service discovery and load balancing. This mode is suitable for clusters that have 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`: an IPv4-only cluster. dual: Creates an IPv4/IPv6 dual-stack cluster.	ipv4
cluster_domain	string	The domain name of the cluster.	cluster.local
size	integer	The total number of nodes in the cluster, including both master and worker nodes.	5
state	string	The state of the cluster. Valid values: `initial`: The cluster is being created. `failed`: 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 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 has been deleted. `delete_failed`: Cluster deletion failed. `waiting`: The cluster is waiting to be connected. `disconnected`: The cluster is disconnected.	running
subnet_cidr `deprecated`	string	Deprecated. Use `container_cidr` instead.	null
tags	array	The tags attached to the cluster.
	tag	A tag attached to the cluster.
updated	string	The time the cluster was last updated.	2025-04-07T09:57:26+08:00
vpc_id	string	The ID of the VPC where 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 control plane VSwitches.
	string	The ID of a control plane VSwitch.	vsw-2vc41xuumx5z2rdma****
worker_ram_role_name `deprecated`	string	The name of the worker RAM role. This role grants permissions to the Elastic Compute Service (ECS) instances that serve as worker nodes in the cluster.	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
zone_id `deprecated`	string	The ID of the zone where 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 for ACK managed clusters and ACK Serverless clusters.
operation_policy	object	The automated O&M policy of the cluster.
cluster_auto_upgrade	object	The settings for automated cluster upgrades.
enabled	boolean	Indicates whether automated cluster upgrades are enabled.	true
channel	string	The channel for automated cluster upgrades. For more information, see Upgrade frequency. Valid values: `patch`: the latest patch version. `stable`: the second-to-latest minor version. rapid: 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 returned 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.