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

id string optional read-only

Example: bd5f5959-5e1e-4205-a714-a914373942af

A unique ID that can be used to identify and reference a Kubernetes cluster.

name string required

Example: prod-cluster-01

A human-readable name for a Kubernetes cluster.

region string required

Example: nyc1

The slug identifier for the region where the Kubernetes cluster is located.

version string required

Example: 1.18.6-do.0

The 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/options endpoint to find all currently available versions.

clusterSubnet string optional

Example: 192.168.0.0/20

The range of IP addresses for the overlay network of the Kubernetes cluster in CIDR notation.

serviceSubnet string optional

Example: 192.168.16.0/24

The range of assignable IP addresses for services running in the Kubernetes cluster in CIDR notation.

vpcUuid string optional

Example: c33931f2-a26a-4e61-b85c-4e95a2ec431b

A string specifying the UUID of the VPC to which the Kubernetes cluster is assigned.

Requires vpc:read scope.

workerSubnetUuid string optional

Example: cbd79771-23eb-49be-b5ea-59cc56222622

The 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_uuid must also be set.


Requires vpc:read scope.

ipv4 string optional read-only

Example: 68.183.121.157

The public IPv4 address of the Kubernetes master node. This will not be set if high availability is configured on the cluster (v1.21+)

endpoint string optional read-only

Example: https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com

The base URL of the API server on the Kubernetes master node.

tags array of strings optional

Example: ["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 k8s and k8s:$K8S_CLUSTER_ID.

Requires tag:read and tag:create scope, as well as tag:delete if existing tags are getting removed.

nodePools array of objects required

An object specifying the details of the worker nodes available to the Kubernetes cluster.

Show child properties
size string required

Example: s-1vcpu-2gb

The slug identifier for the type of Droplet used as workers in the node pool.

id string optional read-only

Example: cdda885e-7663-40c8-bc74-3a036c66545d

A unique ID that can be used to identify and reference a specific node pool.

name string required

Example: frontend-pool

A human-readable name for the node pool.

count integer required

Example: 3

The number of Droplet instances in the node pool.

tags array of strings optional

Example: ["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, and k8s:$K8S_CLUSTER_ID.

Requires tag:read scope.

labels object or null optional

An 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.

taints array of objects optional

An 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
key string optional

Example: priority

An arbitrary string. The key and value fields of the taint object form a key-value pair. For example, if the value of the key field is "special" and the value of the value field is "gpu", the key value pair would be special=gpu.

value string optional

Example: high

An arbitrary string. The key and value fields of the taint object form a key-value pair. For example, if the value of the key field is "special" and the value of the value field is "gpu", the key value pair would be special=gpu.

effect string optional

How the node reacts to pods that it won't tolerate. Available effect values are NoSchedule, PreferNoSchedule, and NoExecute.

One of: NoSchedule, PreferNoSchedule, NoExecute

autoScale boolean optional

Example: true

A boolean value indicating whether auto-scaling is enabled for this node pool.

minNodes integer optional

Example: 3

The minimum number of nodes that this node pool can be auto-scaled to. The value will be 0 if auto_scale is set to false.

maxNodes integer optional

Example: 6

The maximum number of nodes that this node pool can be auto-scaled to. The value will be 0 if auto_scale is set to false.

nodes array of objects optional read-only

An object specifying the details of a specific worker node in a node pool.

Show child properties
id string optional

Example: e78247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f

A unique ID that can be used to identify and reference the node.

name string optional

Example: adoring-newton-3niq

An automatically generated, human-readable name for the node.

status object optional

An object containing a state attribute whose value is set to a string indicating the current status of the node.

Show child properties
state string optional

A string indicating the current status of the node.

One of: provisioning, running, draining, deleting

dropletId string optional

Example: 205545370

The ID of the Droplet used for the worker node.

createdAt string optional

Example: 2018-11-15T16:00:11Z

A time value given in ISO8601 combined date and time format that represents when the node was created.

updatedAt string optional

Example: 2018-11-15T16:00:11Z

A time value given in ISO8601 combined date and time format that represents when the node was last updated.

gpuPartitionMode string optional

The 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.

One of: AMD_PARTITION_MODE_SPX_NPS1, AMD_PARTITION_MODE_DPX_NPS2

maintenancePolicy object or null optional

An object specifying the maintenance window policy for the Kubernetes cluster.

Show child properties
startTime string optional

Example: 12:00

The start time in UTC of the maintenance window policy in 24-hour clock format / HH:MM notation (e.g., 15:00).

duration string optional read-only

Example: 4h0m0s

The duration of the maintenance window policy in human-readable format.

day string optional

The day of the maintenance window policy. May be one of monday through sunday, or any to indicate an arbitrary week day.

One of: any, monday, tuesday, wednesday, thursday, friday, saturday, sunday

autoUpgrade boolean optional

Example: true

A boolean value indicating whether the cluster will be automatically upgraded to new patch releases during its maintenance window.

Default: false

isolatedWorkers boolean optional

Example: false

A 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.

Default: false

gpuOperatorReady boolean optional

Example: false

A 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_driver and amd_gpu_dra_driver. When omitted on create, the default value is false.

Default: false

status object optional read-only

An object containing a state attribute whose value is set to a string indicating the current status of the cluster.

Show child properties
state string optional

A string indicating the current status of the cluster.

One of: running, provisioning, degraded, error, deleted, upgrading, deleting

messageEscaped string optional

Example: provisioning

An optional message providing additional information about the current cluster state.

createdAt string optional read-only

Example: 2018-11-15T16:00:11Z

A time value given in ISO8601 combined date and time format that represents when the Kubernetes cluster was created.

updatedAt string optional read-only

Example: 2018-11-15T16:00:11Z

A time value given in ISO8601 combined date and time format that represents when the Kubernetes cluster was last updated.

surgeUpgrade boolean optional

Example: true

A 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.

Default: false

ha boolean optional

Example: true

A 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.

registryEnabled boolean optional read-only

Example: true

A 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_driver and amd_gpu_dra_driver. When omitted on create, the default value is false.

controlPlaneFirewall object or null optional

An object specifying the control plane firewall for the Kubernetes cluster. Control plane firewall is in early availability (invite only).

Show child properties
enabled boolean optional

Example: true

Indicates whether the control plane firewall is enabled.

allowedAddresses array of strings optional

Example: ["1.2.3.4/32", "1.1.0.0/16"]

An array of public addresses (IPv4 or CIDR) allowed to access the control plane.

clusterAutoscalerConfiguration object or null optional

An object specifying custom cluster autoscaler configuration.

Show child properties
scaleDownUtilizationThreshold number optional

Example: 0.65

Used to customize when cluster autoscaler scales down non-empty nodes by setting the node utilization threshold.

scaleDownUnneededTime string optional

Example: 1m0s

Used to customize how long a node is unneeded before being scaled down.

expanders array of strings optional

Example: ["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 expander random.
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.

sso object or null optional

An object specifying Single Sign-On (SSO) configuration for the Kubernetes cluster.

Show child properties
enabled boolean optional

Example: true

Indicates whether SSO authentication is enabled for the cluster.

Default: false

required boolean optional

Example: false

Indicates whether any non-SSO forms of authentication are disallowed.
Can only be set to true when enabled is
true.

Default: false

issuerUrl string optional

Example: https://sso.example.com

The OIDC issuer URL for the identity provider. Required when enabled is
true.

clientId string optional

Example: doks-cluster-client

The OIDC client ID registered with the identity provider. Required when
enabled is true.

routingAgent object or null optional

An object specifying whether the routing-agent component should be enabled for the Kubernetes cluster.

Show child properties
enabled boolean optional

Example: true

Indicates whether the routing-agent component is enabled.

p2pOciRegistryPlugin object or null optional

An object specifying whether the Peer-to-peer OCI registry component should be enabled for the Kubernetes cluster.

Show child properties
enabled boolean optional

Example: true

Indicates whether the Peer-to-peer OCI registry component is enabled.

nfsCsiPlugin object or null optional

An object specifying whether the NFS CSI plugin should be enabled for the Kubernetes cluster.

Show child properties
enabled boolean optional

Example: true

Indicates whether the NFS CSI plugin is enabled.

amdGpuDevicePlugin object or null optional

An 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
enabled boolean optional

Example: true

Indicates whether the AMD GPU Device Plugin is enabled.

amdGpuDeviceMetricsExporterPlugin object or null optional

An object specifying whether the AMD Device Metrics Exporter should be enabled in the Kubernetes cluster.

Show child properties
enabled boolean optional

Example: true

Indicates whether the AMD Device Metrics Exporter is enabled.

nvidiaGpuDevicePlugin object or null optional

An 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
enabled boolean optional

Example: true

Indicates whether the Nvidia GPU Device Plugin is enabled.

nvidiaGpuDraDriver object or null optional

An 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
enabled boolean optional

Example: true

Indicates whether the NVIDIA GPU DRA Driver is enabled.

amdGpuDraDriver object or null optional

An 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
enabled boolean optional

Example: true

Indicates whether the AMD GPU DRA Driver is enabled.

rdmaSharedDevPlugin object or null optional

An object specifying whether the RDMA shared device plugin should be enabled in the Kubernetes cluster.

Show child properties
enabled boolean optional

Example: true

Indicates whether the RDMA shared device plugin is enabled.

corednsAutoscaler object or null optional

An object specifying whether the Cluster Proportional Autoscaler (CPA) add-on for CoreDNS should be enabled for the Kubernetes cluster.

Show child properties
enabled boolean optional

Example: true

Indicates whether the CoreDNS Cluster Proportional Autoscaler add-on is enabled.

insights object or null optional

An 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 logs is not set, no opt-in is recorded for the cluster.

Show child properties
logs boolean optional

Example: true

A boolean value indicating whether the cluster's logs are sent to Insights. Setting this to false records an explicit opt-out. When omitted, no choice is recorded.

Request Sample

Show Request Sample
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
import {
    createDigitalOceanClient,
    DigitalOceanApiKeyAuthenticationProvider,
} from "@digitalocean/dots";

const authProvider = new DigitalOceanApiKeyAuthenticationProvider(process.env.DIGITALOCEAN_TOKEN!);
const adapter = new FetchRequestAdapter(authProvider);
const client = createDigitalOceanClient(adapter);

const response = await client.v2.kubernetes.clusters.post({
    name: "prod-cluster-01",
    region: "nyc1",
    version: "1.18.6-do.0",
    isolatedWorkers: false,
    gpuOperatorReady: false,
    nodePools: [
        {
            size: "s-1vcpu-2gb",
            count: 3,
            name: "worker-pool",
        },
    ],
});

Response Example

Show Response Example
{
  "kubernetes_cluster": {
    "id": "bd5f5959-5e1e-4205-a714-a914373942af",
    "name": "prod-cluster-01",
    "region": "nyc1",
    "version": "1.18.6-do.0",
    "cluster_subnet": "10.244.0.0/16",
    "service_subnet": "10.245.0.0/16",
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b",
    "ipv4": "",
    "endpoint": "",
    "tags": [
      "k8s",
      "k8s:bd5f5959-5e1e-4205-a714-a914373942af"
    ],
    "node_pools": [
      {
        "id": "cdda885e-7663-40c8-bc74-3a036c66545d",
        "name": "worker-pool",
        "size": "s-1vcpu-2gb",
        "count": 3,
        "tags": [
          "k8s",
          "k8s:bd5f5959-5e1e-4205-a714-a914373942af",
          "k8s:worker"
        ],
        "labels": null,
        "taints": [],
        "auto_scale": false,
        "min_nodes": 0,
        "max_nodes": 0,
        "nodes": [
          {
            "id": "478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f",
            "name": "",
            "status": {
              "state": "provisioning"
            },
            "droplet_id": "",
            "created_at": "2018-11-15T16:00:11Z",
            "updated_at": "2018-11-15T16:00:11Z"
          },
          {
            "id": "ad12e744-c2a9-473d-8aa9-be5680500eb1",
            "name": "",
            "status": {
              "state": "provisioning"
            },
            "droplet_id": "",
            "created_at": "2018-11-15T16:00:11Z",
            "updated_at": "2018-11-15T16:00:11Z"
          },
          {
            "id": "e46e8d07-f58f-4ff1-9737-97246364400e",
            "name": "",
            "status": {
              "state": "provisioning"
            },
            "droplet_id": "",
            "created_at": "2018-11-15T16:00:11Z",
            "updated_at": "2018-11-15T16:00:11Z"
          }
        ]
      }
    ],
    "maintenance_policy": {
      "start_time": "00:00",
      "duration": "4h0m0s",
      "day": "any"
    },
    "auto_upgrade": false,
    "isolated_workers": false,
    "gpu_operator_ready": false,
    "status": {
      "state": "provisioning",
      "message": "provisioning"
    },
    "created_at": "2018-11-15T16:00:11Z",
    "updated_at": "2018-11-15T16:00:11Z",
    "surge_upgrade": false,
    "registry_enabled": false,
    "registries": [
      "registry-a",
      "registry-b"
    ],
    "ha": false,
    "control_plane_firewall": {
      "enabled": true,
      "allowed_addresses": [
        "1.2.3.4/32",
        "1.1.0.0/16"
      ]
    },
    "cluster_autoscaler_configuration": {
      "scale_down_utilization_threshold": 0.65,
      "scale_down_unneeded_time": "1m",
      "expanders": [
        "priority",
        "random"
      ]
    },
    "sso": {
      "enabled": true,
      "required": false,
      "issuer_url": "https://sso.example.com",
      "client_id": "doks-cluster-client"
    },
    "routing_agent": {
      "enabled": false
    },
    "amd_gpu_device_plugin": {
      "enabled": false
    },
    "amd_gpu_device_metrics_exporter_plugin": {
      "enabled": false
    },
    "nvidia_gpu_device_plugin": {
      "enabled": false
    },
    "nvidia_gpu_dra_driver": {
      "enabled": false
    },
    "amd_gpu_dra_driver": {
      "enabled": false
    },
    "rdma_shared_dev_plugin": {
      "enabled": false
    },
    "coredns_autoscaler": {
      "enabled": false
    },
    "p2p_oci_registry_plugin": {
      "enabled": false
    },
    "nfs_csi_plugin": {
      "enabled": false
    }
  }
}

More Information

See /v2/kubernetes/clusters in the API reference for additional detail on responses, headers, parameters, and more.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.