---
title: "Create cluster"
slug: "nks-createcluster"
updated: 2026-09-17T10:05:54Z
published: 2026-09-17T10:05:54Z
canonical: "api.ncloud-docs.com/nks-createcluster"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create cluster

Available in VPC

Create a new cluster based on the entered information.

## Request

This section describes the request format. The method and URI are as follows:

| Method | URI |
| --- | --- |
| POST | /vnks/v2/clusters (Korea Region) |
| POST | /vnks/sgn-v2/clusters (Singapore Region) |
| POST | /vnks/jpn-v2/clusters (Japan Region) |

### Request headers

For information about the headers common to all Ncloud Kubernetes Service APIs, see [Common Ncloud Kubernetes Service request headers](/docs/en/compute-vpckubernetesservice#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### Request body

You can include the following data in the body of your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | String | Required | Cluster name - 3 to 30 characters, including letters, numbers, and the special character "-", and must begin with an English letter and end with an English letter or number. |
| `clusterType` | String | Required | Cluster type - XEN - 10 EA: SVR.VNKS.STAND.C002.M008.NET.SSD.B050.G002 - 50 EA: SVR.VNKS.STAND.C004.M016.NET.SSD.B050.G002 - KVM - 250 EA: SVR.VNKS.STAND.C004.M016.G003 |
| `k8sVersion` | String | Optional | Kubernetes version - See [Get supported K8s versions](/docs/en/nks-viewk8sversion). |
| `loginKeyName` | String | Required | Authentication key name - Enter the name of the authentication key you have. |
| `hypervisorCode` | String | Optional | Hypervisor type - `XEN` (default) \| `KVM` |
| `regionCode` | String | Required | Region code - See [getRegionList](/docs/en/platform-region-getregionlist). |
| `isRegional` | Boolean | Optional | Whether the cluster is a multi-zone (regional) cluster - `true` \| `false`(default) - If `true`, `zoneCode` and `zoneNo` don't need to be entered. - Only versions where `isRegionalSupport` is `true` in [Get supported k8s versions](/docs/en/nks-viewk8sversion) are available. |
| `zoneCode` | String | Conditional | Zone code - Not needed if `isRegional` is `true`. - Required if `zoneNo` is not entered. - See [getZoneList](/docs/en/compute-vserver-server-common-getzonelist). |
| `zoneNo` | Integer | Conditional | Zone number - Not needed if `isRegional` is `true`. - Required if `zoneCode` is not entered. - See [getZoneList](/docs/en/compute-vserver-server-common-getzonelist). |
| `publicNetwork` | Boolean | Optional | Subnet network type - `true` \| `false` (default) - `true`: Public - `false`: Private |
| `vpcNo` | Integer | Required | Number of VPC where the cluster will be placed in - See [getVpcList](/docs/en/networking-vpc-vpcmanagement-getvpclist). |
| `subnetNoList[]` | Array | Required | Subnet number list - If `publicNetwork` is false, enter the subnet ID of the general purpose private subnet. - If `publicNetwork` if true, enter the subnet ID of the general purpose public subnet. - See [getSubnetList](/docs/en/networking-vpc-subnetmanagement-getsubnetlist). |
| `subnetLbNo` | Integer | Conditional | @deprecated Private subnet number dedicated to load balancer - See [getSubnetList](/docs/en/networking-vpc-subnetmanagement-getsubnetlist). |
| `lbPrivateSubnetNo` | Integer | Conditional | Private subnet number dedicated to the load balancer to be applied to the cluster - See [getSubnetList](/docs/en/networking-vpc-subnetmanagement-getsubnetlist). |
| `lbPrivateSubnetNoList[]` | Array | Conditional | List of private subnet numbers dedicated to load balancers to be applied to the cluster - Required if `lbPrivateSubnetNo` is not entered. - For multi-zone configurations, enter up to 2 values (one per zone). Only subnets from different zones are allowed. - The first value is used as the representative subnet for single-zone load balancers and network load balancers. - `lbPrivateSubnetNo` is applied if not entered. - See [getSubnetList](/docs/en/networking-vpc-subnetmanagement-getsubnetlist). |
| `lbPublicSubnetNo` | Integer | Conditional | Public subnet number dedicated to the load balancer to be applied to the cluster - Required if `lbPublicSubnetNoList` is not entered. - See [getSubnetList](/docs/en/networking-vpc-subnetmanagement-getsubnetlist). |
| `lbPublicSubnetNoList[]` | Array | Conditional | List of public subnet numbers dedicated to load balancers to be applied to the cluster - Required if `lbPublicSubnetNo` is not entered. - For multi-zone configurations, enter up to 2 values (one per zone). Only subnets from different zones are allowed. - The first value is used as the representative subnet for single-zone load balancers and network load balancers. - `lbPublicSubnetNo` is applied if not entered. - See [getSubnetList](/docs/en/networking-vpc-subnetmanagement-getsubnetlist). |
| `log` | Object | Optional | Logs |
| `log.audit` | Boolean | Optional | Set audit log. - `true` \| `false` (default) |
| `authType` | String | Optional | Cluster authentication method - `API` (default) \| `CONFIG_MAP` |
| `bootstrapAccessEntry` | Boolean | Optional | Whether to automatically create a bootstrap access entry when creating a cluster - `true` (default) \| `false` |
| `kmsKeyTag` | String | Optional | Key Management Service's key tag - See [Key Management Service list](https://console.ncloud.com/security-kms/management). |
| `nodePool` | Array | Optional | List of node pools to add: [nodePool](/docs/en/nks-createcluster#nodePool) |
| `addons` | Array | Optional | List of add-ons to install when creating a cluster: [addons](/docs/en/nks-createcluster#addons) |

#### `nodePool`

The following describes `nodePool`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | String | Optional | NodePool name |
| `nodeCount` | Integer | Optional | Number of nodes |
| `subnetNo` | Integer | Optional | @deprecated Subnet number |
| `subnetNoList[]` | Array | Optional | Subnet number - Valid range: Cluster subnetNoList |
| `softwareCode` | String | Optional | Server image code - See [Get server image](/docs/en/nks-viewserverimage). |
| `productCode` | String | Optional | Service code - Use only if hypervisorCode is XEN - See [Get server specifications](/docs/en/nks-viewserverspec). |
| `labels[]` | Array | Optional | Node label list |
| `labels[].key` | String | Conditional | Label key - Required when entering `nodePool[].labels` - English letters, numbers, and special characters "-", "_", "." are allowed, and the string must start and end with a English letter or number. |
| `labels[].value` | String | Conditional | Label value - Required when entering `nodePool[].labels` - English letters, numbers, and special characters "-", "_", "." are allowed, and the string must start and end with a English letter or number. |
| `taints[]` | Array | Optional | List of taints |
| `taints[].key` | String | Conditional | Taint key - Required when entering `nodePool[].taints` - English letters, numbers, and special characters "-", "_", "." are allowed, and the string must start and end with a English letter or number. |
| `taints[].value` | String | Optional | Taint value - English letters, numbers, special characters "-", "_", "." are allowed, and the string must start and end with a English letter or number. |
| `taints[].effect` | String | Conditional | taint effect - Required when entering `nodePool[].taints` - `NoSchedule` \| `PreferNoSchedule` \| `NoExecute` |
| `serverSpecCode` | String | Optional | Server type - Use only if hypervisorCode is KVM. - See [Get server specifications](/docs/en/nks-viewserverspec). |
| `storageSize` | Integer | Optional | Storage size (GB) - `100`-`2000` (default: `100`) - Use only if hypervisorCode is KVM. |
| `serverRoleId` | String | Optional | ID to assign roles to NodePool servers - See the console or [Get role list](/docs/en/management-subaccount-getroles). |
| `zoneCode` | String | Conditional | Node pool's zone code - Required if `isRegional` is `true`. - Ignored in the single-zone cluster. - See [getZoneList](/docs/en/compute-vserver-server-common-getzonelist). |
| `fabricCluster` | Object | Conditional | Fabric cluster information - Required when using server specifications that support Fabric clusters |
| `fabricCluster.poolName` | String | Conditional | Fabric cluster pool information - Required when configuring Fabric cluster |
| `fabricCluster.poolNo` | Integer | Conditional | Fabric cluster pool number - Required when configuring Fabric cluster |

#### `addons`

The following describes `addons`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `addonName` | String | Conditional | Name of add-on to install - Required if `addons` is entered. - See [Get add-on list](/docs/en/nks-getaddonconfiglist). |
| `version` | String | Conditional | Version of add-on to install - Required if `addons` is entered. - See `versions[]` of [Get add-on](/docs/en/nks-getaddonconfig). - Example: `1.0.0` |
| `configurationValues` | String | Optional | Helm values override values (JSON object string) - See `configurationSchema` of [Get add-on version](/docs/en/nks-getaddonconfigversion). |

### Request example

The request example is as follows:

```
curl --location --request POST 'https://nks.apigw.ntruss.com/vnks/v2/clusters' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Sub Account Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json'
--data '{
    "name": "String",
    "clusterType": "String",
    "k8sVersion": "String",
    "loginKeyName": "String",
    "hypervisorCode": "String",
    "regionCode": "String",
    "zoneCode": "String",
    "zoneNo": "Integer",
    "publicNetwork": "Boolean",
    "kubeNetworkPlugin": "String",
    "vpcNo": "Integer",
    "subnetNoList": [
      "Integer"
    ],
    "subnetLbNo": "Integer",
    "lbPrivateSubnetNo": "Integer",
    "lbPrivateSubnetNoList": [
      "Integer"
    ],
    "lbPublicSubnetNo": "Integer",
    "lbPublicSubnetNoList": [
      "Integer"
    ],
    "log": {
      "audit": "Boolean"
    },
    "isRegional": "Boolean",
    "nodePool": [
      {
        "name": "String",
        "nodeCount": "Integer",
        "subnetNo": "Integer",
        "subnetNoList": [
          "Integer"
        ],
        "softwareCode": "String",
        "productCode": "String",
        "labels": [
          {
            "key": "String",
            "value": "String"
          }
        ],
        "taints": [
          {
            "key": "String",
            "value": "String",
            "effect": "String"
          }
        ],
        "serverSpecCode": "String",
        "storageSize": "Integer",
        "serverRoleId": "String",
        "zoneCode": "String"
      }
    ],
    "addons": [
      {
        "addonName": "String",
        "version": "String",
        "configurationValues": "String"
      }
    ]
}'
```

## Response

This section describes the response format.

### Response body

The response body includes the following data:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | String | - | UUID of the cluster |

### Response status codes

For information about the HTTP status codes common to all Ncloud Kubernetes Service APIs, see [Ncloud Kubernetes Service response status codes](/docs/en/compute-vpckubernetesservice#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C).

### Response example

The response example is as follows:

```
{
    "uuid": "****a20e-e0fb-4dc9-af1b-97fd3f8d****"
}
```