Query a list of ACK clusters -

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

Request query parameters

Parameter	Type	Required	Example	Description
name	String	No	cluster-demo	The cluster name. The name must be 1 to 63 characters in length, and can contain digits, letters, and hyphens (-). The name cannot start with a hyphen (-).
cluster_type	String	No	Kubernetes	The type of cluster. Valid values: `Kubernetes`: ACK dedicated cluster. `ManagedKubernetes`: ACK managed cluster. ACK managed clusters include ACK Pro clusters, ACK Basic clusters, ACK Serverless Pro clusters, ACK Serverless Basic clusters, ACK Edge Pro clusters, and ACK Edge Basic clusters. `ExternalKubernetes`: external cluster that is registered to ACK.
page_size	Long	No	10	The number of entries per page.
page_number	Long	No	3	The page number.
profile	String	No	Default	The identifier of the cluster. Valid values when the cluster_type parameter is set to `ManagedKubernetes`: `Default`: ACK managed cluster. `Serverless`: ACK Serverless cluster. `Edge`: ACK Edge cluster. Valid values when the cluster_type parameter is set to `Ask`: `ask.v2`: ACK Serverless cluster. By default, this parameter is left empty. If you leave this parameter empty, ACK clusters are not filtered by identifier.
cluster_spec	String	No	ack.pro.small	The edition of the cluster. This parameter is available only when the cluster_type parameter is set to `ManagedKubernetes`. Valid values: `ack.pro.small`: ACK Pro cluster. `ack.standard`: ACK Basic cluster. By default, this parameter is left empty. If you leave this parameter empty, ACK clusters are not filtered by edition.
region_id	String	No	cn-hangzhou	The region ID of the cluster. You can specify this parameter to query all ACK clusters in a region.

Response syntax

HTTP/1.1 200 OK
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

Response body parameters

Parameter	Type	Example	Description
clusters	Array		The details of clusters.
cluster_id	String	c3fb96524f9274b4495df0f12a6b5****	The cluster ID.
cluster_type	String	Kubernetes	The type of cluster. Valid values: `Kubernetes`: ACK dedicated cluster. `ManagedKubernetes`: ACK managed cluster. `Ask`: ACK Serverless cluster. `ExternalKubernetes`: registered 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 Kubernetes version of the cluster. The Kubernetes versions supported by ACK are the same as the versions of open source Kubernetes. We recommend that you specify the latest Kubernetes version. If you do not specify this parameter, the latest Kubernetes version is used. You can create clusters of the latest two Kubernetes versions in the ACK console. You can call the corresponding ACK API operation to create clusters of other Kubernetes versions. 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 current Kubernetes version of the cluster.
next_version	String	1.18.8-aliyun.1	The Kubernetes version to which the cluster can be updated.
deletion_protection	Boolean	true	Indicates whether deletion protection is enabled for the cluster. If deletion protection is enabled, the cluster cannot be deleted in the ACK console or by calling API operations. Valid values: `true`: Deletion protection is enabled 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. This way, the cluster can be deleted in the ACK console or by calling API operations.
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 by 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. The address includes an internal endpoint and a public endpoint.
meta_data	String	{\"Addons\":[{\"config\":***}	The metadata of the cluster.
name	String	cluster-demo	The cluster name. The name must be 1 to 63 characters in length, and can contain digits, letters, and hyphens (-). The name 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 an ACK Edge cluster. `Default`: The cluster is not an ACK Edge cluster.
region_id	String	cn-beijing	The region ID of the cluster.
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 status 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. `updating_failed`: The cluster failed to be updated. `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, see Plan CIDR blocks for an ACK cluster.
tags	Array of tag		The resource 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 worker 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 zone ID of the cluster.
cluster_spec	String	ack.standard	The edition of the cluster. This parameter is available only for ACK managed clusters. Valid values: `ack.pro.small`: ACK Pro cluster. `ack.standard`: ACK Basic cluster.
maintenance_window	maintenance_window		The maintenance window of the cluster. This feature is available only in ACK Pro clusters.
page_info	Object		The pagination information.
page_number	Integer	3	The page number.
page_size	Integer	20	The number of entries 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&profile=Default&cluster_spec=ack.pro.small&region_id=cn-hangzhou HTTP/1.1
Host:cs.aliyuncs.com
Content-Type:application/json

Sample success responses

XML format

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

<DescribeClustersV1Response>
    <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>
</DescribeClustersV1Response>

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, see Service error codes.