文档首页/ 云容器引擎 CCE/ API参考（安卡拉区域）/ API/ 集群管理/ 创建集群

更新时间：2024-12-04 GMT+08:00

查看PDF

创建集群

功能介绍

该API用于创建一个空集群（即只有控制节点Master，没有工作节点Node）。请在调用本接口完成集群创建之后，通过创建节点添加节点。

集群管理的URL格式为：https://Endpoint/uri。其中uri为资源路径，也即API访问的路径。
调用该接口创建集群时，默认不安装ICAgent，若需安装ICAgent，可在请求Body参数的annotations中加入"cluster.install.addons.external/install":"[{"addonTemplateName":"icagent"}]"的集群注解，将在创建集群时自动安装ICAgent。ICAgent是应用性能管理APM的采集代理，运行在应用所在的服务器上，用于实时采集探针所获取的数据，安装ICAgent是使用应用性能管理APM的前提。

接口约束

调用CCE接口创建集群之前，请检查是否已满足如下条件：

创建集群之前，您必须先确保已存在虚拟私有云，否则无法创建集群。若您已有虚拟私有云，可重复使用，无需重复创建。虚拟私有云为CCE集群提供一个隔离的、用户自主配置和管理的虚拟网络环境。
创建集群之前，请提前规划好容器网段和服务网段。网段参数在集群创建后不可更改，需要重新创建集群才能调整，请谨慎选择。
请确保已正确创建委托，并确保委托未被删除，委托校验失败将导致集群创建失败。建议登录CCE控制台，如没有创建委托，会提示您创建，如已经创建则无提示。
默认情况下，一个账户只能创建5个集群（每个Region下），如果您需要创建更多的集群，请申请增加配额。

URI

POST /api/v3/projects/{project_id}/clusters

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	项目ID，获取方式请参见如何获取接口URI中参数。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
Content-Type	是	String	消息体的类型（格式）
X-Auth-Token	是	String	调用接口的认证方式分为Token和AK/SK两种，如果您使用的Token方式，此参数为必填，请填写Token的值，获取方式请参见获取token。

表3 请求Body参数
参数	是否必选	参数类型	描述
kind	是	String	API类型，固定值“Cluster”或“cluster”，该值不可修改。
apiVersion	是	String	API版本，固定值“v3”，该值不可修改。
metadata	是	ClusterMetadata object	集群的基本信息，为集合类的元素类型，包含一组由不同名称定义的属性。
spec	是	ClusterSpec object	spec是集合类的元素类型，您对需要管理的集群对象进行详细描述的主体部分都在spec中给出。CCE通过spec的描述来创建或更新对象。
status	否	ClusterStatus object	集合类的元素类型，用于记录对象在系统中的当前状态信息，包含了集群状态和本次创建集群作业的jobID

表4 ClusterMetadata
参数	是否必选	参数类型	描述
name	是	String	集群名称。命名规则：以小写字母开头，由小写字母、数字、中划线(-)组成，长度范围4-128位，且不能以中划线(-)结尾。
uid	否	String	集群ID，资源唯一标识，创建成功后自动生成，填写无效。
alias	否	String	集群显示名，用于在 CCE 界面显示，该名称创建后可修改。命名规则：以小写字母开头，由小写字母、数字、中划线(-)组成，长度范围4-128位，且不能以中划线(-)结尾。显示名和其他集群的名称、显示名不可以重复。在创建集群、更新集群请求体中，集群显示名alias未指定或取值为空，表示与集群名称name一致。在查询集群等响应体中，集群显示名alias将必然返回，未配置时将返回集群名称name。
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	集群更新时间

表5 ClusterSpec
参数	是否必选	参数类型	描述
category	否	String	集群类别： CCE：CCE集群 CCE集群支持虚拟机与裸金属服务器混合、GPU、NPU等异构节点的混合部署，基于高性能网络模型提供全方位、多场景、安全稳定的容器运行环境。
type	否	String	集群Master节点架构： VirtualMachine：Master节点为x86架构服务器
flavor	是	String	集群规格，当集群为v1.15及以上版本时支持创建后变更，详情请参见变更集群规格。请按实际业务需求进行选择： 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：单控制节点的集群，控制节点数为1。单控制节点故障后，集群将不可用，但已运行工作负载不受影响。 s2：三控制节点的集群，即高可用集群，控制节点数为3。当某个控制节点故障时，集群仍然可用。 small：表示集群支持管理的最大节点规模为50节点。 medium：表示集群支持管理的最大节点规模为200节点。 large：表示集群支持管理的最大节点规模为1000节点。 xlarge：表示集群支持管理的最大节点规模为2000节点。
version	否	String	集群版本，与Kubernetes社区基线版本保持一致，建议选择最新版本。在CCE控制台支持创建两种最新版本的集群。可登录CCE控制台创建集群，在“版本”处获取到集群版本。其它集群版本，当前仍可通过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定义的格式规范。不允许出现同名重复。格式符合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	容器网络参数，包含了容器网络类型和容器网段的信息。
serviceNetwork	否	ServiceNetwork object	服务网段参数，包含IPv4 CIDR。
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：社区传统的kube-proxy模式，完全以iptables规则的方式来实现service负载均衡。该方式最主要的问题是在服务多的时候产生太多的iptables规则，非增量式更新会引入一定的时延，大规模情况下有明显的性能问题。 ipvs：主导开发并在社区获得广泛支持的kube-proxy模式，采用增量式更新，吞吐更高，速度更快，并可以保证service更新期间连接保持不断开，适用于大规模场景。说明：默认使用iptables转发模式。
az	否	String	可用区（仅查询返回字段）。
extendParam	否	ClusterExtendParam object	集群扩展字段，可配置多可用区集群、专属CCE集群，以及将集群创建在特定的企业项目下等。
supportIstio	否	Boolean	支持Istio
configurationsOverride	否	Array of PackageConfiguration objects	覆盖集群默认组件配置若指定了不支持的组件或组件不支持的参数，该配置项将被忽略。当前支持的可配置组件及其参数详见

表6 HostNetwork
参数	是否必选	参数类型	描述
vpc	是	String	用于创建控制节点的VPC的ID。获取方法如下：方法1：登录虚拟私有云服务的控制台界面，在虚拟私有云的详情页面查找VPC ID。方法2：通过虚拟私有云服务的API接口查询。
subnet	是	String	用于创建控制节点的subnet的网络ID。获取方法如下：方法1：登录虚拟私有云服务的控制台界面，单击VPC下的子网，进入子网详情页面，查找网络ID。方法2：通过虚拟私有云服务的查询子网列表接口查询。
SecurityGroup	否	String	集群默认的Node节点安全组ID，不指定该字段系统将自动为用户创建默认Node节点安全组，指定该字段时集群将绑定指定的安全组。Node节点安全组需要放通部分端口来保证正常通信。

表7 ContainerNetwork
参数	是否必选	参数类型	描述
mode	是	String	容器网络类型（只可选择其一） overlay_l2：容器隧道网络，通过OVS（OpenVSwitch）为容器构建的overlay_l2网络。 vpc-router：VPC网络，使用ipvlan和自定义VPC路由为容器构建的Underlay的l2网络。
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类型时，支持多个容器网段，最多配置20个；1.21之前版本若使用cidrs字段，则取值cidrs数组中的第一个cidr元素作为容器网络网段地址。此参数在集群创建后不可更改，请谨慎选择。

表8 ContainerCIDR
参数	是否必选	参数类型	描述
cidr	是	String	容器网络网段，建议使用网段10.0.0.0/12~19，172.16.0.0/16~19，192.168.0.0/16~19。

表9 EniNetwork
参数	是否必选	参数类型	描述
eniSubnetId	是	String	ENI所在子网的IPv4子网ID(暂不支持IPv6,废弃中)。获取方法如下：方法1：登录虚拟私有云服务的控制台界面，单击VPC下的子网，进入子网详情页面，查找IPv4子网ID。方法2：通过虚拟私有云服务的查询子网列表接口查询。
eniSubnetCIDR	否	String	ENI子网CIDR(废弃中)
subnets	是	Array of NetworkSubnet objects	IPv4子网ID列表

**表10** NetworkSubnet
参数	是否必选	参数类型	描述
subnetID	是	String	用于创建控制节点的subnet的IPv4子网ID(暂不支持IPv6)。获取方法如下：方法1：登录虚拟私有云服务的控制台界面，单击VPC下的子网，进入子网详情页面，查找IPv4子网ID。方法2：通过虚拟私有云服务的查询子网列表接口查询。

**表11** ServiceNetwork
参数	是否必选	参数类型	描述
IPv4CIDR	否	String	kubernetes clusterIP IPv4 CIDR取值范围。创建集群时若未传参，默认为"10.247.0.0/16"。

**表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值。不能为空，最多支持128个字符可用UTF-8格式表示的汉字、字母、数字和空格支持部分特殊字符：_.:/=+-@ 不能以"_sys_"开头
value	否	String	Value值。可以为空但不能缺省，最多支持255个字符可用UTF-8格式表示的汉字、字母、数字和空格支持部分特殊字符：_.:/=+-@

**表16** ClusterExtendParam
参数	是否必选	参数类型	描述
clusterAZ	否	String	集群控制节点可用区配置。 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缓存和调度延迟敏感的工作负载。
upgradefrom	否	String	记录集群通过何种升级方式升级到当前版本。

**表17** PackageConfiguration
参数	是否必选	参数类型	描述
name	否	String	组件名称
configurations	否	Array of ConfigurationItem objects	组件配置项

**表18** ConfigurationItem
参数	是否必选	参数类型	描述
name	否	String	组件配置项名称
value	否	Object	组件配置项值

**表19** ClusterStatus
参数	是否必选	参数类型	描述
phase	否	String	集群状态，取值如下 Available：可用，表示集群处于正常状态。 Unavailable：不可用，表示集群异常，需手动删除。 ScalingUp：扩容中，表示集群正处于扩容过程中。 ScalingDown：缩容中，表示集群正处于缩容过程中。 Creating：创建中，表示集群正处于创建过程中。 Deleting：删除中，表示集群正处于删除过程中。 Upgrading：升级中，表示集群正处于升级过程中。 Resizing：规格变更中，表示集群正处于变更规格中。 RollingBack：回滚中，表示集群正处于回滚过程中。 RollbackFailed：回滚异常，表示集群回滚异常。 Hibernating：休眠中，表示集群正处于休眠过程中。 Hibernation：已休眠，表示集群正处于休眠状态。 Awaking：唤醒中，表示集群正处于从休眠状态唤醒的过程中。 Empty：集群无任何资源（已废弃） Error：错误，表示集群资源异常，可尝试手动删除。
jobID	否	String	任务ID,集群当前状态关联的任务ID。当前支持: 创建集群时返回关联的任务ID，可通过任务ID查询创建集群的附属任务信息；删除集群或者删除集群失败时返回关联的任务ID，此字段非空时，可通过任务ID查询删除集群的附属任务信息。说明：任务信息具有一定时效性，仅用于短期跟踪任务进度，请勿用于集群状态判断等额外场景。
reason	否	String	集群变为当前状态的原因，在集群在非“Available”状态下时，会返回此参数。
message	否	String	集群变为当前状态的原因的详细信息，在集群在非“Available”状态下时，会返回此参数。
endpoints	否	Array of ClusterEndpoints objects	集群中 kube-apiserver 的访问地址。
deleteOption	否	Object	删除配置状态（仅删除请求响应包含）
deleteStatus	否	Object	删除状态信息（仅删除请求响应包含）

**表20** ClusterEndpoints
参数	是否必选	参数类型	描述
url	否	String	集群中 kube-apiserver 的访问地址
type	否	String	集群访问地址的类型 Internal：用户子网内访问的地址 External：公网访问的地址

响应参数

状态码： 201

**表21** 响应Body参数
参数	参数类型	描述
kind	String	API类型，固定值“Cluster”或“cluster”，该值不可修改。
apiVersion	String	API版本，固定值“v3”，该值不可修改。
metadata	ClusterMetadata object	集群的基本信息，为集合类的元素类型，包含一组由不同名称定义的属性。
spec	ClusterSpec object	spec是集合类的元素类型，您对需要管理的集群对象进行详细描述的主体部分都在spec中给出。CCE通过spec的描述来创建或更新对象。
status	ClusterStatus object	集合类的元素类型，用于记录对象在系统中的当前状态信息，包含了集群状态和本次创建集群作业的jobID

**表22** ClusterMetadata
参数	参数类型	描述
name	String	集群名称。命名规则：以小写字母开头，由小写字母、数字、中划线(-)组成，长度范围4-128位，且不能以中划线(-)结尾。
uid	String	集群ID，资源唯一标识，创建成功后自动生成，填写无效。
alias	String	集群显示名，用于在 CCE 界面显示，该名称创建后可修改。命名规则：以小写字母开头，由小写字母、数字、中划线(-)组成，长度范围4-128位，且不能以中划线(-)结尾。显示名和其他集群的名称、显示名不可以重复。在创建集群、更新集群请求体中，集群显示名alias未指定或取值为空，表示与集群名称name一致。在查询集群等响应体中，集群显示名alias将必然返回，未配置时将返回集群名称name。
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	集群更新时间

**表23** ClusterSpec
参数	参数类型	描述
category	String	集群类别： CCE：CCE集群 CCE集群支持虚拟机与裸金属服务器混合、GPU、NPU等异构节点的混合部署，基于高性能网络模型提供全方位、多场景、安全稳定的容器运行环境。
type	String	集群Master节点架构： VirtualMachine：Master节点为x86架构服务器
flavor	String	集群规格，当集群为v1.15及以上版本时支持创建后变更，详情请参见变更集群规格。请按实际业务需求进行选择： 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：单控制节点的集群，控制节点数为1。单控制节点故障后，集群将不可用，但已运行工作负载不受影响。 s2：三控制节点的集群，即高可用集群，控制节点数为3。当某个控制节点故障时，集群仍然可用。 small：表示集群支持管理的最大节点规模为50节点。 medium：表示集群支持管理的最大节点规模为200节点。 large：表示集群支持管理的最大节点规模为1000节点。 xlarge：表示集群支持管理的最大节点规模为2000节点。
version	String	集群版本，与Kubernetes社区基线版本保持一致，建议选择最新版本。在CCE控制台支持创建两种最新版本的集群。可登录CCE控制台创建集群，在“版本”处获取到集群版本。其它集群版本，当前仍可通过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定义的格式规范。不允许出现同名重复。格式符合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	容器网络参数，包含了容器网络类型和容器网段的信息。
serviceNetwork	ServiceNetwork object	服务网段参数，包含IPv4 CIDR。
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：社区传统的kube-proxy模式，完全以iptables规则的方式来实现service负载均衡。该方式最主要的问题是在服务多的时候产生太多的iptables规则，非增量式更新会引入一定的时延，大规模情况下有明显的性能问题。 ipvs：主导开发并在社区获得广泛支持的kube-proxy模式，采用增量式更新，吞吐更高，速度更快，并可以保证service更新期间连接保持不断开，适用于大规模场景。说明：默认使用iptables转发模式。
az	String	可用区（仅查询返回字段）。
extendParam	ClusterExtendParam object	集群扩展字段，可配置多可用区集群、专属CCE集群，以及将集群创建在特定的企业项目下等。
supportIstio	Boolean	支持Istio
configurationsOverride	Array of PackageConfiguration objects	覆盖集群默认组件配置若指定了不支持的组件或组件不支持的参数，该配置项将被忽略。当前支持的可配置组件及其参数详见

**表24** HostNetwork
参数	参数类型	描述
vpc	String	用于创建控制节点的VPC的ID。获取方法如下：方法1：登录虚拟私有云服务的控制台界面，在虚拟私有云的详情页面查找VPC ID。方法2：通过虚拟私有云服务的API接口查询。
subnet	String	用于创建控制节点的subnet的网络ID。获取方法如下：方法1：登录虚拟私有云服务的控制台界面，单击VPC下的子网，进入子网详情页面，查找网络ID。方法2：通过虚拟私有云服务的查询子网列表接口查询。
SecurityGroup	String	集群默认的Node节点安全组ID，不指定该字段系统将自动为用户创建默认Node节点安全组，指定该字段时集群将绑定指定的安全组。Node节点安全组需要放通部分端口来保证正常通信。

**表25** ContainerNetwork
参数	参数类型	描述
mode	String	容器网络类型（只可选择其一） overlay_l2：容器隧道网络，通过OVS（OpenVSwitch）为容器构建的overlay_l2网络。 vpc-router：VPC网络，使用ipvlan和自定义VPC路由为容器构建的Underlay的l2网络。
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类型时，支持多个容器网段，最多配置20个；1.21之前版本若使用cidrs字段，则取值cidrs数组中的第一个cidr元素作为容器网络网段地址。此参数在集群创建后不可更改，请谨慎选择。

**表26** ContainerCIDR
参数	参数类型	描述
cidr	String	容器网络网段，建议使用网段10.0.0.0/12~19，172.16.0.0/16~19，192.168.0.0/16~19。

**表27** EniNetwork
参数	参数类型	描述
eniSubnetId	String	ENI所在子网的IPv4子网ID(暂不支持IPv6,废弃中)。获取方法如下：方法1：登录虚拟私有云服务的控制台界面，单击VPC下的子网，进入子网详情页面，查找IPv4子网ID。方法2：通过虚拟私有云服务的查询子网列表接口查询。
eniSubnetCIDR	String	ENI子网CIDR(废弃中)
subnets	Array of NetworkSubnet objects	IPv4子网ID列表

**表28** NetworkSubnet
参数	参数类型	描述
subnetID	String	用于创建控制节点的subnet的IPv4子网ID(暂不支持IPv6)。获取方法如下：方法1：登录虚拟私有云服务的控制台界面，单击VPC下的子网，进入子网详情页面，查找IPv4子网ID。方法2：通过虚拟私有云服务的查询子网列表接口查询。

**表29** ServiceNetwork
参数	参数类型	描述
IPv4CIDR	String	kubernetes clusterIP IPv4 CIDR取值范围。创建集群时若未传参，默认为"10.247.0.0/16"。

**表30** Authentication
参数	参数类型	描述
mode	String	集群认证模式。 kubernetes 1.11及之前版本的集群支持“x509”、“rbac”和“authenticating_proxy”，默认取值为“x509”。 kubernetes 1.13及以上版本的集群支持“rbac”和“authenticating_proxy”，默认取值为“rbac”。
authenticatingProxy	AuthenticatingProxy object	authenticatingProxy模式相关配置。认证模式为authenticating_proxy时必选。

**表31** 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时，此项必须填写。

**表32** MasterSpec
参数	参数类型	描述
availabilityZone	String	可用区

**表33** ResourceTag
参数	参数类型	描述
key	String	Key值。不能为空，最多支持128个字符可用UTF-8格式表示的汉字、字母、数字和空格支持部分特殊字符：_.:/=+-@ 不能以"_sys_"开头
value	String	Value值。可以为空但不能缺省，最多支持255个字符可用UTF-8格式表示的汉字、字母、数字和空格支持部分特殊字符：_.:/=+-@

**表34** ClusterExtendParam
参数	参数类型	描述
clusterAZ	String	集群控制节点可用区配置。 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缓存和调度延迟敏感的工作负载。
upgradefrom	String	记录集群通过何种升级方式升级到当前版本。

**表35** PackageConfiguration
参数	参数类型	描述
name	String	组件名称
configurations	Array of ConfigurationItem objects	组件配置项

**表36** ConfigurationItem
参数	参数类型	描述
name	String	组件配置项名称
value	Object	组件配置项值

**表37** ClusterStatus
参数	参数类型	描述
phase	String	集群状态，取值如下 Available：可用，表示集群处于正常状态。 Unavailable：不可用，表示集群异常，需手动删除。 ScalingUp：扩容中，表示集群正处于扩容过程中。 ScalingDown：缩容中，表示集群正处于缩容过程中。 Creating：创建中，表示集群正处于创建过程中。 Deleting：删除中，表示集群正处于删除过程中。 Upgrading：升级中，表示集群正处于升级过程中。 Resizing：规格变更中，表示集群正处于变更规格中。 RollingBack：回滚中，表示集群正处于回滚过程中。 RollbackFailed：回滚异常，表示集群回滚异常。 Hibernating：休眠中，表示集群正处于休眠过程中。 Hibernation：已休眠，表示集群正处于休眠状态。 Awaking：唤醒中，表示集群正处于从休眠状态唤醒的过程中。 Empty：集群无任何资源（已废弃） Error：错误，表示集群资源异常，可尝试手动删除。
jobID	String	任务ID,集群当前状态关联的任务ID。当前支持: 创建集群时返回关联的任务ID，可通过任务ID查询创建集群的附属任务信息；删除集群或者删除集群失败时返回关联的任务ID，此字段非空时，可通过任务ID查询删除集群的附属任务信息。说明：任务信息具有一定时效性，仅用于短期跟踪任务进度，请勿用于集群状态判断等额外场景。
reason	String	集群变为当前状态的原因，在集群在非“Available”状态下时，会返回此参数。
message	String	集群变为当前状态的原因的详细信息，在集群在非“Available”状态下时，会返回此参数。
endpoints	Array of ClusterEndpoints objects	集群中 kube-apiserver 的访问地址。
deleteOption	Object	删除配置状态（仅删除请求响应包含）
deleteStatus	Object	删除状态信息（仅删除请求响应包含）

**表38** ClusterEndpoints
参数	参数类型	描述
url	String	集群中 kube-apiserver 的访问地址
type	String	集群访问地址的类型 Internal：用户子网内访问的地址 External：公网访问的地址

请求示例

创建一个v1.19版本的CCE集群，集群规模为50节点，且为三控制节点高可用集群。

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

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "cluster"
  },
  "spec" : {
    "category" : "CCE",
    "flavor" : "cce.s2.small",
    "version" : "v1.19",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881"
    },
    "containerNetwork" : {
      "mode" : "vpc-router",
      "cidr" : "10.0.0.0/16"
    },
    "kubernetesSvcIpRange" : "10.247.0.0/16",
    "description" : "",
    "billingMode" : 0,
    "extendParam" : {
      "kubeProxyMode" : "iptables",
      "alpha.cce/fixPoolMask" : "25",
      "enterpriseProjectId" : "0"
    },
    "authentication" : {
      "mode" : "rbac"
    },
    "ipv6enable" : false
  }
}

创建一个v1.19版本的CCE集群，集群规模为50节点，且为三控制节点高可用集群，并在集群中安装ICAgent。

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

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "cluster",
    "annotations" : {
      "cluster.install.addons.external/install" : "[{\"addonTemplateName\":\"icagent\"}]"
    }
  },
  "spec" : {
    "category" : "CCE",
    "flavor" : "cce.s2.small",
    "version" : "v1.19",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881"
    },
    "containerNetwork" : {
      "mode" : "vpc-router",
      "cidr" : "10.0.0.0/16"
    },
    "kubernetesSvcIpRange" : "10.247.0.0/16",
    "description" : "",
    "billingMode" : 0,
    "extendParam" : {
      "kubeProxyMode" : "iptables",
      "alpha.cce/fixPoolMask" : "25",
      "enterpriseProjectId" : "0"
    },
    "authentication" : {
      "mode" : "rbac"
    },
    "ipv6enable" : false
  }
}

创建一个v1.19版本的CCE集群，集群规模为50节点，且为三控制节点高可用集群，并指定自定义的节点默认安全组。

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

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "cluster"
  },
  "spec" : {
    "category" : "CCE",
    "flavor" : "cce.s2.small",
    "version" : "v1.19",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881",
      "SecurityGroup" : "a4ef108c-2ec6-492f-a6c4-7b64e25ae490"
    },
    "containerNetwork" : {
      "mode" : "vpc-router",
      "cidr" : "10.0.0.0/16"
    },
    "kubernetesSvcIpRange" : "10.247.0.0/16",
    "description" : "",
    "billingMode" : 0,
    "extendParam" : {
      "kubeProxyMode" : "iptables",
      "alpha.cce/fixPoolMask" : "25",
      "enterpriseProjectId" : "0"
    },
    "authentication" : {
      "mode" : "rbac"
    },
    "ipv6enable" : false
  }
}

创建一个v1.25版本的CCE Turbo集群，集群规模为50节点，且为三控制节点高可用集群。

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

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "cluster"
  },
  "spec" : {
    "category" : "Turbo",
    "flavor" : "cce.s2.small",
    "version" : "v1.25",
    "type" : "VirtualMachine",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881"
    },
    "containerNetwork" : {
      "mode" : "eni"
    },
    "eniNetwork" : {
      "eniSubnetId" : "861fb11d-2f0e-4c10-a98a-166dc26e4ff7",
      "eniSubnetCIDR" : "192.168.0.0/24",
      "subnets" : [ {
        "subnetID" : "861fb11d-2f0e-4c10-a98a-166dc26e4ff7"
      } ]
    },
    "serviceNetwork" : {
      "IPv4CIDR" : "10.247.0.0/16"
    },
    "description" : "",
    "billingMode" : 0,
    "extendParam" : {
      "kubeProxyMode" : "iptables",
      "enterpriseProjectId" : "0"
    },
    "authentication" : {
      "mode" : "rbac"
    },
    "ipv6enable" : false
  }
}

响应示例

状态码： 201

表示创建集群作业下发成功。

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "alias" : "cluster",
    "name" : "cluster",
    "uid" : "bce956e1-87f3-11ec-b5e5-0255ac101514",
    "creationTimestamp" : "2022-02-07 08:55:45.785425492 +0000 UTC",
    "updateTimestamp" : "2022-02-07 08:55:45.78542824 +0000 UTC",
    "annotations" : {
      "jobid" : "bd42f724-87f3-11ec-b5e5-0255ac101514",
      "resourceJobId" : "bce99f78-87f3-11ec-b5e5-0255ac101514"
    }
  },
  "spec" : {
    "category" : "CCE",
    "type" : "VirtualMachine",
    "flavor" : "cce.s2.small",
    "version" : "v1.19.10-r0",
    "platformVersion" : "cce.5.0",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881"
    },
    "containerNetwork" : {
      "mode" : "vpc-router",
      "cidr" : "10.0.0.0/16",
      "cidrs" : [ {
        "cidr" : "10.0.0.0/16"
      } ]
    },
    "eniNetwork" : { },
    "authentication" : {
      "mode" : "rbac",
      "authenticatingProxy" : { }
    },
    "billingMode" : 0,
    "kubernetesSvcIpRange" : "10.247.0.0/16",
    "kubeProxyMode" : "iptables",
    "extendParam" : {
      "alpha.cce/fixPoolMask" : "25",
      "enterpriseProjectId" : "0",
      "kubeProxyMode" : "iptables",
      "orderID" : ""
    }
  },
  "status" : {
    "phase" : "Creating",
    "jobID" : "bd42f724-87f3-11ec-b5e5-0255ac101514"
  }
}

状态码

状态码	描述
201	表示创建集群作业下发成功。

错误码

请参见错误码。

父主题： 集群管理

上一篇：集群管理

下一篇：获取指定的集群

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消