CreateCluster--容器服务-火山引擎

文档中心

导航

CreateCluster

最近更新时间：2024.09.14 18:01:01首次发布时间：2022.07.07 10:15:44

创建容器服务集群。

使用说明

此接口为异步接口，当此接口返回成功时，会返回集群的 ID 信息，此时不代表集群最终能够成功创建，需要您调用 ListClusters 接口获取该集群当前的状态，查看集群是否创建成功。集群创建成功（状态为{Running, [Ok]}）后，容器服务将开始按量计费，计费详情请参见产品计费。

请求说明

请求方式：POST
请求地址：https://open.volcengineapi.com/?Action=CreateCluster&Version=2022-05-12

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

调用该 API 时的请求参数如下，除此之外还需传入公共请求参数。公共请求参数说明，请参见公共参数。

参数	类型	是否必选	示例值	描述
Action	String	是	CreateCluster	接口名称。当前 API 的名称为 `CreateCluster`。
Version	String	是	2022-05-12	接口版本。当前 API 的版本为 `2022-05-12`。
ClientToken	String	否	BC028527-33B9-4990-A633-84E9F9******	用于保证请求幂等性的字符串。该字符串由调用方传入，需保证不同请求之间唯一。ClientToken 对大小写敏感，且最大值不超过 64 个 ASCII 字符。
Name	String	是	TestCluster	集群名称。同一个地域下，名称必须唯一。支持大小写英文字母、汉字、数字、短划线（-），长度限制为 2～64 个字符。
Description	String	否	A Kubernetes Cluster Managed by VKE	集群描述。长度限制为 300 个字符以内。
DeleteProtectionEnabled	Boolean	否	false	集群删除保护，取值： false：（默认值）关闭删除保护。 true：开启删除保护，不允许直接删除集群。创建集群后，可以通过调用 UpdateClusterConfig 接口，更改集群的 DeleteProtectionEnabled 配置，再次进行删除；也可以在调用 DeleteCluster 时，配置 Force 参数，选择强制删除集群。
ClusterConfig	Object of ClusterConfigRequest	否	-	集群控制面及节点的网络配置。
PodsConfig	Object of PodsConfigRequest	是	-	集群的容器（Pod）网络配置。
ServicesConfig	Object of ServicesConfigRequest	是	-	集群的服务（Service）网络配置。
Tags	Array of Tag	否	-	自定义的资源标签，用于从不同维度对具有相同特征的集群进行分类、搜索和聚合，能够灵活管理集群。 Tags 中各个 Key 不可重复。资源已有相同 Tags.Key 的情况下，重复绑定 Tags.Key 不会报错，会更新为最新的 Tags.Value。单个资源最多支持绑定 50 个 Tags。 Tags 中的 Key、Value 不允许在最前或最后输入空格。
KubernetesVersion	String	否	1.26	集群的 Kubernetes 版本，格式为`x.xx`。创建集群时，系统自动匹配该 Kubernetes 版本对应的最新 VKE 版本。容器服务已发布的 Kubernetes 版本，请参见 Kubernetes 版本发布记录。
LoggingConfig	Object of ClusterLoggingConfigRequest	否	-	集群的日志配置信息。

ClusterConfigRequest

参数	类型	是否必选	示例值	描述
SubnetIds	Array of String	否	["subnet-5g39dwxvppo******"]	集群控制面在私有网络（VPC）内通信的子网 ID。可以调用私有网络API 获取子网 ID。注意创建集群时，请确保所有指定的 SubnetIds（包括但不限于本参数）属于同一个私有网络。建议您尽量选择不同可用区下的子网来提高集群控制面的高可用性。最多可选择 3 个可用区的子网，每个可用区最多允许添加 2 个子网。子网可用 IP 数至少为 1。
ApiServerPublicAccessEnabled	Boolean	否	false	集群 API Server 公网访问配置，取值： false：（默认值）关闭 true：开启
ApiServerPublicAccessConfig	Object of PublicAccessConfigRequest	否	-	集群 API Server 公网访问配置信息。 `ApiServerPublicAccessEnabled=true`时才生效。
ResourcePublicAccessDefaultEnabled	Boolean	否	false	节点公网访问配置，取值： false：（默认值）不开启公网访问。已有 NAT 网关和规则不受影响。 true：开启公网访问。开启后，自动为集群专有网络创建 NAT 网关并配置相应规则。说明集群创建完成后暂不支持修改该参数，请合理配置。

PublicAccessConfigRequest

参数	类型	是否必选	示例值	描述
PublicAccessNetworkConfig	Object of EipConfigRequest	否	-	公网访问网络配置。 `ApiServerPublicAccessEnabled=true`时才需要填写，否则忽略。说明集群创建完成后暂不支持修改该参数，请合理配置。

EipConfigRequest

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
BillingType	Integer	否	2	公网 IP 的计费类型，取值： 3：（默认值）按量计费-按实际流量计费，即指定带宽上限后，将按照实际使用的出公网流量计费，与使用时长无关。 2：按量计费-按带宽上限计费，即指定带宽上限后，将按照使用时长计费，与实际流量无关。
Bandwidth	Integer	否	10	公网 IP 的带宽峰值，单位为 Mbps，取值： `BillingType=2`时：取值范围 1 ~ 500，默认值 10。 `BillingType=3`时：取值范围 1 ~ 200，默认值 10。
Isp	String	否	BGP	公网 IP 的线路类型，取值： BGP：BGP（多线）。

BillingType

Integer

否

公网 IP 的计费类型，取值：

3：（默认值）按量计费-按实际流量计费，即指定带宽上限后，将按照实际使用的出公网流量计费，与使用时长无关。
2：按量计费-按带宽上限计费，即指定带宽上限后，将按照使用时长计费，与实际流量无关。

Bandwidth

Integer

否

公网 IP 的带宽峰值，单位为 Mbps，取值：

BillingType=2时：取值范围 1 ~ 500，默认值 10。
BillingType=3时：取值范围 1 ~ 200，默认值 10。

Isp

String

否

BGP

公网 IP 的线路类型，取值：
BGP：BGP（多线）。

PodsConfigRequest

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
PodNetworkMode	String	是	Flannel	容器（Pod）网络模型（CNI），取值： Flannel：Flannel 网络模型，独立的 Underlay 容器网络方案，配合私有网络（VPC）的全局路由能力，实现集群高性能的网络体验。 VpcCniShared：VPC-CNI 网络模型，基于私有网络的弹性网卡 ENI 实现的 Underlay 容器网络方案，具有较高的网络通信性能。说明集群创建完成后暂不支持修改该参数，请合理配置。
FlannelConfig	Object of FlannelConfigRequest	否	-	Flannel 网络配置。 `PodNetworkMode=Flannel`时才能配置，但非必选。
VpcCniConfig	Object of VpcCniConfigRequest	否	-	PC-CNI 网络配置。 `PodNetworkMode=VpcCniShared`时才能配置，但非必选。

PodNetworkMode

String

是

Flannel

容器（Pod）网络模型（CNI），取值：

Flannel：Flannel 网络模型，独立的 Underlay 容器网络方案，配合私有网络（VPC）的全局路由能力，实现集群高性能的网络体验。
VpcCniShared：VPC-CNI 网络模型，基于私有网络的弹性网卡 ENI 实现的 Underlay 容器网络方案，具有较高的网络通信性能。

说明

集群创建完成后暂不支持修改该参数，请合理配置。

FlannelConfig

Object of FlannelConfigRequest

否

Flannel 网络配置。
PodNetworkMode=Flannel时才能配置，但非必选。

VpcCniConfig

Object of VpcCniConfigRequest

否

PC-CNI 网络配置。
PodNetworkMode=VpcCniShared时才能配置，但非必选。

FlannelConfigRequest

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
PodCidrs	Array of String	是	["172.17../19"]	Flannel 容器网络模型对应的 Pod CIDR。 `PodNetworkMode=Flannel`时才能配置，但非必选。注意集群内 Pod 数量受该 CIDR 的 IP 数量限制，集群创建完成后不支持修改，请合理规划 Pod CIDR。不能与以下网段冲突：同一个集群的 ClusterConfig.SubnetIds 对应的私有网络网段。同一个集群的 ServiceConfig.ServiceCidrsv4 对应的网段。同一个私有网络内所有集群的 ServiceConfig.ServiceCidrsv4 对应的网段。同一个私有网络内不同集群的 FlannelConfig.PodCidrs（本参数）。
MaxPodsPerNode	Integer	否	64	Flannel 模型容器网络的单节点 Pod 实例数量上限，取值： 64（默认值） 16 32 128 256

PodCidrs

Array of String

是

["172.17../19"]

Flannel 容器网络模型对应的 Pod CIDR。
PodNetworkMode=Flannel时才能配置，但非必选。

注意

集群内 Pod 数量受该 CIDR 的 IP 数量限制，集群创建完成后不支持修改，请合理规划 Pod CIDR。
不能与以下网段冲突：
- 同一个集群的 ClusterConfig.SubnetIds 对应的私有网络网段。
- 同一个集群的 ServiceConfig.ServiceCidrsv4 对应的网段。
- 同一个私有网络内所有集群的 ServiceConfig.ServiceCidrsv4 对应的网段。
- 同一个私有网络内不同集群的 FlannelConfig.PodCidrs（本参数）。

MaxPodsPerNode

Integer

否

Flannel 模型容器网络的单节点 Pod 实例数量上限，取值：

64（默认值）
16
32
128
256

VpcCniConfigRequest

参数	类型	是否必选	示例值	描述
SubnetIds	Array of String	是	["subnet-5g39dwxvp****","subnet-5g39dwxvp****"]	VPC-CNI 容器网络模型对应的 Pod 子网 ID 列表。 `PodNetworkMode=VpcCniShared`时才需填写，否则忽略。可以调用私有网络API 获取子网 ID。注意创建集群时，请确保所有指定的 SubnetIds（包括但不限于本参数）属于同一个私有网络。

ServicesConfigRequest

参数	类型	是否必选	示例值	描述
ServiceCidrsv4	Array of String	是	["172.25../17"]	集群内服务使用的 CIDR。注意不能与同一个私有网络内所有集群的 FlannelConfig.PodCidrs.SubnetIds 或 ClusterConfig.SubnetIds 网段冲突。当前仅支持传入一个数组元素，指定多个值时，仅第一个值生效。

参数	类型	是否必选	示例值	描述
Key	String	是	key	标签键。不能以任何大小写形式的`volc:`开头。只能包含语言字符、数字、空格和特殊符号`_.:/=+-@`。长度限制为 1～128 个字符。
Value	String	否	value	标签值，可以为空。只能包含语言字符、数字、空格和特殊符号`_.:/=+-@`。长度不超过 256 个字符。

ClusterLoggingConfigRequest

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
LogSetups	Array of LogSetupRequest	否	-	集群的日志选项信息。空数组代表不开启任何日志。首次开启日志时，日志主题（Log Topic）自动生成。多个日志选项时，LogType 不允许重复。
LogProjectId	String	否	b68324a0-2680-****	集群的日志项目（Log Project）ID。注意不可以空字符串。创建集群时，若 LogProjectId 不传参数值，表示由系统自动创建新的日志项目。系统自动创建日志项目，按照`k8s-log-{clusterId}-{6位随机字符}`格式自动生成项目名称。如果 LogSetups.Enabled 字段取值为 false，则不会自动创建日志项目。更新集群配置时，若 LogProjectId 已指定日志项目，则不可更新为空。更新集群配置时，若集群不存在任何日志配置，此时只传了 LogProjectId 且LogSetups 为空时，LogProjectId 将会被忽略。更新 LogProjectId 会为处于开启状态的日志创建新的主题。

LogSetups

Array of LogSetupRequest

否

集群的日志选项信息。

空数组代表不开启任何日志。
首次开启日志时，日志主题（Log Topic）自动生成。
多个日志选项时，LogType 不允许重复。

LogProjectId

String

否

b68324a0-2680-****

集群的日志项目（Log Project）ID。

注意

不可以空字符串。
创建集群时，若 LogProjectId 不传参数值，表示由系统自动创建新的日志项目。
系统自动创建日志项目，按照k8s-log-{clusterId}-{6位随机字符}格式自动生成项目名称。
如果 LogSetups.Enabled 字段取值为 false，则不会自动创建日志项目。
更新集群配置时，若 LogProjectId 已指定日志项目，则不可更新为空。
更新集群配置时，若集群不存在任何日志配置，此时只传了 LogProjectId 且LogSetups 为空时，LogProjectId 将会被忽略。
更新 LogProjectId 会为处于开启状态的日志创建新的主题。

LogSetupRequest

参数	类型	是否必选	示例值	描述
LogType	String	是	Audit	当前开启的日志类型，取值： Audit：集群审计日志 KubeApiServer：kube-apiserver 组件日志 KubeScheduler：kube-scheduler 组件日志 KubeControllerManager：kube-controller-manager 组件日志
LogTtl	Integer	否	30	日志在日志服务中的保存时间，超过指定的日志存储时长后，此日志主题中的过期日志会被自动清除。取值范围：1～3650 单位：天默认值：30 天指定为 3650 天表示永久存储。
Enabled	Boolean	否	false	是否开启该日志选项，取值： false：（默认值）不开启 true：开启注意更新集群配置时，若 LogType 为 Audit，则更改 Enabled 会重启 Apiserver。更新集群配置时，若 Enabled 由 false 更换为 true，则会创建新的日志主题。

参数

类型

是否必选

示例值

描述

LogType

String

是

Audit

当前开启的日志类型，取值：

Audit：集群审计日志
KubeApiServer：kube-apiserver 组件日志
KubeScheduler：kube-scheduler 组件日志
KubeControllerManager：kube-controller-manager 组件日志

LogTtl

Integer

否

日志在日志服务中的保存时间，超过指定的日志存储时长后，此日志主题中的过期日志会被自动清除。

取值范围：1～3650
单位：天
默认值：30 天
指定为 3650 天表示永久存储。

Enabled

Boolean

否

false

是否开启该日志选项，取值：

false：（默认值）不开启
true：开启

注意

更新集群配置时，若 LogType 为 Audit，则更改 Enabled 会重启 Apiserver。
更新集群配置时，若 Enabled 由 false 更换为 true，则会创建新的日志主题。

请求示例

创建 Flannel 网络模型集群

POST https://open.volcengineapi.com/?Action=CreateCluster&Version=2022-05-12 HTTP/1.1
Content-Type:application/json
{
    "Name": "flannel-test",
    "Description": "",
    "DeleteProtectionEnabled": false,
    "ClusterConfig": {
        "SubnetIds": ["subnet-3rf6vwbgkg9og5zsk2if****"]
    },
    "PodsConfig": {
        "PodNetworkMode": "Flannel",
        "FlannelConfig": {
            "MaxPodsPerNode": 32,
            "PodCidrs": ["172.17.**.**/19"]
        }
    },
    "ServicesConfig": {
        "ServiceCidrsv4": ["172.25.**.**/17"]
    },
    "Tags": [
        {
            "Key": "key",
            "Value": "value"
        }
    ],
    "KubernetesVersion": "1.20",
    "LoggingConfig": {
        "LogSetups": [
            {
                "LogType": "Audit",
                "LogTtl": 30,
                "Enabled": true
            }
        ]
    }
}

创建 VPC-CNI 网络模型集群

POST https://open.volcengineapi.com/?Action=CreateCluster&Version=2022-05-12
Content-Type: application/json
{
    "Name": "vpc-cni-test",
    "Description": "xxxx",
    "DeleteProtectionEnabled": false,
    "ClusterConfig": {
        "SubnetIds": ["subnet-3rf6vwbgkg9og5zsk2if****"],
        "ApiServerPublicAccessEnabled": true,
        "ResourcePublicAccessDefaultEnabled": true
    },
    "PodsConfig": {
        "PodNetworkMode": "VpcCniShared",
        "VpcCniConfig": {
            "SubnetIds": ["subnet-2d6tcun83e96o58ozfddc****"]
        }
    },
    "ServicesConfig": {
        "ServiceCidrsv4": ["172.17.**.**/21"]
    },
    "Tags": [
        {
            "Key": "key",
            "Value": "value"
        }
    ],
    "KubernetesVersion": "1.20",
    "LoggingConfig": {
        "LogSetups": [
            {
                "LogType": "Audit",
                "LogTtl": 30,
                "Enabled": true
            }
        ]
    }
}

返回参数

本接口返回参数如下表所示，公共返回参数请参见返回结果。

参数	类型	示例值	描述
Id	String	cc5silum****	集群 ID。

返回示例

HTTP/1.1 200 OK
Content-Type:application/json

{
    "ResponseMetadata": {
        "RequestId": "0216353****",
        "Action": "CreateCluster",
        "Version": "2022-05-12",
        "Service": "vke",
        "Region": "cn-beijing"
    },
    "Result": {
        "Id": "nc5t5****"
    }
}

错误码

本接口错误码如下表所示，公共错误码请参见公共错误码。

HTTP 状态码	错误码	错误信息	说明
400	Insufficient.Balance	Your account has run out of balance.	当前火山引擎账户余额不足。请充值账户后重试。
400	QuotaExceeded.Cluster	The number of clusters has reached the limit.	当前地域所要创建的集群数量达到配额限制。产品限制说明，请参见使用限制。您可以选择其他地域创建集群，也可以提交工单申请提高配额。
400	VpcMismatch.{{parameter}}	The specified {{resourceType}} {{resourceId}} is not in the same VPC.	指定的 SubnetIds 不属于同一个私有网络。请重新配置参数后重试。
400	OutOfRange.{{cidrParameter}}	The range of specified CIDR is too small.	CIDR IP 地址段过小，影响 Pod 数量。请合理规划 CIDR 后重试。
400	InvalidRange.{{parameter}}	The range of specified CIDR addresses is in conflict with that of CIDR/Subnet in the cluster or in conflict with that of CIDR/Subnet of another cluster or NOT in the valid CIDR ranges.	CIDR 地址范围错误。请确认参数后重试。
400	OperationDenied.VpcStatus	The status of the specified VPC {{vpcId}} is not valid.	指定私有网络（VPC）的当前状态不支持此操作。请确认该接口依赖的私有网络状态后重试。VPC 状态，可以调用 DescribeVpcs 获取。
409	Conflict.Name	The specified name conflicts with existing {{resourceType}}.	指定地域存在同名资源，请更新资源名称后重试。
400	QuotaExceeded.{{ResourceType}}	The quota of {{ResourceType}} has reached the limit.	指定资源的配额达到上限，如 EIP、LogProject、LogTopic 等。请提升相关资源配额，或删除无用资源，预留出配额后重试。
400	NotSupported.{{parameter}}	The specified {{resourceType}} {{resourceContent}} is not supported.	指定的参数不支持，如 KubernetesVersion、SubnetId 等。请确认参数值后重试。
400	Insufficient.SubnetIp	The IP of subnet {{subnetId}} is insufficient.	指定的子网可用 IP 数量不足。请指定符合要求的子网后重试。
400	LimitExceeded.ClusterSubnetZones	You have reached the limit of the number of cluster subnet zones that you can add.	集群子网可用区个数超过限制。请确保子网可用区不超过 3 个。
400	LimitExceeded.ClusterSubnetsOfZone	You have reached the limit of the number of cluster subnets in zone {{zone}} that you can add.	单个可用区下已指定的子网个数超过限制。请确保每个可用区下已指定的子网数不超过 2 个。