Create a VKE cluster.

Usage instructions

This is an asynchronous API. When it returns a success message, the cluster ID is returned. This does not necessarily indicate that the cluster is created. You need to call the ListClusters API to obtain the current status of the cluster, based on which you check whether it has been created. After the cluster is created (with the status of {Running, [Ok]}), VKE starts to bill the cluster on a pay-as-you-go basis. For billing details, see Product billing.

Request description

VKE has deployed services in multiple regions globally to provide a stable and low-latency access experience. You can refer to the Service addresses topic and select the most suitable access point for your business region.

Request method: POST

Request URL: https://vke.cn-beijing.volcengineapi.com?Action=CreateCluster&Version=2022-05-12

Debugging

API Explorer

You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.

Go to debug

Request parameters

The following table describes the API request parameters. You also need to provide public parameters when calling this API. For details about public request parameters, see Public parameters.

Parameter	Type	Required	Sample value	Description
Action	String	Yes	CreateCluster	The API name. The current API is CreateCluster.
Version	String	Yes	2022-05-12	The API version. The current version of the API is 2022-05-12.
ClientToken	String	No	BC028527-33B9-4990-A633-84E9F9******	A string used to ensure the idempotency of the request. This string is passed in by the caller and must be unique across different requests. ClientToken is case-sensitive and can consist of 64 ASCII characters at most.
Name	String	Yes	TestCluster	Cluster name. The name must be unique within the same region. It can contain uppercase and lowercase letters, Chinese characters, digits, and hyphens (-). It can be 2 to 64 characters in length.
Description	String	No	A Kubernetes Cluster Managed by VKE	Cluster description. It cannot exceed 300 characters in length.
DeleteProtectionEnabled	Boolean	No	false	Specify whether to enable cluster deletion protection. Valid values: false: (Default) Disable deletion protection. true: Enable deletion protection. Direct deletion of the cluster is not allowed. To delete a cluster with deletion protection enabled, call the UpdateClusterConfig API to modify the DeleteProtectionEnabled configuration before you delete the cluster or configure the Force parameter in a call to DeleteCluster to force deletion of the cluster.
ClusterConfig	Object of ClusterConfigRequest	No	-	The network configurations of the control plane and nodes.
PodsConfig	Object of PodsConfigRequest	No	-	The cluster container (Pod) network configurations.
ServicesConfig	Object of ServicesConfigRequest	No	-	Service network configuration of the cluster.
Tags	Array of Tag	No	-	Specify custom resource tags. They are used to classify, search, and aggregate clusters with the same characteristics from different dimensions, enabling flexible cluster management. Each Key in Tags must be unique. If the resource already has the same Tags.Key, an error will not occur if you bind the same Tags.Key again. Instead, the latest Tags.Value will be used. A resource can have up to 50 tags. The Key and Value in Tags cannot start or end with a space.
KubernetesVersion	String	No	1.36	Kubernetes version of the cluster. The value is in the x.xx format. During cluster creation, the system automatically matches the latest VKE version corresponding to the specified Kubernetes version. For the release notes for Kubernetes versions supported by VKE, see Kubernetes version release notes.
LoggingConfig	Object of ClusterLoggingConfigRequest	No	-	The log configurations for the cluster.
ProjectName	String	No	default	Name of the project to which the cluster belongs. Each cluster can only belong to one project. It can only contain letters, digits, underscores (_), periods (.), and hyphens (-). It can be up to 64 characters in length. Default value: default.
KubernetesConfig	Object of ClusterKubernetesConfigRequest	No	-	The Kubernetes-related parameter settings of the cluster.
MonitoringConfig	Object of ClusterMonitoringConfigRequest	No	-	The monitoring configurations of the cluster.
MaintenanceWindowConfig	Object of ClusterMaintenanceWindowConfigRequest	No	-	The O&M configurations of the cluster.

ClusterConfigRequest

Parameter	Type	Required	Sample value	Description
SubnetIds	Array of String	No	["subnet-5g39dwxvppo******"]	The IDs of subnets used by the cluster control plane to communicate within the VPC. You can call the VPC API to obtain subnet IDs. warning When creating a cluster, make sure that all specified SubnetIds (including but not limited to this parameter) belong to the same VPC. We recommend selecting subnets in different availability zones to improve the high availability of the control plane. You can select subnets from up to 3 availability zones, with up to 2 subnets allowed per availability zone. The number of available IP addresses in a subnet must be at least 1.
ApiServerPublicAccessEnabled	Boolean	No	false	Whether to enable public access to the API Server of the cluster. Values: false: (Default) Disable it. true: Enable it.
ApiServerPublicAccessConfig	Object of PublicAccessConfigRequest	No	-	The public access configurations of the API server for the cluster. This parameter takes effect only if ApiServerPublicAccessEnabled is set to true.
ResourcePublicAccessDefaultEnabled	Boolean	No	false	Public node access configuration. Values: false: (Default) Disable public access. Existing NAT Gateways and rules are not affected. true: Enable public access. If this option is enabled, a NAT Gateway will be automatically created for the VPC of the cluster, and corresponding rules will be configured.
IpFamily	String	No	Ipv4	Cluster network protocol stack, available values: Ipv4: (Default) IPv4 single stack. Ipv6: [Beta - apply for trial] IPv6 single stack. DualStack: [Beta - apply for trial] Enable IPv4 and IPv6 dual stack. warning After cluster creation is complete, you cannot modify this parameter. Configure it appropriately.

PublicAccessConfigRequest

Parameter	Type	Required	Sample value	Description
PublicAccessNetworkConfig	Object of EipConfigRequest	No	-	The public access configurations of the API server of the cluster. This setting is required only when ApiServerPublicAccessEnabled is set to true. Otherwise, it is ignored. tip After cluster creation is complete, you cannot modify this parameter. Configure it appropriately.

EipConfigRequest

Parameter	Type	Required	Sample value	Description
Isp	String	No	BGP	The line type of the EIP. Valid values: BGP: BGP (multi-line).
Bandwidth	Integer	No	100	The maximum bandwidth of the EIP. Unit: Mbit/s. Valid values: If BillingType is set to 2, the valid values of Bandwidth are 1 to 500, and the default value is 10. If BillingType is set to 3, the valid values of Bandwidth are 1 to 200, and the default value is 10.
BillingType	Integer	No	3	The billing type of the EIP. Valid values: 3: (Default) Pay-as-you-go - by actual traffic. This billing method requires a maximum bandwidth limit and incurs fees based on the actual outbound traffic over the Internet, regardless of the usage duration. 2: Pay-as-you-go - by bandwidth limit. After you specify a maximum bandwidth, fees are calculated based on the usage duration, regardless of the actual traffic.
BandwidthPackageId	String	No	bwp-2zeo********	The ID of the shared bandwidth package. The EIP address will be added to the shared bandwidth package. You can call the DescribeBandwidthPackages API to query the ID of the shared bandwidth package. warning An EIP address can be added to a shared bandwidth package only when all of the following conditions are met: The line types are identical. The shared bandwidth package is of type IPv4. No security protection is configured for the shared bandwidth package.

PodsConfigRequest

Parameter	Type	Required	Sample value	Description
PodNetworkMode	String	Yes	Flannel	Pod network model (CNI). Values: Flannel: an independent underlay container network solution, based on which a high-performance network for clusters can be built along with the global routing capabilities of VPCs. VpcCniShared: an underlay network solution implemented based on the ENIs of VPCs, providing high network performance. warning After cluster creation is complete, you cannot modify this parameter. Configure it appropriately.
VpcCniConfig	Object of VpcCniConfigRequest	No	-	The VPC-CNI network configuration. It can be configured only when PodNetworkMode is set to VpcCniShared and is optional.
FlannelConfig	Object of FlannelConfigRequest	No	-	The Flannel network configurations. It is optional and can be specified only if PodNetworkMode is set to Flannel.

VpcCniConfigRequest

Parameter	Type	Required	Sample value	Description
SubnetIds	Array of String	Yes	["subnet-5g39dxxxx","subnet-dwxvxxxx"]	The list of Pod subnet IDs in VPC-CNI networking. It is required only when PodNetworkMode is VpcCniShared. Otherwise, this parameter can be omitted. You can call the VPC API to obtain subnet IDs. warning When creating a cluster, make sure that all specified SubnetIds (including but not limited to this parameter) belong to the same VPC.

FlannelConfigRequest

Parameter	Type	Required	Sample value	Description
PodCidrs	Array of String	Yes	["172.17../19"]	The Pod CIDR blocks in Flannel networking. It is optional and can be specified only if PodNetworkMode is set to Flannel. warning The number of Pods in the cluster is limited by the number of IP addresses in the CIDR blocks. After the cluster is created, you cannot modify the Pod CIDR blocks. Plan the Pod CIDR blocks appropriately. They cannot conflict with the following network segments: The VPC network segments specified by ClusterConfig.SubnetIds of the same cluster. The network segments specified by ServiceConfig.ServiceCidrsv4 of the same cluster. The network segments specified by ServiceConfig.ServiceCidrsv4 of all clusters within the same VPC. The network segments specified by FlannelConfig.PodCidrs (this parameter) of different clusters within the same VPC.
SubnetIds	Array of String	No	["subnet-5g39**","subnet-5g39**"]	The VPC subnet that provides IP addresses for VCI Pods. It is optional and can be specified only if PodNetworkMode is set to Flannel. You can call the VPC API to obtain subnet IDs. warning When creating a cluster, make sure that all specified SubnetIds (including but not limited to this parameter) belong to the same VPC.
MaxPodsPerNode	Integer	No	64	Maximum number of Pod instances per node for Flannel pod networking. Values: 64 (default value) 16 32 128 256

ServicesConfigRequest

Parameter	Type	Required	Sample value	Description
ServiceCidrsv4	Array of String	Yes	["172.25../17"]	The CIDR block used by services within the cluster. warning It must not conflict with the CIDR blocks of FlannelConfig.PodCidrs.SubnetIds or ClusterConfig.SubnetIds for any cluster in the same VPC. Only one array element is supported. If you specify multiple elements, only the first one takes effect.

Tag

Parameter	Type	Required	Sample value	Description
Key	String	Yes	key	The tag key. It cannot start with volc: in ‌any case variation‌. It can only contain letters, digits, spaces, and special characters _.:/=+-@. The length is limited to 1 to 128 characters.
Value	String	No	value	The tag value, which can be left empty. It can only contain letters, digits, spaces, and the following special characters: _.:/=+-@. Its length does not exceed 256 characters.

ClusterLoggingConfigRequest

Parameter	Type	Required	Sample value	Description
LogSetups	Array of LogSetupRequest	No	-	The logging option information for the cluster. An empty array indicates that no logging options are enabled. When logging is enabled for the first time, a log topic is generated automatically. When multiple logging options are provided, LogType cannot be repeated.
LogProjectId	String	No	b68324a0-2680-48c7********	ID of the log project for the cluster. warning It cannot be an empty string. If LogProjectId is not specified during cluster creation, the system will automatically create a new log project. A log project automatically created by the system has a name in the format k8s-log-{clusterId}-{6 random characters}. If LogSetups.Enabled is set to false, no log project will be automatically created. When updating the cluster configuration, if LogProjectId already points to a log project, it cannot be set to an empty value. In a cluster configuration update, if the cluster does not have any log configuration, and only LogProjectId is provided while LogSetups is empty, LogProjectId will be ignored. Updating LogProjectId will create a topic for each log that is enabled.

LogSetupRequest

Parameter	Type	Required	Sample value	Description
LogTtl	Integer	No	30	Log retention duration in TLS. Logs that exceed the specified retention duration in this log topic will be automatically cleared. Valid values: 1 to 3650. Unit: days. Default value: 30 days. A value of 3650 indicates permanent storage.
Enabled	Boolean	No	false	Specify whether to enable this log option. Valid values: false: (Default) Disable it. true: Enable it. warning In a cluster configuration update, if LogType is Audit, modifying Enabled will restart the API server. When you update the cluster configuration, if the value of Enabled changes from false to true, a new log topic will be created.
LogType	String	Yes	Audit	The type of enabled logs. Valid values: Audit: cluster audit logging KubeApiServer: kube-apiserver add-on log KubeScheduler: kube-scheduler add-on log KubeControllerManager: kube-controller-manager add-on log Etcd: etcd add-on log ClusterAutoscaler: cluster-autoscaler add-on log

ClusterKubernetesConfigRequest

Parameter	Type	Required	Sample value	Description
CustomSans	Array of String	No	["abc.com","192.168.0.10"]	Custom certificate SAN (Subject Alternative Name), i.e., the ability to customize domain names or IPs in certificates. Supports entering custom IPs, domain names, or URIs that comply with the specifications. Separate multiple configurations with half-width commas (,), the Enter key, or spaces. Supports up to 6 custom SAN entries in the certificate.
ClusterDomain	String	No	cluster.local	Cluster local domain name. A domain name consists of two or more parts separated by dots (.). Each part supports only lowercase letters, digits, and hyphens (-), and must start and end with a lowercase letter or digit. The maximum length is 57 characters. If you do not specify a local domain name for the cluster, it defaults to cluster.local.
AdvancedConfig	Object of AdvancedConfig	No	-	API Server advanced configuration.
ControlPlaneConfig	Object of KubernetesComponentConfigs	No	-	The custom parameter configuration for Kubernetes core add-ons.

AdvancedConfig

Parameter	Type	Required	Sample value	Description
InternalDnsEnabled	Boolean	No	true	Whether to enable private domain access to the API Server for the cluster: true: (Default) Enabled. Node-side components access the API Server via the private domain. false: Disable it. warning When a new cluster is created, API Server private domain name access is enabled by default and is the only supported option. Disabling it is not supported, meaning that setting it to false will not take effect.

KubernetesComponentConfigs

Parameter	Type	Required	Sample value	Description
KubeApiServerConfig	Object of KubeApiServerConfig	No	-	The custom parameter configuration for the kube-apiserver add-on.

KubeApiServerConfig

Parameter	Type	Required	Sample value	Description
AdmissionPlugins	Object of AdmissionPlugins	No	-	The list of admission control add-ons additionally enabled in kube-apiserver beyond those enabled by default.

AdmissionPlugins

Parameter	Type	Required	Sample value	Description
AlwaysPullImages	Boolean	No	true	Whether to enable the AlwaysPullImages admission control add-on. Valid values: true: Enable it. This indicates that images are forcibly pulled again whenever a Pod is modified. false: (Default) Disable it.

ClusterMonitoringConfigRequest

Parameter	Type	Required	Sample value	Description
WorkspaceId	String	Yes	a72bxxxx-83xx-4axx********	The ID of the VMP workspace used for cluster monitoring. You can obtain the workspace ID by calling the VMP API.
ComponentConfigs	Array of ClusterMonitoringComponentConfigRequest	No	-	The control plane monitoring configuration.

ClusterMonitoringComponentConfigRequest

Parameter	Type	Required	Sample value	Description
Name	String	Yes	KubeApiServer	The control plane add-on of the cluster that needs to be monitored. Valid values: KubeApiServer, KubeScheduler, Etcd, and ClusterAutoscaler.
Enabled	Boolean	No	true	Specify whether to enable control plane add-on monitoring. Valid values: true: Enable it. false: (Default) Disable it.

ClusterMaintenanceWindowConfigRequest

Parameter	Type	Required	Sample value	Description
Duration	Integer	No	4	The duration of automatic O&M. The value is an integer. Value range: 4 to 24. Unit: hours. The default value is 4 if this parameter is not specified.
StartTime	String	No	20:00:00Z	The start time of automatic O&M. It must follow the standard Golang time format and use a 24-hour clock. Valid values are whole hours from 00 to 23. Examples: 01:00:00Z and 14:00:00Z. If this parameter is not configured, the default value is 16:00:00Z (UTC). This corresponds to 00:00:00 the next day in Beijing Time (UTC+8). tip This parameter can only be set to UTC. If you need to use another time zone, you need to manually convert the time to UTC. The ExemptStartDate and ExemptEndDate parameters use Beijing Time (UTC+8) as their default time zone. When the preceding parameters are specified together with this parameter, ensure time zone consistency.
TaskConfigs	Array of WindowTaskConfig	No	-	The configurations of the automatic O&M task. If this parameter is not specified, the system by default only executes cluster control plane daily O&M tasks and does not execute other O&M tasks.
WeeklyCycle	Array of String	No	["Monday","Tuesday"]	The automatic O&M cycle. Valid values: Monday Tuesday Wednesday Thursday Friday Saturday Sunday If this parameter is not specified, the system performs O&M tasks every day by default.
ExemptEndDate	String	No	20260704	The end time of the automatic O&M exemption window, which is in the format of YYYYMMDD, and calculated by calendar day in Beijing Time (UTC+8). For example, if the value is set to 20260704, it indicates that automatic O&M tasks will no longer be executed by 23:59:59 on that date. tip This date must be later than the date configured for ExemptStartDate, and the difference between the two dates must not exceed 60 days.
ExemptStartDate	String	No	20260702	The start time of the automatic O&M exemption window, which is in the format of YYYYMMDD, and calculated by calendar days in Beijing Time (UTC+8). For example, if the value is set to 20260702, it indicates that automatic O&M tasks will no longer be executed from 00:00:00 on that date. tip This date must be earlier than the date configured for ExemptEndDate, and the difference between the two dates must not exceed 60 days. In scenarios such as business-critical periods or network lockdowns, you can configure an exemption window to prohibit the system from performing automatic O&M operations.

WindowTaskConfig

Parameter	Type	Required	Sample value	Description
Group	String	Yes	Cluster	The group of automatic O&M tasks. Valid values: Cluster: Control plane O&M. Addon: Data plane O&M.
Action	String	Yes	AutoUpgradeAddonVersion	The automatic O&M task. Valid values: AutoUpgradeClusterMinorVersion: A task that automatically upgrades cluster patch versions. This task can be configured only if Group is set to Cluster. AutoUpgradeAddonVersion: A task that automatically upgrades add-on versions. This task can be configured only if Group is set to Addon. When you configure this task, you also need to use Targets to specify the add-ons to be upgraded.
Targets	Array of String	No	["metrics-server","cluster-autoscaler"]	Specify the add-on for which automatic version upgrade is performed. You can specify multiple add-ons, which are separated by commas (,). The following add-ons are supported: cluster-autoscaler, metrics-server, log-collector, event-collector, node-problem-detector, metrics-collector, and prometheus-agent. tip For the introduction and description of the preceding add-ons, see Add-on overview. Currently, only some add-ons support automatic upgrades. To upgrade other add-ons, manually upgrade them on the "Addons" page. For details, see Upgrading add-ons.

Sample requests

Response parameters

The following table contains the response parameters of this API. See Response results for details about public response parameters.

Parameter	Type	Sample value	Description
Id	String	cc5si******	Cluster ID.

Sample responses

Error codes

The error codes for this API are listed in the table below. For public error codes, see Public error codes.

HTTP status code	Error code	Error message	Description
400	Insufficient.Balance	Your account has run out of balance.	The balance of the current account is insufficient. Top up your account and try again.
400	QuotaExceeded.Cluster	The number of clusters has reached the limit.	The number of clusters in the current region has reached the quota limit. For more information about product limits, see Usage limits. You can create clusters in other regions, or submit a ticket to apply for a quota increase.
400	VpcMismatch.{{parameter}}	The specified {{resourceType}} {{resourceId}} is not in the same VPC.	The specified subnet IDs do not belong to the same VPC. Specify the parameter and try again.
400	OutOfRange.{{cidrParameter}}	The range of specified CIDR is too small.	The range of the CIDR block is too small, which affects the number of Pods. Plan the CIDR block appropriately and try again.
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.	The CIDR address range is invalid. Check the parameter and try again.
400	OperationDenied.VpcStatus	The status of the specified VPC {{vpcId}} is not valid.	The current status of the specified VPC does not support this action. Confirm the VPC status that this API depends on and try again. You can query VPC status by calling DescribeVpcs.
409	Conflict.Name	The specified name conflicts with existing {{resourceType}}.	A resource with the same name exists in the specified region. Update the resource name and try again.
400	QuotaExceeded.{{ResourceType}}	The quota of {{ResourceType}} has reached the limit.	The quota for the specified resource (such as EIP, LogProject, and LogTopic) has reached the upper limit. Increase the relevant resource quota or delete unused resources. When the available quota is sufficient, try again later.
400	NotSupported.{{parameter}}	The specified {{resourceType}} {{resourceContent}} is not supported.	The specified parameter (such as KubernetesVersion or SubnetId) is not supported. Check the parameter value and try again.
400	Insufficient.SubnetIp	The IP of subnet {{subnetId}} is insufficient.	The available IP addresses in the specified subnet are insufficient. Please specify a compliant subnet and try again later.
400	LimitExceeded.ClusterSubnetZones	You have reached the limit of the number of cluster subnet zones that you can add.	The number of availability zones of subnets in the cluster exceeds the limit. Make sure that the availability zones of subnets do not exceed three.
400	LimitExceeded.ClusterSubnetsOfZone	You have reached the limit of the number of cluster subnets in zone {{zone}} that you can add.	The number of specified subnets in a single availability zone exceeds the limit. Make sure that the number of specified subnets in each availability zone does not exceed 2.

Volcengine Kubernetes Engine