dots.v2.kubernetes.clusters.post()
Generated on 13 Nov 2026
from DoTs version
v1.24.0
Usage
client.v2.kubernetes.clusters.post(body: Cluster, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | ClustersPostResponse>Description
To create a new Kubernetes cluster, send a POST request to
/v2/kubernetes/clusters. The request must contain at least one node pool
with at least one worker.
The request may contain a maintenance window policy describing a time period when disruptive maintenance tasks may be carried out. Omitting the policy implies that a window will be chosen automatically. See here for details.
Parameters
idstring optional read-onlyExample:
bd5f5959-5e1e-4205-a714-a914373942afA unique ID that can be used to identify and reference a Kubernetes cluster.
namestring requiredExample:
prod-cluster-01A human-readable name for a Kubernetes cluster.
regionstring requiredExample:
nyc1The slug identifier for the region where the Kubernetes cluster is located.
versionstring requiredExample:
1.18.6-do.0The slug identifier for the version of Kubernetes used for the cluster. If set to a minor version (e.g. "1.14"), the latest version within it will be used (e.g. "1.14.6-do.1"); if set to "latest", the latest published version will be used. See the
/v2/kubernetes/optionsendpoint to find all currently available versions.clusterSubnetstring optionalExample:
192.168.0.0/20The range of IP addresses for the overlay network of the Kubernetes cluster in CIDR notation.
serviceSubnetstring optionalExample:
192.168.16.0/24The range of assignable IP addresses for services running in the Kubernetes cluster in CIDR notation.
vpcUuidstring optionalExample:
c33931f2-a26a-4e61-b85c-4e95a2ec431bA string specifying the UUID of the VPC to which the Kubernetes cluster is assigned.
Requiresvpc:readscope.workerSubnetUuidstring optionalExample:
cbd79771-23eb-49be-b5ea-59cc56222622The UUID of the VPC subnet to attach worker nodes to. When omitted on
create, the default subnet for the VPC is used. This value cannot be changed
after the cluster is created.vpc_uuidmust also be set.
Requiresvpc:readscope.ipv4string optional read-onlyExample:
68.183.121.157The public IPv4 address of the Kubernetes master node. This will not be set if high availability is configured on the cluster (v1.21+)
endpointstring optional read-onlyExample:
https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.comThe base URL of the API server on the Kubernetes master node.
tagsarray of strings optionalExample:
["k8s", "k8s:bd5f5959-5e1e-4205-a714-a914373942af", "production", "web-team"]An array of tags to apply to the Kubernetes cluster. All clusters are automatically tagged
k8sandk8s:$K8S_CLUSTER_ID.
Requirestag:readandtag:createscope, as well astag:deleteif existing tags are getting removed.nodePoolsarray of objects requiredAn object specifying the details of the worker nodes available to the Kubernetes cluster.
Show child properties
sizestring requiredExample:
s-1vcpu-2gbThe slug identifier for the type of Droplet used as workers in the node pool.
idstring optional read-onlyExample:
cdda885e-7663-40c8-bc74-3a036c66545dA unique ID that can be used to identify and reference a specific node pool.
namestring requiredExample:
frontend-poolA human-readable name for the node pool.
countinteger requiredExample:
3The number of Droplet instances in the node pool.
tagsarray of strings optionalExample:
["k8s", "k8s:bd5f5959-5e1e-4205-a714-a914373942af", "k8s-worker", "production", "web-team"]An array containing the tags applied to the node pool. All node pools are automatically tagged
k8s,k8s-worker, andk8s:$K8S_CLUSTER_ID.
Requirestag:readscope.labelsobject or null optionalAn object of key/value mappings specifying labels to apply to all nodes in a pool. Labels will automatically be applied to all existing nodes and any subsequent nodes added to the pool. Note that when a label is removed, it is not deleted from the nodes in the pool.
taintsarray of objects optionalAn array of taints to apply to all nodes in a pool. Taints will automatically be applied to all existing nodes and any subsequent nodes added to the pool. When a taint is removed, it is deleted from all nodes in the pool.
Show child properties
keystring optionalExample:
priorityAn arbitrary string. The
keyandvaluefields of thetaintobject form a key-value pair. For example, if the value of thekeyfield is "special" and the value of thevaluefield is "gpu", the key value pair would bespecial=gpu.valuestring optionalExample:
highAn arbitrary string. The
keyandvaluefields of thetaintobject form a key-value pair. For example, if the value of thekeyfield is "special" and the value of thevaluefield is "gpu", the key value pair would bespecial=gpu.effectstring optionalHow the node reacts to pods that it won't tolerate. Available effect values are
NoSchedule,PreferNoSchedule, andNoExecute.
autoScaleboolean optionalExample:
trueA boolean value indicating whether auto-scaling is enabled for this node pool.
minNodesinteger optionalExample:
3The minimum number of nodes that this node pool can be auto-scaled to. The value will be
0ifauto_scaleis set tofalse.maxNodesinteger optionalExample:
6The maximum number of nodes that this node pool can be auto-scaled to. The value will be
0ifauto_scaleis set tofalse.nodesarray of objects optional read-onlyAn object specifying the details of a specific worker node in a node pool.
Show child properties
idstring optionalExample:
e78247f8-b1bb-4f7a-8db9-2a5f8d4b8f8fA unique ID that can be used to identify and reference the node.
namestring optionalExample:
adoring-newton-3niqAn automatically generated, human-readable name for the node.
statusobject optionalAn object containing a
stateattribute whose value is set to a string indicating the current status of the node.Show child properties
statestring optionalA string indicating the current status of the node.
dropletIdstring optionalExample:
205545370The ID of the Droplet used for the worker node.
createdAtstring optionalExample:
2018-11-15T16:00:11ZA time value given in ISO8601 combined date and time format that represents when the node was created.
updatedAtstring optionalExample:
2018-11-15T16:00:11ZA time value given in ISO8601 combined date and time format that represents when the node was last updated.
gpuPartitionModestring optionalThe AMD GPU partition mode for this node pool. Only applicable to AMD GPU sizes that support partitioning. Immutable after the node pool is created. When omitted, the GPUs in the pool are left unpartitioned.
maintenancePolicyobject or null optionalAn object specifying the maintenance window policy for the Kubernetes cluster.
Show child properties
startTimestring optionalExample:
12:00The start time in UTC of the maintenance window policy in 24-hour clock format / HH:MM notation (e.g.,
15:00).durationstring optional read-onlyExample:
4h0m0sThe duration of the maintenance window policy in human-readable format.
daystring optionalThe day of the maintenance window policy. May be one of
mondaythroughsunday, oranyto indicate an arbitrary week day.
autoUpgradeboolean optionalExample:
trueA boolean value indicating whether the cluster will be automatically upgraded to new patch releases during its maintenance window.
isolatedWorkersboolean optionalExample:
falseA boolean value indicating whether worker nodes in the cluster are not assigned public IP addresses. When omitted on create, the default value is false. When enabled, a NAT gateway must exist in the VPC where the cluster is created.
gpuOperatorReadyboolean optionalExample:
falseA boolean value indicating whether GPU nodes in the cluster are launched with images that do not include pre-installed GPU drivers, allowing GPU drivers to be managed by a GPU operator instead. Mutually exclusive with other GPU-related cluster options, such as
nvidia_gpu_dra_driverandamd_gpu_dra_driver. When omitted on create, the default value is false.statusobject optional read-onlyAn object containing a
stateattribute whose value is set to a string indicating the current status of the cluster.Show child properties
statestring optionalA string indicating the current status of the cluster.
messageEscapedstring optionalExample:
provisioningAn optional message providing additional information about the current cluster state.
createdAtstring optional read-onlyExample:
2018-11-15T16:00:11ZA time value given in ISO8601 combined date and time format that represents when the Kubernetes cluster was created.
updatedAtstring optional read-onlyExample:
2018-11-15T16:00:11ZA time value given in ISO8601 combined date and time format that represents when the Kubernetes cluster was last updated.
surgeUpgradeboolean optionalExample:
trueA boolean value indicating whether surge upgrade is enabled/disabled for the cluster. Surge upgrade makes cluster upgrades fast and reliable by bringing up new nodes before destroying the outdated nodes.
haboolean optionalExample:
trueA boolean value indicating whether the control plane is run in a highly available configuration in the cluster. Highly available control planes incur less downtime. The property cannot be disabled. When omitted on create, the default is version-dependent; for DOKS 1.36.0 and later, the default is true; for earlier versions, the default is false.
registryEnabledboolean optional read-onlyExample:
trueA boolean value indicating whether GPU nodes in the cluster are launched with images that do not include pre-installed GPU drivers, allowing GPU drivers to be managed by a GPU operator instead. Mutually exclusive with other GPU-related cluster options, such as
nvidia_gpu_dra_driverandamd_gpu_dra_driver. When omitted on create, the default value is false.controlPlaneFirewallobject or null optionalAn object specifying the control plane firewall for the Kubernetes cluster. Control plane firewall is in early availability (invite only).
Show child properties
enabledboolean optionalExample:
trueIndicates whether the control plane firewall is enabled.
allowedAddressesarray of strings optionalExample:
["1.2.3.4/32", "1.1.0.0/16"]An array of public addresses (IPv4 or CIDR) allowed to access the control plane.
clusterAutoscalerConfigurationobject or null optionalAn object specifying custom cluster autoscaler configuration.
Show child properties
scaleDownUtilizationThresholdnumber optionalExample:
0.65Used to customize when cluster autoscaler scales down non-empty nodes by setting the node utilization threshold.
scaleDownUnneededTimestring optionalExample:
1m0sUsed to customize how long a node is unneeded before being scaled down.
expandersarray of strings optionalExample:
["priority", "random"]Customizes expanders used by cluster-autoscaler.
The autoscaler will apply each expander from the provided list to narrow down the selection of node types created to scale up,
until either a single node type is left, or the list of expanders is exhausted.
If this flag is unset, autoscaler will use its default expanderrandom.
Passing an empty list (_not_null) will unset any previous expander customizations.
Available expanders:
-random: Randomly selects a node group to scale.
-priority: Selects the node group with the highest priority as per user-provided configuration
-least_waste: Selects the node group that will result in the least amount of idle resources.
ssoobject or null optionalAn object specifying Single Sign-On (SSO) configuration for the Kubernetes cluster.
Show child properties
enabledboolean optionalExample:
trueIndicates whether SSO authentication is enabled for the cluster.
requiredboolean optionalExample:
falseIndicates whether any non-SSO forms of authentication are disallowed.
Can only be set totruewhenenabledistrue.issuerUrlstring optionalExample:
https://sso.example.comThe OIDC issuer URL for the identity provider. Required when
enabledistrue.clientIdstring optionalExample:
doks-cluster-clientThe OIDC client ID registered with the identity provider. Required when
enabledistrue.
routingAgentobject or null optionalAn object specifying whether the routing-agent component should be enabled for the Kubernetes cluster.
Show child properties
enabledboolean optionalExample:
trueIndicates whether the routing-agent component is enabled.
p2pOciRegistryPluginobject or null optionalAn object specifying whether the Peer-to-peer OCI registry component should be enabled for the Kubernetes cluster.
Show child properties
enabledboolean optionalExample:
trueIndicates whether the Peer-to-peer OCI registry component is enabled.
nfsCsiPluginobject or null optionalAn object specifying whether the NFS CSI plugin should be enabled for the Kubernetes cluster.
Show child properties
enabledboolean optionalExample:
trueIndicates whether the NFS CSI plugin is enabled.
amdGpuDevicePluginobject or null optionalAn object specifying whether the AMD GPU Device Plugin should be enabled in the Kubernetes cluster. It's enabled by default for clusters with an AMD GPU node pool.
Show child properties
enabledboolean optionalExample:
trueIndicates whether the AMD GPU Device Plugin is enabled.
amdGpuDeviceMetricsExporterPluginobject or null optionalAn object specifying whether the AMD Device Metrics Exporter should be enabled in the Kubernetes cluster.
Show child properties
enabledboolean optionalExample:
trueIndicates whether the AMD Device Metrics Exporter is enabled.
nvidiaGpuDevicePluginobject or null optionalAn object specifying whether the Nvidia GPU Device Plugin should be enabled in the Kubernetes cluster. It's enabled by default for clusters with an Nvidia GPU node pool.
Show child properties
enabledboolean optionalExample:
trueIndicates whether the Nvidia GPU Device Plugin is enabled.
nvidiaGpuDraDriverobject or null optionalAn object specifying whether the NVIDIA GPU DRA Driver should be enabled in the Kubernetes cluster. Mutually exclusive with
nvidia_gpu_device_plugin.Show child properties
enabledboolean optionalExample:
trueIndicates whether the NVIDIA GPU DRA Driver is enabled.
amdGpuDraDriverobject or null optionalAn object specifying whether the AMD GPU DRA Driver should be enabled in the Kubernetes cluster. Mutually exclusive with
amd_gpu_device_plugin.Show child properties
enabledboolean optionalExample:
trueIndicates whether the AMD GPU DRA Driver is enabled.
rdmaSharedDevPluginobject or null optionalAn object specifying whether the RDMA shared device plugin should be enabled in the Kubernetes cluster.
Show child properties
enabledboolean optionalExample:
trueIndicates whether the RDMA shared device plugin is enabled.
corednsAutoscalerobject or null optionalAn object specifying whether the Cluster Proportional Autoscaler (CPA) add-on for CoreDNS should be enabled for the Kubernetes cluster.
Show child properties
enabledboolean optionalExample:
trueIndicates whether the CoreDNS Cluster Proportional Autoscaler add-on is enabled.
insightsobject or null optionalAn object specifying the Insights telemetry that the customer opts in to for the Kubernetes cluster. This is only accepted when creating a cluster and is not returned in responses. If the object is omitted, or if
logsis not set, no opt-in is recorded for the cluster.Show child properties
logsboolean optionalExample:
trueA boolean value indicating whether the cluster's logs are sent to Insights. Setting this to
falserecords an explicit opt-out. When omitted, no choice is recorded.
Request Sample
Response Example
More Information
See /v2/kubernetes/clusters in the API reference for additional detail on responses, headers, parameters, and more.