更新时间:2022-04-18 GMT+08:00
分享

获取指定的集群

功能介绍

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

集群管理的URL格式为:https://Endpoint/uri。其中uri为资源路径,也即API访问的路径。

调试

您可以在API Explorer中调试该接口。

URI

GET /api/v3/projects/{project_id}/clusters/{cluster_id}

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID,获取方式请参见如何获取接口URI中参数

cluster_id

String

集群 ID,获取方式请参见如何获取接口URI中参数

表2 Query参数

参数

是否必选

参数类型

描述

detail

String

查询集群详细信息。若设置为true,获取集群下节点总数(totalNodesNumber)、正常节点数(activeNodesNumber)、CPU总量(totalNodesCPU)、内存总量(totalNodesMemory)和已安装插件列表(installedAddonInstances),已安装插件列表中包含名称(addonTemplateName)、版本号(version)、插件的状态信息(status),放入到annotation中。

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

Content-Type

String

消息体的类型(格式)

X-Auth-Token

String

调用接口的认证方式分为Token和AK/SK两种,如果您使用的Token方式,此参数为必填,请填写Token的值,获取方式请参见获取token

响应参数

状态码: 200

表4 响应Body参数

参数

参数类型

描述

kind

String

API类型,固定值“Cluster”或“cluster”,该值不可修改。

apiVersion

String

API版本,固定值“v3”,该值不可修改。

metadata

ClusterMetadata object

集群的基本信息,为集合类的元素类型,包含一组由不同名称定义的属性。

spec

ClusterSpec object

spec是集合类的元素类型,您对需要管理的集群对象进行详细描述的主体部分都在spec中给出。CCE通过spec的描述来创建或更新对象。

status

ClusterStatus object

集群状态信息

表5 ClusterMetadata

参数

参数类型

描述

name

String

集群名称。

命名规则:以小写字母开头,由小写字母、数字、中划线(-)组成,长度范围4-128位,且不能以中划线(-)结尾。

uid

String

资源唯一标识,创建成功后自动生成,填写无效

annotations

Map<String,String>

集群注解,由key/value组成:

"annotations": {
   "key1" : "value1",
   "key2" : "value2"
}
说明:
  • Annotations不用于标识和选择对象。Annotations中的元数据可以是small 或large,structured 或unstructured,并且可以包括标签不允许使用的字符。

  • 该字段不会被数据库保存,当前仅用于指定集群待安装插件。

  • 可通过加入"cluster.install.addons.external/install": "[{"addonTemplateName":"icagent"}]"的键值对在创建集群时安装ICAgent。

labels

Map<String,String>

集群标签,key/value对格式。

说明:

该字段值由系统自动生成,用于升级时前端识别集群支持的特性开关,用户指定无效。

creationTimestamp

String

集群创建时间

updateTimestamp

String

集群更新时间

表6 ClusterSpec

参数

参数类型

描述

category

String

集群类别:

  • CCE:CCE集群

    CCE集群支持虚拟机与裸金属服务器混合、GPU、NPU等异构节点的混合部署,基于高性能网络模型提供全方位、多场景、安全稳定的容器运行环境。

  • Turbo: CCE Turbo集群

    全面基于云原生基础设施构建的云原生2.0的容器引擎服务,具备软硬协同、网络无损、安全可靠、调度智能的优势,为用户提供一站式、高性价比的全新容器服务体验。

type

String

集群管控面节点架构:

  • VirtualMachine:管控面节点为x86架构服务器

  • ARM64: 管控面节点为鲲鹏(ARM架构)服务器

flavor

String

字段默认值:创建CCE集群或鲲鹏集群时,如果是非专属云为 cce.s1.small,专属云则为cce.dec.s1.small;

集群规格,集群创建完成后规格不可再变更,请按实际业务需求进行选择:

  • cce.s1.small: 小规模单控制节点CCE集群(最大50节点)

  • cce.s1.medium: 中等规模单控制节点CCE集群(最大200节点)

  • cce.s2.small: 小规模多控制节点CCE集群(最大50节点)

  • cce.s2.medium: 中等规模多控制节点CCE集群(最大200节点)

  • cce.s2.large: 大规模多控制节点CCE集群(最大1000节点)

  • cce.s2.xlarge: 超大规模多控制节点CCE集群(最大2000节点)

说明:
  • s1:单控制节点CCE集群。

  • s2:多控制节点CCE集群。

  • dec:专属CCE集群规格。如cce.dec.s1.small为小规模单控制节点专属CCE集群(最大50节点)。

  • 最大节点数:当前集群支持管理的最大节点规模,请根据业务需求选择。

  • 单控制节点集群:普通集群是单控制节点,控制节点故障后,集群将不可用,但已运行工作负载不受影响。

  • 多控制节点集群:即高可用集群,当某个控制节点故障时,集群仍然可用。

version

String

集群版本,与Kubernetes社区基线版本保持一致,建议选择最新版本。

在CCE控制台中支持创建两种最新版本的集群。可登录CCE控制台,单击“总览 > 购买Kubernetes集群”,在“版本”处获取到集群版本。 其它集群版本,当前仍可通过api创建,但后续会逐渐下线,具体下线策略请关注CCE官方公告。

说明:
  • 若不配置,默认创建最新版本的集群。

  • 若指定集群基线版本但是不指定具体r版本,则系统默认选择对应集群版本的最新r版本。建议不指定具体r版本由系统选择最新版本。

platformVersion

String

CCE集群平台版本号,表示集群版本(version)下的内部版本。用于跟踪某一集群版本内的迭代,集群版本内唯一,跨集群版本重新计数。不支持用户指定,集群创建时自动选择对应集群版本的最新平台版本。

platformVersion格式为:cce.X.Y

  • X: 表示内部特性版本。集群版本中特性或者补丁修复,或者OS支持等变更场景。其值从1开始单调递增。

  • Y: 表示内部特性版本的补丁版本。仅用于特性版本上线后的软件包更新,不涉及其他修改。其值从0开始单调递增。

description

String

集群描述,对于集群使用目的的描述,可根据实际情况自定义,默认为空。集群创建成功后可通过接口更新指定的集群来做出修改,也可在CCE控制台中对应集群的“集群详情”下的“描述”处进行修改。仅支持utf-8编码。

customSan

Array of strings

集群的API Server服务端证书中的自定义SAN(Subject Alternative Name)字段,遵从SSL标准X509定义的格式规范。

  1. 不允许出现同名重复。

  2. 格式符合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版本及以上支持。

hostNetwork

HostNetwork object

节点网络参数,包含了虚拟私有云VPC和子网的ID信息,而VPC是集群内节点之间的通信依赖,所以是必选的参数集。

containerNetwork

ContainerNetwork object

容器网络参数,包含了容器网络类型和容器网段的信息。

eniNetwork

EniNetwork object

云原生网络2.0网络配置,创建CCE Turbo集群时指定。

authentication

Authentication object

集群认证方式相关配置。

billingMode

Integer

集群的计费方式。计费方式为“按需计费”时,取值为“0”;计费方式为“包周期”时,取值为“1”。若不填,则默认为“按需计费”。

masters

Array of MasterSpec objects

控制节点的高级配置

kubernetesSvcIpRange

String

服务网段参数,kubernetes clusterIp取值范围,1.11.7版本及以上支持。

clusterTags

Array of ResourceTag objects

集群资源标签

kubeProxyMode

String

服务转发模式,支持以下两种实现:

  • iptables:社区传统的kube-proxy模式,完全以iptables规则的方式来实现service负载均衡。该方式最主要的问题是在服务多的时候产生太多的iptables规则,非增量式更新会引入一定的时延,大规模情况下有明显的性能问题。

  • ipvs:主导开发并在社区获得广泛支持的kube-proxy模式,采用增量式更新,吞吐更高,速度更快,并可以保证service更新期间连接保持不断开,适用于大规模场景。

az

String

可用区(仅查询返回字段)。 CCE支持的可用区请参考地区和终端节点

extendParam

ClusterExtendParam object

集群扩展字段,可配置多可用区集群、专属CCE集群,以及将集群创建在特定的企业项目下等。

supportIstio

Boolean

支持Istio

表7 HostNetwork

参数

参数类型

描述

vpc

String

用于创建控制节点的VPC的ID。 获取方法如下:

  • 方法1:登录虚拟私有云服务的控制台界面,在虚拟私有云的详情页面查找VPC ID。

  • 方法2:通过虚拟私有云服务的API接口查询,具体操作可参考 链接请参见查询VPC列表

说明:
  • 当前vpc-router容器网络模型不支持对接含拓展网段的VPC。

  • 若您的用户类型为企业用户,则需要保证vpc所属的企业项目ID和集群创建时选择的企业项目ID一致。集群所属的企业项目ID通过extendParam字段下的enterpriseProjectId体现,该值默认为"0",表示默认的企业项目。

subnet

String

用于创建控制节点的subnet的网络ID。获取方法如下:

  • 方法1:登录虚拟私有云服务的控制台界面,单击VPC下的子网,进入子网详情页面,查找网络ID。

  • 方法2:通过虚拟私有云服务的查询子网列表接口查询。 链接请参见查询子网列表

SecurityGroup

String

节点安全组ID,创建时指定无效

表8 ContainerNetwork

参数

参数类型

描述

mode

String

容器网络类型(只可选择其一)

  • overlay_l2:通过OVS(OpenVSwitch)为容器构建的overlay_l2网络。

  • vpc-router:使用ipvlan和自定义VPC路由为容器构建的Underlay的l2网络。

  • eni:云原生网络2.0,深度整合VPC原生ENI弹性网卡能力,采用VPC网段分配容器地址,支持ELB直通容器,享有高性能,创建CCE Turbo集群(公测中)时指定。

说明:
  • 容器隧道网络(Overlay):基于VXLAN技术实现的Overlay容器网络。VXLAN是将以太网报文封装成UDP报文进行隧道传输。容器网络是承载于VPC网络之上的Overlay网络平面,具有付出少量隧道封装性能损耗,获得了通用性强、互通性强、高级特性支持全面(例如NetworkPolicy网络隔离)的优势,可以满足大多数应用需求。

  • VPC网络:基于VPC网络的自定义路由,直接将容器网络承载于VPC网络之中。每个节点将会被分配固定大小的IP地址段。vpc-router网络由于没有隧道封装的消耗,容器网络性能相对于容器隧道网络有一定优势。vpc-router集群由于VPC路由中配置有容器网段与节点IP的路由,可以支持集群外直接访问容器实例等特殊场景。

cidr

String

容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19,如存在网段冲突,将会报错。

此参数在集群创建后不可更改,请谨慎选择。(已废弃,如填写cidrs将忽略该cidr)

cidrs

Array of ContainerCIDR objects

容器网络网段列表。1.21及新版本集群使用cidrs字段,当集群网络类型为vpc-router类型时,支持多个容器网段;1.21之前版本若使用cidrs字段,则取值cidrs数组中的第一个cidr元素作为容器网络网段地址。

此参数在集群创建后不可更改,请谨慎选择。

表9 ContainerCIDR

参数

参数类型

描述

cidr

String

容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19。

表10 EniNetwork

参数

参数类型

描述

eniSubnetId

String

用于创建控制节点的subnet的IPv4网络ID(暂不支持IPv6,废弃中)。获取方法如下:

  • 方法1:登录虚拟私有云服务的控制台界面,单击VPC下的子网,进入子网详情页面,查找IPv4子网ID。

  • 方法2:通过虚拟私有云服务的查询子网列表接口查询。 链接请参见查询子网列表

eniSubnetCIDR

String

ENI子网CIDR(废弃中)

subnets

Array of NetworkSubnet objects

IPv4子网ID列表

表11 NetworkSubnet

参数

参数类型

描述

subnetID

String

用于创建控制节点的subnet的IPv4网络ID(暂不支持IPv6)。获取方法如下:

  • 方法1:登录虚拟私有云服务的控制台界面,单击VPC下的子网,进入子网详情页面,查找IPv4子网ID。

  • 方法2:通过虚拟私有云服务的查询子网列表接口查询。 链接请参见查询子网列表

表12 Authentication

参数

参数类型

描述

mode

String

集群认证模式。

  • kubernetes 1.11及之前版本的集群支持“x509”、“rbac”和“authenticating_proxy”,默认取值为“x509”。

  • kubernetes 1.13及以上版本的集群支持“rbac”和“authenticating_proxy”,默认取值为“rbac”。

authenticatingProxy

AuthenticatingProxy object

authenticatingProxy模式相关配置。认证模式为authenticating_proxy时必选。

表13 AuthenticatingProxy

参数

参数类型

描述

ca

String

authenticating_proxy模式配置的x509格式CA证书(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。

最大长度:1M

cert

String

authenticating_proxy模式配置的x509格式CA证书签发的客户端证书,用于kube-apiserver到扩展apiserver的认证。(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。

privateKey

String

authenticating_proxy模式配置的x509格式CA证书签发的客户端证书时对应的私钥,用于kube-apiserver到扩展apiserver的认证。Kubernetes集群使用的私钥尚不支持密码加密,请使用未加密的私钥。(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。

表14 MasterSpec

参数

参数类型

描述

availabilityZone

String

可用区

表15 ResourceTag

参数

参数类型

描述

key

String

Key值。

  • 支持最大长度为36个UTF-8字符。

  • 不支持特殊字符[=*<>\,|/]+

  • 不支持ASCII控制字符(0-31)

value

String

Value值。

  • 支持最大长度为43个UTF-8字符。

  • 不支持特殊字符[=*<>\,|/]+

  • 不支持ASCII控制字符(0-31)

表16 ClusterExtendParam

参数

参数类型

描述

clusterAZ

String

集群控制节点可用区配置。 CCE支持的可用区请参考地区和终端节点

  • multi_az:多可用区,可选。仅使用高可用集群时才可以配置多可用区。

  • 专属云计算池可用区:用于指定专属云可用区部署集群控制节点。如果需配置专属CCE集群,该字段为必选。

dssMasterVolumes

String

用于指定控制节点的系统盘和数据盘使用专属分布式存储,未指定或者值为空时,默认使用EVS云硬盘。 如果配置专属CCE集群,该字段为必选,请按照如下格式设置:

<rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType>

字段说明:

  • rootVol为系统盘;dataVol为数据盘;

  • dssPoolID为专属分布式存储池ID;

  • volType为专属分布式存储池的存储类型,如SAS、SSD。

样例:c950ee97-587c-4f24-8a74-3367e3da570f.sas;6edbc2f4-1507-44f8-ac0d-eed1d2608d38.ssd

说明:

非专属CCE集群不支持配置该字段。

enterpriseProjectId

String

集群所属的企业项目ID。

说明:
  • 需要开通企业项目功能后才可配置企业项目。

  • 集群所属的企业项目与集群下所关联的其他云服务资源所属的企业项目必须保持一致。

kubeProxyMode

String

服务转发模式,支持以下两种实现:

  • iptables:社区传统的kube-proxy模式,完全以iptables规则的方式来实现service负载均衡。该方式最主要的问题是在服务多的时候产生太多的iptables规则,非增量式更新会引入一定的时延,大规模情况下有明显的性能问题

  • ipvs:主导开发并在社区获得广泛支持的kube-proxy模式,采用增量式更新,吞吐更高,速度更快,并可以保证service更新期间连接保持不断开,适用于大规模场景。

说明:

此参数已废弃,若同时指定此参数和ClusterSpec下的kubeProxyMode,以ClusterSpec下的为准。

clusterExternalIP

String

master 弹性公网IP

alpha.cce/fixPoolMask

String

容器网络固定IP池掩码位数,仅vpc-router网络支持。

该参数决定节点可分配容器IP数量,与创建节点时设置的maxPods参数共同决定节点最多可以创建多少个Pod, 具体请参见节点最多可以创建多少Pod

整数字符传取值范围: 24 ~ 28

decMasterFlavor

String

专属CCE集群指定可控制节点的规格。

dockerUmaskMode

String

集群默认Docker的UmaskMode配置,可取值为secure或normal,不指定时默认为normal。

kubernetes.io/cpuManagerPolicy

String

集群CPU管理策略。取值为none或static,默认为none。

  • none:关闭工作负载实例独占CPU核的功能,优点是CPU共享池的可分配核数较多

  • static:支持给节点上的工作负载实例配置CPU独占,适用于对CPU缓存和调度延迟敏感的工作负载,Turbo集群下仅对普通容器节点有效,安全容器节点无效。

orderID

String

订单ID,集群付费类型为自动付费包周期类型时,响应中会返回此字段。

periodType

String

  • month:月

  • year:年

说明:

billingMode为1(包周期)时生效,且为必选。

periodNum

Integer

订购周期数,取值范围:

  • periodType=month(周期类型为月)时,取值为[1-9]。

  • periodType=year(周期类型为年)时,取值为1-3。

说明:

billingMode为1时生效,且为必选。

isAutoRenew

String

是否自动续订

  • “true”:自动续订

  • “false”:不自动续订

说明:

billingMode为1时生效,不填写此参数时默认不会自动续费。

isAutoPay

String

是否自动扣款

  • “true”:自动扣款

  • “false”:不自动扣款

说明:

billingMode为1时生效,不填写此参数时默认不会自动扣款。

upgradefrom

String

记录集群通过何种升级方式升级到当前版本。

表17 ClusterStatus

参数

参数类型

描述

phase

String

集群状态,取值如下

  • Available:可用,表示集群处于正常状态。

  • Unavailable:不可用,表示集群异常,需手动删除或联系管理员删除。

  • ScalingUp:扩容中,表示集群正处于扩容过程中。

  • ScalingDown:缩容中,表示集群正处于缩容过程中。

  • Creating:创建中,表示集群正处于创建过程中。

  • Deleting:删除中,表示集群正处于删除过程中。

  • Upgrading:升级中,表示集群正处于升级过程中。

  • Resizing:规格变更中,表示集群正处于变更规格中。

  • RollingBack:回滚中,表示集群正处于回滚过程中。

  • RollbackFailed:回滚异常,表示集群回滚异常,需联系管理员进行回滚重试。

  • Empty:集群无任何资源

jobID

String

作业ID

reason

String

集群变为当前状态的原因,在集群在非“Available”状态下时,会返回此参数。

message

String

集群变为当前状态的原因的详细信息,在集群在非“Available”状态下时,会返回此参数。

endpoints

Array of ClusterEndpoints objects

集群中 kube-apiserver 的访问地址。

isLocked

Boolean

CBC资源锁定

lockScene

String

CBC资源锁定场景

lockSource

String

锁定资源

lockSourceId

String

锁定的资源ID

deleteOption

Object

删除配置状态(仅删除请求响应包含)

deleteStatus

Object

删除状态信息(仅删除请求响应包含)

表18 ClusterEndpoints

参数

参数类型

描述

url

String

集群中 kube-apiserver 的访问地址

type

String

集群访问地址的类型

  • Internal:用户子网内访问的地址

  • External:公网访问的地址

请求示例

响应示例

状态码: 200

表示获取指定集群成功。

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "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.7.3-r13",
    "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"
    },
    "containerNetwork" : {
      "mode" : "overlay_l2",
      "cidr" : "172.16.0.0/16"
    },
    "authentication" : {
      "mode" : "x509",
      "authenticatingProxy" : { }
    },
    "billingMode" : 0
  },
  "status" : {
    "phase" : "Available",
    "endpoints" : [ {
      "url" : "https://192.168.0.11:5443",
      "type" : "Internal"
    } ]
  }
}

状态码

状态码

描述

200

表示获取指定集群成功。

错误码

请参见错误码

分享:

    相关文档

    相关产品

close