> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nscale.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Managed Kubernetes
Nscale Kubernetes Service (NKS) lets you provision isolated, single-tenant Kubernetes clusters without managing the underlying infrastructure. Each cluster gets its own control plane and API server, so you can use standard tools like `kubectl` and `helm` straight away.
**Prerequisite:** You need an existing [project](/docs/manage/projects) before creating a cluster.
## Availability
Managed Kubernetes is available in the **reserved cloud service environment.**
## Requirements
* Permissions and sufficient quota to create Kubernetes clusters
* [kubectl CLI](https://kubernetes.io/docs/tasks/tools/) installed locally
## Cluster lifecycle
| State | Description |
| ------------------ | -------------------------------------------------------------------- |
| **Provisioning** | The cluster is being created and resources are being allocated |
| **Provisioned** | The cluster is ready — kubeconfig is available for download |
| **Deprovisioning** | The cluster deletion is in progress and resources are being released |
| **Error** | Something went wrong during provisioning or operation |
**Actions you can take after creation:**
* **Add a workload pool** — add more node pools with different hardware configurations
* **Scale a workload pool** — increase or decrease the node count in an existing pool
* **Delete a pool** — remove an individual workload pool from the cluster
* **Delete the cluster** — permanently remove the cluster and all its workload pools
**Deleting a cluster is permanent.** All workload pools, nodes, and ephemeral data are removed. Ensure any data you need is persisted externally before deleting.
## Step-by-step
### Create a cluster
1. In the Console, open your project, then go to **Services → Kubernetes** and click **Create Cluster**
2. Fill in the **cluster details**:
* **Cluster Name** — enter a name for your cluster
* **Project** — select the project the cluster should belong to
* **Region** — choose the region where the cluster will be deployed
The console provisions the control plane with default sizing (3 replicas and an automatically selected flavor). **Control plane sizing cannot be changed in the console** — to customize the flavor or replica count, create the cluster via the API instead (see [Configure the control plane via API](#configure-the-control-plane-via-api) below).
3. **Configure a workload pool**
Workload pools define the compute resources allocated to the cluster. For each pool, set:
* **Workload Pool Name** — must use lowercase alphanumeric characters and dashes (e.g. `workload-pool-1`)
* **Node Type** — hardware configuration (e.g. `g.4.standard.80s` or 1 × NVIDIA B200)
* **Node Count** — number of nodes in the pool
4. Review the cluster summary and click **Create Cluster**
* The cluster status will move to **Provisioning**, then **Provisioned** after a few minutes
### Access your cluster
5. Once the cluster is **Provisioned**, the **Access your cluster** section becomes available in the cluster overview
* Click **Download Kubeconfig** to download `kubeconfig.yaml`, or **Copy to clipboard** to paste it into a file
6. Set your `KUBECONFIG` environment variable and verify connectivity:
```bash theme={null}
export KUBECONFIG=~/Downloads/kubeconfig.yaml
kubectl get nodes
```
The output will show the nodes in your workload pool along with the Kubernetes version running on them.
7. **Create a namespace for your workloads (optional)**
```bash theme={null}
kubectl create namespace dev-team
kubectl get namespaces
```
### Configure the control plane via API
To specify control plane sizing when creating a cluster through the API, include the `controlPlane` object in your request:
```bash theme={null}
curl -X POST "https://compute.nscale.com/api/v2/clusters" \
-H "Authorization: Bearer $NSCALE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"metadata": { "name": "my-cluster" },
"spec": {
"regionId": "",
"projectId": "",
"controlPlane": {
"flavorId": "",
"replicas": 3
},
"workloadPools": [...]
}
}'
```
| Field | Type | Required | Default | Description |
| ---------- | ------- | ------------------------------ | ------------- | ---------------------------------------------- |
| `flavorId` | string | Yes (if `controlPlane` is set) | Auto-selected | Machine flavor for control plane nodes |
| `replicas` | integer | No | 3 | Number of control plane replicas (must be odd) |
The replica count must be an **odd number** to maintain etcd quorum. Even values are rejected with a validation error.
## Quotas
To check your current cluster quota, go to the **Resource Usage** section on the **Dashboard**. The dashboard shows your cluster usage alongside GPU, server, network, and filesystem quotas.
## Common issues / troubleshooting
**Access controls aren't shown on the cluster page**
* **Symptom:** You don't see **Access your cluster** (download/copy kubeconfig options)
* **Likely cause:** The cluster is not yet provisioned; the access section appears after provisioning completes
* **Fix:** Wait until the cluster status is **Provisioned**, then refresh the cluster overview page
**Workload pool name validation error**
* **Symptom:** You can't proceed when entering the workload pool name
* **Likely cause:** The workload pool name must use lowercase alphanumeric characters and dashes
* **Fix:** Rename the pool to match the required format (e.g. `workload-pool-1`)
***
## Related resources
Organise your clusters by project
Create individual VMs alongside your clusters
Manage clusters as infrastructure as code
Manage clusters programmatically via the API