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

Use the DescribeClustersV1 API to list ACK clusters by 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 name of the cluster.	cluster-demo
cluster_type	string	No	The cluster type. `Kubernetes`: an ACK dedicated cluster. `ManagedKubernetes`: an ACK managed cluster. This type includes ACK managed clusters (Pro and Standard), ACK Serverless clusters (Pro and Standard), ACK Edge clusters (Pro and Standard), and ACK Lingjun clusters (Pro). `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	When `cluster_type` is set to `ManagedKubernetes`, you can further specify a sub-type of the cluster. `Default`: an ACK managed cluster. This includes ACK Pro and ACK Standard clusters. `Edge`: an ACK Edge cluster. This includes ACK Edge Pro and ACK Edge Standard clusters. `Serverless`: an ACK Serverless cluster. This includes ACK Serverless Pro and ACK Serverless Standard clusters. `Lingjun`: an ACK Lingjun cluster (Pro edition).	Default
cluster_spec	string	No	The cluster specification. This parameter is valid only when `cluster_type` is set to `ManagedKubernetes` and the `profile` parameter is specified. Valid values: `ack.standard`: Standard `ack.pro.small`: Pro `ack.pro.xlarge`: Pro XL `ack.pro.2xlarge`: Pro 2XL `ack.pro.4xlarge`: Pro 4XL (Contact customer service to enable this option.) Pro XL, Pro 2XL, and Pro 4XL are three tiers provided by the ACK Pro provisioned control plane. These tiers pre-allocate and dedicate control plane resources to ensure a consistently high, predictable level of performance for API concurrency and pod scheduling. 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 ID of the region to which the clusters belong.	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>	A cluster.
cluster_id	string	The cluster ID.	c3fb96524f9274b4495df0f12a6b5****
cluster_type	string	The cluster type.	Kubernetes
created	string	The time when 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 supported by 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. If deletion protection is enabled, you cannot delete the 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 Server Load Balancer (SLB) instance that is used for the Ingress. Default instance specification: slb.s1.small (performance-guaranteed).	lb-2vcrbmlevo6kjpgch****
master_url	string	The endpoints of the API server. The endpoints include an internal endpoint and a public endpoint.	{\"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. 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 applicable to Flannel networks.	172.20.xx.xx/16
service_cidr	string	The CIDR block of Services.	172.21.xx.xx/20
proxy_mode	string	The kube-proxy proxy mode. `iptables`: a stable and mature proxy mode. The service discovery and load balancing of Kubernetes Services are implemented by using iptables rules. This mode offers moderate performance and is suitable for clusters that have a small number of Services. `ipvs`: a high-performance proxy mode. The service discovery and load balancing of Kubernetes Services are implemented by using the Linux IP Virtual Server (IPVS) module. 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`: a dual-stack cluster that supports both IPv4 and IPv6.	ipv4
cluster_domain	string	The domain name of the cluster.	cluster.local
size	integer	The total number of nodes in the cluster. This includes master nodes and worker nodes.	5
state	string	The state 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 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 has been deleted. `delete_failed`: The cluster failed to be deleted. `waiting`: The cluster is awaiting connection. `disconnected`: The cluster is disconnected.	running
subnet_cidr `deprecated`	string	This parameter is deprecated. Use the `container_cidr` parameter to obtain the pod CIDR block.	null
tags	array	The tags of the cluster.
	tag	The tags of the cluster.
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 in which the cluster is deployed.	vpc-2vcg932hsxsxuqbgl****
vswitch_id `deprecated`	string	The ID of the vSwitch to which the cluster belongs.	vsw-2vc41xuumx5z2rdma**,vsw-2vc41xuumx5z2rdma**
vswitch_ids	array	The vSwitches of the cluster control plane.
	string	The vSwitches of the cluster control plane.	vsw-2vc41xuumx5z2rdma****
worker_ram_role_name `deprecated`	string	The name of the worker RAM role. This role is used to authorize Elastic Compute Service (ECS) instances to be used as worker nodes.	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
zone_id `deprecated`	string	The ID of the zone in which the cluster is deployed.	cn-beijing-b
cluster_spec	string	The edition 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 auto O&M policy of the cluster.
cluster_auto_upgrade	object	The cluster auto-upgrade policy.
enabled	boolean	Indicates whether auto-upgrade is enabled for the cluster.	true
channel	string	The upgrade channel. For more information, see Upgrade channels. Valid values: `patch`: Upgrades the cluster to the latest available patch version. `stable`: Upgrades the cluster to the latest stable minor version. This version is typically the second latest minor version. `rapid`: Upgrades the cluster to the latest available 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 that were 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.