创建集群
功能介绍
该API用于创建一个空集群(即只有控制节点Master,没有工作节点Node)。请在调用本接口完成集群创建之后,通过创建节点添加节点。
接口约束
调用CCE接口创建集群之前,请检查是否已满足如下条件:
创建集群之前,您必须先确保已存在虚拟私有云,否则无法创建集群。若您已有虚拟私有云,可重复使用,无需重复创建。虚拟私有云为CCE集群提供一个隔离的、用户自主配置和管理的虚拟网络环境。创建方法请参见创建虚拟私有云和子网
您需要新建一个密钥对,用于远程登录节点时的身份认证。创建方法请参见创建密钥对。若使用密码登录节点,请跳过此操作。
创建集群之前,请提前规划好容器网段和服务网段。网段参数在集群创建后不可更改,需要重新创建集群才能调整,请谨慎选择。
请确保已正确创建委托,并确保委托未被删除,委托校验失败将导致集群创建失败。新建委托请参见委托其他云服务管理资源,创建委托时委托类型选择“云服务”,单击“选择”按钮并在弹出的窗口中选择“ECS BMS”,即允许ECS或BMS调用云服务。
请确保您有足够的集群配额,集群配额校验不通过将导致创建失败。如何查看配额请参见关于配额。
调试
您可以在API Explorer中调试该接口。
URI
POST /api/v3/projects/{project_id}/clusters
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
project_id |
是 |
String |
项目ID,获取方式请参见如何获取接口URI中参数 |
请求参数
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
Content-Type |
是 |
String |
消息体的类型(格式) 缺省值:application/json |
X-Auth-Token |
是 |
String |
"调用接口的认证方式分为Token和AK/SK两种,如果您使用的Token方式,此参数为必填,请填写Token的值,获取方式请参见获取token。" 最大长度:16384 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
kind |
是 |
String |
API类型,固定值“Cluster”或“cluster”,该值不可修改。 缺省值:Cluster |
apiVersion |
是 |
String |
API版本,固定值“v3”,该值不可修改。 缺省值:v3 |
metadata |
是 |
ClusterMetadata object |
集群的基本信息,为集合类的元素类型,包含一组由不同名称定义的属性。 |
spec |
是 |
V3ClusterSpec object |
spec是集合类的元素类型,您对需要管理的集群对象进行详细描述的主体部分都在spec中给出。CCE通过spec的描述来创建或更新对象。 |
status |
否 |
ClusterStatus object |
集合类的元素类型,用于记录对象在系统中的当前状态信息,包含了集群状态和本次创建集群作业的jobID |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
name |
是 |
String |
集群名称。 命名规则:以小写字母开头,由小写字母、数字、中划线(-)组成,长度范围4-128位,且不能以中划线(-)结尾。 最小长度:4 最大长度:128 |
uid |
否 |
String |
资源唯一标识,创建成功后自动生成,填写无效 |
annotations |
否 |
Map<String,String> |
集群注解,由key/value组成: "annotations": { "key1" : "value1", "key2" : "value2" } 说明:
Annotations不用于标识和选择对象。Annotations中的元数据可以是small 或large,structured 或unstructured,并且可以包括标签不允许使用的字符。 该字段不会被数据库保存,当前仅用于指定集群待安装插件。 |
labels |
否 |
Map<String,String> |
集群标签,key/value对格式。 说明:
该字段值由系统自动生成,用于升级时前端识别集群支持的特性开关,用户指定无效。 |
creationTimestamp |
否 |
String |
集群创建时间 |
updateTimestamp |
否 |
String |
集群更新时间 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
type |
是 |
String |
集群类型:
基于Kubernetes来管理一组节点资源,支持虚拟机和裸金属的管理,Kubernetes将自动调度容器运行在可用节点上。在创建容器工作负载前,您需要存在一个可用集群。
鲲鹏容器集群(ARM指令集)提供了容器在鲲鹏(ARM架构)服务器上的运行能力,提供与X86服务器相同的调度伸缩和快速部署能力。 枚举值:
|
flavor |
是 |
String |
字段默认值:创建混合集群或鲲鹏集群时,如果是非专属云为 cce.s1.small,专属云则为 cce.dec.s1.small; 集群规格,集群创建完成后规格不可再变更,请按实际业务需求进行选择:
说明:
s1:单控制节点混合集群。 s2:多控制节点混合集群。 dec:专属混合集群规格。如cce.dec.s1.small为小规模单控制节点专属混合集群(最大50节点)。 最大节点数:当前集群支持管理的最大节点规模,请根据业务需求选择。 单控制节点集群:普通集群是单控制节点,控制节点故障后,集群将不可用,但已运行工作负载不受影响。 多控制节点集群:即高可用集群,当某个控制节点故障时,集群仍然可用。查看集群模式请参见如何排查已创建的集群是否为高可用集群? |
version |
否 |
String |
集群版本,与Kubernetes社区基线版本保持一致,建议选择最新版本。 在CCE控制台中支持创建两种最新版本的集群。可登录CCE控制台,单击“总览 > 购买Kubernetes集群”,在“版本”处获取到集群版本。 其它集群版本,当前仍可通过api创建,但后续会逐渐下线,具体下线策略请关注CCE官方公告。 说明:
|
description |
否 |
String |
集群描述,对于集群使用目的的描述,可根据实际情况自定义,默认为空。集群创建成功后可通过接口更新指定的集群来做出修改,也可在CCE控制台中对应集群的“集群详情”下的“描述”处进行修改。仅支持utf-8编码。 最小长度:0 最大长度:200 |
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”。若不填,则默认为“0”。 缺省值:0 |
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更新期间连接保持不断开,适用于大规模场景。 说明:
此参数目前仅在响应中体现,创建集群时请在extendParam中配置此参数。 枚举值:
|
az |
否 |
String |
可用区(仅查询返回字段) |
extendParam |
否 |
Map<String,String> |
扩展字段,key/value对格式。可配置多可用区集群、专属混合集群,以及将集群创建在特定的企业项目下。可配置的key/value对如下:
|
supportIstio |
否 |
Boolean |
支持Istio |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
vpc |
是 |
String |
用于创建控制节点的VPC的ID。该值在创建VPC和子网中获取。 获取方法如下:
说明:
当前vpc-router容器网络模型不支持对接含拓展网段的VPC。 若您的用户类型为企业用户,则需要保证vpc所属的企业项目ID和集群创建时选择的企业项目ID一致。集群所属的企业项目ID通过extendParam字段下的enterpriseProjectId体现,该值默认为"0",表示默认的企业项目。 最小长度:0 最大长度:64 |
subnet |
是 |
String |
用于创建控制节点的subnet的网络ID。获取方法如下:
最小长度:0 最大长度:64 |
SecurityGroup |
否 |
String |
节点安全组ID,创建时指定无效 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
mode |
是 |
String |
容器网络类型(只可选择其一)
说明:
最小长度:0 最大长度:64 枚举值:
|
cidr |
否 |
String |
容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19,如存在网段冲突,将自动重新选择。 当节点最大实例数为默认值110时,当前容器网段至少支持582个节点,此参数在集群创建后不可更改,请谨慎选择。 最小长度:0 最大长度:64 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
eniSubnetId |
是 |
String |
用于创建控制节点的subnet的网络ID。获取方法如下:
最小长度:0 最大长度:64 |
eniSubnetCIDR |
是 |
String |
ENI子网CIDR |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
mode |
否 |
String |
集群认证模式。
|
authenticatingProxy |
否 |
AuthenticatingProxy object |
authenticatingProxy模式相关配置。认证模式为authenticating_proxy时必选。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
ca |
否 |
String |
authenticating_proxy模式配置的x509格式CA证书(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。 最大长度:1M |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
key |
否 |
String |
Key值。
最小长度:1 最大长度:36 |
value |
否 |
String |
Value值。
最大长度:43 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
phase |
否 |
String |
集群状态,取值如下
|
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 |
删除状态信息(仅删除请求响应包含) |
响应参数
状态码: 201
参数 |
参数类型 |
描述 |
---|---|---|
kind |
String |
API类型,固定值“Cluster”或“cluster”,该值不可修改。 缺省值:Cluster |
apiVersion |
String |
API版本,固定值“v3”,该值不可修改。 缺省值:v3 |
metadata |
ClusterMetadata object |
集群的基本信息,为集合类的元素类型,包含一组由不同名称定义的属性。 |
spec |
V3ClusterSpec object |
spec是集合类的元素类型,您对需要管理的集群对象进行详细描述的主体部分都在spec中给出。CCE通过spec的描述来创建或更新对象。 |
status |
ClusterStatus object |
集合类的元素类型,用于记录对象在系统中的当前状态信息,包含了集群状态和本次创建集群作业的jobID |
参数 |
参数类型 |
描述 |
---|---|---|
name |
String |
集群名称。 命名规则:以小写字母开头,由小写字母、数字、中划线(-)组成,长度范围4-128位,且不能以中划线(-)结尾。 最小长度:4 最大长度:128 |
uid |
String |
资源唯一标识,创建成功后自动生成,填写无效 |
annotations |
Map<String,String> |
集群注解,由key/value组成: "annotations": { "key1" : "value1", "key2" : "value2" } 说明:
Annotations不用于标识和选择对象。Annotations中的元数据可以是small 或large,structured 或unstructured,并且可以包括标签不允许使用的字符。 该字段不会被数据库保存,当前仅用于指定集群待安装插件。 |
labels |
Map<String,String> |
集群标签,key/value对格式。 说明:
该字段值由系统自动生成,用于升级时前端识别集群支持的特性开关,用户指定无效。 |
creationTimestamp |
String |
集群创建时间 |
updateTimestamp |
String |
集群更新时间 |
参数 |
参数类型 |
描述 |
---|---|---|
type |
String |
集群类型:
基于Kubernetes来管理一组节点资源,支持虚拟机和裸金属的管理,Kubernetes将自动调度容器运行在可用节点上。在创建容器工作负载前,您需要存在一个可用集群。
鲲鹏容器集群(ARM指令集)提供了容器在鲲鹏(ARM架构)服务器上的运行能力,提供与X86服务器相同的调度伸缩和快速部署能力。 枚举值:
|
flavor |
String |
字段默认值:创建混合集群或鲲鹏集群时,如果是非专属云为 cce.s1.small,专属云则为 cce.dec.s1.small; 集群规格,集群创建完成后规格不可再变更,请按实际业务需求进行选择:
说明:
s1:单控制节点混合集群。 s2:多控制节点混合集群。 dec:专属混合集群规格。如cce.dec.s1.small为小规模单控制节点专属混合集群(最大50节点)。 最大节点数:当前集群支持管理的最大节点规模,请根据业务需求选择。 单控制节点集群:普通集群是单控制节点,控制节点故障后,集群将不可用,但已运行工作负载不受影响。 多控制节点集群:即高可用集群,当某个控制节点故障时,集群仍然可用。查看集群模式请参见如何排查已创建的集群是否为高可用集群? |
version |
String |
集群版本,与Kubernetes社区基线版本保持一致,建议选择最新版本。 在CCE控制台中支持创建两种最新版本的集群。可登录CCE控制台,单击“总览 > 购买Kubernetes集群”,在“版本”处获取到集群版本。 其它集群版本,当前仍可通过api创建,但后续会逐渐下线,具体下线策略请关注CCE官方公告。 说明:
|
description |
String |
集群描述,对于集群使用目的的描述,可根据实际情况自定义,默认为空。集群创建成功后可通过接口更新指定的集群来做出修改,也可在CCE控制台中对应集群的“集群详情”下的“描述”处进行修改。仅支持utf-8编码。 最小长度:0 最大长度:200 |
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”。若不填,则默认为“0”。 缺省值:0 |
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更新期间连接保持不断开,适用于大规模场景。 说明:
此参数目前仅在响应中体现,创建集群时请在extendParam中配置此参数。 枚举值:
|
az |
String |
可用区(仅查询返回字段) |
extendParam |
Map<String,String> |
扩展字段,key/value对格式。可配置多可用区集群、专属混合集群,以及将集群创建在特定的企业项目下。可配置的key/value对如下:
|
supportIstio |
Boolean |
支持Istio |
参数 |
参数类型 |
描述 |
---|---|---|
vpc |
String |
用于创建控制节点的VPC的ID。该值在创建VPC和子网中获取。 获取方法如下:
说明:
当前vpc-router容器网络模型不支持对接含拓展网段的VPC。 若您的用户类型为企业用户,则需要保证vpc所属的企业项目ID和集群创建时选择的企业项目ID一致。集群所属的企业项目ID通过extendParam字段下的enterpriseProjectId体现,该值默认为"0",表示默认的企业项目。 最小长度:0 最大长度:64 |
subnet |
String |
用于创建控制节点的subnet的网络ID。获取方法如下:
最小长度:0 最大长度:64 |
SecurityGroup |
String |
节点安全组ID,创建时指定无效 |
参数 |
参数类型 |
描述 |
---|---|---|
mode |
String |
容器网络类型(只可选择其一)
说明:
最小长度:0 最大长度:64 枚举值:
|
cidr |
String |
容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19,如存在网段冲突,将自动重新选择。 当节点最大实例数为默认值110时,当前容器网段至少支持582个节点,此参数在集群创建后不可更改,请谨慎选择。 最小长度:0 最大长度:64 |
参数 |
参数类型 |
描述 |
---|---|---|
eniSubnetId |
String |
用于创建控制节点的subnet的网络ID。获取方法如下:
最小长度:0 最大长度:64 |
eniSubnetCIDR |
String |
ENI子网CIDR |
参数 |
参数类型 |
描述 |
---|---|---|
mode |
String |
集群认证模式。
|
authenticatingProxy |
AuthenticatingProxy object |
authenticatingProxy模式相关配置。认证模式为authenticating_proxy时必选。 |
参数 |
参数类型 |
描述 |
---|---|---|
ca |
String |
authenticating_proxy模式配置的x509格式CA证书(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。 最大长度:1M |
参数 |
参数类型 |
描述 |
---|---|---|
key |
String |
Key值。
最小长度:1 最大长度:36 |
value |
String |
Value值。
最大长度:43 |
参数 |
参数类型 |
描述 |
---|---|---|
phase |
String |
集群状态,取值如下
|
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 |
删除状态信息(仅删除请求响应包含) |
请求示例
创建混合集群
/api/v3/projects/{project_id}/clusters { "kind" : "Cluster", "apiVersion" : "v3", "metadata" : { "name" : "mycluster", "labels" : { "foo" : "bar" }, "annotations" : { "cluster.install.addons/install" : "[{\"addonTemplateName\":\"autoscaler\",\"version\":\"1.13.11\",\"values\":{\"flavor\":{\"description\":\"Has only one instance\",\"name\":\"Single\",\"replicas\":1,\"resources\":[{\"limitsCpu\":\"90m\",\"limitsMem\":\"200Mi\",\"name\":\"autoscaler\",\"requestsCpu\":\"50m\",\"requestsMem\":\"100Mi\"}]},\"custom\":{\"coresTotal\":32000,\"maxEmptyBulkDeleteFlag\":10,\"maxNodesTotal\":1000,\"memoryTotal\":128000,\"scaleDownDelayAfterAdd\":10,\"scaleDownDelayAfterDelete\":10,\"scaleDownDelayAfterFailure\":3,\"scaleDownEnabled\":false,\"scaleDownUnneededTime\":10,\"scaleDownUtilizationThreshold\":0.5,\"scaleUpCpuUtilizationThreshold\":1,\"scaleUpMemUtilizationThreshold\":1,\"scaleUpUnscheduledPodEnabled\":true,\"scaleUpUtilizationEnabled\":true,\"tenant_id\":\"22a8a02394794b908d256103a5b63c65\",\"unremovableNodeRecheckTimeout\":5}}},{\"addonTemplateName\":\"coredns\",\"version\":\"1.13.3\",\"values\":{\"flavor\":{\"description\":\"Has two instances\",\"name\":2500,\"replicas\":2,\"resources\":[{\"limitsCpu\":\"500m\",\"limitsMem\":\"512Mi\",\"name\":\"coredns\",\"requestsCpu\":\"500m\",\"requestsMem\":\"512Mi\"}]},\"custom\":{\"stub_domains\":{},\"upstream_nameservers\":[],\"tenant_id\":\"22a8a02394794b908d256103a5b63c65\"}}},{\"addonTemplateName\":\"gpu-beta\",\"version\":\"1.1.7\",\"values\":{\"custom\":{\"is_driver_from_nvidia\":true,\"nvidia_driver_download_url\":\"https://us.download.nvidia.com/tesla/396.37/NVIDIA-Linux-x86_64-396.37.run\"}}},{\"addonTemplateName\":\"storage-driver\",\"version\":\"\"}]" } }, "spec" : { "type" : "VirtualMachine", "flavor" : "cce.s1.small", "version" : "v1.13.10-r1", "description" : "this is a demo cluster", "hostNetwork" : { "vpc" : "1cb74d47-8e09-4d14-a065-75f4fc03e5eb", "subnet" : "d44c089c-fbdc-49b3-ae8f-7b42c64219cf" }, "containerNetwork" : { "mode" : "overlay_l2", "cidr" : "172.16.0.0/16" }, "kubeProxyMode" : "iptables", "extendParam" : { "foo" : "bar" } } }
响应示例
状态码: 201
表示创建集群作业下发成功。
{ "kind" : "Cluster", "apiVersion" : "v3", "metadata" : { "name" : "auto-check-cce-name", "uid" : "128e36e5-ac4a-11ea-9846-0255ac101d1a", "creationTimestamp" : "2020-06-12 01:14:32.70889292 +0000 UTC", "updateTimestamp" : "2020-06-12 01:14:32.708893619 +0000 UTC" }, "spec" : { "type" : "VirtualMachine", "flavor" : "cce.s2.small", "version" : "v1.15.6-r1", "ipv6enable" : false, "hostNetwork" : { "vpc" : "95e0ff1a-4c5f-478c-b6a7-f8ab09512d13", "subnet" : "a0bcff14-424d-450b-ad6a-fa89f839ef56" }, "containerNetwork" : { "mode" : "overlay_l2", "cidr" : "172.16.0.0/16" }, "eniNetwork" : { }, "authentication" : { "mode" : "rbac", "authenticatingProxy" : { } }, "billingMode" : 0, "kubernetesSvcIpRange" : "10.247.0.0/16" }, "status" : { "phase" : "Creating", "jobID" : "1305e56c-ac4a-11ea-9846-0255ac101d1a" } }
状态码
状态码 |
描述 |
---|---|
201 |
表示创建集群作业下发成功。 |
错误码
请参见错误码。
