Query cluster details with DescribeClustersV1 - Container Service for Kubernetes - Alibaba Cloud - Container Service for Kubernetes

Queries a list of ACK clusters that meet specified conditions, such as cluster type and cluster specification, within the current account.

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`: ACK dedicated cluster. `ManagedKubernetes`: ACK managed cluster types, including ACK managed clusters (Pro and Basic), ACK Serverless clusters (Pro and Basic), ACK Edge clusters (Pro and Basic), and ACK Lingjun clusters (Pro). `ExternalKubernetes`: registered cluster.	Kubernetes
page_size	integer	No	The number of records per page.	10
page_number	integer	No	The current page number.	1
profile	string	No	When you set `cluster_type` to `ManagedKubernetes`, you can further specify the subtype of the cluster. `Default`: ACK managed cluster, including ACK cluster Pro and ACK cluster Basic. `Edge`: ACK Edge cluster, including ACK Edge cluster Pro and ACK Edge cluster Basic. `Serverless`: ACK Serverless cluster, including ACK Serverless cluster Pro and ACK Serverless cluster Basic. `Lingjun`: ACK Lingjun cluster, available in Pro.	Default
cluster_spec	string	No	The cluster specification when `cluster_type` is set to `ManagedKubernetes` and `profile` is configured. Valid values: `ack.standard`: Basic `ack.pro.small`: Pro `ack.pro.xlarge`: Pro XL `ack.pro.2xlarge`: Pro 2XL `ack.pro.4xlarge`: Pro 4XL (contact customer service to be added to the whitelist) Pro XL, Pro 2XL, and Pro 4XL are three tiers provided by ACK Pro Provisioned Control Plane. By pre-allocating and dedicating control plane resources, these tiers ensure that API concurrency and pod scheduling capabilities remain at a consistently high level. They are suitable for AI training and inference, ultra-large-scale clusters, and mission-critical workloads. For information about the cluster management fees for Pro and provisioned control plane editions, see Cluster management fee.	ack.pro.small
region_id	string	No	The region of the cluster. Specify this parameter to filter the cluster list by region.	cn-hangzhou
cluster_id	string	No	The cluster ID.	c3fb96524f9274b4495df0f12a6b5****

Response elements

Element	Type	Description	Example
	object	The response body.
clusters	array<object>	The list of cluster information.
	array<object>	The cluster instance.
cluster_domain	string	The local domain name of the cluster.	cluster.local
cluster_id	string	The cluster ID.	c3fb96524f9274b4495df0f12a6b5****
cluster_spec	string	The cluster specification.	ack.standard
cluster_type	string	The cluster type.	Kubernetes
container_cidr	string	The CIDR block of pods. This is the Flannel network configuration.	172.20.xx.xx/16
created	string	The time when the cluster was created.	2025-04-07T09:57:26+08:00
current_version	string	The current version of the cluster.	1.32.1-aliyun.1
deletion_protection	boolean	Indicates whether deletion protection is enabled for the cluster. Deletion protection prevents the cluster from being accidentally deleted in the console or by calling API operations. Valid values: `true`: Deletion protection is enabled. The cluster cannot be deleted in the console or by calling API operations. `false`: Deletion protection is not enabled. The cluster can be deleted in the console or by calling API operations.	true
docker_version `deprecated`	string	The Docker version used by the cluster.	19.03.5
external_loadbalancer_id `deprecated`	string	The SLB instance associated with the Ingress of the cluster. Default instance type: guaranteed-performance instance (slb.s1.small).	lb-2vcrbmlevo6kjpgch****
init_version	string	The initial version of the cluster. For more information about the Kubernetes versions supported by ACK, see Kubernetes version release overview.	1.32.1-aliyun.1
ip_stack	string	The IP protocol stack of the cluster. Valid values: ipv4: creates a cluster that supports only the IPv4 protocol stack. dual: creates a cluster that supports the IPv4/IPv6 dual stack.	ipv4
maintenance_window	maintenance_window	The maintenance window of the cluster. This feature takes effect only for ACK managed clusters and ACK Serverless clusters.
master_url	string	The access addresses of the cluster API server, including the internal network access address and the public network access address.	{\"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 cluster name.	cluster-demo
network_mode `deprecated`	string	The network mode of the cluster. Valid values: `classic`: classic network. `vpc`: virtual private cloud (VPC). `overlay`: overlay network. `calico`: Calico network.	vpc
next_version	string	The version to which the cluster can be upgraded.	1.xx.x-aliyun.1
operation_policy	object	The automatic O&M policy of the cluster.
cluster_auto_upgrade	object	The cluster auto-upgrade configuration.
channel	string	The auto-upgrade frequency of the cluster. For more information, see Upgrade frequency. Valid values: patch: the latest patch version. stable: the second latest minor version. rapid: the latest minor version.	patch
enabled	boolean	Indicates whether cluster auto-upgrade is enabled.	true
private_zone `deprecated`	boolean	The Private Zone configuration of the cluster. Valid values: `true`: Private Zone is enabled. `false`: Private Zone is not enabled.	false
profile	string	The subtype of the cluster.	Default
proxy_mode	string	The kube-proxy mode. Valid values: `iptables`: a mature and stable kube-proxy mode. Service discovery and load balancing for Kubernetes Services are configured by using iptables rules. The performance is average and is affected by the cluster scale. This mode is suitable for clusters that contain a small number of Services. `ipvs`: a high-performance kube-proxy mode. Service discovery and load balancing for Kubernetes Services are configured by using the Linux IPVS module. This mode is suitable for clusters that contain a large number of Services and require high-performance load balancing.	ipvs
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 associated with the cluster.	sg-2vcgwsrwgt5mp0yi****
service_cidr	string	The CIDR block of Services.	172.21.xx.xx/20
size	integer	The current number of nodes in the cluster, including master nodes and worker nodes.	5
state	string	The running status of the cluster. Valid values: `initial`: The cluster is being created. `failed`: The cluster failed to be created. `running`: The cluster is running. `updating`: The cluster is being updated. `upgrading`: The cluster is being upgraded. `removing`: Nodes are being removed. `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`: The cluster failed to be deleted. `waiting`: The cluster is in the accessed state, waiting to be connected. `disconnected`: The cluster is disconnected.	running
subnet_cidr `deprecated`	string	[Deprecated] Use container_cidr to obtain the Pod CIDR block.	null
tags	array	The resource tags of the cluster.
	tag	The resource tags of the cluster.
timezone	string	The time zone.	Asia/Shanghai
updated	string	The time when the cluster was last updated.	2025-04-07T09:57:26+08:00
vpc_id	string	The ID of the VPC associated with the cluster.	vpc-2vcg932hsxsxuqbgl****
vswitch_id `deprecated`	string	The vSwitch ID of the cluster.	vsw-2vc41xuumx5z2rdma**,vsw-2vc41xuumx5z2rdma**
vswitch_ids	array	The vSwitches for the cluster control plane.
	string	The vSwitches for the cluster control plane.	vsw-2vc41xuumx5z2rdma****
worker_ram_role_name `deprecated`	string	The name of the Worker RAM role that authorizes ECS instances to serve as cluster worker nodes.	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
zone_id `deprecated`	string	The zone ID of the cluster.	cn-beijing-b
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 results.	50

Examples

Success response

JSON format

{
  "clusters": [
    {
      "cluster_domain": "cluster.local",
      "cluster_id": "c3fb96524f9274b4495df0f12a6b5****",
      "cluster_spec": "ack.standard",
      "cluster_type": "Kubernetes",
      "container_cidr": "172.20.xx.xx/16",
      "created": "2025-04-07T09:57:26+08:00",
      "current_version": "1.32.1-aliyun.1",
      "deletion_protection": true,
      "docker_version": "19.03.5",
      "external_loadbalancer_id": "lb-2vcrbmlevo6kjpgch****",
      "init_version": "1.32.1-aliyun.1",
      "ip_stack": "ipv4",
      "maintenance_window": {
        "duration": "3h",
        "enable": false,
        "exclusions": [
          {
            "description": "All changes are prohibited during the freeze period",
            "end_time": "2026-11-15T00:00:00+08:00",
            "scope": "NoOperations",
            "start_time": "2026-11-01T00:00:00+08:00"
          }
        ],
        "maintenance_time": "2020-10-15T12:31:00.000+08:00",
        "recurrence": "FREQ=WEEKLY;INTERVAL=4;BYDAY=MO,TU",
        "weekly_period": "Monday,Thursday"
      },
      "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",
      "next_version": "1.xx.x-aliyun.1",
      "operation_policy": {
        "cluster_auto_upgrade": {
          "channel": "patch",
          "enabled": true
        }
      },
      "private_zone": false,
      "profile": "Default",
      "proxy_mode": "ipvs",
      "region_id": "cn-beijing",
      "resource_group_id": "rg-acfmyvw3wjm****",
      "security_group_id": "sg-2vcgwsrwgt5mp0yi****",
      "service_cidr": "172.21.xx.xx/20",
      "size": 5,
      "state": "running",
      "subnet_cidr": "null",
      "tags": [
        {
          "key": "env",
          "value": "prod"
        }
      ],
      "timezone": "Asia/Shanghai",
      "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"
    }
  ],
  "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.