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, you need to specify its configuration details by completing the payload of the request with the required fields. These fields include information such as the cluster name, node type, Kubernetes version, hardware configuration, and other relevant parameters. Once you have filled out the payload with the necessary information, send the request to the /core/clusters API using the POST method to create the Kubernetes clusters with the provided 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 30 minutes, please remove the cluster and try again.
Body parameters
name string Required
The name assigned to the Kubernetes cluster.
Cluster names AND environment names must consist only of lowercase alphanumeric characters and hyphens. Uppercase letters, special characters, and spaces are not allowed. Maximum length of 50 characters.
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
The image names with the suffix with Docker (e.g. Ubuntu Server 22.04 LTS R535 CUDA 12.2 with Docker) are not supported for now.
kubernetes_version string Required
The Kubernetes cluster version you obtained in the previous step 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.
Click here to see the available CPU-only flavors and their hardware configurations
| Flavor Name | CPU Cores | CPU Sockets | RAM (GB) | Disk (GB) |
|---|---|---|---|---|
n1-cpu-small | 4 | 2 | 4 | 100 |
n1-cpu-medium | 8 | 2 | 8 | 100 |
n1-cpu-large | 16 | 2 | 16 | 200 |
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.
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 clusters 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.