创建容器服务集群。 ## 使用说明此接口为异步接口，当此接口返回成功时，会返回集群的 ID 信息，此时不代表集群最终能够成功创建，需要您调用 [ListClusters](https://www.volcengine.com/docs/6460/115190) 接口获取该集群当前的状态，查看集群是否创建成功。集群创建成功（状态为`{Running, [Ok]}`）后，容器服务将开始按量计费，计费详情请参见 [产品计费](https://www.volcengine.com/docs/6460/70612)。 ## 请求说明 * 请求方式：POST * 请求地址：https://open.volcengineapi.com/?Action=CreateCluster&Version=2022\-05\-12 ## 调试 ## 请求参数调用该 API 时的请求参数如下，除此之外还需传入公共请求参数。公共请求参数说明，请参见 [公共参数](https://www.volcengine.com/docs/6460/70904)。 |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |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](https://www.volcengine.com/docs/6460/115189) 接口，更改集群的 **DeleteProtectionEnabled** 配置，再次进行删除；也可以在调用 [DeleteCluster](https://www.volcengine.com/docs/6460/115188) 时，配置 **Force**参数，选择强制删除集群。 | |ClusterConfig |Object of [ClusterConfigRequest](#clusterconfigrequest) |否 |\- |集群控制面及节点的网络配置。 | |PodsConfig |Object of [PodsConfigRequest](#podsconfigrequest) |否 |\- |集群的容器（Pod）网络配置。 | |ServicesConfig |Object of [ServicesConfigRequest](#servicesconfigrequest) |否 |\- |集群的服务（Service）网络配置。 | |Tags |Array of [Tag](#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 版本发布记录](https://www.volcengine.com/docs/6460/108841)。 | |LoggingConfig |Object of [ClusterLoggingConfigRequest](#clusterloggingconfigrequest) |否 |\- |集群的日志配置信息。 | |ProjectName |String |否 |default |集群所属项目名称，一个集群只能归属于一个项目。|\ | | | | ||\ | | | | |* 只能包含英文字母、数字、下划线（`_`）、英文句点（`.`）和中划线（`-`）。|\ | | | | |* 长度限制在 64 个字符以内。|\ | | | | |* 默认值：default。 | ### ClusterConfigRequest |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |SubnetIds |Array of String |否 |["subnet\-5g39dwxvppo\*\*\*\*\*\*"] |集群控制面在私有网络（VPC）内通信的子网 ID。|\ | | | | |可以调用 [私有网络API](https://www.volcengine.com/docs/6401/70484) 获取子网 ID。|\ | | | | |:::warning|\ | | | | ||\ | | | | |* 创建集群时，请确保所有指定的 SubnetIds（包括但不限于本参数）属于同一个私有网络。|\ | | | | |* 建议您尽量选择不同可用区下的子网来提高集群控制面的高可用性。|\ | | | | |* 最多可选择 3 个可用区的子网，每个可用区最多允许添加 2 个子网。|\ | | | | |* 子网可用 IP 数至少为 1。|\ | | | | ||\ | | | | |:::| |ApiServerPublicAccessEnabled |Boolean |否 |false |集群 API Server 公网访问配置，取值：|\ | | | | ||\ | | | | |* **false**：（默认值）关闭|\ | | | | |* **true**：开启 | |ApiServerPublicAccessConfig |Object of [PublicAccessConfigRequest](#publicaccessconfigrequest) |否 |\- |集群 API Server 公网访问配置信息。|\ | | | | |`ApiServerPublicAccessEnabled=true`时才生效。 | |ResourcePublicAccessDefaultEnabled |Boolean |否 |false |节点公网访问配置，取值：|\ | | | | ||\ | | | | |* **false**：（默认值）不开启公网访问。已有 NAT 网关和规则不受影响。|\ | | | | |* **true**：开启公网访问。开启后，自动为集群专有网络创建 NAT 网关并配置相应规则。|\ | | | | ||\ | | | | |:::tip|\ | | | | |集群创建完成后暂不支持修改该参数，请合理配置。|\ | | | | ||\ | | | | |:::| ### PublicAccessConfigRequest |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |PublicAccessNetworkConfig |Object of [EipConfigRequest](#eipconfigrequest) |否 |\- |公网访问网络配置。|\ | | | | |`ApiServerPublicAccessEnabled=true`时才需要填写，否则忽略。|\ | | | | |:::tip|\ | | | | |集群创建完成后暂不支持修改该参数，请合理配置。|\ | | | | ||\ | | | | |:::| ### 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（多线）。 | ### PodsConfigRequest |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |PodNetworkMode |String |是 |Flannel |容器（Pod）网络模型（CNI），取值：|\ | | | | ||\ | | | | |* **Flannel**：Flannel 网络模型，独立的 Underlay 容器网络方案，配合私有网络（VPC）的全局路由能力，实现集群高性能的网络体验。|\ | | | | |* **VpcCniShared**：VPC\-CNI 网络模型，基于私有网络的弹性网卡 ENI 实现的 Underlay 容器网络方案，具有较高的网络通信性能。|\ | | | | ||\ | | | | |:::tip|\ | | | | |集群创建完成后暂不支持修改该参数，请合理配置。|\ | | | | ||\ | | | | |:::| |FlannelConfig |Object of [FlannelConfigRequest](#flannelconfigrequest) |否 |\- |Flannel 网络配置。|\ | | | | |`PodNetworkMode=Flannel`时才能配置，但非必选。 | |VpcCniConfig |Object of [VpcCniConfigRequest](#vpccniconfigrequest) |否 |\- |PC\-CNI 网络配置。|\ | | | | |`PodNetworkMode=VpcCniShared`时才能配置，但非必选。 | ### FlannelConfigRequest |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |PodCidrs |Array of String |是 |["172.17. **.** /19"] |Flannel 容器网络模型对应的 Pod CIDR。|\ | | | | |`PodNetworkMode=Flannel`时才能配置，但非必选。|\ | | | | |:::warning|\ | | | | ||\ | | | | |* 集群内 Pod 数量受该 CIDR 的 IP 数量限制，集群创建完成后不支持修改，请合理规划 Pod CIDR。|\ | | | | |* 不能与以下网段冲突：|\ | | | | | * 同一个集群的 **ClusterConfig.SubnetIds** 对应的私有网络网段。|\ | | | | | * 同一个集群的 **ServiceConfig.ServiceCidrsv4** 对应的网段。|\ | | | | | * 同一个私有网络内所有集群的 **ServiceConfig.ServiceCidrsv4** 对应的网段。|\ | | | | | * 同一个私有网络内不同集群的 **FlannelConfig.PodCidrs**（本参数）。|\ | | | | ||\ | | | | |:::| |MaxPodsPerNode |Integer |否 |64 |Flannel 模型容器网络的单节点 Pod 实例数量上限，取值：|\ | | | | ||\ | | | | |* 64（默认值）|\ | | | | |* 16|\ | | | | |* 32|\ | | | | |* 128|\ | | | | |* 256 | ### VpcCniConfigRequest |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |SubnetIds |Array of String |是 |["subnet\-5g39dwxvp\*\*\*\*\*\*","subnet\-5g39dwxvp\*\*\*\*\*\*"] |VPC\-CNI 容器网络模型对应的 Pod 子网 ID 列表。|\ | | | | |`PodNetworkMode=VpcCniShared`时才需填写，否则忽略。|\ | | | | |可以调用 [私有网络API](https://www.volcengine.com/docs/6401/70484) 获取子网 ID。|\ | | | | |:::warning|\ | | | | |创建集群时，请确保所有指定的 **SubnetIds**（包括但不限于本参数）属于同一个私有网络。|\ | | | | ||\ | | | | |:::| ### ServicesConfigRequest |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |ServiceCidrsv4 |Array of String |是 |["172.25.\*\*.\*\*/17"] |集群内服务使用的 CIDR。|\ | | | | |:::warning|\ | | | | ||\ | | | | |* 不能与同一个私有网络内所有集群的 **FlannelConfig.PodCidrs.SubnetIds** 或 **ClusterConfig.SubnetIds** 网段冲突。|\ | | | | |* 当前仅支持传入一个数组元素，指定多个值时，仅第一个值生效。|\ | | | | ||\ | | | | |:::| ### Tag |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Key |String |是 |key |标签键。|\ | | | | ||\ | | | | |* 不能以任何大小写形式的`volc:`开头。|\ | | | | |* 只能包含语言字符、数字、空格和特殊符号`_.:/=+-@`。|\ | | | | |* 长度限制为 1～128 个字符。 | |Value |String |否 |value |标签值，可以为空。|\ | | | | ||\ | | | | |* 只能包含语言字符、数字、空格和特殊符号`_.:/=+-@`。|\ | | | | |* 长度不超过 256 个字符。 | ### ClusterLoggingConfigRequest |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |LogSetups |Array of [LogSetupRequest](#logsetuprequest) |否 |\- |集群的日志选项信息。|\ | | | | ||\ | | | | |* 空数组代表不开启任何日志。|\ | | | | |* 首次开启日志时，日志主题（Log Topic）自动生成。|\ | | | | |* 多个日志选项时，**LogType**不允许重复。 | |LogProjectId |String |否 |b68324a0\-2680\-48c7\-a42e\-8d78\*\*\*\*\*\*\*\* |集群的日志项目（Log Project）ID。|\ | | | | |:::warning|\ | | | | ||\ | | | | |* 不可以空字符串。|\ | | | | |* 创建集群时，若 **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 组件日志|\ | | | | |* **Etcd**：etcd 组件日志|\ | | | | |* **ClusterAutoscaler**：cluster\-autoscaler 组件日志 | |LogTtl |Integer |否 |30 |日志在日志服务中的保存时间，超过指定的日志存储时长后，此日志主题中的过期日志会被自动清除。|\ | | | | ||\ | | | | |* 取值范围：1～3650|\ | | | | |* 单位：天|\ | | | | |* 默认值：30 天|\ | | | | | 指定为 3650 天表示永久存储。 | |Enabled |Boolean |否 |false |是否开启该日志选项，取值：|\ | | | | ||\ | | | | |* **false**：（默认值）不开启|\ | | | | |* **true**：开启|\ | | | | ||\ | | | | |:::warning|\ | | | | ||\ | | | | |* 更新集群配置时，若 **LogType** 为 **Audit**，则更改 **Enabled** 会重启 Apiserver。|\ | | | | |* 更新集群配置时，若 **Enabled** 由 **false** 更换为 **tru**e，则会创建新的日志主题。|\ | | | | ||\ | | | | |:::| ## 请求示例 * 创建 Flannel 网络模型集群 ```JSON POST /?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 网络模型集群 ```JSON 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 } ] } } ``` ## 返回参数本接口返回参数如下表所示，公共返回参数请参见 [返回结果](https://www.volcengine.com/docs/6460/79674)。 |**参数** |**类型** |**示例值** |**描述** | |---|---|---|---| |Id |String |cc5silumrsfeq\*\*\*\* |集群 ID。 | ## 返回示例 ```JSON HTTP/1.1 200 OK Content-Type:application/json { "ResponseMetadata": { "RequestId": "021635330810134****", "Action": "CreateCluster", "Version": "2022-05-12", "Service": "vke", "Region": "cn-beijing" }, "Result": { "Id": "nc5t5epmrsf****" } } ``` ## 错误码本接口错误码如下表所示，公共错误码请参见 [公共错误码](https://www.volcengine.com/docs/6460/118978)。 |**HTTP 状态码** |**错误码** |**错误信息** |**说明** | |---|---|---|---| |400 |Insufficient.Balance |Your account has run out of balance. |当前火山引擎账户余额不足。请充值账户后重试。 | |400 |QuotaExceeded.Cluster |The number of clusters has reached the limit. |当前地域所要创建的集群数量达到配额限制。产品限制说明，请参见 [使用限制](https://www.volcengine.com/docs/6460/79642)。您可以选择其他地域创建集群，也可以 [提交工单](https://console.volcengine.com/ticket/createTicketV2/?step=2&Service=vke)申请提高配额。 | |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](https://www.volcengine.com/docs/6401/70495)获取。 | |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 个。 |