Persistent Storage for Kubernetes: Install the Hyperstack CSI Driver

The Hyperstack CSI (Container Storage Interface) Driver provides Kubernetes clusters running on Hyperstack with dynamic provisioning and lifecycle management of persistent volumes. By integrating with the Hyperstack platform, the driver allows workloads to request and consume persistent storage in a cloud‑native, declarative way. Installation is handled through a public Helm chart, which deploys all required components including the controller service, node plugins and an optional default StorageClass.

Provisioner name: hyperstack.csi.nexgencloud.com

View Hyperstack CSI Driver on GitHub

Prerequisites

Before you begin, ensure the following requirements are met:

An ACTIVE Kubernetes cluster running on Hyperstack (v1.24 or later). Learn how to deploy a cluster.
A valid Hyperstack API key.
Helm 3+
kubectl configured to interact with your cluster. Click here for instructions.

Install the CSI Driver with Helm

The Hyperstack CSI driver is distributed via a public Helm chart.

Add the Helm Repository
```
helm repo add nexgencloud https://nexgencloud.github.io/csi-hyperstack
helm repo update
```
This command adds the official Hyperstack CSI Helm chart repository to your local Helm configuration and updates the index.
Install the Chart
```
helm install csi-hyperstack nexgencloud/csi-hyperstack \
--namespace kube-system \
--create-namespace \
--set hyperstack.apiKey=<YOUR_HYPERSTACK_API_KEY>
```
This installs the driver into the kube-system namespace using your Hyperstack API key. Replace <YOUR_HYPERSTACK_API_KEY> with your actual key. To generate a Hyperstack API key, click here.
Cluster Status
If you encounter the following error, verify that your Kubernetes cluster is in the ACTIVE state and that your kubectl context is correctly configured with the cluster's kubeconfig:
Error: INSTALLATION FAILED: Kubernetes cluster unreachable: Get "http://localhost:8080/version": dial tcp 129.0.0.1:8080: connect: connection refused

Verify Installation

kubectl get pods -n kube-system

You should see all CSI controller and node pods in Running state. Example:

NAME                             READY   STATUS    RESTARTS   AGE
csi-hyperstack-xxxxx             5/5     Running   0          10s
csi-hyperstack-node-yyyyy        2/2     Running   0          10s

Custom Configuration (Optional)

This section provides an overview of the key values that can be customized when installing the CSI driver using Helm. It includes both required and optional parameters to tailor the deployment to your needs.

Mandatory value during chart installation

The following value is required to authenticate your deployment with the Hyperstack platform:

Key	Type	Description	Example
`hyperstack.apiKey`	string	API key for authenticating with the Hyperstack API	`hyperstack.apiKey=abcd1234`

To generate a Hyperstack API key, click here.

Other commonly used optional values

You can optionally configure the CSI driver’s image version, API endpoint, and behavior of the default StorageClass:

Key	Type	Description	Default
`components.csiHyperstack.tag`	string	CSI Hyperstack Image tag	`latest`
`hyperstack.apiAddress`	string	Base URL of the Hyperstack API	`https://infrahub-api.nexgencloud.com/v1`
`storageClass.enabled`	bool	Whether to create a default StorageClass	`true`
`storageClass.name`	string	Name of the StorageClass	`csi-hyperstack`
`storageClass.volumeBindingMode`	string	Volume binding mode (Immediate or WaitForFirstConsumer)	`Immediate`
`storageClass.reclaimPolicy`	string	Reclaim policy (Delete or Retain)	`Delete`

Install (or re-install with updated configuration)

Use the following command to install or upgrade the CSI driver using your custom values:

helm upgrade csi-hyperstack nexgencloud/csi-hyperstack \
--install -f values.yaml -n kube-system --create-namespace

Custom Namespace (optional)

To use a custom namespace:

NS="csi-driver"
kubectl create namespace "$NS"
# Then install with -n "$NS"

Volumes and Access Modes in Kubernetes

Kubernetes uses volumes to persist and manage data beyond the lifecycle of a pod. A volume in Kubernetes is a directory that is accessible to containers in a pod. Volumes are crucial for stateful applications, backups, and shared storage across pods. When combined with a CSI driver like Hyperstack's, volumes are dynamically provisioned and attached to pods as needed.

Volumes can be backed by different storage systems (e.g., cloud disks, NFS, or block storage) and are managed declaratively using PersistentVolume (PV) and PersistentVolumeClaim (PVC) objects.

For more background, see the Kubernetes Volumes documentation.

Volume Access Modes

The Hyperstack CSI driver currently supports only the ReadWriteOnce access mode. This means each persistent volume can be attached and written to by a single pod at a time.

For more details, refer to the official Kubernetes Access Models documentation.

Create a StorageClass and PVC (Optional)

If storageClass.enabled: true is set in your Helm values, a default StorageClass will be created automatically.

If you prefer to define a custom class, disable the default and use the example below.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: hyperstack-sc
provisioner: hyperstack.csi.nexgencloud.com
volumeBindingMode: Immediate
parameters:
  type: Cloud-SSD
reclaimPolicy: Delete
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: hyperstack-sc
---
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  namespace: default
spec:
  containers:
  - name: my-container
    image: nginx:latest
    command: [ "sleep", "infinity" ]
    volumeMounts:
    - mountPath: "/mnt/test"
      name: my-pvc
  volumes:
  - name: my-pvc
    persistentVolumeClaim:
      claimName: my-pvc

Apply the manifest:

kubectl apply -f manifest.yaml

Expected output:

storageclass.storage.k8s.io/hyperstack-sc created
persistentvolumeclaim/my-pvc created
pod/my-pod created

These results confirm that the storage class, PVC, and pod were successfully created in your cluster.

Verify:

kubectl get pvc my-pvc
kubectl describe pod my-pod

Expected output:

NAME      STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS    AGE
my-pvc    Bound    pvc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   1Gi        RWO            hyperstack-sc   10s

This confirms that the PVC is bound to a volume and attached to the pod as expected.

Upgrade & Uninstall

Use the following commands to keep your CSI driver up to date, or to completely remove it if needed.

Upgrade to The Latest Chart Version

helm upgrade csi-hyperstack nexgencloud/csi-hyperstack -n kube-system

This command fetches and applies the latest changes from the chart repository without deleting existing resources.

Uninstall The CSI Driver

helm uninstall csi-hyperstack -n kube-system

This removes the CSI driver deployment from your cluster.