Query information about all clusters - API Reference| Alibaba Cloud Documentation Center

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request syntax

GET /api/v1/clusters?name=String&cluster_type=String&page_size=Long&page_number=Long HTTP/1.1 
Content-Type:application/json

Request parameters

Table 1. Request query parameters
Parameter	Type	Required	Example	Description
name	String	No	cluster-demo	The name of the cluster. The name must be 1 to 63 characters in length, and can contain digits, letters, and hyphens (-). It cannot start with a hyphen (-).
cluster_type	String	No	Kubernetes	The type of ACK clusters. Valid values: `Kubernetes`: dedicated Kubernetes cluster `ManagedKubernetes`: managed Kubernetes cluster `Ask`: serverless Kubernetes (ASK) cluster `ExternalKubernetes`: registered external Kubernetes cluster
page_size	Long	No	10	The number of entries to return on each page.
page_number	Long	No	3	The page number of the returned page.

Response syntax

HTTP/1.1 200
Content-Type:application/json
{
  "clusters" : [ {
    "cluster_id" : "String",
    "cluster_type" : "String",
    "created" : "String",
    "init_version" : "String",
    "current_version" : "String",
    "next_version" : "String",
    "deletion_protection" : Boolean,
    "docker_version" : "String",
    "external_loadbalancer_id" : "String",
    "master_url" : "String",
    "meta_data" : "String",
    "name" : "String",
    "network_mode" : "String",
    "private_zone" : Boolean,
    "profile" : "String",
    "region_id" : "String",
    "resource_group_id" : "String",
    "security_group_id" : "String",
    "size" : Long,
    "state" : "String",
    "subnet_cidr" : "String",
    "tags" : [ {
      "key" : "String",
      "value" : "String"
    } ],
    "updated" : "String",
    "vpc_id" : "String",
    "vswitch_id" : "String",
    "worker_ram_role_name" : "String",
    "zone_id" : "String",
    "cluster_spec" : "String",
    "maintenance_window" : {
      "enable" : Boolean,
      "maintenance_time" : "String",
      "duration" : "String",
      "weekly_period" : "String"
    }
  } ],
  "page_info" : {
    "page_number" : Integer,
    "page_size" : Integer,
    "total_count" : Integer
  }
}

Response parameters

Table 2. Response body parameters
Parameter	Type	Example	Description
clusters	Array		The list of the details of the queried cluster.
cluster_id	String	c3fb96524f9274b4495df0f12a6b5****	The ID of the cluster.
cluster_type	String	Kubernetes	The type of ACK clusters. Valid values: `Kubernetes`: dedicated Kubernetes cluster `ManagedKubernetes`: managed Kubernetes cluster `Ask`: ASK cluster `ExternalKubernetes`: registered external Kubernetes cluster
created	String	2020-08-20T10:51:29+08:00	The time when the cluster was created.
init_version	String	1.16.9-aliyun.1	The version of the cluster. The cluster versions provided by ACK are consistent with the open source versions. We recommend that you select the latest version. If you do not specify this parameter, the latest version is used. You can create clusters of the latest two versions in the ACK console. You can create clusters of earlier versions by calling API operations. For more information about the Kubernetes versions supported by ACK, see Release notes for Kubernetes versions.
current_version	String	1.16.9-aliyun.1	The Kubernetes version of the cluster.
next_version	String	1.18.8-aliyun.1	The Kubernetes version to which the cluster can be upgraded.
deletion_protection	Boolean	true	Indicates whether deletion protection is enabled for the cluster. After deletion protection is enabled, the cluster cannot be deleted in the console or by calling API operations. Valid values: `true`: enables deletion protection for the cluster. This way, the cluster cannot be deleted in the ACK console or by calling API operations. `false`: Deletion protection is disabled for the cluster. You can delete the cluster in the console or by calling the API.
docker_version	String	19.03.5	The Docker version that is used by the cluster.
external_loadbalancer_id	String	lb-2vcrbmlevo6kjpgch****	The ID of the Server Load Balancer (SLB) instance that is used for the Ingress of the cluster. The default SLB specification is slb.s1.small, which belongs to the high-performance instance type.
master_url	String	{\"api_server_endpoint\":\"\",\"intranet_api_server_endpoint\":\"https://192.168.0.251:6443\"}	The address of the cluster API server. It includes an internal endpoint and a public endpoint.
meta_data	String	{\"Addons\":[{\"config\":***}	The metadata of the cluster.
name	String	cluster-demo	The name of the cluster. The name must be 1 to 63 characters in length, and can contain digits, letters, and hyphens (-). It cannot start with a hyphen (-).
network_mode	String	vpc	The network mode of the cluster. Valid values: `classic`: classic network `vpc`: virtual private cloud (VPC) `overlay`: overlay network `calico`: network powered by Calico
private_zone	Boolean	false	Indicates whether Alibaba Cloud DNS PrivateZone is enabled. Valid values: `true`: Alibaba Cloud DNS PrivateZone is enabled. `false`: Alibaba Cloud DNS PrivateZone is disabled.
profile	String	Default	The identifier of the cluster. Valid values: `Edge`: The cluster is a managed edge Kubernetes cluster. `Default`: The cluster is not a managed edge Kubernetes cluster.
region_id	String	cn-beijing	The ID of the region where the cluster is deployed.
resource_group_id	String	rg-acfmyvw3wjm****	The ID of the resource group to which the cluster belongs.
security_group_id	String	sg-2vcgwsrwgt5mp0yi****	The ID of the security group to which the instances of the cluster belong.
size	Long	5	The number of nodes in the cluster. Master nodes and worker nodes are included.
state	String	running	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 upgraded. `updating_failed`: The cluster failed to be upgraded. `scaling`: The cluster is being scaled. `stopped`: The cluster is stopped. `deleting`: The cluster is being deleted. `deleted`: The cluster is deleted. `delete_failed`: The cluster failed to be deleted.
subnet_cidr	String	172.21.0.0/16	The pod CIDR block. It must be a valid and private CIDR block, and must be one of the following CIDR blocks or their subnets: 10.0.0.0/8 172.16-31.0.0/12-16 192.168.0.0/16 The CIDR block of pods cannot overlap with the CIDR block of the VPC in which the cluster is deployed and the CIDR blocks of existing clusters in the VPC. You cannot modify the pod CIDR block after the cluster is created. For more information about the network segmentation of ACK clusters, see Plan CIDR blocks for ACK clusters in a VPC.
tags	Array of tag		The labels of the cluster.
updated	String	2020-09-16T11:09:55+08:00	The time when the cluster was updated.
vpc_id	String	vpc-2vcg932hsxsxuqbgl****	The ID of the VPC where the cluster is deployed. This parameter is required when you create a cluster.
vswitch_id	String	vsw-2vc41xuumx5z2rdma**,vsw-2vc41xuumx5z2rdma**	The IDs of the vSwitches. You can select one to three vSwitches when you create a cluster. We recommend that you select vSwitches in different zones to ensure high availability.
worker_ram_role_name	String	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****	The name of the Resource Access Management (RAM) role. The RAM role is assigned to the worker nodes that are created on Elastic Compute Service (ECS) instances.
zone_id	String	cn-beijing-b	The ID of the zone where the cluster is deployed.
cluster_spec	String	ack.standard	The type of the managed Kubernetes cluster. This parameter is returned for a managed Kubernetes cluster. Valid values: `ack.pro.small`: professional managed Kubernetes cluster `ack.standard`: standard managed Kubernetes cluster
maintenance_window	maintenance_window		The maintenance window of the cluster. This feature is available in only professional managed Kubernetes clusters.
page_info	object		The pagination details.
page_number	Integer	3	The page number of the returned page.
page_size	Integer	20	The number of entries returned per page.
total_count	Integer	50	The total number of entries returned.

Examples

Sample requests

GET /api/v1/clusters?name=cluster-demo&cluster_type=Kubernetes&page_size=10&page_number=3 HTTP/1.1 
Content-Type:application/json

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<clusters>
    <cluster_id>c3fb96524f9274b4495df0f12a6b5****</cluster_id>
    <cluster_type>Kubernetes</cluster_type>
    <created>2020-08-20T10:51:29+08:00</created>
    <init_version>1.16.9-aliyun.1</init_version>
    <current_version>1.16.9-aliyun.1</current_version>
    <next_version>1.18.8-aliyun.1</next_version>
    <deletion_protection>true</deletion_protection>
    <docker_version>19.03.5</docker_version>
    <external_loadbalancer_id>lb-2vcrbmlevo6kjpgch****</external_loadbalancer_id>
    <master_url>{\"api_server_endpoint\":\"\",\"intranet_api_server_endpoint\":\"https://192.168.0.251:6443\"}</master_url>
    <meta_data>{\"Addons\":[{\"config\":***}</meta_data>
    <name>cluster-demo</name>
    <network_mode>vpc</network_mode>
    <private_zone>false</private_zone>
    <profile>Default</profile>
    <region_id>cn-beijing</region_id>
    <resource_group_id>rg-acfmyvw3wjm****</resource_group_id>
    <security_group_id>sg-2vcgwsrwgt5mp0yi****</security_group_id>
    <size>5</size>
    <state>running</state>
    <subnet_cidr>172.21.0.0/16</subnet_cidr>
    <tags>
        <key>env</key>
        <value>prod</value>
    </tags>
    <updated>2020-09-16T11:09:55+08:00</updated>
    <vpc_id>vpc-2vcg932hsxsxuqbgl****</vpc_id>
    <vswitch_id>vsw-2vc41xuumx5z2rdma****,vsw-2vc41xuumx5z2rdma****</vswitch_id>
    <worker_ram_role_name>KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****</worker_ram_role_name>
    <zone_id>cn-beijing-b</zone_id>
    <cluster_spec>ack.standard</cluster_spec>
    <maintenance_window>
        <enable>false</enable>
        <maintenance_time>03:00:00Z</maintenance_time>
        <duration>3h</duration>
        <weekly_period>Monday,Thursday</weekly_period>
    </maintenance_window>
</clusters>
<page_info>
    <page_number>3</page_number>
    <page_size>20</page_size>
    <total_count>50</total_count>
</page_info>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "clusters" : [ {
    "cluster_id" : "c3fb96524f9274b4495df0f12a6b5****",
    "cluster_type" : "Kubernetes",
    "created" : "2020-08-20T10:51:29+08:00",
    "init_version" : "1.16.9-aliyun.1",
    "current_version" : "1.16.9-aliyun.1",
    "next_version" : "1.18.8-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.0.251: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****",
    "size" : 5,
    "state" : "running",
    "subnet_cidr" : "172.21.0.0/16",
    "tags" : [ {
      "key" : "env",
      "value" : "prod"
    } ],
    "updated" : "2020-09-16T11:09:55+08:00",
    "vpc_id" : "vpc-2vcg932hsxsxuqbgl****",
    "vswitch_id" : "vsw-2vc41xuumx5z2rdma****,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" : "03:00:00Z",
      "duration" : "3h",
      "weekly_period" : "Monday,Thursday"
    }
  } ],
  "page_info" : {
    "page_number" : 3,
    "page_size" : 20,
    "total_count" : 50
  }
}

Error codes

For a list of error codes, visit the API Error Center.