获取指定的集群
功能介绍
该API用于获取指定集群的详细信息。

集群管理的URL格式为:https://Endpoint/uri。其中uri为资源路径,也即API访问的路径。
URI
GET /api/v3/projects/{project_id}/clusters/{cluster_id}
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
project_id |
是 |
String |
参数解释: 项目ID,获取方式请参见如何获取接口URI中参数。 约束限制: 不涉及 取值范围: 账号的项目ID 默认取值: 不涉及 |
cluster_id |
是 |
String |
参数解释: 集群ID,获取方式请参见如何获取接口URI中参数。 约束限制: 不涉及 取值范围: 集群ID 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
detail |
否 |
String |
参数解释: 查询集群详细信息。 约束限制: 不涉及 取值范围: 若设置为true,获取集群下节点总数(totalNodesNumber)、正常节点数(activeNodesNumber)、CPU总量(totalNodesCPU)、内存总量(totalNodesMemory)和已安装插件列表(installedAddonInstances),已安装插件列表中包含名称(addonTemplateName)、版本号(version)、插件的状态信息(status),放入到annotation中。 默认取值: 无 |
请求参数
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
Content-Type |
是 |
String |
参数解释: 消息体的类型(格式) 约束限制: GET方法不做校验 取值范围: 默认取值: 不涉及 |
X-Auth-Token |
是 |
String |
参数解释: 调用接口的认证方式分为Token和AK/SK两种,如果您使用的Token方式,此参数为必填,请填写Token的值,获取方式请参见获取token。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
响应参数
状态码:200
参数 |
参数类型 |
描述 |
---|---|---|
kind |
String |
参数解释: API类型。 约束限制: 该值不可修改 取值范围: 默认取值: 不涉及 |
apiVersion |
String |
参数解释: API版本。 约束限制: 该值不可修改 取值范围: 默认取值: 不涉及 |
metadata |
ClusterMetadata object |
参数解释: 集群的基本信息,为集合类的元素类型,包含一组由不同名称定义的属性。 约束限制: 不涉及 |
spec |
ClusterSpec object |
spec是集合类的元素类型,您对需要管理的集群对象进行详细描述的主体部分都在spec中给出。CCE通过spec的描述来创建或更新对象。 |
status |
ClusterStatus object |
参数解释: 集群状态信息。 约束限制: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
name |
String |
参数解释: 集群名称。 约束限制: 不涉及 取值范围: 以小写字母开头,由小写字母、数字、中划线(-)组成,长度范围4-128位,且不能以中划线(-)结尾。 默认取值: 不涉及 |
uid |
String |
参数解释: 集群ID,资源唯一标识。 约束限制: 创建成功后自动生成,填写无效。 取值范围: 不涉及 默认取值: 不涉及 |
alias |
String |
参数解释: 集群显示名,用于在 CCE 界面显示,该名称创建后可修改。显示名和其他集群的名称、显示名不可以重复。 约束限制: 在创建集群、更新集群请求体中,集群显示名alias未指定或取值为空,表示与集群名称name一致。在创建集群等响应体中,集群显示名alias未配置时将不返回。 取值范围: 以中文或英文字符开头,由数字、中文、英文字符、中划线(-)组成,长度范围 4-128位,且不能以中划线(-)开头和结尾。 默认取值: 不涉及 |
annotations |
Map<String,String> |
参数解释: 集群注解,由key/value组成: "annotations": { "key1" : "value1", "key2" : "value2" } 约束限制: 该字段不会被数据库保存,当前仅用于指定集群待安装插件。 取值范围: 不涉及 默认取值: 不涉及 |
labels |
Map<String,String> |
参数解释: 集群标签,key/value对格式。 约束限制: 该字段值由系统自动生成,用于升级时前端识别集群支持的特性开关,用户指定无效。 取值范围: 不涉及 默认取值: 不涉及 |
creationTimestamp |
String |
参数解释: 集群创建时间。 约束限制: 创建集群时自动记录,不支持传入。 取值范围: 不涉及 默认取值: 不涉及 |
updateTimestamp |
String |
参数解释: 集群更新时间。 约束限制: 更新集群时自动记录,不支持传入。 取值范围: 不涉及 默认取值: 不涉及 |
timezone |
String |
参数解释: 集群时区。IANA Time Zone Database中收录的时区名称, 例如:"Asia/Shanghai"。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
category |
String |
参数解释: 集群类别。 约束限制: 不涉及 取值范围: CCE集群支持虚拟机与裸金属服务器混合、GPU、NPU等异构节点的混合部署,基于高性能网络模型提供全方位、多场景、安全稳定的容器运行环境。 默认取值: 容器网络参数设置非eni模式时,默认为CCE |
type |
String |
参数解释: 集群Master节点架构 约束限制: 不涉及 取值范围: 默认取值: VirtualMachine |
flavor |
String |
参数解释: 集群规格,当集群为v1.15及以上版本时支持创建后变更,详情请参见变更集群规格。请按实际业务需求进行选择 约束限制: 不涉及 取值范围: 默认取值: 不涉及 |
version |
String |
参数解释: 集群版本,与Kubernetes社区基线版本保持一致,建议选择最新商用版本。 在CCE控制台支持创建三种最新版本的集群。可登录CCE控制台创建集群,在“版本”处获取到集群版本。 其它集群版本,当前仍可通过api创建,但后续会逐渐下线,具体下线策略请关注CCE官方公告。 约束限制: 格式必须为:vX.Y[.Z[-rN]],例如 v1.30,v1.30.0,v1.30.0-r0 都将创建1.30版本的集群 取值范围: 不涉及 默认取值: |
platformVersion |
String |
参数解释: CCE集群平台版本号,表示集群版本(version)下的内部版本。用于跟踪某一集群版本内的迭代,集群版本内唯一,跨集群版本重新计数。 约束限制: 不支持用户指定,集群创建时自动选择对应集群版本的最新平台版本。 取值范围: platformVersion格式为:cce.X.Y 默认取值: 不涉及 |
legacyVersion |
String |
参数解释: CCE集群旧版本(已废弃),无实际功能,仅用于集群version与platformVersion组合展示,该版本号全局内唯一。如集群version为va.b, platformVersion为cce.X.Y,则legacyVersion值为va.b.X-rY。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
description |
String |
参数解释: 集群描述,对于集群使用目的的描述,可根据实际情况自定义,默认为空。集群创建成功后可通过接口更新指定的集群来做出修改,也可在CCE控制台中对应集群的“集群详情”下的“描述”处进行修改。 约束限制: 仅支持utf-8编码,长度必须小于等于200个字节 取值范围: 不涉及 默认取值: 不涉及 |
customSan |
Array of strings |
参数解释: 集群的API Server服务端证书中的自定义SAN(Subject Alternative Name)字段,遵从SSL标准X509定义的格式规范。 约束限制: 不允许出现同名重复。 取值范围: 格式符合IP和域名格式。 默认取值: 不涉及 示例: SAN 1: DNS Name=example.com SAN 2: DNS Name=www.example.com SAN 3: DNS Name=example.net SAN 4: IP Address=93.184.216.34 |
ipv6enable |
Boolean |
参数解释: 集群是否使用IPv6模式,1.15版本及以上支持。 约束限制: 开启IPv6后不支持iptables转发模式;VPC网络模式不支持IPv4/IPv6双栈网络。 取值范围: 默认取值: false |
hostNetwork |
HostNetwork object |
参数解释: 节点网络参数,包含了虚拟私有云VPC和子网的ID信息,而VPC是集群内节点之间的通信依赖,所以是必选的参数集。 约束限制: 不涉及 |
containerNetwork |
ContainerNetwork object |
参数解释: 容器网络参数,包含了容器网络类型和容器网段的信息。 约束限制: 不涉及 |
serviceNetwork |
ServiceNetwork object |
参数解释: 服务网段参数,包含IPv4 CIDR。 约束限制: 不涉及 |
publicAccess |
PublicAccess object |
参数解释: 集群API访问控制。 约束限制: 不涉及 |
authentication |
Authentication object |
参数解释: 集群认证方式相关配置。 约束限制: 不涉及 |
billingMode |
Integer |
参数解释: 集群的计费方式。 约束限制: 不涉及 取值范围: 默认取值: 默认0。 |
masters |
Array of MasterSpec objects |
参数解释: 集群控制节点的高级配置,支持指定控制节点的可用区。 约束限制: 该参数未配置时将不返回。 |
kubernetesSvcIpRange |
String |
参数解释: 服务网段参数,kubernetes clusterIP取值范围,1.11.7版本及以上支持。创建集群时如若未传参,默认为"10.247.0.0/16"。该参数废弃中,推荐使用新字段serviceNetwork,包含IPv4服务网段。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
clusterTags |
Array of ResourceTag objects |
参数解释: 集群资源标签。 约束限制: 不涉及 |
kubeProxyMode |
String |
参数解释: 服务转发模式。 约束限制: 不涉及 取值范围:
默认取值: 默认使用iptables转发模式。 |
az |
String |
参数解释: 可用区(废弃中)。 约束限制: 仅查询接口返回该字段。 |
extendParam |
ClusterExtendParam object |
参数解释: 集群扩展字段,可配置多可用区集群、专属CCE集群,以及将集群创建在特定的企业项目下等。 约束限制: 不涉及 |
supportIstio |
Boolean |
参数解释: 支持Istio。 约束限制: 不涉及 取值范围: 默认取值: 默认true |
deletionProtection |
Boolean |
参数解释: 集群删除保护,如果开启后用户将无法删除该集群。 约束限制: 不涉及。 取值范围: 默认取值: 默认false |
configurationsOverride |
Array of PackageConfiguration objects |
参数解释: 覆盖集群默认组件配置。 约束限制: 若指定了不支持的组件或组件不支持的参数,该配置项将被忽略。 |
clusterOps |
ClusterOps object |
参数解释: 集群运维相关配置。 约束限制: 不涉及 |
encryptionConfig |
EncryptionConfig object |
参数解释: secret资源落盘加密配置,当前仅支持配置一种加密方式。默认使用cce托管密钥(用户侧不感知该密钥)进行加密。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
vpc |
String |
参数解释: 用于创建节点的VPC的ID。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 获取方法如下: |
subnet |
String |
参数解释: 用于创建节点的子网的网络ID。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 获取方法如下: |
SecurityGroup |
String |
参数解释: 集群默认的Node节点安全组ID。 约束限制: 不涉及 取值范围: 不涉及 默认取值:
说明:
指定Node节点安全组需要放通部分端口来保证正常通信。 |
controlPlaneSecurityGroup |
String |
参数解释: 集群控制面节点安全组ID。 约束限制: 创建成功后自动生成,填写无效。 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
mode |
String |
参数解释: 容器网络类型。 约束限制: 只可选择一个容器网络类型。 取值范围: 默认取值: 不涉及 |
cidr |
String |
参数解释: 容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19,如存在网段冲突,将会报错。 约束限制: 此参数在集群创建后不可更改,请谨慎选择。(已废弃,如填写cidrs将忽略该cidr) vpc网络模式的集群在创建后可以新增网段参数,不可修改已有网段参数,需要重新创建集群才能调整。 取值范围: 满足IPv4 CIDR格式 默认取值: 不填此参数时,将从172.(16 ~ 31).0.0/16、10.(0 | 16 | 32 | 48 | 64 | 80 | 96 | 112).0.0/12中随机分配一个不冲突的网段供用户使用。 |
cidrs |
Array of ContainerCIDR objects |
参数解释: 容器网络网段列表。1.21及新版本集群使用cidrs字段,当集群网络类型为vpc-router类型时,支持多个容器网段,最多配置20个;1.21之前版本若使用cidrs字段,则取值cidrs数组中的第一个cidr元素作为容器网络网段地址。 约束限制: 容器隧道网络模式的集群在创建之后,无法修改网段参数; vpc网络模式的集群在创建后可以新增网段参数,不可修改已有网段参数,需要重新创建集群才能调整。 |
参数 |
参数类型 |
描述 |
---|---|---|
cidr |
String |
参数解释: 容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19。 约束限制: 如存在网段冲突,将会报错。 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
eniSubnetId |
String |
参数解释: ENI所在子网的IPv4子网ID。 约束限制: 暂不支持IPv6。该字段将会被废弃,推荐使用新字段subnets。 取值范围: 不涉及 默认取值: 不涉及 获取方法如下: |
eniSubnetCIDR |
String |
参数解释: ENI子网CIDR。 约束限制: 废弃中,推荐使用新字段subnets。 取值范围: 不涉及 默认取值: 不涉及 |
subnets |
Array of NetworkSubnet objects |
参数解释: IPv4子网ID列表。 约束限制: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
subnetID |
String |
参数解释: 用于创建容器网卡的子网的IPv4子网ID。 约束限制: 暂不支持IPv6 取值范围: 不涉及 默认取值: 不涉及 获取方法如下: |
参数 |
参数类型 |
描述 |
---|---|---|
IPv4CIDR |
String |
参数解释: kubernetes clusterIP IPv4 CIDR取值范围。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 默认为"10.247.0.0/16"。 |
IPv6CIDR |
String |
参数解释: kubernetes clusterIP IPv6 CIDR取值范围。 约束限制: 仅开启IPV6双栈的Turbo集群支持配置IPv6服务网段。 取值范围: 不涉及 默认取值: Turbo集群默认为"fc00::/112" CCE集群默认为"fd00:1234::/120" |
参数 |
参数类型 |
描述 |
---|---|---|
cidrs |
Array of strings |
参数解释: 允许访问集群API的白名单网段列表,建议对VPC网段、容器网段放通。 约束限制: 该字段仅支持创建集群时传入,更新时指定无效 取值范围: 不涉及 默认取值: 默认无白名单配置,为["0.0.0.0/0"]。 |
参数 |
参数类型 |
描述 |
---|---|---|
mode |
String |
参数解释: 集群认证模式。 约束限制: 不涉及 取值范围:
默认取值: |
authenticatingProxy |
AuthenticatingProxy object |
参数解释: authenticatingProxy模式相关配置。 约束限制: 认证模式为authenticating_proxy时必选。 |
参数 |
参数类型 |
描述 |
---|---|---|
ca |
String |
参数解释: authenticating_proxy模式配置的x509格式CA证书(base64编码)。 约束限制: 当集群认证模式为authenticating_proxy时,此项必须填写。 取值范围: 最大长度:1M。 默认取值: 不涉及 |
cert |
String |
参数解释: authenticating_proxy模式配置的x509格式CA证书签发的客户端证书,用于kube-apiserver到扩展apiserver的认证。(base64编码)。 约束限制: 当集群认证模式为authenticating_proxy时,此项必须填写。 取值范围: 最大长度:1M。 默认取值: 不涉及 |
privateKey |
String |
参数解释: authenticating_proxy模式配置的x509格式CA证书签发的客户端证书时对应的私钥,用于kube-apiserver到扩展apiserver的认证。Kubernetes集群使用的私钥尚不支持密码加密,请使用未加密的私钥。(base64编码)。 约束限制: 当集群认证模式为authenticating_proxy时,此项必须填写。 取值范围: 最大长度:1M。 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
availabilityZone |
String |
参数解释: 控制节点所在的可用区,需要指定可用区(AZ)的名称。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
key |
String |
参数解释: Key值。 约束限制: 不涉及 取值范围: 默认取值: 不涉及 |
value |
String |
参数解释: Value值。 约束限制: 不涉及 取值范围: 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
clusterAZ |
String |
参数解释: 集群控制节点可用区配置。 约束限制: 不涉及 取值范围: 默认取值: 不指定默认随机分配可用区。 |
dssMasterVolumes |
String |
参数解释: 用于指定控制节点的系统盘和数据盘使用专属分布式存储,未指定或者值为空时,默认使用EVS云硬盘。 约束限制: 如果配置专属CCE集群,该字段为必选,请按照如下格式设置: <rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType> 字段说明: 取值范围: 不涉及 默认取值: 不涉及 样例:c950ee97-587c-4f24-8a74-3367e3da570f.sas;6edbc2f4-1507-44f8-ac0d-eed1d2608d38.ssd
说明:
非专属CCE集群不支持配置该字段。 |
enterpriseProjectId |
String |
参数解释: 集群所属的企业项目ID。 约束限制: 需要开通企业项目功能后才可配置企业项目。 取值范围: 不涉及 默认取值: 不涉及 |
kubeProxyMode |
String |
参数解释: 服务转发模式,支持以下两种实现: 约束限制: 此参数已废弃,若同时指定此参数和ClusterSpec下的kubeProxyMode,以ClusterSpec下的为准。 取值范围:
默认取值: 默认iptables。 |
clusterExternalIP |
String |
参数解释: 集群控制节点弹性公网IP,绑定后可以通过该弹性公网IP访问集群管控面API。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
alpha.cce/fixPoolMask |
String |
参数解释: 容器网络固定IP池掩码位数,该参数决定节点可分配容器IP数量,与创建节点时设置的maxPods参数共同决定节点最多可以创建多少个Pod, 具体请参见节点可创建的最大Pod数量说明。 约束限制: 仅vpc-router网络支持。 取值范围: 整数字符串取值范围: 24 ~ 28 默认取值: 默认值24 |
decMasterFlavor |
String |
参数解释: 专属CCE集群指定可控制节点的规格。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
dockerUmaskMode |
String |
参数解释: 集群默认Docker的UmaskMode配置。 约束限制: 不涉及 取值范围: 默认取值: 默认normal |
kubernetes.io/cpuManagerPolicy |
String |
参数解释: 集群CPU管理策略。 约束限制: 不涉及 取值范围: 默认取值: 默认none |
upgradefrom |
String |
参数解释: 记录集群通过何种升级方式升级到当前版本。 约束限制: 仅查询接口返回该字段 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
name |
String |
参数解释: 组件名称。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
configurations |
Array of ConfigurationItem objects |
参数解释: 组件配置项。 约束限制: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
name |
String |
参数解释: 覆盖集群默认组件配置。 约束限制: 若指定了不支持的组件或组件不支持的参数,该配置项将被忽略。 取值范围: 不涉及 默认取值: 不涉及 |
value |
AnyType |
参数解释: 覆盖集群默认组件配置。 约束限制: 若指定了不支持的组件或组件不支持的参数,该配置项将被忽略。 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
alarm |
AlarmInfo object |
参数解释: 告警助手参数配置。基于AOM服务的告警能力实现,提供集群内的告警快速检索、告警快速配置的能力,告警中心的指标类告警规则依赖云原生监控插件上报数据到AOM实例。 约束限制: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
topics |
Array of strings |
参数解释: 联系组列表。填写SMN主题名称,通过配置告警联系组,分组管理订阅终端,接收告警信息。 约束限制: 不涉及 |
alarmRuleTemplateId |
String |
参数解释: 开启告警助手时传入告警模板ID。默认采用容器场景下的告警规则模板。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
promInstanceID |
String |
参数解释: 开启告警助手时传入AOM普罗实例的id。若未安装普罗插件或者未对接AOM实例,此参数无需指定,告警中心将不会创建指标类告警规则。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
promEnterpriseProjectID |
String |
参数解释: 开启告警助手时传入AOM普罗实例的企业项目id。若未安装普罗插件或者未对接AOM实例,此参数无需指定,告警中心将不会创建指标类告警规则。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
参数类型 |
描述 |
---|---|---|
phase |
String |
参数解释: 集群状态。 约束限制: 不涉及 取值范围: |
jobID |
String |
参数解释: 任务ID,集群当前状态关联的任务ID。当前支持: 约束限制: 不涉及 取值范围: 不涉及
说明:
任务信息具有一定时效性,仅用于短期跟踪任务进度,请勿用于集群状态判断等额外场景。 |
reason |
String |
参数解释: 集群变为当前状态的原因,在集群在非“Available”状态下时,会返回此参数。 约束限制: 不涉及 取值范围: 不涉及 |
message |
String |
参数解释: 集群变为当前状态的原因的详细信息,在集群在非“Available”状态下时,会返回此参数。 约束限制: 不涉及 取值范围: 不涉及 |
endpoints |
Array of ClusterEndpoints objects |
参数解释: 集群中 kube-apiserver 的访问地址。 约束限制: 不涉及 |
deleteOption |
Object |
参数解释: 删除配置状态(仅删除请求响应包含) 约束限制: 不涉及 取值范围: 不涉及 |
deleteStatus |
Object |
参数解释: 删除状态信息(仅删除请求响应包含) 约束限制: 不涉及 取值范围: 不涉及 |
请求示例
无
响应示例
状态码:200
表示获取指定集群成功。
{ "kind" : "Cluster", "apiVersion" : "v3", "metadata" : { "alias" : "mycluster", "name" : "mycluster", "uid" : "4d1ecb2c-229a-11e8-9c75-0255ac100ceb", "creationTimestamp" : "2018-08-02 03:48:58.968214406 +0000 UTC", "updateTimestamp" : "2018-08-02 04:05:29.386391813 +0000 UTC" }, "spec" : { "type" : "VirtualMachine", "flavor" : "cce.s1.small", "version" : "v1.25", "platformVersion" : "cce.6.0", "legacyVersion" : "v1.25.6-r0", "description" : "this is a demo cluster", "customSan" : [ "192.168.1.0", "example.com" ], "hostNetwork" : { "vpc" : "4d1ecb2c-229a-11e8-9c75-0255ac100ceb", "subnet" : "4d1ecb2c-229a-11e8-9c75-0255ac100ceb", "controlPlaneSecurityGroup" : "14834251-ac69-460a-bfbd-7ac84274c52b" }, "containerNetwork" : { "mode" : "overlay_l2", "cidr" : "172.16.0.0/16" }, "authentication" : { "mode" : "x509", "authenticatingProxy" : { } }, "billingMode" : 0, "deletionProtection" : false }, "status" : { "phase" : "Available", "endpoints" : [ { "url" : "https://192.168.0.11:5443", "type" : "Internal" } ] } }
状态码
状态码 |
描述 |
---|---|
200 |
表示获取指定集群成功。 |
错误码
请参见错误码。