POST/v2/kubernetes/clusters

Create a New Kubernetes Cluster

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.

IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

35 body fields

idstringoptional

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

namestringrequired

A human-readable name for a Kubernetes cluster.

regionstringrequired

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

versionstringrequired

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.

cluster_subnetstringoptional

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

service_subnetstringoptional

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

vpc_uuidstringoptional

A string specifying the UUID of the VPC to which the Kubernetes cluster is assigned. Requires `vpc:read` scope.

worker_subnet_uuidstringoptional

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.

ipv4stringoptional

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

endpointstringoptional

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

tagsarray<string>optional

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.

node_poolsarray<object>required

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

maintenance_policyobjectoptional

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

auto_upgradebooleanoptional

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

Default:false

isolated_workersbooleanoptional

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

gpu_operator_readybooleanoptional

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

statusobjectoptional

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

created_atstringoptional

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

updated_atstringoptional

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

surge_upgradebooleanoptional

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

habooleanoptional

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.

registry_enabledbooleanoptional

control_plane_firewallobjectoptional

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

cluster_autoscaler_configurationobjectoptional

An object specifying custom cluster autoscaler configuration.

ssoobjectoptional

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

routing_agentobjectoptional

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

p2p_oci_registry_pluginobjectoptional

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

nfs_csi_pluginobjectoptional

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

amd_gpu_device_pluginobjectoptional

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.

amd_gpu_device_metrics_exporter_pluginobjectoptional

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

nvidia_gpu_device_pluginobjectoptional

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.

nvidia_gpu_dra_driverobjectoptional

An object specifying whether the NVIDIA GPU DRA Driver should be enabled in the Kubernetes cluster. Mutually exclusive with `nvidia_gpu_device_plugin`.

amd_gpu_dra_driverobjectoptional

An object specifying whether the AMD GPU DRA Driver should be enabled in the Kubernetes cluster. Mutually exclusive with `amd_gpu_device_plugin`.

rdma_shared_dev_pluginobjectoptional

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

coredns_autoscalerobjectoptional

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

5 status codes

201The response will be a JSON object with a key called `kubernetes_cluster`. The value of this will be an object containing the standard attributes of a Kubernetes cluster. The IP address and cluster API server endpoint will not be available until the cluster has finished provisioning. The initial value of the cluster's `status.state` attribute will be `provisioning`. When the cluster is ready, this will transition to `running`.

kubernetes_clusterobjectoptional

401Authentication failed due to invalid credentials.

idstringrequired

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

messagestringrequired

A message providing additional information about the error, including details to help resolve it when possible.

request_idstringoptional

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429The API rate limit has been exceeded.

idstringrequired

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

messagestringrequired

A message providing additional information about the error, including details to help resolve it when possible.

request_idstringoptional

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500There was a server error.

idstringrequired

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

messagestringrequired

A message providing additional information about the error, including details to help resolve it when possible.

request_idstringoptional

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

defaultThere was an unexpected error.

idstringrequired

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

messagestringrequired

A message providing additional information about the error, including details to help resolve it when possible.

request_idstringoptional

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned: Authentication failed due to invalid credentials. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.

import { Client } from "@octridev/digitalocean";

const client = new Client({
  baseUrl: "https://api.digitalocean.com",
  auth: { bearer: process.env.API_TOKEN },
});

const result = await client.clusters.create({
  name: "Untitled",
  region: "example",
  version: "example",
  nodePools: [],
  id: "9b2f1c10-7a3e-4d54-8c2a-1f6b9e0d4a21",
});

{
  "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
    }
  }
}

Request

Response

Errors