调用DescribeClusterDetail接口查询集群详细信息-容器服务 Kubernetes 版 ACK-阿里云-容器服务 Kubernetes 版 ACK(ACK)-阿里云帮助中心

您可以调用DescribeClusterDetail接口，根据集群ID查询指定集群的详细信息。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

cs:DescribeClusterDetail

get

*Cluster

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

无

请求语法

GET /clusters/{ClusterId} HTTP/1.1

路径参数

名称	类型	必填	描述	示例值
ClusterId	string	是	集群 ID。	cdde1f21ae22e483ebcb068a6eb7f****

请求参数

名称

类型

必填

描述

示例值

当前API无需请求参数

返回参数

名称	类型	描述	示例值
	object	返回体参数。
cluster_id	string	集群 ID。	c82e6987e2961451182edacd74faf****
cluster_type	string	集群类型。 `Kubernetes`: ACK 专有集群。 `ManagedKubernetes`：ACK 托管类的集群，包括 ACK 托管集群（ACK 集群 Pro 版、ACK 集群基础版）、ACK Serverless 集群（Pro 版、基础版）、ACK Edge 集群（Pro 版、基础版）、ACK 灵骏集群（Pro 版）。 `ExternalKubernetes`：注册集群。	Kubernetes
created	string	集群创建时间。	2025-04-07T09:57:26+08:00
init_version	string	集群初始化版本。	1.32.1-aliyun.1
current_version	string	集群当前版本。ACK 支持的 Kubernetes 版本，请参见 Kubernetes 版本发布概览。	1.32.1-aliyun.1
next_version	string	集群可升级版本。	1.xx.x-aliyun.1
deletion_protection	boolean	集群删除保护，防止通过控制台或 API 误删除集群。取值： `true`：启用集群删除保护，将不能通过控制台或 API 删除集群。 `false`：不启用集群删除保护，则能通过控制台或 API 删除集群。	true
docker_version `deprecated`	string	集群中的 Docker 版本。	19.03.5
external_loadbalancer_id `deprecated`	string	集群 Ingress LB 实例 ID。	lb-2zehc05z3b8dwiifh****
meta_data	string	集群元数据信息。	\"Addons\":***
name	string	集群名称。	cluster-demo
network_mode `deprecated`	string	集群采用的网络类型，例如：VPC 网络。	vpc
region_id	string	集群所在地域 ID。	cn-beijing
resource_group_id	string	集群资源组 ID。	rg-acfmyvw3wjm****
security_group_id	string	集群安全组 ID。	sg-25yq****
size	integer	集群节点数，包含 Master 节点及 Worker 节点。	5
state	string	集群运行状态，取值： `initial`：集群创建中。 `failed`：集群创建失败。 `running`：集群运行中。 `updating`：集群变更中。 `upgrading`：集群升级中。 `removing`：节点移除中。 `draining`：节点排水中。 `scaling`：集群伸缩中。 `inactive`：集群不活跃。 `unavailable`：集群不可用。 `deleting`：集群删除中。 `deleted`：集群已经被删除。 `delete_failed`：集群删除失败。 `waiting`：等待接入状态。 `disconnected`：断开状态。	running
tags	array	集群资源标签。
	tag	集群资源标签。
updated	string	集群更新时间。	2025-04-10T13:28:09+08:00
vpc_id	string	集群专有网络 ID，创建集群时的必填参数。	vpc-2zecuu62b9zw7a7qn****
vswitch_id `deprecated`	string	虚拟交换机 ID。该字段已废弃，控制面交换机请使用 vswitch_ids 查询，数据面交换机请通过节点池的 vswitch_ids 查询。	vsw-2zete8s4qocqg0mf6**,vsw-2zete8s4qocqg0mf6**
subnet_cidr `deprecated`	string	Pod 网络地址段。	172.20.xx.xx/16
zone_id `deprecated`	string	集群所在地域内的可用区 ID。	cn-beijing-a
master_url	string	集群访问地址，包含内网访问地址及公网访问地址。	{\"intranet_api_server_endpoint\":\"https://192.168.xx.xx:6443\"***}
private_zone `deprecated`	boolean	集群是否启用 PrivateZone。 `true`：启用。 `false`：不启用。默认值：false。	false
profile	string	集群子类型。 `Default`：ACK 托管集群，包括 ACK 集群 Pro 版和 ACK 集群基础版。 `Edge`：ACK Edge 集群，包括 ACK Edge 集群 Pro 版和 ACK Edge 集群基础版。 `Serverless`：ACK Serverless 集群，包括 ACK Serverless 集群 Pro 版和 ACK Serverless 集群基础版。 `Lingjun`：ACK 灵骏集群，提供 Pro 版。	Default
cluster_spec	string	选择`cluster_type`为`ManagedKubernetes`并配置`profile`时，集群的规格。取值： `ack.standard`：基础版（取值为空时默认选择） `ack.pro.small`：Pro 版 `ack.pro.xlarge`：Pro XL `ack.pro.2xlarge`：Pro 2XL `ack.pro.4xlarge`: Pro 4XL （需联系客服开通白名单） Pro XL、Pro 2XL、Pro 4XL 为ACK Pro 预设控制面提供的三个档位，通过预先分配并固化控制面资源，确保 API 并发与 Pod 调度能力始终处于确定的高水平状态，适用于 AI 训练推理、超大规模集群及关键任务型业务。 Pro 版及预设控制面版本的集群管理费用请参见集群管理费用。	ack.pro.small
worker_ram_role_name	string	Worker RAM 角色名称，授权 ECS 实例为集群 Woker 节点。	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
maintenance_window	maintenance_window	集群维护窗口配置，只在托管版本（即：ACK Pro 集群）中生效。
parameters `deprecated`	object	集群 ROS 参数集合。
	string	ROS 参数。	"ALIYUN::Region": "cn-qingdao"
container_cidr	string	Pod 网络网段，Flannel 网络配置。	172.20.xx.xx/16
service_cidr	string	服务网络网段。	172.21.xx.xx/20
proxy_mode	string	kube-proxy 代理模式 `iptables`: 成熟稳定的 kube-proxy 代理模式，Kubernetes Service 的服务发现和负载均衡使用 iptables 规则配置，但是性能一般，受规模影响较大，适用于集群存在少量的 Service。 `ipvs`：高性能的 kube-proxy 代理模式，Kubernetes Service 的服务发现和负载均衡使用 Linux IPVS 模块进行配置，适用于集群存在大量的 Service，对负载均衡有高性能要求的场景。	ipvs
timezone	string	时区。	Asia/Shanghai
node_cidr_mask	string	仅适用于 Flannel 网络插件。节点分配的子网掩码大小，用于控制节点可以分配的 IP 地址的数量。	26
ip_stack	string	集群的 IP 协议栈，可取值： ipv4：创建仅支持 IPv4 协议栈的集群； dual：创建支持 IPv4/IPv6 双栈的集群。	ipv4
cluster_domain	string	集群本地域名。	cluster.local
extra_sans	array	自定义的 API Server 证书 SAN（Subject Alternative Name）。
	string	证书 SAN。	192.168.xx.xx
rrsa_config	object	RRSA 配置。
enabled	boolean	是否启用 RRSA。	true
oidc_name	string	OIDC 身份提供商名称。	ack-rrsa-***
oidc_arn	string	OIDC 身份提供商 ARN。	acs:ram::1138*:oidc-provider/ack-rrsa-*
max_oidc_token_expiration	string	OIDC Token 可配置的最大有效期。	12h
audience	string	OIDC Token 的默认受众信息。包含多个值时将使用英文逗号（,）分隔。该值将以数组形式成为 OIDC Token 中 aud 字段的值。	https://kubernetes.default.svc,https://example.***.com
issuer	string	OIDC Token 的签发者信息。包含多个值时将使用英文逗号（,）分隔。其中第一个值将成为 OIDC Token 中 iss 字段的值以及 OIDC 身份提供商的颁发者 URL。	https://oidc-ack-***,https://kubernetes.default.svc
open_api_configuration_url	string	OIDC 配置文档 URL。	https://oidc-ack-*/c12b990*/.well-known/openid-configuration
jwks_url	string	OIDC 公钥信息 URL。	https://oidc-ack-*/c12b990*/keys
vswitch_ids	array	集群控制面虚拟交换机。
	string	集群控制面虚拟交换机。	vsw-2zete8s4qocqg0mf6****
operation_policy	object	集群自动运维策略。
cluster_auto_upgrade	object	集群自动升级。
enabled	boolean	是否开启集群自动升级。	true
channel	string	集群自动升级频次。更多信息，请参见升级频次。可取值： patch：最新补丁版本。 stable：次新次要版本。 rapid：最新次要版本。	patch
control_plane_config	object	专有版集群控制面配置。
charge_type	string	控制面节点付费类型。	PrePaid
period	integer	节点包年包月时长。	1
period_unit	string	节点包年包月时间单位。	Month
auto_renew	boolean	节点是否自动续费。	true
auto_renew_period	integer	节点自动续费时长。	1
instance_types	array	节点实例规格类型。
	string	实例规格。	ecs.g6.large
image_type	string	操作系统镜像类型。	AliyunLinux3
image_id	string	镜像 ID。	aliyun_3_x64_20G_alibase_20240819
key_pair	string	密钥对名称，和 login_password 二选一。	ack
system_disk_category	string	节点系统盘类型。	cloud_essd
system_disk_size	integer	节点系统盘大小，至少 40。	120
system_disk_snapshot_policy_id	string	节点自动快照备份策略。	sp-2zej1nogjvovnz4z****
system_disk_performance_level	string	节点系统盘磁盘性能，只针对 ESSD 磁盘生效。	PL1
system_disk_provisioned_iops	integer	节点系统盘预配置的读写 IOPS。	1000
system_disk_bursting_enabled	boolean	节点系统盘是否开启 Burst（性能突发）。	true
deploymentset_id	string	部署集 ID。	ds-bp10b35imuam5amw****
cloud_monitor_flags	boolean	是否为节点安装云监控。	true
soc_enabled	boolean	是否开启等保安全加固。	false
security_hardening_os	boolean	是否开启阿里云 OS 安全加固。	true
cpu_policy	string	节点 CPU 管理策略。	none
runtime	string	运行时名称。	containerd
node_port_range	string	节点服务端口范围。	30000-32767
size	integer	控制面节点数量。	3
instance_metadata_options	InstanceMetadataOptions	ECS 实例的元数据访问配置。
auto_mode	object	智能托管模式配置。
enable	boolean	是否开启智能托管模式。	false
control_plane_endpoints_config	object	集群连接配置。
internal_dns_config	object	集群内部域名配置，适用于 ACK 托管集群。集群内部域名用于 kubelet、kube-proxy 等节点侧系统组件访问 API Server；未开启集群内部域名访问时，节点侧系统组件将通过 CLB IP 方式访问。
bind_vpcs	array	集群内部域名记录解析生效的 VPC 范围，默认包括集群所在 VPC。
	string	集群内部域名记录解析生效的 VPC。	vpc-xxxxxx
enabled	boolean	是否开启集群内部域名访问。 true：开启集群内部域名访问，节点侧组件（kubelet、kube-proxy）将通过集群内部域名访问 API Server。	true

示例

正常返回示例

JSON格式

{
  "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
    }
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。