Kubernetes Clusters on Hyperstack - API Guide
Hyperstack supports on-demand provisioning of managed Kubernetes clusters, providing a quick and efficient way to deploy and manage your containerized applications. Similar to other major cloud providers, you only need to specify the target Kubernetes version, node type, and a few basic parameters. The platform takes care of the rest, ensuring a streamlined and hassle-free experience.
In this document, you will find step-by-step instructions to create a Kubernetes cluster on Hyperstack. By following these guidelines, you will be able to leverage the full power of Kubernetes for orchestration, scalability, and management of your applications with minimal effort.
For a hands-on tutorial on getting started with Kubernetes, check out our Deploy an LLM with vLLM on Hyperstack Kubernetes tutorial.
Hyperstack's on-demand Kubernetes is currently in Beta testing. There are a couple of limitations:
- Cluster names AND environment names must consist only of lowercase alphanumeric characters and hyphens. Uppercase letters, special characters, and spaces are not allowed.
- Depending on the number of clusters being created, there may be a delay or a failure in cluster creation.
- No (auto-)scaling is available for the cluster.
- To view the details of the cluster, you need to use the API. We are working on a UI to display the cluster details.
In this article
How to create a Kubernetes cluster
1. Choose a supported Kubernetes cluster version
GET https://infrahub-api.nexgencloud.com/v1/core/clusters/versions
To obtain the Kubernetes cluster versions supported by Hyperstack, call the 'List Kubernetes Versions' endpoint. This will return a list of available versions, as shown in the example request. Choose the version you want to use for your Kubernetes cluster.
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters/versions" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
{
"status": true,
"message": "Retrieved Cluster Versions.",
"kubernetes_version": [
"1.27.8",
...
]
}
Save the supported Kubernetes version as it will be used in the next step to 'Create a Kubernetes cluster'.
2. Create a Kubernetes cluster
POST https://infrahub-api.nexgencloud.com/v1/core/clusters
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.
Please note: 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 'Check cluster status' API. If your cluster is not in the ACTIVE state after 30 minutes, please remove the cluster and try again.
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 Organisation” in the Hyperstack WebUI.
- Select “Create a new User role”, name it (e.g., “Operator”), and enable all permissions.
3: Assign Role:
- In “My Organisation”, find your account.
- Click “Change Role” and assign the newly created “Operator” role to your account.
See more details on User Roles here.
Request 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.
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.
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": "example-environment",
"keypair_name": "example-ssh-key",
"image_name": "Ubuntu Server 22.04 LTS R535 CUDA 12.2",
"kubernetes_version": "1.27.8",
"master_flavor_name": "",
"node_flavor_name": "n3-A100x1",
"node_count": 3
}'
{
"status": true,
"message": "Success",
"cluster": {
"id": 1,
"name": "example-cluster",
"environment_name": "example-environment",
"kubernetes_version": "1.27.8",
"api_address": "",
"kube_config": "",
"status": "CREATING",
"status_reason": String,
"node_count": 3,
"node_flavor": {
"name": "n3-A100x1",
"cpu": 28,
"ram": 120.0,
"disk": 100,
"ephemeral": 750,
"gpu": "A100-80G-PCIe",
"gpu_count": 1
},
"node_addresses": [""],
"keypair_name": "example-ssh-key",
"created_at": "2024-06-17T09:33:46",
}
}
Save the cluster ID returned, as it will be used in the next step to 'Check cluster status'.
3. Check cluster status
GET https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}
The last step in deploying a cluster is to confirm that the cluster is ACTIVE and ready for use. To check its status, use the 'Retrieve Cluster Details' API, which provides information about the deployed cluster, including the status field indicating its operational state. Send the request to the /core/clusters/{id} API using the GET method, replacing {id}in the path with the clusterid` obtained in the previous step.
Path parameters
id integer Required
The ID of the cluster for which we are retrieving details.
This is obtained from the id field in the response of the `Create Cluster' API call from the previous step.
Attributes
Click here for descriptions of the fields within the cluster object.
id integer
The unique identifier assigned to the cluster.
name string
The name of the Kubernetes cluster.
environment name string
The name of the environment where the cluster is deployed.
kubernetes_version string
The version of Kubernetes running on the cluster.
kube_config string
A string representing the kubeconfig file contents required for connecting to the cluster.
status_reason string
A message providing information about the status of the cluster, especially in case of errors.
status string
The current status of the Kubernetes cluster.
Possible values:
CREATING: The cluster is being created.ACTIVE: The cluster is active and operational.ERROR: An error occurred during cluster creation or operation. Check thestatus_reasonfield for more details.
node_count number
The number of nodes (virtual machines) in the cluster.
node_flavor object
Details about the flavor (hardware configuration) of the nodes in the cluster.
node_addresses array of strings
A list of public IP addresses assigned to the nodes in the cluster.
keypair_name string
The name of the key pair used for SSH access to the nodes.
created_at datetime
The date and time when the cluster was created.
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
{
"status": true,
"message": "Success",
"cluster": {
"id": 1,
"name": "example-cluster",
"environment_name": "example-environment",
"kubernetes_version": "1.27.8",
"kube_config": "",
"status": "ACTIVE",
"status_reason": String,
"node_count": 3,
"node_flavor": {
"name": "n3-A100x1",
"cpu": 28,
"ram": 120.0,
"disk": 100,
"ephemeral": 750,
"gpu": "A100-80G-PCIe",
"gpu_count": 1
},
"node_addresses": [""],
"keypair_name": "example-ssh-key",
"created_at": "2024-06-17T09:33:46",
}
}
A status of ACTIVE indicates that your cluster has been deployed successfully and is ready for use.
Other Kubernetes cluster APIs
Retrieve a list of clusters
GET https://infrahub-api.nexgencloud.com/v1/core/clusters
Retrieve a list of your current clusters, providing detailed information for each, including configuration, cluster ID, operational status, environment, flavor (hardware configuration), and more.
Parameters
No parameters.
Attributes
status boolean
Indicates the success status of the API response.
message string
A description of the success or failure of the API request.
clusters array of objects
An array of objects containing information about Kubernetes clusters.
Click here to see child attributes
id integer
The unique identifier assigned to the cluster.
name string
The name of the Kubernetes cluster.
environment name string
The name of the environment where the cluster is deployed.
kubernetes_version string
The version of Kubernetes running on the cluster.
kube_config string
A string representing the kubeconfig file contents required for connecting to the cluster.
status string
The current status of the Kubernetes cluster.
Possible values:
CREATING: The cluster is being created.ACTIVE: The cluster is active and operational.ERROR: An error occurred during cluster creation or operation. Check thestatus_reasonfield for more details.
status_reason string
A message providing information about the status of the cluster, particularly useful in case of errors.
node_count number
The number of nodes (virtual machines) in the cluster.
node_flavor object
Details about the flavor (hardware configuration) of the nodes in the cluster.
Click here to see attributes
node_addresses array of strings
A list of public IP addresses assigned to the nodes in the cluster.
keypair_name string
The name of the key pair used for SSH access to the nodes.
created_at datetime
The date and time when the cluster was created.
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
{
"status": true,
"message": "Success",
"clusters": [
{
"id": 1,
"name": "example-cluster",
"environment_name": "example-environment",
"kubernetes_version": "1.27.8",
"kube_config": "",
"status": "ACTIVE",
"status_reason": String,
"node_count": 3,
"node_flavor": {
"name": "n3-A100x1",
"cpu": 28,
"ram": 120.0,
"disk": 100,
"ephemeral": 750,
"gpu": "A100-80G-PCIe",
"gpu_count": 1
},
"node_addresses": [""],
"keypair_name": "example-ssh-key",
"created_at": "2024-06-17T09:33:46",
},
{...}
]
}
Delete a cluster
DELETE https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}
To delete a cluster, include its ID in the path replacing the placeholder {id}`.
Please note: deleting a cluster will delete all data associated with it, including the nodes, configurations, and any other resources. This action is irreversible.
Retrieve events for a cluster
GET https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}/events
Retrieve a complete history of events for a specified cluster by including its ID in the path replacing the placeholder {id}`. The returned cluster events provide detailed information about actions executed on the cluster, including the user, organization, time of the event, and specifics about what event took place and why.
Path parameters
id integer Required
The ID of the cluster for which to retrieve the event history.
Attributes
status boolean
Indicates whether the API call was successful.
message string
A message describing the result of the API call.
cluster_events array of objects
An array of event objects related to the specified cluster.
Click here to see child attributes
id integer
The unique identifier of the event.
cluster_id integer
The identifier of the cluster associated with the event.
user_id integer
The identifier of the user who triggered the event.
org_id integer
The organization identifier associated with the event.
time datetime
The timestamp when the event occurred.
type string
The type of the event.
reason string
The reason for the event, describing why the event was triggered.
object string
Additional details associated with the event.
message string
A descriptive message associated with the event, providing more details about what happened.
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}/events" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
{
"status": true,
"message": "Success",
"cluster_events": [
{
"id": 1,
"cluster_id": 2,
"user_id": 3,
"org_id": 4,
"time": "",
"type": "",
"reason": "",
"object": "",
"message": ""
},
{...}
]
}
3. Tips and Tricks for Working with Hyperstack Kubernetes
Below is a list of tips and tricks to help you maximize your experience with Hyperstack Kubernetes clusters.
1. Interacting with Your Kubernetes Cluster
To interact with your Kubernetes cluster, you have two options:
Option 1: Use the Bastion node
- Connect to the bastion node using the SSH key provided during cluster creation. Replace
KEYPAIR_PATHwith the path to your SSH key, andBASTION_IP_ADDRESSwith the IP address of the bastion node.BASTION_IP_ADDRESS="38.80.122.252"
KEYPAIR_PATH="../_ssh_keys/example-k8s-key_hyperstack"
ssh -i $KEYPAIR_PATH ubuntu@$BASTION_IP_ADDRESS - Once connected to the bastion node, you can interact with the Kubernetes cluster using
kubectl.kubectl get nodes
Option 2: Use the Kubeconfig file
-
Retrieve the kubeconfig file from the cluster details and save it to the a file (e.g.
kubeconfig.yaml. Replace{id}with the cluster ID and[API_KEY]with your API key.# Retrieve the kubeconfig file (base64 encoded)
B64_KUBECONFIG = $(curl --location 'https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}' --header 'api_key: [API_KEY]' | jq -r '.cluster.kube_config')
# Save the kubeconfig file to a file
echo $B64_KUBECONFIG | base64 -d > kubeconfig.yamlYou can also get the kubeconfig through Terraform (currently in alpha). You will need the output variable below. For a full example, see instructions here.
output "kube_config" {
value = base64decode(hyperstack_core_cluster.my_k8s.kube_config)
} -
Set the
KUBECONFIGenvironment variable to the path of the kubeconfig file:export KUBECONFIG=kubeconfig.yaml -
Access the Kubernetes cluster using
kubectl:kubectl get nodes
2. Enabling the Kubernetes Dashboard
By default, the Kubernetes Dashboard is not enabled on Hyperstack Kubernetes clusters. To enable it, follow the steps outlined here.
3. Whitelisting IP Addresses for Third-Party Services
To whitelist IP addresses for third-party services, add the IP addresses of the Kubernetes worker nodes to the whitelist. You can retrieve the worker node IP addresses by using the following commands from within the bastion node:
# List nodes
kubectl get nodes
# Open a debug terminal in a worker node (see example command below)
kubectl debug node/kube-cluster-1729305379-default-worker-0 -it --image=busybox
# Retrieve the IP address
wget -qO- ifconfig.me
# Expected output:
# 38.80.122.72
4. Firewall settings for the nodes
By default, we have configured all network settings to ensure secure access to the nodes. This setup includes the following:
- The bastion node and load balancer are accessible from the public internet via their public IP addresses.
- The master node and worker nodes are not accessible from the public internet through their public IP addresses.
- Worker nodes are accessible only from the master node and the bastion node through the internal network.
- The master node is accessible from the bastion node through the internal network.
If you wish to modify any of these settings, please keep the following in mind:
- By default, all ports on the worker nodes are open to facilitate inter-node communication. Enabling a public IP address for the worker nodes will expose all ports to the public internet. To restrict access, configure the firewall settings on the worker nodes before enabling a public IP address. You can find instructions on configuring firewall settings here.