All Products
Search
Document Center

Container Service for Kubernetes:DescribeClustersV1

Last Updated:Feb 29, 2024

You can call the DescribeClustersV1 operation to query the details about all Container Service for Kubernetes (ACK) clusters.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request syntax

GET /api/v1/clusters

Request parameters

ParameterTypeRequiredDescriptionExample
namestringNo

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-demo
cluster_typestringNo

The cluster type. 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: registered cluster.
Kubernetes
page_sizelongNo

The number of entries per page.

10
page_numberlongNo

The page number.

3
profilestringNo

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.

Default
cluster_specstringNo

The cluster type, which is available only when the cluster type is set to ManagedKubernetes. Valid values:

  • ack.pro.small: ACK Pro cluster
  • ack.standard: ACK Basic cluster

By default, this parameter is left empty, which means that ACK clusters are not filtered by this parameter.

ack.pro.small
region_idstringNo

The region ID of the clusters. You can use this parameter to query all clusters in the specified region.

cn-hangzhou

Response parameters

ParameterTypeDescriptionExample
object

The response body.

clustersobject []

The details of the clusters.

cluster_idstring

The cluster ID.

c3fb96524f9274b4495df0f12a6b5****
cluster_typestring

The cluster type. Valid values:

  • Kubernetes: ACK dedicated cluster
  • ManagedKubernetes: ACK managed cluster
  • Ask: ACK Serverless cluster
  • ExternalKubernetes: registered cluster
Kubernetes
createdstring

The time when the cluster was created.

2020-08-20T10:51:29+08:00
init_versionstring

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.

1.16.9-aliyun.1
current_versionstring

The Kubernetes version of the cluster.

1.16.9-aliyun.1
next_versionstring

The Kubernetes version to which the cluster can be updated.

1.18.8-aliyun.1
deletion_protectionboolean

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. The cluster cannot be deleted in the ACK console or by calling API operations.
  • false: Deletion protection is disabled for the cluster. The cluster can be deleted in the ACK console or by calling API operations.
true
docker_versionstring

The Docker version that is used by the cluster.

19.03.5
external_loadbalancer_idstring

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.

lb-2vcrbmlevo6kjpgch****
master_urlstring

The endpoint of the cluster API server, including an internal endpoint and a public endpoint.

{\"api_server_endpoint\":\"\",\"intranet_api_server_endpoint\":\"https://192.168.0.251:6443\"}
meta_datastring

The metadata of the cluster.

{\"Addons\":[{\"config\":***}
namestring

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-demo
network_modestring

The network mode of the cluster. Valid values:

  • classic: classic network
  • vpc: virtual private cloud (VPC)
  • overlay: overlay network
  • calico: network powered by Calico.
vpc
private_zoneboolean

Indicates whether Alibaba Cloud DNS PrivateZone is enabled. Valid values:

  • true: Alibaba Cloud DNS PrivateZone is enabled.
  • false: Alibaba Cloud DNS PrivateZone is disabled.
false
profilestring

The cluster identifier. Valid values:

  • Edge: The cluster is an ACK Edge cluster.
  • Default: The cluster is not an ACK Edge cluster.
Default
region_idstring

The region ID of the cluster.

cn-beijing
resource_group_idstring

The ID of the resource group to which the cluster belongs.

rg-acfmyvw3wjm****
security_group_idstring

The ID of the security group to which the instances of the cluster belong.

sg-2vcgwsrwgt5mp0yi****
sizelong

The number of nodes in the cluster, including master nodes and worker nodes.

5
statestring

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.
running
subnet_cidrstring

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.

172.21.0.0/16
tagsarray

The resource labels of the cluster.

tag

The resource label.

updatedstring

The time when the cluster was updated.

2020-09-16T11:09:55+08:00
vpc_idstring

The ID of the VPC where the cluster is deployed. This parameter is required when you create a cluster.

vpc-2vcg932hsxsxuqbgl****
vswitch_idstring

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.

vsw-2vc41xuumx5z2rdma****,vsw-2vc41xuumx5z2rdma****
worker_ram_role_namestring

The name of the worker Resource Access Management (RAM) role. The RAM role is assigned to the worker nodes of the cluster to allow the worker nodes to manage Elastic Compute Service (ECS) instances.

KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
zone_idstring

The zone ID.

cn-beijing-b
cluster_specstring

The type of ACK managed cluster. This parameter is available only for ACK managed clusters. Valid values:

  • ack.pro.small: ACK Pro cluster
  • ack.standard: ACK Basic cluster
ack.standard
maintenance_windowmaintenance_window

The maintenance window of the cluster. This feature is available only for ACK Pro clusters.

page_infoobject

The pagination information.

page_numberinteger

The page number.

3
page_sizeinteger

The number of entries per page.

20
total_countinteger

The total number of entries returned.

50

Examples

Sample success responses

JSONformat

{
  "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 Service error codes.

Change history

Change timeSummary of changesOperation
2023-11-24The request parameters of the API has changedsee changesets
Change itemChange content
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: cluster_id
2020-09-14The request parameters of the API has changedsee changesets
Change itemChange content
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: region_id