创建容器服务集群。

使用说明

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

请求说明

VKE 已在全球多个地域部署服务，旨在为您提供更稳定、低延迟的访问体验。您可以通过查阅服务地址文档，根据业务所在地域，选择最合适的接入点。

请求方式：POST

请求地址：https://vke.cn-beijing.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.36	集群的 Kubernetes 版本，格式为x.xx。创建集群时，系统自动匹配该 Kubernetes 版本对应的最新 VKE 版本。容器服务已发布的 Kubernetes 版本，请参见 Kubernetes 版本发布记录。
LoggingConfig	Object of ClusterLoggingConfigRequest	否	-	集群的日志配置信息。
ProjectName	String	否	default	集群所属项目名称，一个集群只能归属于一个项目。只能包含英文字母、数字、下划线（_）、英文句点（.）和中划线（-）。长度限制在 64 个字符以内。默认值：default。
KubernetesConfig	Object of ClusterKubernetesConfigRequest	否	-	集群 Kubernetes 相关参数设置。
MonitoringConfig	Object of ClusterMonitoringConfigRequest	否	-	集群的监控配置信息。
MaintenanceWindowConfig	Object of ClusterMaintenanceWindowConfigRequest	否	-	集群的运维配置信息。

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 网关并配置相应规则。
IpFamily	String	否	Ipv4	集群网络协议栈，取值： Ipv4：（默认值）IPv4 单栈。 Ipv6：【邀测·申请试用】IPv6 单栈。 DualStack：【邀测·申请试用】开启 IPv4 和 IPv6 双栈。注意集群创建完成后暂不支持修改该参数，请合理配置。

PublicAccessConfigRequest

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

EipConfigRequest

参数	类型	是否必选	示例值	描述
Isp	String	否	BGP	公网 IP 的线路类型，取值： BGP：BGP（多线）。
Bandwidth	Integer	否	100	公网 IP 的带宽峰值，单位为 Mbps，取值： BillingType=2时：取值范围 1 ~ 500，默认值 10。 BillingType=3时：取值范围 1 ~ 200，默认值 10。
BillingType	Integer	否	3	公网 IP 的计费类型，取值： 3：（默认值）按量计费-按实际流量计费，即指定带宽上限后，将按照实际使用的出公网流量计费，与使用时长无关。 2：按量计费-按带宽上限计费，即指定带宽上限后，将按照使用时长计费，与实际流量无关。
BandwidthPackageId	String	否	bwp-2zeo********	共享带宽包的 ID，表示将公网 IP 加入到共享带宽包。共享带宽包 ID 请调用 DescribeBandwidthPackages 接口获取。注意公网 IP 加入到共享带宽包时，必须同时满足如下条件：二者的线路类型相同。共享带宽包为 IPv4 类型。共享带宽包未配置安全防护。

PodsConfigRequest

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

VpcCniConfigRequest

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

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（本参数）。
SubnetIds	Array of String	否	["subnet-5g39**","subnet-5g39**"]	VCI Pod 使用的 VPC 子网，用于为 VCI Pod 分配 IP 地址。 PodNetworkMode=Flannel时才能配置，但非必选。可以调用私有网络API 获取子网 ID。注意创建集群时，请确保所有指定的 SubnetIds（包括但不限于本参数）属于同一个私有网络。
MaxPodsPerNode	Integer	否	64	Flannel 模型容器网络的单节点 Pod 实例数量上限，取值： 64（默认值） 16 32 128 256

ServicesConfigRequest

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

Tag

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

ClusterLoggingConfigRequest

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

LogSetupRequest

参数	类型	是否必选	示例值	描述
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 组件日志 Etcd：etcd 组件日志 ClusterAutoscaler：cluster-autoscaler 组件日志

ClusterKubernetesConfigRequest

参数	类型	是否必选	示例值	描述
CustomSans	Array of String	否	["abc.com","192.168.0.10"]	自定义证书 SAN（Subject Alternative Name），即自定义签发域名或 IP 能力。支持输入符合规范的自定义 IP、域名或 URI。多个配置之间以半角逗号（,）、回车键或空格分隔。支持最多 6 条自定义证书 SAN。
ClusterDomain	String	否	cluster.local	集群本地域名。域名由小数点（.）分隔的两个或多个部分组成。每个部分仅支持小写字母、数字和中划线（-），且首尾必须为小写字母或数字。最长支持 57 个字符。若不设置，则默认集群本地域名为cluster.local。
AdvancedConfig	Object of AdvancedConfig	否	-	API Server 增强配置。
ControlPlaneConfig	Object of KubernetesComponentConfigs	否	-	Kubernetes 核心组件的自定义参数配置。

AdvancedConfig

参数	类型	是否必选	示例值	描述
InternalDnsEnabled	Boolean	否	true	是否为集群开启 API Server 私网域名访问： true：（默认值）开启，节点侧组件通过私网域名访问 API Server。 false：关闭。注意新建集群时默认且仅支持开启 API Server 私网域名访问，不支持关闭，即设置为false时不生效。

KubernetesComponentConfigs

参数	类型	是否必选	示例值	描述
KubeApiServerConfig	Object of KubeApiServerConfig	否	-	kube-apiserver 组件的自定义参数配置。

KubeApiServerConfig

参数	类型	是否必选	示例值	描述
AdmissionPlugins	Object of AdmissionPlugins	否	-	kube-apiserver 中除默认启用的准入控制插件之外，额外启用的准入控制插件列表。

AdmissionPlugins

参数	类型	是否必选	示例值	描述
AlwaysPullImages	Boolean	否	true	是否启用 AlwaysPullImages 准入控制插件。取值： true：启用，表示修改每个 Pod 的时候都强制重新拉取镜像。 false：（默认值）不启用。

ClusterMonitoringConfigRequest

参数	类型	是否必选	示例值	描述
WorkspaceId	String	是	a72bxxxx-83xx-4axx********	集群监控使用的托管 Prometheus 工作区 ID。可以调用托管 Prometheus API 获取工作区 ID。
ComponentConfigs	Array of ClusterMonitoringComponentConfigRequest	否	-	控制面监控配置。

ClusterMonitoringComponentConfigRequest

参数	类型	是否必选	示例值	描述
Name	String	是	KubeApiServer	需要监控的集群控制面组件，取值：KubeApiServer、KubeScheduler、Etcd 和 ClusterAutoscaler。
Enabled	Boolean	否	true	是否开启控制面组件监控，取值： true：开启。 false：（默认值）关闭。

ClusterMaintenanceWindowConfigRequest

参数	类型	是否必选	示例值	描述
Duration	Integer	否	4	自动运维的持续时长，整数形式，取值范围为 4～24，单位为小时。未配置该参数时，默认值为 4。
StartTime	String	否	20:00:00Z	自动运维的开始时间，Golang 标准时间格式，24 小时制。取值范围为 00～23 中的整点。例如：01:00:00Z、14:00:00Z。未配置该参数时，默认值为 16:00:00Z，即 UTC 标准时间 16:00:00，北京时间（UTC +8）次日 00:00:00。说明本参数当前仅支持配置为 UTC 标准时间，如果您需要配置为其他时区，需要将其他时区时间人工转换为 UTC 标准时间。 ExemptStartDate和ExemptEndDate参数默认为 UTC + 8 时区时间。当与本参数共同配置时，请额外注意时区一致性。
TaskConfigs	Array of WindowTaskConfig	否	-	自动运维任务配置。未配置该参数时，系统默认只执行集群控制面日常运维任务，不执行其他运维任务。
WeeklyCycle	Array of String	否	["Monday","Tuesday"]	自动运维的周期，取值： Monday：周一 Tuesday：周二 Wednesday：周三 Thursday：周四 Friday：周五 Saturday：周六 Sunday：周日未配置该参数时，系统默认每天都执行运维任务。
ExemptEndDate	String	否	20260704	自动运维豁免窗口的结束时间，格式为YYYYMMDD，按北京时间（UTC +8）自然日执行。例如：配置为20260704时，表示截止到该日期的 23:59:59，不再执行自动运维任务。说明该日期必须晚于ExemptStartDate配置的日期，且最多不超过 60 天。
ExemptStartDate	String	否	20260702	自动运维豁免窗口的开始时间，格式为YYYYMMDD，按北京时间（UTC +8）自然日执行。例如：配置为20260702时，表示从该日期的 00:00:00 点起，不再执行自动运维任务。说明该日期必须早于ExemptEndDate配置的日期，且最多不超过 60 天。在业务重保、封网等场景下，您可以通过配置豁免窗口来禁止系统的自动运维操作。

WindowTaskConfig

参数	类型	是否必选	示例值	描述
Group	String	是	Cluster	自动运维任务的分组，取值： Cluster：控制面运维。 Addon：数据面运维。
Action	String	是	AutoUpgradeAddonVersion	自动运维任务，取值： AutoUpgradeClusterMinorVersion：集群补丁版本自动升级任务。仅当Group配置为Cluster时，支持配置该任务。 AutoUpgradeAddonVersion：组件版本自动升级任务。仅当Group配置为Addon时，支持配置该任务。配置该任务时，还需要使用Targets指定需要升级的组件。
Targets	Array of String	否	["metrics-server","cluster-autoscaler"]	指定需要进行版本自动升级的组件。支持配置多个组件，多个组件之间使用半角逗号,分割。当前支持如下组件：cluster-autoscaler、metrics-server、log-collector、event-collector、node-problem-detector、metrics-collector 和 prometheus-agent。说明上述组件的介绍和说明，请参见组件概述。当前只有部分组件支持自动升级能力。如果您需要升级其他组件，请在组件管理手动操作。详情请参见升级组件。

请求示例

返回参数

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

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

返回示例

错误码

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

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 个。