DescribeClustersForRegion API Reference for ACK - Container Service for Kubernetes - Alibaba Cloud - Container Service for Kubernetes

Lists all clusters in a region.

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:DescribeClustersForRegion

list

*All Resource

*

None

Request syntax

GET /regions/{region_id}/clusters HTTP/1.1

Path Parameters

Parameter	Type	Required	Description	Example
region_id	string	Yes	The region ID.	cn-hangzhou

Request parameters

Parameter	Type	Required	Description	Example
name	string	No	The cluster name. Fuzzy search is supported.	test-cluster
cluster_type	string	No	The type of the cluster. Valid values: `Kubernetes`: an ACK dedicated cluster. `ManagedKubernetes`: an ACK managed cluster. This type includes standard ACK managed clusters (ACK Cluster Pro Edition and ACK Cluster Basic Edition), ACK Serverless Clusters (Pro and Basic editions), ACK Edge Clusters (Pro and Basic editions), and ACK Lingjun Clusters (Pro Edition). `ExternalKubernetes`: a registered cluster. Valid values: ExternalKubernetes : ExternalKubernetes ManagedKubernetes : ManagedKubernetes Kubernetes : Kubernetes	Kubernetes
page_size	integer	No	The number of items to return per page.	3
page_number	integer	No	The page number.	10
profile	string	No	The subtype of the cluster. This parameter is used to filter ACK managed clusters. Valid values: `Default`: a standard ACK managed cluster, including ACK Cluster Pro Edition and ACK Cluster Basic Edition. `Edge`: an ACK Edge Cluster, including Pro and Basic editions. `Serverless`: an ACK Serverless Cluster, including Pro and Basic editions. `LingJun`: an ACK Lingjun Cluster (Pro Edition). Valid values: LingJun : LingJun Serverless : Serverless Default : Default Edge : Edge	Serverless
cluster_spec	string	No	The specification of the cluster. 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 have your account added to the allowlist.) These specifications pre-allocate and dedicate control plane resources to guarantee deterministic, high-level performance for API concurrency and pod scheduling. They are ideal for AI training and inference, ultra-large-scale clusters, and mission-critical services. For information about the cluster management fee for Pro Edition clusters and those with a provisioned control plane, see Cluster management fee. Valid values: ack.pro.small : ack.pro.small ack.standard : ack.standard	ack.standard
cluster_id	string	No	The cluster ID.	c8155823d057948c69a****

Response elements

Element	Type	Description	Example
	object	The response body.
clusters	array<object>	A list of clusters.
	object	A cluster.
cluster_id	string	The cluster ID.	c905d1364c2dd4b6284a3f41790c4****
cluster_type	string	The cluster type. Valid values: `Kubernetes`: An ACK dedicated cluster. `ManagedKubernetes`: An ACK managed cluster. This includes ACK Pro, ACK Basic, ACK Serverless (Pro and Basic), ACK Edge (Pro and Basic), and ACK Lingjun (Pro) clusters. `ExternalKubernetes`: A registered cluster.	ManagedKubernetes
created	string	The time when the cluster was created.	2020-12-01T20:40:40+08:00
init_version	string	The initial cluster version.	1.16.6-aliyun.1
current_version	string	The current cluster version.	1.16.6-aliyun.1
next_version	string	The version to which the cluster can be upgraded.	1.18.8-aliyun.1
deletion_protection	boolean	Indicates whether deletion protection is enabled. When enabled, the cluster is protected from accidental deletion via the console or API calls. Valid values: `true`: Deletion protection is enabled. `false`: Deletion protection is disabled.	false
name	string	The cluster name.	test-cluster
profile	string	The cluster subtype. Valid values: `Default`: An ACK managed cluster, available in Pro and Basic editions. `Edge`: An ACK Edge cluster, available in Pro and Basic editions. `Serverless`: An ACK Serverless cluster, available in Pro and Basic editions. `LingJun`: An ACK Lingjun cluster, available in Pro edition.	Default
region_id	string	The region ID.	cn-beijing-a
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-2zeihch86ooz9io4****
container_cidr	string	The Pod CIDR block.	172.20.0.0/16
service_cidr	string	The service CIDR block.	172.21.0.0/20
proxy_mode	string	The proxy mode for kube-proxy. Valid values: iptables : iptables ipvs : ipvs	ipvs
timezone	string	The time zone of the cluster.	Asia/Shanghai
ip_stack	string	The IP stack of the cluster.	ipv4
cluster_domain	string	The domain name of the cluster.	cluster.local
size	integer	The number of nodes in the cluster.	2
state	string	The status of the cluster. Valid values: `initial`: The cluster is initializing. `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`: Applies only to registered clusters. The cluster is waiting to establish a connection. `disconnected`: Applies only to registered clusters. The cluster is disconnected.	running
tags	array	The tags of the cluster.
	tag	A tag.
updated	string	The time when the cluster was last updated.	2020-12-08T15:37:00+08:00
vpc_id	string	The ID of the VPC to which the cluster belongs.	vpc-2zeg8nf1ukc0fcmvq****
vswitch_ids	array	A list of vSwitches.
	string	A vSwitch.	vsw-2vc41xuumx5z2rdma****
cluster_spec	string	The cluster specification. 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 support to add your account to the allowlist.) For more information, see ACK Pro with a provisioned control plane. For the management fees of Pro Edition and provisioned control plane clusters, see Cluster management fee.	ack.standard
page_info	object	The pagination information.
page_number	integer	The page number.	1
page_size	integer	The number of entries per page.	10
total_count	integer	The total number of entries.	10

Examples

Success response

JSON format

{
  "clusters": [
    {
      "cluster_id": "c905d1364c2dd4b6284a3f41790c4****",
      "cluster_type": "ManagedKubernetes",
      "created": "2020-12-01T20:40:40+08:00",
      "init_version": "1.16.6-aliyun.1",
      "current_version": "1.16.6-aliyun.1",
      "next_version": "1.18.8-aliyun.1",
      "deletion_protection": false,
      "name": "test-cluster",
      "profile": "Default",
      "region_id": "cn-beijing-a",
      "resource_group_id": "rg-acfmyvw3wjm****",
      "security_group_id": "sg-2zeihch86ooz9io4****",
      "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": 2,
      "state": "running",
      "tags": [
        {
          "key": "env",
          "value": "prod"
        }
      ],
      "updated": "2020-12-08T15:37:00+08:00",
      "vpc_id": "vpc-2zeg8nf1ukc0fcmvq****",
      "vswitch_ids": [
        "vsw-2vc41xuumx5z2rdma****"
      ],
      "cluster_spec": "ack.standard"
    }
  ],
  "page_info": {
    "page_number": 1,
    "page_size": 10,
    "total_count": 10
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.