DescribeClusterDetail-阿里云帮助中心

Queries the details of a specified cluster by 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 body parameters.
auto_mode	object	The auto mode configuration.
enable	boolean	Indicates whether auto mode is enabled.	false
cluster_domain	string	The local domain name of the cluster.	cluster.local
cluster_id	string	The cluster ID.	c82e6987e2961451182edacd74faf****
cluster_spec	string	The specification of the cluster when `cluster_type` is set to `ManagedKubernetes` and `profile` is configured. Valid values: `ack.standard`: Basic Edition (selected by default if the value is empty). `ack.pro.small`: Pro Edition. `ack.pro.xlarge`: Pro XL. `ack.pro.2xlarge`: Pro 2XL. `ack.pro.4xlarge`: Pro 4XL (requires contacting customer service to apply for a whitelist). Pro XL, Pro 2XL, and Pro 4XL are the three tiers provided by the ACK Pro provisioned control plane. By pre-allocating and reserving control plane resources, these tiers ensure that API concurrency and pod scheduling capabilities remain consistently at a high level. They are suitable for AI training and inference, ultra-large-scale clusters, and mission-critical workloads. For more information about the cluster management fees for Pro Edition and provisioned control plane editions, see Cluster management fees.	ack.pro.small
cluster_type	string	The cluster type. Valid values: `Kubernetes`: ACK dedicated cluster. `ManagedKubernetes`: ACK ACK cluster, including ACK ACK clusters (Pro Edition and Basic Edition), ACK Serverless clusters (Pro Edition and Basic Edition), ACK Edge clusters (Pro Edition and Basic Edition), and ACK Lingjun clusters (Pro Edition). `ExternalKubernetes`: registered cluster.	Kubernetes
container_cidr	string	The CIDR block for pods in the Flannel network configuration.	172.20.xx.xx/16
control_plane_config	object	The control plane configuration for dedicated clusters.
auto_renew	boolean	Indicates whether auto-renewal is enabled for the nodes.	true
auto_renew_period	integer	The auto-renewal period for the nodes.	1
charge_type	string	The billing method for the control plane nodes.	PrePaid
cloud_monitor_flags	boolean	Indicates whether CloudMonitor is installed on the nodes.	true
cpu_policy	string	The CPU management policy for the nodes.	none
deploymentset_id	string	The ID of the deployment set.	ds-bp10b35imuam5amw****
image_id	string	The ID of the image.	aliyun_3_x64_20G_alibase_20240819
image_type	string	The type of the operating system image.	AliyunLinux3
instance_metadata_options	InstanceMetadataOptions	The metadata access configuration for the ECS instances.
instance_types	array	The instance types of the nodes.
	string	The instance type.	ecs.g6.large
key_pair	string	The name of the key pair. This parameter and `login_password` are mutually exclusive.	ack
node_port_range	string	The service port range for nodes.	30000-32767
period	integer	The subscription period for the nodes.	1
period_unit	string	The unit of the subscription period for the nodes.	Month
runtime	string	The name of the container runtime.	containerd
security_hardening_os	boolean	Indicates whether Alibaba Cloud OS security hardening is enabled.	true
size	integer	The number of control plane nodes.	3
soc_enabled	boolean	Indicates whether classified protection security hardening is enabled.	false
system_disk_bursting_enabled	boolean	Indicates whether performance bursting is enabled for the system disks of the nodes.	true
system_disk_category	string	The category of the system disks for the nodes.	cloud_essd
system_disk_performance_level	string	The performance level of the system disks for the nodes. This parameter takes effect only for ESSDs.	PL1
system_disk_provisioned_iops	integer	The provisioned read and write IOPS for the system disks of the nodes.	1000
system_disk_size	integer	The size of the system disks for the nodes. The minimum value is 40.	120
system_disk_snapshot_policy_id	string	The ID of the automatic snapshot policy for the nodes.	sp-2zej1nogjvovnz4z****
control_plane_endpoints_config	object	The connection configuration of the cluster.
internal_dns_config	object	The internal domain name configuration for ACK managed clusters. The internal domain name is used by node-side system components such as kubelet and kube-proxy to access the API server. If internal domain name access is not enabled, node-side system components access the API server by using the IP address of the Classic Load Balancer (CLB) instance.
bind_vpcs	array	The VPCs where the internal DNS records of the cluster take effect. By default, this includes the VPC where the cluster is deployed.
	string	The VPC where the internal DNS records of the cluster take effect.	vpc-xxxxxx
enabled	boolean	Indicates whether internal domain name access is enabled for the cluster. Valid values: true: Internal domain name access is enabled. Node-side components such as kubelet and kube-proxy access the API server by using the internal domain name.	true
load_balancers_config	array<object>	The load balancing configuration for cluster access.
	object
endpoint	string	The endpoint address.	nlb-0ogk9aaxxxxxxx.cn-hangzhou.nlb.aliyuncsslb.com
endpoint_type	string	The endpoint type.	private
load_balancer_id	string	The ID of the Server Load Balancer (SLB) instance associated with the endpoint.	nlb-0ogk9aaxxxxxxx
created	string	The time when the cluster was created.	2025-04-07T09:57:26+08:00
current_version	string	The current version of the cluster. For more information about the Kubernetes versions supported by ACK, see Overview of Kubernetes versions.	1.32.1-aliyun.1
deletion_protection	boolean	Specifies whether deletion protection is enabled for the cluster to prevent accidental deletion through the console or API calls. Valid values: `true`: Deletion protection is enabled. The cluster cannot be deleted through the console or API calls. `false`: Deletion protection is disabled. The cluster can be deleted through the console or API calls.	true
docker_version `deprecated`	string	The Docker version in the cluster.	19.03.5
external_loadbalancer_id `deprecated`	string	The instance ID of the Ingress load balancer (LB) for the cluster.	lb-2zehc05z3b8dwiifh****
extra_sans	array	The custom Subject Alternative Names (SANs) for the API server certificate.
	string	The certificate SAN.	192.168.xx.xx
init_version	string	The initial version of the cluster.	1.32.1-aliyun.1
ip_stack	string	The IP protocol stack of the cluster. Valid values: ipv4: The cluster supports only the IPv4 protocol stack. dual: The cluster supports both the IPv4 and IPv6 protocol stacks.	ipv4
maintenance_window	maintenance_window	The maintenance window configuration of the cluster. This parameter takes effect only for managed clusters, such as ACK Pro clusters.
master_url	string	The access endpoints of the cluster, including the internal network access endpoint and the public network access endpoint.	{\"intranet_api_server_endpoint\":\"https://192.168.xx.xx:6443\"***}
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, such as VPC.	vpc
next_version	string	The version to which the cluster can be upgraded.	1.xx.x-aliyun.1
node_cidr_mask	string	This parameter is applicable only to the Flannel network plug-in. The size of the subnet mask allocated to nodes, which determines the number of IP addresses that can be allocated to each node.	26
operation_policy	object	The automatic O&M policy of the cluster.
cluster_auto_upgrade	object	The automatic upgrade configuration of the cluster.
channel	string	The channel for automatic cluster upgrades. For more information, see Upgrade channels. Valid values: patch: The latest patch version. stable: The second latest minor version. rapid: The latest minor version.	patch
enabled	boolean	Specifies whether automatic cluster upgrade is enabled.	true
parameters `deprecated`	object	The collection of Resource Orchestration Service (ROS) parameters for the cluster.
	string	The ROS parameter.	"ALIYUN::Region": "cn-qingdao"
private_zone `deprecated`	boolean	Specifies whether PrivateZone is enabled for the cluster. Valid values: `true`: Enabled. `false`: Disabled. Default value: false.	false
profile	string	The subtype of the cluster. Valid values: `Default`: ACK managed clusters, including ACK Pro clusters and ACK ACK clusters. `Edge`: ACK Edge clusters, including ACK Edge Pro clusters and ACK Edge ACK clusters. `Serverless`: ACK Serverless clusters, including ACK Serverless Pro clusters and ACK Serverless ACK clusters. `Lingjun`: ACK Lingjun clusters, available only in the Pro edition.	Default
proxy_mode	string	The kube-proxy mode. Valid values: `iptables`: The mature and stable kube-proxy mode. Service discovery and load balancing for Kubernetes Services are configured by using iptables rules. This mode provides average performance and is affected by the cluster scale. It is suitable for clusters with a small number of Services. `ipvs`: The high-performance kube-proxy mode. Service discovery and load balancing for Kubernetes Services are configured by using the Linux IPVS module. This mode is suitable for clusters with a large number of Services and scenarios that require high-performance load balancing.	ipvs
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****
rrsa_config	object	The RAM Roles for Service Accounts (RRSA) configuration.
audience	string	The default audience of the OpenID Connect (OIDC) token. Multiple values are separated by commas (,). The values are used as an array for the `aud` field in the OIDC token.	https://kubernetes.default.svc,https://example.***.com
enabled	boolean	Specifies whether RRSA is enabled.	true
issuer	string	The issuer of the OIDC token. Multiple values are separated by commas (,). The first value is used as the `iss` field in the OIDC token and the issuer URL of the OIDC identity provider (IdP).	https://oidc-ack-***,https://kubernetes.default.svc
jwks_url	string	The URL of the OIDC public key.	https://oidc-ack-*/c12b990*/keys
max_oidc_token_expiration	string	The maximum configurable expiration time of the OIDC token.	12h
oidc_arn	string	The Alibaba Cloud Resource Name (ARN) of the OIDC IdP.	acs:ram::1138*:oidc-provider/ack-rrsa-*
oidc_name	string	The name of the OIDC IdP.	ack-rrsa-***
open_api_configuration_url	string	The URL of the OIDC configuration document.	https://oidc-ack-*/c12b990*/.well-known/openid-configuration
security_group_id	string	The ID of the security group to which the cluster belongs.	sg-25yq****
service_cidr	string	The CIDR block of the Service network.	172.21.xx.xx/20
size	integer	The number of nodes in the cluster, including master nodes and worker nodes.	5
state	string	The cluster status. Valid values: `initial`: The cluster is being created. `failed`: The 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 being scaled. `inactive`: The cluster is inactive. `unavailable`: The cluster is unavailable. `deleting`: The cluster is being deleted. `deleted`: The cluster has been deleted. `delete_failed`: The cluster deletion failed. `waiting`: The cluster is waiting for the accessed state. `disconnected`: The cluster is disconnected.	running
subnet_cidr `deprecated`	string	The Pod CIDR block.	172.20.xx.xx/16
tags	array	The cluster resource tags.
	tag	The cluster resource tags.
timezone	string	The time zone.	Asia/Shanghai
updated	string	The time when the cluster was 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. [Deprecated] To query the vSwitches for the control plane, use vswitch_ids. To query the vSwitches for the data plane, use the vswitch_ids of the node pool.	vsw-2zete8s4qocqg0mf6**,vsw-2zete8s4qocqg0mf6**
vswitch_ids	array	The vSwitches for the cluster control plane.
	string	The vSwitches for the cluster control plane.	vsw-2zete8s4qocqg0mf6****
worker_ram_role_name	string	The name of the Resource Access Management (RAM) role for worker nodes, which authorizes ECS instances to serve as worker nodes in the cluster.	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
zone_id `deprecated`	string	The ID of the zone where the cluster is deployed.	cn-beijing-a

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.