Create Kubernetes Cluster
POST https://infrahub-api.nexgencloud.com/v1/core/clusters
Creates a Kubernetes cluster with the specified custom configuration and features provided in the request body.
To create a Kubernetes cluster, specify its configuration details by filling in the required fields in the request payload. These fields include the cluster name, node type, Kubernetes version, hardware configuration, and other relevant parameters. Once the payload is complete, send the request to the /core/clusters API using the POST method to deploy the cluster with the specified configuration.
Cluster creation can take between 5-20 minutes, depending on the cluster size and the number of clusters being created. You can check the status of the cluster by calling the 'Retrieve Cluster Details' API. If your cluster is not in the ACTIVE state after 60 minutes, please remove the cluster and try again.
Body parameters
name string Required
The name assigned to the Kubernetes cluster.
Cluster names can only contain alphanumeric characters, hyphens, underscores, and spaces, with a maximum length of 20 characters.
Leading or trailing spaces and special characters are not allowed.
environment_name string Required
The name of the environment where the cluster will be created.
To learn how to create a new environment, click here.
keypair_name integer Required
The name of the SSH key used to securely access your cluster.
To learn how to create a new SSH key, click here.
image_name string optional
Name of the operating system image to be installed on your cluster.
Use the GET /core/images API to retrieve a list of images offered by Hyperstack.
Recommended image: Ubuntu Server 22.04 LTS R535 CUDA 12.2
Only images with the k8s label can be used for worker nodes.
kubernetes_version string Required
The Kubernetes version to build your cluster with. Obtain a list of compatible Kubernetes versions by calling the GET /core/clusters/versions API.
Recommended version: 1.27.8
master_flavor_name string Required
The flavor of the master node determines its hardware configuration, including the CPUs, RAM, and disk storage capacity.
The master node requires a CPU-only flavor. Select the size that best suits your workload. Please note that there are no running costs associated with the resources consumed by the master node.
We recommend using a CPU flavor size of n1-cpu-medium or larger.
Click here to see the available CPU-only flavors and their hardware configurations
| Flavor Name | CPU Cores | CPU Sockets | RAM (GB) | Root Disk (GB) | Ephemeral Disk (GB) | Region |
|---|---|---|---|---|---|---|
n1-cpu-small | 4 | 2 | 4 | 100 | 0 | NORWAY-1, CANADA-1 |
n1-cpu-medium | 8 | 2 | 8 | 100 | 0 | NORWAY-1, CANADA-1 |
n1-cpu-large | 16 | 2 | 16 | 200 | 0 | NORWAY-1, CANADA-1 |
node_flavor_name string Required
The flavor used for the worker nodes which determines its hardware configuration, including the GPU model and quantity, CPUs, RAM, and disk storage capacity.
Call the GET /core/flavors API to retrieve a list of available flavors.
node_count integer Required
The number of worker nodes in the cluster. Must be between 1 and 20.
Attributes
status boolean
Indicates the result of the request to create cluster. true signifies success, while false indicates an error.
message string
A description of the status of the request.
cluster object
An object containing details about the created cluster.
For descriptions of the fields within the cluster object returned in response to your request, please refer to the documentation here.
curl -X POST "https://infrahub-api.nexgencloud.com/v1/core/clusters" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"\
-H "content-type: application/json" \
-d '{
"name": "example-cluster",
"environment_name": "CANADA-1",
"keypair_name": "example-key",
"image_name": "Ubuntu Server 22.04 LTS R535 CUDA 12.2",
"kubernetes_version": "1.27.8",
"master_flavor_name": "n1-cpu-large",
"node_flavor_name": "n3-A100x1",
"node_count": 2
}'
- To authenticate Infrahub API requests, add an
api_keyheader to your API request that contains an API Key.
{
"status": true,
"message": "Cluster created successfully",
"cluster": {
"id": 339,
"name": "exampple-cluster",
"environment_name": "CANADA-1",
"kubernetes_version": "1.27.8",
"api_address": null,
"kube_config": null,
"status": "CREATING",
"status_reason": null,
"node_count": 2,
"master_flavor": {
"id": 106,
"name": "n1-cpu-large",
"cpu": 16,
"ram": 16.0,
"disk": 200,
"ephemeral": 0,
"gpu": "",
"gpu_count": 0,
"labels": [],
"features": {
"network_optimised": false,
"no_hibernation": false,
"no_snapshot": false,
"local_storage_only": false
}
},
"node_flavor": {
"id": 100,
"name": "n3-A100x1",
"cpu": 28,
"ram": 120.0,
"disk": 100,
"ephemeral": 750,
"gpu": "A100-80G-PCIe",
"gpu_count": 1,
"labels": [],
"features": {
"network_optimised": false,
"no_hibernation": false,
"no_snapshot": false,
"local_storage_only": false
}
},
"keypair_name": "test1",
"enable_public_ip": true,
"created_at": "2025-02-14T15:39:09"
}
}
Returns
Returns the status of cluster deployment and the cluster object containing the details of the created cluster. The CREATING status in the response indicates a successful deployment of the Kubernetes cluster.
If you encounter an error due to insufficient permissions, ensure the following steps:
1: Check Account Role: Confirm that you’re not using an account without an assigned Role. Without proper permissions, you won’t be able to perform certain actions.
2: Admin Actions Required: Only Admins can assign Roles. If you’re not the Admin, ask them to:
- Go to “My Organization” in the Hyperstack WebUI.
- Select “Create a new User role”, name it (e.g., “Operator”), and enable all permissions.
3: Assign Role:
- In “My Organization”, find your account.
- Click “Change Role” and assign the newly created “Operator” role to your account.
See more details on User Roles here.