Use DescribeClusterDetail to query cluster details - Container Service for Kubernetes - Alibaba Cloud - Container Service for Kubernetes

You can call the DescribeClusterDetail operation to query detailed information about a specified 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	Cluster ID.	cdde1f21ae22e483ebcb068a6eb7f****

Request parameters

Parameter

Type

Required

Description

Example

No parameters required.

Response elements

Element	Type	Description	Example
	object	Response body parameters.
cluster_id	string	Cluster ID.	c82e6987e2961451182edacd74faf****
cluster_type	string	Cluster type. `Kubernetes`: ACK dedicated cluster. `ManagedKubernetes`: ACK managed clusters, including ACK Pro Edition and Basic Edition clusters, ACK Serverless clusters (Pro and Basic), ACK Edge clusters (Pro and Basic), and ACK LINGJUN clusters (Pro). `ExternalKubernetes`: registered cluster.	Kubernetes
created	string	Time when the cluster was created.	2025-04-07T09:57:26+08:00
init_version	string	Initial Kubernetes version of the cluster.	1.32.1-aliyun.1
current_version	string	Current Kubernetes version of the cluster. For supported Kubernetes versions in ACK, see Overview of Kubernetes versions.	1.32.1-aliyun.1
next_version	string	Next available Kubernetes version for upgrade.	1.xx.x-aliyun.1
deletion_protection	boolean	Deletion protection for the cluster prevents accidental deletion through the console or API. Valid values: `true`: Deletion protection is enabled. You cannot delete the cluster through the console or API. `false`: Deletion protection is disabled. You can delete the cluster through the console or API.	true
docker_version `deprecated`	string	Docker version used in the cluster.	19.03.5
external_loadbalancer_id `deprecated`	string	ID of the Server Load Balancer instance used for the cluster Ingress.	lb-2zehc05z3b8dwiifh****
meta_data	string	Metadata of the cluster.	\"Addons\":***
name	string	Cluster name.	cluster-demo
network_mode `deprecated`	string	Network type used by the cluster, such as VPC.	vpc
region_id	string	Region ID where the cluster is deployed.	cn-beijing
resource_group_id	string	Resource group ID of the cluster.	rg-acfmyvw3wjm****
security_group_id	string	Security group ID of the cluster.	sg-25yq****
size	integer	Total number of nodes in the cluster, including master and worker nodes.	5
state	string	Cluster status. Valid values: `initial`: The cluster is being created. `failed`: Cluster creation failed. `running`: The cluster is running. `updating`: The cluster is being updated. `upgrading`: The cluster is being upgraded. `removing`: Nodes are being removed. `draining`: Nodes are being drained. `scaling`: The cluster is scaling. `inactive`: The cluster is inactive. `unavailable`: The cluster is unavailable. `deleting`: The cluster is being deleted. `deleted`: The cluster has been deleted. `delete_failed`: Cluster deletion failed. `waiting`: Waiting for access. `disconnected`: Disconnected.	running
tags	array	Tags associated with the cluster.
	tag	Tags associated with the cluster.
updated	string	Last time the cluster was updated.	2025-04-10T13:28:09+08:00
vpc_id	string	VPC ID of the cluster. This parameter is required when creating a cluster.	vpc-2zecuu62b9zw7a7qn****
vswitch_id `deprecated`	string	vSwitch ID. This field is deprecated. Use vswitch_ids to query control plane vSwitches and node pool vswitch_ids to query data plane vSwitches.	vsw-2zete8s4qocqg0mf6**,vsw-2zete8s4qocqg0mf6**
subnet_cidr `deprecated`	string	CIDR block for pod networks.	172.20.xx.xx/16
zone_id `deprecated`	string	Zone ID within the region where the cluster is deployed.	cn-beijing-a
master_url	string	Cluster endpoint, including 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`: Enabled. `false`: Disabled. Default value: false.	false
profile	string	Cluster subtype. `Default`: ACK managed cluster, including ACK Pro Edition and Basic Edition. `Edge`: ACK Edge cluster, including ACK Edge Pro Edition and Basic Edition. `Serverless`: ACK Serverless cluster, including ACK Serverless Pro Edition and Basic Edition. `Lingjun`: ACK LINGJUN cluster, available in Pro Edition.	Default
cluster_spec	string	Cluster specification when `cluster_type` is set to `ManagedKubernetes` and `profile` is configured. Valid values: `ack.standard`: Basic Edition (default if left empty) `ack.pro.small`: Pro Edition `ack.pro.xlarge`: Pro XL `ack.pro.2xlarge`: Pro 2XL `ack.pro.4xlarge`: Pro 4XL (requires whitelist approval from customer service) Pro XL, Pro 2XL, and Pro 4XL are three tiers offered by ACK Pro Provisioned Control Plane. These tiers pre-allocate and dedicate control plane resources to ensure consistent high performance for API concurrency and pod scheduling, making them suitable for AI training and inference, large-scale clusters, and mission-critical workloads. For cluster management fees of Pro Edition and provisioned control plane clusters, see Cluster management fees.	ack.pro.small
worker_ram_role_name	string	Name of the RAM role assigned to ECS instances acting as worker nodes in the cluster.	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
maintenance_window	maintenance_window	Maintenance window configuration for the cluster. This setting applies only to managed clusters (ACK Pro clusters).
parameters `deprecated`	object	Collection of ROS parameters for the cluster.
	string	ROS parameter.	"ALIYUN::Region": "cn-qingdao"
container_cidr	string	CIDR block for pod networks, used with Flannel.	172.20.xx.xx/16
service_cidr	string	CIDR block for service networks.	172.21.xx.xx/20
proxy_mode	string	kube-proxy proxy mode. `iptables`: A mature and stable kube-proxy mode that uses iptables rules for Kubernetes service discovery and load balancing. Performance is moderate and degrades at scale. Suitable for clusters with a small number of services. `ipvs`: A high-performance kube-proxy mode that uses the Linux IPVS module for Kubernetes service discovery and load balancing. Suitable for clusters with many services and high load balancing demands.	ipvs
timezone	string	Time zone.	Asia/Shanghai
node_cidr_mask	string	Applies only to Flannel network plugin. Subnet mask size allocated to each node, which controls the number of IP addresses assignable to the node.	26
ip_stack	string	IP protocol stack of the cluster. Valid values: ipv4: Creates a cluster that supports IPv4 only. dual: Creates a cluster that supports both IPv4 and IPv6.	ipv4
cluster_domain	string	Local domain name of the cluster.	cluster.local
extra_sans	array	Custom Subject Alternative Names (SANs) for the API server certificate.
	string	Certificate SAN.	192.168.xx.xx
rrsa_config	object	RRSA configuration.
enabled	boolean	Indicates whether RRSA is enabled.	true
oidc_name	string	Name of the OIDC identity provider.	ack-rrsa-***
oidc_arn	string	ARN of the OIDC identity provider.	acs:ram::1138*:oidc-provider/ack-rrsa-*
max_oidc_token_expiration	string	Maximum validity period configurable for the OIDC token.	12h
audience	string	Default audience for the OIDC token. Multiple values are separated by commas (,). These values appear as an array in the aud field of the OIDC token.	https://kubernetes.default.svc,https://example.***.com
issuer	string	Issuer of the OIDC token. Multiple values are separated by commas (,). The first value appears in the iss field of the OIDC token and serves as the issuer URL for the OIDC identity provider.	https://oidc-ack-***,https://kubernetes.default.svc
open_api_configuration_url	string	URL of the OIDC configuration document.	https://oidc-ack-*/c12b990*/.well-known/openid-configuration
jwks_url	string	URL of the OIDC public key information.	https://oidc-ack-*/c12b990*/keys
vswitch_ids	array	vSwitches for the cluster control plane.
	string	vSwitch for the cluster control plane.	vsw-2zete8s4qocqg0mf6****
operation_policy	object	Automatic O&M policy for the cluster.
cluster_auto_upgrade	object	Automatic cluster upgrade settings.
enabled	boolean	Indicates whether automatic cluster upgrade is enabled.	true
channel	string	Frequency of automatic cluster upgrades. For more information, see Upgrade frequency. Valid values: patch: Latest patch version. stable: Second latest minor version. rapid: Latest minor version.	patch
control_plane_config	object	Control plane configuration for dedicated clusters.
charge_type	string	Billing method for control plane nodes.	PrePaid
period	integer	Subscription duration for nodes.	1
period_unit	string	Time unit for node subscription.	Month
auto_renew	boolean	Indicates whether auto-renewal is enabled for nodes.	true
auto_renew_period	integer	Auto-renewal duration for nodes.	1
instance_types	array	Instance types for control plane nodes.
	string	Instance type.	ecs.g6.large
image_type	string	Operating system image type.	AliyunLinux3
image_id	string	Image ID.	aliyun_3_x64_20G_alibase_20240819
key_pair	string	Key pair name. Specify either this parameter or login_password.	ack
system_disk_category	string	System disk category for nodes.	cloud_essd
system_disk_size	integer	System disk size for nodes, in GB. Minimum value: 40.	120
system_disk_snapshot_policy_id	string	Automatic snapshot backup policy for node system disks.	sp-2zej1nogjvovnz4z****
system_disk_performance_level	string	Disk performance level for node system disks. Applies only to ESSD disks.	PL1
system_disk_provisioned_iops	integer	Provisioned IOPS for node system disks.	1000
system_disk_bursting_enabled	boolean	Indicates whether burst performance is enabled for node system disks.	true
deploymentset_id	string	Deployment set ID.	ds-bp10b35imuam5amw****
cloud_monitor_flags	boolean	Indicates whether Cloud Monitor is installed on nodes.	true
soc_enabled	boolean	Indicates whether security hardening for compliance is enabled.	false
security_hardening_os	boolean	Indicates whether Alibaba Cloud OS security hardening is enabled.	true
cpu_policy	string	CPU management policy for nodes.	none
runtime	string	Runtime name.	containerd
node_port_range	string	Port range for node services.	30000-32767
size	integer	Number of control plane nodes.	3
instance_metadata_options	InstanceMetadataOptions	Metadata access configuration for ECS instances.
auto_mode	object	Smart managed mode configuration.
enable	boolean	Indicates whether smart managed mode is enabled.	false
control_plane_endpoints_config	object	Cluster connection configuration.
internal_dns_config	object	Internal domain name configuration for the cluster, applicable to ACK managed clusters. The internal domain name allows node-side system components such as kubelet and kube-proxy to access the API server. If internal domain name access is disabled, these components access the API server through the CLB IP address.
bind_vpcs	array	VPCs where the internal domain name resolution takes effect. By default, this includes the VPC where the cluster resides.
	string	VPC where the internal domain name resolution takes effect.	vpc-xxxxxx
enabled	boolean	Indicates whether internal domain name access is enabled. true: Internal domain name access is enabled. Node-side components (kubelet, kube-proxy) access the API server through the 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.