All Products
Search
Document Center

Container Service for Kubernetes:DescribeClustersV1

Last Updated:Nov 07, 2024

Queries the details about Container Service for Kubernetes (ACK) clusters of specified types or specifications within an account.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
cs:GetClustersget
  • All Resources
    *
    none
none

Request syntax

GET /api/v1/clusters HTTP/1.1

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
  • Kubernetes: ACK dedicated cluster.
  • ManagedKubernetes: ACK managed cluster. ACK managed clusters include ACK Basic clusters, ACK Pro clusters, ACK Serverless Basic clusters, ACK Serverless Pro clusters, ACK Edge Basic clusters, ACK Edge Pro clusters, and ACK Lingjun Pro clusters.
  • ExternalKubernetes: registered cluster.
Kubernetes
page_sizelongNo

The number of entries per page.

10
page_numberlongNo

The page number.

3
profilestringNo

If you set cluster_type to ManagedKubernetes, an ACK managed cluster is created. In this case, you can further specify the cluster edition. Valid values:

  • Default: ACK managed cluster. ACK managed clusters include ACK Basic clusters and ACK Pro clusters.
  • Edge: ACK Edge cluster. ACK Edge clusters include ACK Edge Basic clusters and ACK Edge Pro clusters.
  • Serverless: ACK Serverless cluster. ACK Serverless clusters include ACK Serverless Basic clusters and ACK Serverless Pro clusters.
  • Lingjun: ACK Lingjun Pro cluster.
Default
cluster_specstringNo

After you set cluster_type to ManagedKubernetes and configure the profile parameter, you can further specify the edition of the cluster. Valid values:

  • ack.pro.small: ACK Pro cluster.
  • ack.standard: ACK Basic cluster. If you leave the parameter empty, ACK Basic cluster is selected.
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
cluster_idstringNo

The cluster ID.

ca418e5e6fa2849d78301341700axxxxx

Response parameters

ParameterTypeDescriptionExample
object

The response body.

clustersarray<object>

The details of the clusters.

clustersobject

Information about the cluster.

cluster_idstring

The cluster ID.

c3fb96524f9274b4495df0f12a6b5****
cluster_typestring
  • Kubernetes: ACK dedicated cluster.
  • ManagedKubernetes: ACK managed cluster. ACK managed clusters include ACK Basic clusters, ACK Pro clusters, ACK Serverless Basic clusters, ACK Serverless Pro clusters, ACK Edge Basic clusters, ACK Edge Pro clusters, and ACK Lingjun Pro clusters.
  • 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 Kubernetes versions supported by open source Kubernetes. We recommend that you specify the latest Kubernetes version. If you do not configure this parameter, the latest Kubernetes version is used.

You can create clusters that run the latest two Kubernetes versions in the ACK console. You can call the 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

Specifies whether to enable cluster deletion protection. If this option is enabled, the cluster cannot be deleted in the ACK 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: disables deletion protection for the cluster. This way, 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 Ingresses of the cluster.

The default SLB specification is slb.s1.small, which belongs to the high-performance instance type.

lb-2vcrbmlevo6kjpgch****
master_urlstring

The address of the cluster API server. It includes 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:

  • Default: ACK managed cluster. ACK managed clusters include ACK Basic clusters and ACK Pro clusters.
  • Edge: ACK Edge cluster. ACK Edge clusters include ACK Edge Basic clusters and ACK Edge Pro clusters.
  • Serverless: ACK Serverless cluster. ACK Serverless clusters include ACK Serverless Basic clusters and ACK Serverless Pro clusters.
  • Lingjun: ACK Lingjun Pro 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 of the cluster.

sg-2vcgwsrwgt5mp0yi****
container_cidrstring

The pod CIDR block.

172.20.0.0/16
service_cidrstring

The Service CIDR block.

172.21.0.0/20
proxy_modestring

The kube-proxy mode. Valid values: ipvs and iptables.

ipvs
timezonestring

The time zone.

Asia/Shanghai
ip_stackstring

The IP stack of the cluster. Valid values:

  • ipv4: The cluster is an IPv4 cluster.
  • dual: The cluster is a dual-stack cluster.
ipv4
cluster_domainstring

The domain name of the cluster.

cluster.local
sizelong

The number of nodes in the cluster, including control planes 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_cidrdeprecatedstring

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 pod CIDR block 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 you create the cluster.

For more information about the network planning of Container Service for Kubernetes (ACK) clusters, see Plan CIDR blocks for an ACK cluster.

172.21.0.0/16
tagsarray

The resource labels of the cluster.

tagstag

The resource labels of the cluster.

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_iddeprecatedstring

The IDs of the vSwitches. You can select one to three vSwitches when you create a cluster. To ensure the high availability of the cluster, we recommend that you select vSwitches in different zones.

vsw-2vc41xuumx5z2rdma****,vsw-2vc41xuumx5z2rdma****
vswitch_idsarray

The vSwitches of the control planes.

string
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 ECS instances.

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

The ID of the zone where the cluster is deployed.

cn-beijing-b
cluster_specstring

After you set cluster_type to ManagedKubernetes and configure the profile parameter, you can further specify the edition of the cluster. Valid values:

  • ack.pro.small: ACK Pro cluster.
  • ack.standard: ACK Basic cluster. If you leave the parameter empty, ACK Basic cluster is selected.
ack.standard
maintenance_windowmaintenance_window

The maintenance window of the cluster. This feature is available only for ACK managed clusters and ACK Serverless clusters.

operation_policyobject

The automatic O&M policy of the cluster.

cluster_auto_upgradeobject

The configurations of auto cluster update.

enabledboolean

Specifies whether to enable auto cluster update.

true
channelstring

The frequency of auto cluster updates. For more information, see Update frequency.

Valid values:

  • patch: the latest patch version.
  • stables: the second-latest minor version.
  • rapid: the latest minor version.
patch
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****",
      "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": 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****",
      "vswitch_ids": [
        "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",
        "recurrence": "FREQ=WEEKLY;INTERVAL=4;BYDAY=MO,TU"
      },
      "operation_policy": {
        "cluster_auto_upgrade": {
          "enabled": true,
          "channel": "patch"
        }
      }
    }
  ],
  "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
2024-10-18The response structure of the API has changedView Change Details
2024-10-15The response structure of the API has changedView Change Details
2023-11-24The request parameters of the API has changedView Change Details
2020-09-14The request parameters of the API has changedView Change Details