Kubernetes CSI Driver

Dynamic provisioning and lifecycle management of persistent volumes for Kubernetes clusters, installed with Helm.

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

Install the CSI Driver with Helm

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.

• Helm 3+

• kubectl configured to interact with your cluster. Click here for instructions.

• A valid Hyperstack API key from the organization owner or from a member who has been granted permissions enabling CSI Driver functionality. Click below for details:

  Permissions required to enable CSI Driver functionality for non-owner accounts

  To determine whether your account is an owner or member, visit the My Organization page in Hyperstack.

  If the API key was generated by a Hyperstack account that is not the owner of your organization, you must ensure the user has the appropriate permissions assigned as a User Role to allow CSI Driver volume operations. Learn how to create and assign user roles here.

  The following permissions must be added to a User Role and assigned to the organization member:

  • volume:list
  • volume:details
  • volume:create
  • volume:delete
  • virtual-machine:volume-attach
  • virtual-machine:volume-detach

  
  

  These permissions allow the CSI Driver to provision volumes, attach/detach them from VMs, and manage their lifecycle dynamically.

CSI Driver Compatibility

To ensure compatibility with the Hyperstack Kubernetes CSI driver, your cluster must meet one of the following conditions:

• The cluster was provisioned on or after September 4, 2025, or
• If the cluster was provisioned before September 4, 2025, at least one node must have been added or removed since then to trigger reconciliation.

Volume Attachment Limit

Each worker node in a Kubernetes cluster can have a maximum of 10 volumes attached at any given time. This means a cluster with 3 nodes can support up to 30 volumes total, with up to 10 per node.

1. Add the Helm Repository

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

   terminal

   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.

2. Install the Chart

   Replace <your_api_key> with your actual key, ensuring it was generated by a user with the necessary permissions described in the prerequisites section above. If you need to generate a new Hyperstack API key, click here.

   terminal

   helm install csi-hyperstack nexgencloud/csi-hyperstack \
   --namespace kube-system \
   --create-namespace \
   --set hyperstack.apiKey=<your_api_key>

   This installs the driver into the kube-system namespace using your Hyperstack API key.

   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:

   terminal

   Error: INSTALLATION FAILED: Kubernetes cluster unreachable: Get "http://localhost:8080/version": dial tcp 129.0.0.1:8080: connect: connection refused

3. Verify Installation

   terminal

   kubectl get pods -n kube-system

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

   terminal

   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:

terminal

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

Custom Namespace (optional)

To use a custom namespace:

terminal

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.

yaml

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:

terminal

kubectl apply -f manifest.yaml

Expected output:

terminal

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:

terminal

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

Expected output:

terminal

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

terminal

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

terminal

helm uninstall csi-hyperstack -n kube-system

This removes the CSI driver deployment from your cluster.

Resources

• How to Deploy a Kubernetes Cluster in Hyperstack
• Connecting to a Hyperstack Cluster
• API Authentication Guide
• Kubernetes Storage Documentation