Query the details of a cluster by cluster ID - Container Service for Kubernetes - Alibaba Cloud - Container Service for Kubernetes

Call the DescribeClusterDetail operation to get the details of a specific cluster by its cluster ID.

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:DescribeClusterDetail

get

*Cluster

acs:cs:{#regionId}:{#accountId}:cluster/{#ClusterId}

None

Request syntax

GET /clusters/{ClusterId} HTTP/1.1

Path Parameters

Parameter	Type	Required	Description	Example
ClusterId	string	Yes	The cluster ID.	cdde1f21ae22e483ebcb068a6eb7f****

Request parameters

Parameter

Type

Required

Description

Example

No parameters required.

Response elements

Element	Type	Description	Example
	object	The response parameters.
cluster_id	string	The cluster ID.	c82e6987e2961451182edacd74faf****
cluster_type	string	The type of cluster. `Kubernetes`: ACK Dedicated Cluster. `ManagedKubernetes`: ACK Managed Clusters. This category includes ACK Pro Clusters, standard ACK clusters, ACK Serverless Clusters (Pro and standard editions), ACK Edge Clusters (Pro and standard editions), and ACK Lingjun Pro clusters. `ExternalKubernetes`: registered cluster.	Kubernetes
created	string	The time the cluster was created.	2025-04-07T09:57:26+08:00
init_version	string	The initial Kubernetes version of the cluster.	1.32.1-aliyun.1
current_version	string	The current Kubernetes version of the cluster. For more information about the Kubernetes versions that ACK supports, see Kubernetes release overview.	1.32.1-aliyun.1
next_version	string	The Kubernetes version to which the cluster can be upgraded.	1.xx.x-aliyun.1
deletion_protection	boolean	Specifies whether to enable deletion protection for the cluster to prevent accidental deletion from the console or by an API call. Valid values: `true`: Deletion protection is enabled. The cluster cannot be deleted from the console or by an API call. `false`: Deletion protection is disabled. The cluster can be deleted from the console or by an API call.	true
docker_version `deprecated`	string	The Docker version of the cluster.	19.03.5
external_loadbalancer_id `deprecated`	string	The ID of the Server Load Balancer (SLB) instance for the Ingress.	lb-2zehc05z3b8dwiifh****
meta_data	string	The metadata of the cluster.	\"Addons\":***
name	string	The name of the cluster.	cluster-demo
network_mode `deprecated`	string	The network type of the cluster, for example, Virtual Private Cloud (VPC).	vpc
region_id	string	The ID of the region where the cluster is deployed.	cn-beijing
resource_group_id	string	The ID of the resource group to which the cluster belongs.	rg-acfmyvw3wjm****
security_group_id	string	The ID of the security group to which the cluster is added.	sg-25yq****
size	integer	The number of nodes in the cluster, including control plane nodes and worker nodes.	5
state	string	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 updated. `upgrading`: The cluster is being upgraded. `removing`: Nodes are being removed from the cluster. `draining`: The nodes in the cluster are being drained. `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`: The cluster failed to be deleted. `waiting`: The cluster is in the waiting state. `disconnected`: The cluster is disconnected.	running
tags	array	The tags attached to the cluster.
	tag	A tag for a cluster resource.
updated	string	The time the cluster was last updated.	2025-04-10T13:28:09+08:00
vpc_id	string	The ID of the Virtual Private Cloud (VPC) where the cluster is deployed. This parameter is required when you create a cluster.	vpc-2zecuu62b9zw7a7qn****
vswitch_id `deprecated`	string	The vSwitch ID. This parameter is deprecated. To query the vSwitches of the control plane, use the vswitch_ids parameter. To query the vSwitches of the data plane, query the vswitch_ids parameter of the corresponding node pool.	vsw-2zete8s4qocqg0mf6**,vsw-2zete8s4qocqg0mf6**
subnet_cidr `deprecated`	string	The Pod CIDR block.	172.20.xx.xx/16
zone_id `deprecated`	string	The ID of the availability zone where the cluster is deployed.	cn-beijing-a
master_url	string	The endpoints for the cluster's API server, including the internal and public endpoints.	{\"intranet_api_server_endpoint\":\"https://192.168.xx.xx:6443\"***}
private_zone `deprecated`	boolean	Indicates whether PrivateZone is enabled for the cluster. `true`: PrivateZone is enabled. `false`: PrivateZone is disabled. Default value: false.	false
profile	string	The subtype of the cluster. Valid values: `Default`: A standard ACK cluster. This type can be an ACK Pro cluster or a standard ACK cluster. `Edge`: An ACK Edge cluster. This type can be an ACK Edge Pro cluster or a standard ACK Edge cluster. `Serverless`: An ACK Serverless cluster. This type can be an ACK Serverless Pro cluster or a standard ACK Serverless cluster. `Lingjun`: An ACK Lingjun Pro cluster.	Default
cluster_spec	string	The edition of the cluster. This parameter applies only when `cluster_type` is `ManagedKubernetes`. Valid values: `ack.standard`: standard edition. This is the default value. `ack.pro.small`: Pro edition. `ack.pro.xlarge`: Pro XL edition. `ack.pro.2xlarge`: Pro 2XL edition. `ack.pro.4xlarge`: Pro 4XL edition. To use this edition, you must be added to the allowlist. This model pre-allocates and dedicates control plane resources to ensure high API concurrency and Pod scheduling capabilities. It is suitable for AI training and inference, large-scale clusters, and mission-critical applications. For more information about the management fees for Pro and provisioned control plane editions, see Cluster management fee.	ack.pro.small
worker_ram_role_name	string	The name of the worker RAM role. This role grants permissions to the ECS instances that serve as worker nodes in the cluster.	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
maintenance_window	maintenance_window	The maintenance window configuration of the cluster. This parameter applies only to ACK Pro Clusters.
parameters `deprecated`	object	The set of ROS parameters for the cluster.
	string	A ROS parameter.	"ALIYUN::Region": "cn-qingdao"
container_cidr	string	The CIDR block for Pods. This parameter applies only to clusters that use the Flannel network plugin.	172.20.xx.xx/16
service_cidr	string	The CIDR block for Services.	172.21.xx.xx/20
proxy_mode	string	The proxy mode of kube-proxy. `iptables`: A mature and stable proxy mode. It uses iptables rules for service discovery and load balancing for Kubernetes Services. Its performance is moderate and can be affected by the cluster scale, making it suitable for clusters with a small number of Services. `ipvs`: A high-performance proxy mode. It uses the Linux IPVS module for service discovery and load balancing for Kubernetes Services. This mode is suitable for large clusters that have a large number of Services and require high-performance load balancing.	ipvs
timezone	string	The time zone of the cluster.	Asia/Shanghai
node_cidr_mask	string	The size of the subnet mask that is assigned to each node. This value controls the number of IP addresses that can be allocated to each node. This parameter applies only to clusters that use the Flannel network plugin.	26
ip_stack	string	The IP stack of the cluster. Valid values: `ipv4`: an IPv4-only cluster. `dual`: a dual-stack cluster that supports both IPv4 and IPv6.	ipv4
cluster_domain	string	The cluster-local domain name.	cluster.local
extra_sans	array	The custom Subject Alternative Names (SANs) for the API server certificate.
	string	A SAN for the certificate.	192.168.xx.xx
rrsa_config	object	The RRSA configuration.
enabled	boolean	Indicates whether RRSA is enabled.	true
oidc_name	string	The name of the OIDC identity provider.	ack-rrsa-***
oidc_arn	string	The ARN of the OIDC identity provider.	acs:ram::1138*:oidc-provider/ack-rrsa-*
max_oidc_token_expiration	string	The maximum configurable validity period of an OIDC token.	12h
audience	string	The default audience of an OIDC token. If multiple audiences are specified, they are separated by commas (,). These values form the aud claim array in the OIDC token.	https://kubernetes.default.svc,https://example.***.com
issuer	string	The issuer of an OIDC token. If multiple issuers are specified, they are separated by commas (,). The first value becomes the iss claim of the OIDC token and the issuer URL of the OIDC identity provider.	https://oidc-ack-***,https://kubernetes.default.svc
open_api_configuration_url	string	The URL of the OIDC discovery document.	https://oidc-ack-*/c12b990*/.well-known/openid-configuration
jwks_url	string	The URL of the OIDC JSON Web Key Set (JWKS).	https://oidc-ack-*/c12b990*/keys
vswitch_ids	array	The vSwitches of the cluster control plane.
	string	A vSwitch of the cluster control plane.	vsw-2zete8s4qocqg0mf6****
operation_policy	object	The automated O&M policies for the cluster.
cluster_auto_upgrade	object	The auto-upgrade settings for the cluster.
enabled	boolean	Indicates whether auto-upgrade is enabled for the cluster.	true
channel	string	The release channel for automatic cluster upgrades. For more information, see Release channels. Valid values: `patch`: The cluster is automatically upgraded to the latest patch version. `stable`: The cluster is automatically upgraded to a recent, stable minor version. rapid: The latest minor version.	patch
control_plane_config	object	The control plane configuration of the ACK Dedicated Cluster.
charge_type	string	The billing method of the control plane nodes.	PrePaid
period	integer	The subscription duration of the nodes.	1
period_unit	string	The unit of the subscription duration for the nodes.	Month
auto_renew	boolean	Indicates whether auto-renewal is enabled for the nodes.	true
auto_renew_period	integer	The auto-renewal duration for the nodes.	1
instance_types	array	The instance types of the nodes.
	string	The instance type.	ecs.g6.large
image_type	string	The OS image type.	AliyunLinux3
image_id	string	The image ID.	aliyun_3_x64_20G_alibase_20240819
key_pair	string	The name of the key pair.	ack
system_disk_category	string	The category of the system disk for the nodes.	cloud_essd
system_disk_size	integer	The size of the system disk for the nodes. Unit: GiB. Minimum value: 40.	120
system_disk_snapshot_policy_id	string	The ID of the automatic snapshot policy for the system disks of the nodes.	sp-2zej1nogjvovnz4z****
system_disk_performance_level	string	The performance level of the system disks. This parameter takes effect only for ESSDs.	PL1
system_disk_provisioned_iops	integer	The provisioned read/write IOPS of the system disks.	1000
system_disk_bursting_enabled	boolean	Indicates whether bursting is enabled for the system disks.	true
deploymentset_id	string	The ID of the deployment set.	ds-bp10b35imuam5amw****
cloud_monitor_flags	boolean	Indicates whether to install the CloudMonitor agent on the nodes.	true
soc_enabled	boolean	Indicates whether security hardening that complies with the Multi-Level Protection Scheme (MLPS) is enabled.	false
security_hardening_os	boolean	Indicates whether Alibaba Cloud OS security hardening is enabled.	true
cpu_policy	string	The CPU management policy of the nodes.	none
runtime	string	The name of the container runtime.	containerd
node_port_range	string	The port range of NodePort Services.	30000-32767
size	integer	The number of control plane nodes.	3
instance_metadata_options	InstanceMetadataOptions	The metadata access options for the ECS instances.
auto_mode	object	The configuration of the smart hosting mode.
enable	boolean	Indicates whether smart hosting is enabled.	false
control_plane_endpoints_config	object	The cluster connection configurations.
internal_dns_config	object	The internal DNS settings for the cluster, applicable to ACK Managed Clusters. Node components such as kubelet and kube-proxy use the internal domain to access the API server. If internal domain access is not enabled, these components access the API server by using the IP address of the Server Load Balancer (SLB) instance.
bind_vpcs	array	The VPCs in which the DNS records for the internal domain take effect. By default, this includes the VPC where the cluster is deployed.
	string	The VPC where the DNS records for the internal domain take effect.	vpc-xxxxxx
enabled	boolean	`true`: Internal domain access is enabled. Node components, such as kubelet and kube-proxy, access the API server through the internal domain. true: Enables internal domain access for the cluster. Node-side components (kubelet and kube-proxy) will access the API Server through the cluster's internal domain name.	true

Examples

Success response

JSON format

{
  "cluster_id": "c82e6987e2961451182edacd74faf****",
  "cluster_type": "Kubernetes",
  "created": "2025-04-07T09:57:26+08:00",
  "init_version": "1.32.1-aliyun.1",
  "current_version": "1.32.1-aliyun.1",
  "next_version": "1.xx.x-aliyun.1",
  "deletion_protection": true,
  "docker_version": "19.03.5",
  "external_loadbalancer_id": "lb-2zehc05z3b8dwiifh****",
  "meta_data": "\\\"Addons\\\":***",
  "name": "cluster-demo",
  "network_mode": "vpc",
  "region_id": "cn-beijing",
  "resource_group_id": "rg-acfmyvw3wjm****",
  "security_group_id": "sg-25yq****",
  "size": 5,
  "state": "running",
  "tags": [
    {
      "key": "env",
      "value": "prod"
    }
  ],
  "updated": "2025-04-10T13:28:09+08:00",
  "vpc_id": "vpc-2zecuu62b9zw7a7qn****",
  "vswitch_id": "vsw-2zete8s4qocqg0mf6****,vsw-2zete8s4qocqg0mf6****",
  "subnet_cidr": "172.20.xx.xx/16",
  "zone_id": "cn-beijing-a",
  "master_url": "{\\\"intranet_api_server_endpoint\\\":\\\"https://192.168.xx.xx:6443\\\"***}",
  "private_zone": false,
  "profile": "Default",
  "cluster_spec": "ack.pro.small",
  "worker_ram_role_name": "KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****",
  "maintenance_window": {
    "enable": false,
    "maintenance_time": "2020-10-15T12:31:00.000+08:00",
    "duration": "3h",
    "weekly_period": "Monday,Thursday",
    "recurrence": "FREQ=WEEKLY;INTERVAL=4;BYDAY=MO,TU"
  },
  "parameters": {
    "key": "\"ALIYUN::Region\": \"cn-qingdao\""
  },
  "container_cidr": "172.20.xx.xx/16",
  "service_cidr": "172.21.xx.xx/20",
  "proxy_mode": "ipvs",
  "timezone": "Asia/Shanghai",
  "node_cidr_mask": "26",
  "ip_stack": "ipv4",
  "cluster_domain": "cluster.local",
  "extra_sans": [
    "192.168.xx.xx"
  ],
  "rrsa_config": {
    "enabled": true,
    "oidc_name": "ack-rrsa-***",
    "oidc_arn": "acs:ram::1138***:oidc-provider/ack-rrsa-***",
    "max_oidc_token_expiration": "12h",
    "audience": "https://kubernetes.default.svc,https://example.***.com",
    "issuer": "https://oidc-ack-***,https://kubernetes.default.svc",
    "open_api_configuration_url": "https://oidc-ack-***/c12b990***/.well-known/openid-configuration",
    "jwks_url": "https://oidc-ack-***/c12b990***/keys"
  },
  "vswitch_ids": [
    "vsw-2zete8s4qocqg0mf6****"
  ],
  "operation_policy": {
    "cluster_auto_upgrade": {
      "enabled": true,
      "channel": "patch"
    }
  },
  "control_plane_config": {
    "charge_type": "PrePaid",
    "period": 1,
    "period_unit": "Month",
    "auto_renew": true,
    "auto_renew_period": 1,
    "instance_types": [
      "ecs.g6.large"
    ],
    "image_type": "AliyunLinux3",
    "image_id": "aliyun_3_x64_20G_alibase_20240819",
    "key_pair": "ack",
    "system_disk_category": "cloud_essd",
    "system_disk_size": 120,
    "system_disk_snapshot_policy_id": "sp-2zej1nogjvovnz4z****",
    "system_disk_performance_level": "PL1",
    "system_disk_provisioned_iops": 1000,
    "system_disk_bursting_enabled": true,
    "deploymentset_id": "ds-bp10b35imuam5amw****",
    "cloud_monitor_flags": true,
    "soc_enabled": false,
    "security_hardening_os": true,
    "cpu_policy": "none",
    "runtime": "containerd",
    "node_port_range": "30000-32767",
    "size": 3,
    "instance_metadata_options": {
      "http_tokens": "optional"
    }
  },
  "auto_mode": {
    "enable": false
  },
  "control_plane_endpoints_config": {
    "internal_dns_config": {
      "bind_vpcs": [
        "vpc-xxxxxx"
      ],
      "enabled": true
    }
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.