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

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.
cluster_id	string	The cluster ID.	c82e6987e2961451182edacd74faf****
cluster_type	string	The cluster type. `Kubernetes`: ACK dedicated cluster. `ManagedKubernetes`: ACK ACK cluster types, including ACK ACK clusters (ACK Pro and ACK Basic), ACK Serverless clusters (Pro and Basic), ACK Edge clusters (Pro and Basic), and ACK Lingjun clusters (Pro). `ExternalKubernetes`: registered cluster.	Kubernetes
created	string	The time when 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 supported by ACK, see Kubernetes version 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	Indicates whether deletion protection is enabled for the cluster to prevent accidental deletion through the console or API. Valid values: `true`: Deletion protection is enabled. The cluster cannot be deleted through the console or API. `false`: Deletion protection is not enabled. The cluster can be deleted through the console or API.	true
docker_version `deprecated`	string	The Docker version used in the cluster.	19.03.5
external_loadbalancer_id `deprecated`	string	The instance ID of the Server Load Balancer (SLB) instance associated with the cluster Ingress.	lb-2zehc05z3b8dwiifh****
meta_data	string	The cluster metadata information.	\"Addons\":***
name	string	The cluster name.	cluster-demo
network_mode `deprecated`	string	The network type used by the cluster, such as 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 associated with the cluster.	sg-25yq****
size	integer	The number of nodes in the cluster, including master nodes and worker nodes.	5
state	string	The running 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. `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 failed to be deleted. `waiting`: The cluster is in the accessed state, waiting to be connected. `disconnected`: The cluster is disconnected.	running
tags	array	The resource tags of the cluster.
	tag	The resource tags of the cluster.
updated	string	The time when the cluster was last updated.	2025-04-10T13:28:09+08:00
vpc_id	string	The VPC ID of the cluster. This is a required parameter when you create a cluster.	vpc-2zecuu62b9zw7a7qn****
vswitch_id `deprecated`	string	The vSwitch ID. This field is deprecated. Use vswitch_ids to query control plane vSwitches, and use vswitch_ids in node pools to query data plane vSwitches.	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 zone where the cluster is deployed.	cn-beijing-a
master_url	string	The access addresses of the cluster, including internal network access address and public network access address.	{\"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`: Not enabled. Default value: false.	false
profile	string	The cluster child class. `Default`: ACK managed cluster, including ACK cluster Pro and ACK cluster Basic. `Edge`: ACK Edge cluster, including ACK Edge cluster Pro and ACK Edge cluster Basic. `Serverless`: ACK Serverless cluster, including ACK Serverless cluster Pro and ACK Serverless cluster Basic. `Lingjun`: ACK Lingjun cluster, available in Pro.	Default
cluster_spec	string	The cluster specification when `cluster_type` is set to `ManagedKubernetes` and `profile` is configured. Valid values: `ack.standard`: Basic (selected by default when the value is empty) `ack.pro.small`: Pro `ack.pro.xlarge`: Pro XL `ack.pro.2xlarge`: Pro 2XL `ack.pro.4xlarge`: Pro 4XL (requires contacting customer service to enable the whitelist) Pro XL, Pro 2XL, and Pro 4XL are three tiers provided by ACK Pro Provisioned Control Plane. By pre-allocating and dedicating control plane resources, these tiers ensure that API concurrency and Pod scheduling capabilities remain at a consistently high level. They are suitable for AI training and inference, ultra-large-scale clusters, and mission-critical workloads. For information about the cluster management fees for Pro and provisioned control plane editions, see Cluster management fees.	ack.pro.small
worker_ram_role_name	string	The name of the Worker RAM role that authorizes ECS instances to serve as cluster worker nodes.	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
maintenance_window	maintenance_window	The cluster maintenance window configuration. This takes effect only for managed clusters (ACK Pro clusters).
parameters `deprecated`	object	The collection of cluster ROS parameters.
	string	The ROS parameter.	"ALIYUN::Region": "cn-qingdao"
container_cidr	string	The Pod CIDR block, configured for Flannel networking.	172.20.xx.xx/16
service_cidr	string	The Service CIDR block.	172.21.xx.xx/20
proxy_mode	string	The kube-proxy mode. `iptables`: A mature and stable kube-proxy mode. Service discovery and load balancing for Kubernetes Services are configured using iptables rules. However, performance is moderate and affected by scale. This mode is suitable for clusters with a small number of Services. `ipvs`: A high-performance kube-proxy mode. Service discovery and load balancing for Kubernetes Services are configured using the Linux IPVS module. This mode is suitable for clusters with a large number of Services that require high-performance load balancing.	ipvs
timezone	string	The time zone.	Asia/Shanghai
node_cidr_mask	string	Applicable only to the Flannel network plugin. The subnet mask size assigned to nodes, which controls the number of IP addresses that can be allocated to each node.	26
ip_stack	string	The IP protocol stack of the cluster. Valid values: ipv4: creates a cluster that supports only the IPv4 protocol stack. dual: creates a cluster that supports the IPv4/IPv6 dual stack.	ipv4
cluster_domain	string	The cluster local domain name.	cluster.local
extra_sans	array	The custom Subject Alternative Name (SAN) for the API Server certificate.
	string	The certificate SAN.	192.168.xx.xx
rrsa_config	object	The RRSA configuration.
enabled	boolean	Indicates whether RRSA is enabled.	true
oidc_name	string	The OIDC IdP name.	ack-rrsa-***
oidc_arn	string	The OIDC IdP ARN.	acs:ram::1138*:oidc-provider/ack-rrsa-*
max_oidc_token_expiration	string	The maximum configurable validity period of the OIDC token.	12h
audience	string	The default audience information of the OIDC token. Multiple values are separated by commas (,). The values are included as an array in the aud field of the OIDC token.	https://kubernetes.default.svc,https://example.***.com
issuer	string	The issuer information of the OIDC token. Multiple values are separated by commas (,). The first value becomes the value of the iss field in the OIDC token and the issuer URL of the OIDC IdP.	https://oidc-ack-***,https://kubernetes.default.svc
open_api_configuration_url	string	The OIDC configuration document URL.	https://oidc-ack-*/c12b990*/.well-known/openid-configuration
jwks_url	string	The OIDC public key information URL.	https://oidc-ack-*/c12b990*/keys
vswitch_ids	array	The vSwitches used by the cluster control plane.
	string	The vSwitches used by the cluster control plane.	vsw-2zete8s4qocqg0mf6****
operation_policy	object	The cluster automatic O&M policy.
cluster_auto_upgrade	object	The cluster auto-upgrade configuration.
enabled	boolean	Indicates whether cluster auto upgrade is enabled.	true
channel	string	The auto upgrade frequency of the cluster. 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	The control plane configuration for dedicated clusters.
charge_type	string	The billing type of control plane nodes.	PrePaid
period	integer	The subscription duration of nodes.	1
period_unit	string	The unit of the subscription duration for nodes.	Month
auto_renew	boolean	Indicates whether auto-renewal is enabled for nodes.	true
auto_renew_period	integer	The auto-renewal period of nodes.	1
instance_types	array	The instance types of nodes.
	string	The instance type.	ecs.g6.large
image_type	string	The operating system image type.	AliyunLinux3
image_id	string	The image ID.	aliyun_3_x64_20G_alibase_20240819
key_pair	string	The key pair name. Specify either this parameter or login_password.	ack
system_disk_category	string	The system cloud disk type of nodes.	cloud_essd
system_disk_size	integer	The system cloud disk size of nodes. Minimum value: 40.	120
system_disk_snapshot_policy_id	string	The automatic snapshot policy for node system cloud disks.	sp-2zej1nogjvovnz4z****
system_disk_performance_level	string	The performance level of node system cloud disks. This parameter takes effect only for ESSD cloud disks.	PL1
system_disk_provisioned_iops	integer	The provisioned read/write IOPS of node system cloud disks.	1000
system_disk_bursting_enabled	boolean	Indicates whether burst (performance burst) is enabled for node system cloud disks.	true
deploymentset_id	string	The deployment set ID.	ds-bp10b35imuam5amw****
cloud_monitor_flags	boolean	Indicates whether CloudMonitor is installed on nodes.	true
soc_enabled	boolean	Indicates whether MLPS security hardening 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 nodes.	none
runtime	string	The container runtime name.	containerd
node_port_range	string	The node service port range.	30000-32767
size	integer	The number of control plane nodes.	3
instance_metadata_options	InstanceMetadataOptions	The metadata access configuration of ECS instances.
auto_mode	object	The intelligent managed mode configuration.
enable	boolean	Indicates whether intelligent managed mode is enabled.	false
control_plane_endpoints_config	object	The cluster connection configuration.
load_balancers_config	array<object>	The load balancing configuration for cluster access.
	object
endpoint_type	string	The endpoint type.	private
load_balancer_id	string	The SLB instance associated with the endpoint.	nlb-0ogk9aaxxxxxxx
endpoint	string	The access address.	nlb-0ogk9aaxxxxxxx.cn-hangzhou.nlb.aliyuncsslb.com
internal_dns_config	object	The cluster internal domain name configuration, applicable to ACK managed clusters. The cluster internal domain name is used by node-side system components such as kubelet and kube-proxy to access the API Server. If the cluster internal domain name access is not enabled, node-side system components access the API Server through the CLB IP address.
bind_vpcs	array	The VPCs in which the internal domain name records take effect. By default, this includes the VPC where the cluster is deployed.
	string	The VPC in which the internal domain name records take effect.	vpc-xxxxxx
enabled	boolean	Indicates whether internal domain name access is enabled for the cluster. 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": {
    "load_balancers_config": [
      {
        "endpoint_type": "private",
        "load_balancer_id": "nlb-0ogk9aaxxxxxxx",
        "endpoint": "nlb-0ogk9aaxxxxxxx.cn-hangzhou.nlb.aliyuncsslb.com"
      }
    ],
    "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.