---
title: "Create Kubernetes cluster"
method: POST
path: "/v1/kubernetes"
tags: ["Kubernetes clusters"]
---

# Create Kubernetes cluster

`POST /v1/kubernetes`

## Request

- Base URL: `https://api.emma.ms/external`
- URL: `https://api.emma.ms/external/v1/kubernetes`
- Auth: HTTP bearer

Creates a Managed Kubernetes cluster. Kubernetes Service provides the ability to deploy and manage Kubernetes clusters without worrying about the setup and maintenance of master nodes. emma manages the Kubernetes control plane, so you can focus on deploying and managing your applications. You do not need to create master nodes.

We offer reliable and highly available infrastructure for your cluster across multiple cloud providers. For Direct Connect, clusters can be deployed on AWS, Azure, and GCP. For Internet Connect, clusters can be deployed on AWS, Azure, and GCP by default. DigitalOcean and Gcore are also available for Internet Connect on request.

By default, clusters can be deployed only in the European region. Deployment in the US region is available on request.

Choose the network type: Direct Connect or Internet Connect. Direct Connect requires this option to be enabled in the Network section. Internet Connect does not require any additional actions.

When creating worker nodes, you need to select the appropriate hardware configuration. The available configuration depends on the provider and the data center. Use the `/v1/kubernetes-configs` endpoint to find available worker node configurations.

If workerNodes is not provided, at least one autoscaling group must have minimumNodes >= 1.

A cluster currently supports up to 5 autoscaling groups and a total of 16 worker nodes.

## Request body

- KubernetesCreateRequest
  - `deploymentLocation` 'eu' | 'us', required: Deployment location
  - `k8sVersion` string: Kubernetes version
  - `projectName` string: Project name
  - `name` string, required: Kubernetes cluster name
  - `k8sConnectionType` 'direct_connect' | 'internet_connect', required: Kubernetes connection type
  - `workerNodes` object[], nullable: List of worker nodes.
    - `name` string, required: Worker node name
    - `providerId` integer: Provider ID
    - `locationId` integer: Location ID
    - `dataCenterId` string, required: Data center ID
    - `osId` integer: Operating system ID
    - `osType` string: Operating system type
    - `osVersion` string: Operating system version
    - `cloudNetworkTypes` string[]: Cloud network types
    - `vCpuType` 'shared' | 'standard' | 'hpc', required: Type of the virtual Central Processing Unit (vCPU)
    - `vCpu` integer, required: Number of virtual Central Processing Units (vCPUs)
    - `ramGb` integer, required: Capacity of the RAM in gigabytes
    - `volumeGb` integer, required: Capacity of the volume in gigabytes
    - `volumeType` 'ssd' | 'ssd-plus', required: Volume type
    - `acceleratorTypeId` string: GPU accelerator type identifier
    - `accelerators` integer: Number of GPUs for the node configuration
    - `instanceType` 'on_demand' | 'spot': How the node's VM is purchased. A spot instance is cheaper, but the provider may reclaim it at any time and the platform then recreates the node. At least one `on_demand` node is required per cluster.
  - `autoscalingConfigs` object[], nullable: Configurations of the autoscaling group. If `workerNodes` is omitted or empty, `autoscalingConfigs` must contain at least one group. Each group must have either node-count scaling fields (`minimumNodes`, `maximumNodes`, `targetNodes`) or vCPU-count scaling fields (`minimumVCpus`, `maximumVCpus`, `targetVCpus`) — but not both and not neither.
    - `groupName` string: Name of the autoscaling group
    - `dataCenterId` string: ID of the data center
    - `minimumNodes` integer: Minimum number of nodes
    - `maximumNodes` integer: Maximum number of nodes
    - `targetNodes` integer: Deprecated alias of minOnDemandCount (former desired total node count). Used only when minOnDemandCount is not provided.
    - `minimumVCpus` integer, nullable: Minimum number of vCPUs.Required when using vCPU-count based autoscaling. Must be null if `minimumNodes` is set.
    - `maximumVCpus` integer, nullable: Maximum number of vCPUs. Required when using vCPU-count based autoscaling. Must be null if `maximumNodes` is set.
    - `targetVCpus` integer, nullable: Deprecated alias of minOnDemandCount (former desired total vCPU count). Used only when minOnDemandCount is not provided.
    - `minOnDemandCount` integer, nullable: Minimum guaranteed number of on-demand (non-spot) units in the group — nodes for node-count scaling, vCPUs for vCPU-count scaling. Allowed range is 0..maximum. It constrains the composition of the existing nodes, not the group size. Defaults to 0 (or to the deprecated target field when provided).
    - `useOnDemandInstancesInsteadOfSpots` boolean: Use on-demand compute instances instead of spot compute instances
    - `spotPercent` integer: Percentage of spot instances in the autoscaling group
    - `spotMarkup` number: Extra markup to the spot instance price
    - `userLabels` object[], nullable: ASG labels applied to nodes created by this autoscaling group
      - `key` string, required: ASG label key
      - `value` string, required: ASG label value
    - `configurationPriorities` object[]: Compute instance configurations with priorities
      - `ramGb` integer: Capacity of the RAM in gigabytes
      - `volumeGb` integer: Capacity of the volume in gigabytes
      - `volumeType` 'ssd' | 'ssd-plus': Volume type
      - `priority` 'high' | 'med' | 'low': Configuration priority
      - `vCpuType` 'shared' | 'standard' | 'hpc': Type of the virtual Central Processing Unit (vCPU)
      - `vCpu` integer: Number of virtual Central Processing Units (vCPUs)

## Response `200`

Successful operation

- KubernetesCreateResponse
  - `id` integer: ID of the Kubernetes cluster
  - `createdAt` string: Date and time of the Kubernetes cluster creation
  - `createdByName` string: Name of the user who created the Kubernetes cluster
  - `createdById` integer: ID of the user who created the Kubernetes cluster
  - `modifiedAt` string: Date and time when the Kubernetes cluster was last edited
  - `modifiedByName` string: Name of the user who last edited the Kubernetes cluster
  - `modifiedById` integer: ID of the user who last edited the Kubernetes cluster
  - `name` string: Name of the Kubernetes cluster
  - `version` string: Version of the Kubernetes cluster
  - `deploymentLocation` 'eu' | 'us': Deployment region of the Kubernetes cluster. Currently, only Europe (eu) is available.
  - `k8sConnectionType` 'direct_connect' | 'internet_connect': Specifies the network connectivity type for the cluster. Immutable: set at creation only. To change, delete and create a new cluster.
  - `status` string: Status of the Kubernetes cluster
  - `cost` object: Total cost of the Kubernetes cluster for the period
    - `unit` string: Cost period
    - `currency` string: Currency of the cost
    - `price` number: Cost for the period
  - `controlPlaneStatus` 'CREATING' | 'ACTIVE' | 'UPDATING' | 'DEGRADED' | 'UNHEALTHY' | 'FAILED' | 'DESTRUCTION': Control Plane Status. The Control Plane status provides information about the health and functionality of various components that are part of the Control Plane.
  - `domainName` string, nullable: Domain attached to the Kubernetes cluster
  - `nodeGroups` object[]: List of the worker node groups
    - `name` string: Name of the worker node group
    - `nodes` object[]: List of the worker nodes
      - `id` integer: ID of the worker node
      - `createdAt` string: Date and time when the worker node was created
      - `name` string: Name of the worker node
      - `status` 'POWERED_ON' | 'POWERED_OFF' | 'BUSY' | 'DRAFT': Status of the worker node
      - `instanceType` 'on_demand' | 'spot': How the node's VM was purchased. A `spot` node is cheaper, but the provider may reclaim it at any time and the platform then recreates it. Absent when the purchase mode cannot be resolved — read that as `on_demand`.
      - `nodeStatus` 'PROVISIONING' | 'JOINING' | 'ACTIVE' | 'PENDING' | 'DELETING' | 'FAILED': Worker node lifecycle status
      - `provider` object: Cloud provider of the worker node
        - `id` integer: ID of the cloud provider of the worker node
        - `name` string: Name of the cloud provider of the worker node
      - `location` object: Geographic location where the worker node is deployed
        - `id` integer: Location ID of the worker node
        - `name` string: Location name (city or state) of the worker node
        - `country` string: Country of the worker node location
        - `continent` string: Name of the geographical continent
        - `region` string: Name of the geographical region
        - `latitude` number, double: Approximate latitude of the geographical location
        - `longitude` number, double: Approximate longitude of the geographical location
      - `dataCenter` object: Data center where the worker node is deployed
        - `id` string: ID of the cloud provider's data center where the worker node is deployed
        - `name` string: Name of the cloud provider's data center where the worker node is deployed
        - `providerId` integer: ID of the cloud provider
        - `providerName` string: Name of the cloud provider
        - `locationId` integer: Location ID
        - `locationName` string: Location Name (city or state)
      - `os` object: Operating system
        - `id` integer: ID of the operating system
        - `family` string: Family of the operating system
        - `architecture` string: Architecture of the operating system
        - `type` string: Type of the operating system
        - `version` string: Version of the operating system
      - `vCpu` integer: Number of virtual Central Processing Units (vCPUs)
      - `vCpuType` 'shared' | 'standard' | 'hpc': Type of the virtual Central Processing Unit
      - `cloudNetworkType` 'multi-cloud' | 'default': Type of the cloud network (multi-cloud, isolated)
      - `ramGb` integer: Capacity of the RAM in gigabytes
      - `disks` object[]: Volumes attached
        - `id` integer: Volume ID
        - `name` string: Volume name
        - `sizeGb` integer: Volume size in gigabytes
        - `typeId` integer: ID of the volume type
        - `type` string: Volume type
        - `isBootable` boolean: Indicates whether the volume is bootable or not
        - `deviceIdentifier` string, nullable: Device identifier of the volume as seen by the operating system
      - `networks` object[], nullable: Public and private networks
        - `id` integer: Network ID
        - `ip` string, nullable: Network IP. Null for nodes that have not yet received an IP address (e.g. PENDING or FAILED nodes).
        - `networkTypeId` integer: ID of the network type
        - `networkType` string: Network type
        - `ipVersion` string, nullable: IP version
      - `securityGroup` object, nullable: Security group of the worker node
        - `id` integer: ID of the security group
        - `name` string: Name of the security group
      - `localDisks` object[], nullable: Local SSD storage directly attached to the host. Data is ephemeral and will be lost when the VM is stopped or deleted.
        - `sizeTb` number: Volume size in TB
        - `typeId` integer, nullable: ID of the volume type
        - `type` string: Volume type
      - `accelerator` object, nullable: GPU accelerator
        - `acceleratorTypeId` string: GPU accelerator type ID
        - `acceleratorType` string: GPU accelerator type
        - `accelerators` number: Quantity of GPU accelerators
        - `totalGpuMemoryGb` integer: Total GPU memory (GPU)
      - `cost` object: Total cost of the worker node for the period
        - `unit` string: Period
        - `currency` string: Currency of the cost
        - `price` number: Cost for the period
    - `status` 'CREATING' | 'ACTIVE' | 'SCALING_UP' | 'SCALING_DOWN' | 'READY' | 'UNHEALTHY' | 'DESTRUCTION', nullable: Node group (ASG) runtime status. Null for static (non-autoscaling) node groups.
    - `scalingPolicy` 'ENABLED' | 'SCALE_UP_ONLY' | 'SCALE_DOWN_ONLY' | 'DISABLED', nullable: Autoscaling policy applied to the node group. Null for static node groups.
  - `autoscalingConfigs` object[], nullable: Configurations of the autoscaling group
    - `groupName` string: Name of the autoscaling group
    - `dataCenterId` string: ID of the data center
    - `minimumNodes` integer: Minimum number of nodes
    - `maximumNodes` integer: Maximum number of nodes
    - `targetNodes` integer: Deprecated alias of minOnDemandCount (former desired total node count). Used only when minOnDemandCount is not provided.
    - `minimumVCpus` integer, nullable: Minimum number of vCPUs. Required when using vCPU-count based autoscaling. Must be null if `minimumNodes` is set.
    - `maximumVCpus` integer, nullable: Maximum number of vCPUs. Required when using vCPU-count based autoscaling. Must be null if `maximumNodes` is set.
    - `targetVCpus` integer, nullable: Target number of vCPUs
    - `minOnDemandCount` integer, nullable: Minimum guaranteed number of on-demand (non-spot) units in the group — nodes for node-count scaling, vCPUs for vCPU-count scaling. Allowed range is 0..maximum. It constrains the composition of the existing nodes, not the group size. Defaults to 0 (or to the deprecated target field when provided).
    - `nodeGroupPriceLimit` number, nullable: Price limit of the autoscaling group
    - `useOnDemandInstancesInsteadOfSpots` boolean: Use on-demand compute instances instead of spot compute instances
    - `spotPercent` integer: Percentage of spot instances in the autoscaling group
    - `spotMarkup` number: Extra markup to the spot instance price
    - `userLabels` object[], nullable: ASG labels applied to nodes created by this autoscaling group
      - `key` string, required: ASG label key
      - `value` string, required: ASG label value. Required and non-nullable; empty string is allowed.
    - `configurationPriorities` object[]: Compute instance configurations with priorities
      - `vCpuType` 'shared' | 'standard' | 'hpc': Type of the virtual Central Processing Unit (vCPU)
      - `vCpu` integer: Number of virtual Central Processing Units (vCPUs)
      - `ramGb` integer: Capacity of the RAM in gigabytes
      - `volumeGb` integer: Capacity of the volume in gigabytes
      - `volumeType` 'ssd' | 'ssd-plus': Volume type
      - `priority` 'high' | 'med' | 'low': Configuration priority
    - `limitsNotice` string, nullable: Limits notice message

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable entity
- `500`: Internal server error

---

[API](https://skmtc.dev/emma/apis/public-emma-api.md) - [All operations](https://skmtc.dev/emma/apis/public-emma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/emma/apis/public-emma-api/revisions/9e55f0920078?raw)