Skip to main content

Kubernetes Clusters on Hyperstack - How-to 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.

warning

Hyperstack's on-demand Kubernetes is currently in Beta testing. There are a couple of limitations:

  1. Cluster names AND environment names must consist only of lowercase alphanumeric characters and hyphens. Uppercase letters, special characters, and spaces are not allowed.
  2. Depending on the number of clusters being created, there may be a delay or a failure in cluster creation.
  3. No (auto-)scaling is available for the cluster.
  4. 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. 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.

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 'Retrieve Cluster Details' API. If your cluster is not in the ACTIVE state after 30 minutes, please delete the cluster using the Delete Cluster API and try again.


Request body parameters​

name string   Required​

The name assigned to the Kubernetes cluster.

note

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.

note

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 version of Kubernetes to be used for the cluster. See a list of supported versions by calling the List Cluster Versions API.

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 NameCPU CoresCPU SocketsRAM (GB)Root Disk (GB)Ephemeral Disk (GB)Region
n1-cpu-small4241000NORWAY-1, CANADA-1
n1-cpu-medium8281000NORWAY-1, CANADA-1
n1-cpu-large162162000NORWAY-1, CANADA-1
n1-cpu-xlarge16232100512CANADA-1
n1-cpu-xxlarge322641001024CANADA-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.


Example request
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
  }'
Response
{
  "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",
  }
}

Response​

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.

2. Check cluster status​

Simplest method is using the Hyperstack user interface.

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 the status_reason field 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.

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}" \
 -H "accept: application/json"\
 -H "api_key: YOUR API KEY"
Response
{
  "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",
  }
}

3. Connecting to your cluster​

To interact with your Kubernetes cluster, there are two options:

Option 1: Use the Bastion node​

  1. Connect to the bastion node using the SSH key provided during cluster creation. Replace KEYPAIR_PATH with the path to your SSH key, and BASTION_IP_ADDRESS with 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
  2. Once connected to the bastion node, you can interact with the Kubernetes cluster using kubectl. 
    kubectl get nodes

Option 2: Use the Kubeconfig file​

  1. 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.yaml

    You 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)
    }

  2. Set the KUBECONFIG environment variable to the path of the kubeconfig file:

    export KUBECONFIG=kubeconfig.yaml

  3. Access the Kubernetes cluster using kubectl:

    kubectl get nodes

All Kubernetes Cluster APIs​

Click on the name of the cluster APIs below to view detailed documentation.

Endpoint NameURLDescription
Create ClusterPOST /core/clustersCreates a Kubernetes cluster.
List ClustersGET /core/clustersRetrieves a list of your clusters along with their details.
Retrieve Cluster DetailsGET /core/clusters/{id}Retrieves the details of a specified cluster.
Delete ClusterDELETE /core/clusters/{id}Deletes a specified cluster.
List Cluster VersionsGET /core/clusters/versionsRetrieves a list of compatible Kubernetes versions.
Verify Cluster Name AvailabilityGET /core/clusters/name-availability/{cluster_name}Verifies the availabity of the specified cluster name.
Retrieve Cluster EventsGET /core/clusters/{id}/eventsRetrieves a list of events for a specified cluster.

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.

Enabling the Kubernetes Dashboard​

By default, the Kubernetes Dashboard is not enabled on Hyperstack Kubernetes clusters. To enable it, follow the steps outlined here.

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

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:

  1. The bastion node and load balancer are accessible from the public internet via their public IP addresses.
  2. The master node and worker nodes are not accessible from the public internet through their public IP addresses.
  3. Worker nodes are accessible only from the master node and the bastion node through the internal network.
  4. 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.

Back to top​