Skip to main content

Getting Started with Kubernetes

Deploy and connect to your first Hyperstack Kubernetes cluster. Follow the steps below to configure the cluster, deploy it, and connect with kubectl.

Before you begin​

You'll need:

Deploy and connect to a cluster​

  1. Open the Deploy a New Cluster page​

    On the Kubernetes page, click Deploy a New Cluster.

  2. Choose a worker flavor​

    The flavor determines the GPU, CPU, RAM, and storage of the cluster's worker nodes, which run your workloads. In the Choose default worker flavor section, select 1x L40. It's a good fit for a first cluster, and it may already be selected. See all available flavors.

  3. Create an environment​

    In the Environment section, click Create New Environment, give it a name, choose the CANADA-1 or NORWAY-1 region, and confirm. An environment groups your cluster, SSH keys, and other resources together. Environments that aren't compatible with your flavor are marked in the list. See Environments for details.

  4. Create an SSH key​

    An SSH key is required to deploy, and it's scoped to a single environment, so create one for the environment you just made. In the Select SSH Key section, click Create New SSH Key, then choose how to add your key:

    Select the Generate SSH key tab, choose the environment you created, enter a name, and click Generate. Hyperstack creates an RSA key pair for you. Save the private key somewhere safe.

    You connect to the cluster with kubectl and a kubeconfig file, not with this key. The key is used for SSH access to the cluster's individual nodes.

  5. Keep the remaining defaults​

    The rest of the form is already set up for a standard cluster, so you can leave every section as it is:

    • Select Kubernetes Version: the newest version is pre-selected.
    • Number of Master Nodes: 3. These run the control plane and are currently offered for free.
    • Number of default Worker Nodes: 1.
    • Select Firewalls: optional, and none are needed to get started.
    • Select Deployment Mode: Full, which adds a bastion node and a load balancer. See Cluster Deployment Modes.
    • Select Master Node Flavor: n1-cpu-small.
    • Cluster Name: auto-generated, such as virgo-helium. Customize it if needed.

  6. Deploy​

    Check the Final Configuration and Price Breakdown, then click Deploy. Hyperstack opens the cluster's Overview tab, where the status starts at CREATING.

    The cluster moves through CREATING while its virtual machines are provisioned, then RECONCILING while Kubernetes is installed, and finally ACTIVE.

    Deployment time and billing

    Cluster creation usually takes around 15 minutes for a cluster this size, and larger clusters take longer. Billing starts only once the underlying virtual machines are ACTIVE. Worker nodes and public IP addresses are billed, while master, bastion, and load balancer nodes are not. See Cluster Billing & Data Retention.

  7. Copy your kubeconfig​

    The Kubeconfig action stays disabled until the cluster reaches the ACTIVE state. Once it does, return to the Kubernetes page, hover over the ⋮ in the ACTIONS column of your cluster, then click Kubeconfig. Hyperstack opens a page showing the cluster's kubeconfig file.

    Click Copy, then paste the contents into a file named kubeconfig.yaml on your local machine.

  8. Connect with kubectl​

    Point kubectl at the file you just saved, then list the cluster's nodes:

    terminalConnect to your cluster
    export KUBECONFIG=$PWD/kubeconfig.yaml
    kubectl get nodes

    Each master and worker node reports Ready:

    terminalExample output
    NAME                     STATUS   ROLES           AGE   VERSION
    virgo-helium-default-0   Ready    worker          7m    v1.36.1
    virgo-helium-master-0    Ready    control-plane   8m    v1.36.1
    virgo-helium-master-1    Ready    control-plane   8m    v1.36.1
    virgo-helium-master-2    Ready    control-plane   8m    v1.36.1

    The bastion and load balancer nodes don't appear here. They support the cluster's access and traffic paths rather than running workloads, so they aren't registered as Kubernetes nodes.

    Confirm the worker's GPU is available to Kubernetes:

    terminalCheck the worker's GPU
    kubectl get nodes -o custom-columns='NAME:.metadata.name,GPU:.status.allocatable.nvidia\.com/gpu'

    The worker node advertises one GPU, ready to be requested by a pod:

    terminalExample output
    NAME                     GPU
    virgo-helium-default-0   1
    virgo-helium-master-0    <none>
    virgo-helium-master-1    <none>
    virgo-helium-master-2    <none>
Your cluster is ready

Schedule a GPU workload on it. The NVIDIA drivers and device plugin are already installed, so a pod that requests nvidia.com/gpu runs on the worker node without any further setup.

Managing your cluster

Kubernetes clusters do not support hibernation, so they bill until deleted. To reduce cost, remove worker nodes, or delete the cluster from the ⋮ menu on the Kubernetes page when you're finished. See Cluster Billing & Data Retention.

Next steps​

Get more out of your Hyperstack Kubernetes cluster:

Clusters via the Console

Scale your cluster, manage node groups, and understand cluster statuses and billing.

Clusters via the API

Create, connect to, scale, and delete clusters programmatically with the REST API.

CSI Driver

Provision persistent volumes so your data survives a node being replaced.

Deploy an LLM with vLLM

Run a large language model on your cluster with the vLLM inference framework.

On this page