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

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 region ID.	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 Standard Editions), ACK Serverless clusters (Pro and Standard Editions), ACK Edge clusters (Pro and Standard 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 to return on each page.	3
page_number	integer	No	The page number to return.	10
profile	string	No	The subtype of the cluster. Valid values: `Default`: ACK managed clusters, including Pro and Standard Editions. `Edge`: ACK Edge clusters, including Pro and Standard Editions. `Serverless`: ACK Serverless clusters, including Pro and Standard Editions. `LingJun`: ACK Lingjun clusters, available in the 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`: Standard 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 submit a ticket.) Pro XL, Pro 2XL, and Pro 4XL are three specifications available for the ACK Pro provisioned control plane. These specifications ensure a high and deterministic 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 workloads. For information about the cluster management fees for Pro Edition and provisioned control plane clusters, see cluster management fee. Valid values: ack.pro.small : ack.pro.small ack.standard : ack.standard	ack.standard
cluster_id	string	No	The ID of the cluster.	c8155823d057948c69a****

Response elements

Element	Type	Description	Example
	object	The returned data.
clusters	array<object>	A list of clusters.
	object	The details of a cluster.
cluster_id	string	The cluster ID.	c905d1364c2dd4b6284a3f41790c4****
cluster_type	string	The type of the cluster. Valid values: `Kubernetes`: an ACK dedicated cluster. `ManagedKubernetes`: an ACK managed cluster. This type 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.	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 available upgrade version.	1.18.8-aliyun.1
deletion_protection	boolean	Specifies whether deletion protection is enabled for the cluster. If enabled, you cannot delete the cluster from 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 subtype of the cluster. Valid values: `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
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 security group ID of the cluster.	sg-2zeihch86ooz9io4****
container_cidr	string	The CIDR block for Pods in the cluster.	172.20.0.0/16
service_cidr	string	The CIDR block for the service network.	172.21.0.0/20
proxy_mode	string	The kube-proxy proxy mode of the cluster. Valid values: iptables : The iptables proxy mode. ipvs : The IP Virtual Server (IPVS) proxy mode.	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 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`: Node draining is in progress. `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 is deleted. `delete_failed`: Cluster deletion failed. `waiting`: The cluster is waiting for a connection. `disconnected`: The cluster is disconnected.	running
tags	array	The tags attached to the cluster.
	tag	A tag attached to the cluster.
updated	string	The time the cluster was last updated.	2020-12-08T15:37:00+08:00
vpc_id	string	The VPC ID of the cluster.	vpc-2zeg8nf1ukc0fcmvq****
vswitch_ids	array	The IDs of the vSwitches for the control plane.
	string	The ID of a vSwitch for the control plane.	vsw-2vc41xuumx5z2rdma****
cluster_spec	string	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. This specification is available only to allowlisted users. Pro XL, Pro 2XL, and Pro 4XL are three specifications available for the ACK Pro provisioned control plane. These specifications ensure a high and deterministic 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 workloads. For information about the cluster management fee for Pro Edition and ACK Pro provisioned control plane specifications, see the linked topic.	ack.standard
page_info	object	The pagination information.
page_number	integer	The returned page number.	1
page_size	integer	The number of entries per page.	10
total_count	integer	The total number of entries that match the query.	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.