Sign in

v8

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2025-10-165266542.4 MB
DigitalOcean-public.v2-new_Kubernetes

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.

post/v2/kubernetes/clusters

Request body

idstring uuid

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

namestring required

A human-readable name for a Kubernetes cluster.

regionstring required

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

versionstring required

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_subnetstring cidr

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

service_subnetstring cidr

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

vpc_uuidstring uuid

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

ipv4string

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

endpointstring

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

tagsstring[]

An array of tags to apply to the Kubernetes cluster. All clusters are automatically tagged k8s and k8s:$K8S_CLUSTER_ID. <br><br>Requires tag:read and tag:create scope, as well as tag:delete if existing tags are getting removed.

auto_upgradeboolean

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

created_atstring date-time

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

updated_atstring date-time

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

surge_upgradeboolean

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.

haboolean

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.

registry_enabledboolean

A read-only boolean value indicating if a container registry is integrated with the cluster.

Example request

{
  "id": "bd5f5959-5e1e-4205-a714-a914373942af",
  "name": "prod-cluster-01",
  "region": "nyc1",
  "version": "1.18.6-do.0",
  "cluster_subnet": "192.168.0.0/20",
  "service_subnet": "192.168.16.0/24",
  "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b",
  "ipv4": "68.183.121.157",
  "endpoint": "https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com",
  "tags": [
    "k8s",
    "k8s:bd5f5959-5e1e-4205-a714-a914373942af",
    "production",
    "web-team"
  ],
  "node_pools": [
    {
      "size": "s-1vcpu-2gb",
      "id": "cdda885e-7663-40c8-bc74-3a036c66545d",
      "name": "frontend-pool",
      "count": 3,
      "tags": [
        "k8s",
        "k8s:bd5f5959-5e1e-4205-a714-a914373942af",
        "k8s-worker",
        "production",
        "web-team"
      ],
      "taints": [
        {
          "key": "priority",
          "value": "high",
          "effect": "NoSchedule"
        }
      ],
      "auto_scale": true,
      "min_nodes": 3,
      "max_nodes": 6,
      "nodes": [
        {
          "id": "e78247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f",
          "name": "adoring-newton-3niq",
          "status": {
            "state": "provisioning"
          },
          "droplet_id": "205545370",
          "created_at": "2018-11-15T16:00:11Z",
          "updated_at": "2018-11-15T16:00:11Z"
        }
      ]
    }
  ],
  "maintenance_policy": {
    "start_time": "12:00",
    "duration": "4h0m0s",
    "day": "any"
  },
  "auto_upgrade": true,
  "status": {
    "state": "provisioning",
    "message": "provisioning"
  },
  "created_at": "2018-11-15T16:00:11Z",
  "updated_at": "2018-11-15T16:00:11Z",
  "surge_upgrade": true,
  "ha": true,
  "registry_enabled": true,
  "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": "1m0s",
    "expanders": [
      "priority",
      "random"
    ]
  },
  "routing_agent": {
    "enabled": true
  },
  "amd_gpu_device_plugin": {
    "enabled": true
  },
  "amd_gpu_device_metrics_exporter_plugin": {
    "enabled": true
  },
  "nvidia_gpu_device_plugin": {
    "enabled": true
  }
}

Response

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

Example response

{
  "kubernetes_cluster": {
    "id": "bd5f5959-5e1e-4205-a714-a914373942af",
    "name": "prod-cluster-01",
    "region": "nyc1",
    "version": "1.18.6-do.0",
    "cluster_subnet": "192.168.0.0/20",
    "service_subnet": "192.168.16.0/24",
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b",
    "ipv4": "68.183.121.157",
    "endpoint": "https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com",
    "tags": [
      "k8s",
      "k8s:bd5f5959-5e1e-4205-a714-a914373942af",
      "production",
      "web-team"
    ],
    "node_pools": [
      {
        "size": "s-1vcpu-2gb",
        "id": "cdda885e-7663-40c8-bc74-3a036c66545d",
        "name": "frontend-pool",
        "count": 3,
        "tags": [
          "k8s",
          "k8s:bd5f5959-5e1e-4205-a714-a914373942af",
          "k8s-worker",
          "production",
          "web-team"
        ],
        "taints": [
          {
            "key": "priority",
            "value": "high",
            "effect": "NoSchedule"
          }
        ],
        "auto_scale": true,
        "min_nodes": 3,
        "max_nodes": 6,
        "nodes": [
          {
            "id": "e78247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f",
            "name": "adoring-newton-3niq",
            "status": {
              "state": "provisioning"
            },
            "droplet_id": "205545370",
            "created_at": "2018-11-15T16:00:11Z",
            "updated_at": "2018-11-15T16:00:11Z"
          }
        ]
      }
    ],
    "maintenance_policy": {
      "start_time": "12:00",
      "duration": "4h0m0s",
      "day": "any"
    },
    "auto_upgrade": true,
    "status": {
      "state": "provisioning",
      "message": "provisioning"
    },
    "created_at": "2018-11-15T16:00:11Z",
    "updated_at": "2018-11-15T16:00:11Z",
    "surge_upgrade": true,
    "ha": true,
    "registry_enabled": true,
    "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": "1m0s",
      "expanders": [
        "priority",
        "random"
      ]
    },
    "routing_agent": {
      "enabled": true
    },
    "amd_gpu_device_plugin": {
      "enabled": true
    },
    "amd_gpu_device_metrics_exporter_plugin": {
      "enabled": true
    },
    "nvidia_gpu_device_plugin": {
      "enabled": true
    }
  }
}