DescribeClustersForRegion-阿里云帮助中心

Lists all clusters in a specified 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 ID of the region.	cn-hangzhou

Request parameters

Parameter	Type	Required	Description	Example
name	string	No	The name of the cluster. 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 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. Valid values: ExternalKubernetes : ExternalKubernetes ManagedKubernetes : ManagedKubernetes Kubernetes : Kubernetes	Kubernetes
page_size	integer	No	The number of entries per page.	3
page_number	integer	No	The page number.	10
profile	string	No	The subtype of the cluster. Valid values: Default: an ACK managed cluster. This includes the Pro and Basic editions. Edge: an ACK Edge cluster. This includes the Pro and Basic editions. Serverless: an ACK Serverless cluster. This includes the 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 support to add this specification to the allowlist.) Pro XL, Pro 2XL, and Pro 4XL are three tiers of the ACK Pro provisioned control plane. These tiers ensure a consistently high level of API concurrency and pod scheduling capabilities by pre-allocating and dedicating control plane resources. They are suitable for AI training and inference, large-scale clusters, and mission-critical services. For information about the cluster management fee for the Pro edition and provisioned control plane editions, 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 cluster details.
	object	The details of a cluster.
cluster_id	string	The cluster ID.	c905d1364c2dd4b6284a3f41790c4****
cluster_type	string	The type of the cluster. Valid values: Kubernetes: ACK dedicated cluster. ManagedKubernetes: ACK managed clusters, including the default 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.	ManagedKubernetes
created	string	The time the cluster was created.	2020-12-01T20:40:40+08:00
init_version	string	The initial version of the cluster.	1.16.6-aliyun.1
current_version	string	The current version of the cluster.	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	Specifies whether deletion protection is enabled. If this parameter is set to true, the cluster cannot be deleted in the console or by an API call. 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: ACK managed clusters, which include the Pro and Basic editions. Edge: ACK Edge clusters, which include the Pro and Basic editions. Serverless: ACK Serverless clusters, which include the Pro and Basic editions. LingJun: ACK Lingjun clusters, which are available only in the 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 network CIDR block.	172.20.0.0/16
service_cidr	string	The service CIDR block.	172.21.0.0/20
proxy_mode	string	The kube-proxy mode for the cluster. 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 cluster domain.	cluster.local
size	integer	The number of nodes in the cluster.	2
state	string	The lifecycle 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`: The 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 waiting for connection. `disconnected`: The cluster is disconnected.	running
tags	array	A list of cluster tags.
	tag	A cluster tag.
updated	string	The time the cluster was last updated.	2020-12-08T15:37:00+08:00
vpc_id	string	The ID of the VPC where the cluster is deployed.	vpc-2zeg8nf1ukc0fcmvq****
vswitch_ids	array	A list of vSwitch IDs for the cluster control plane.
	string	The vSwitch ID for the control plane.	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 (This specification is available only to allowlisted users. To use it, contact customer service.) Pro XL, Pro 2XL, and Pro 4XL are three specifications available for the ACK Pro provisioned control plane. These specifications pre-allocate and dedicate control plane resources to ensure high API concurrency and Pod scheduling capabilities. They are suitable for AI training and inference, large-scale clusters, and mission-critical services. For information about the cluster management fees for the Pro edition and provisioned control plane editions, 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.