How to Use an Existing LINSTOR Resource as a Kubernetes Persistent Volume

This article describes how to attach an existing LINSTORⓇ resource inside a Kubernetes Pod by using manually defined PersistentVolume (PV) and PersistentVolumeClaim (PVC) resources. This is helpful in scenarios where a LINSTOR volume has been created outside of Kubernetes, such as after restoring a backup sent from a remote LINSTOR cluster, and therefore needs to be defined within Kubernetes manually.

Prerequisites

A working Kubernetes cluster with the LINSTOR CSI driver installed and configured.
An existing LINSTOR resource (res0 in this KB) created manually or through processes outside of Kubernetes.
The resource must be accessible from the Kubernetes nodes (LINSTOR satellite nodes known to Kubernetes are within the same LINSTOR cluster as the LINSTOR satellite nodes with replicas of the existing resource).

Importing the LINSTOR resource

Create the PersistentVolume

This YAML defines a PV that uses the existing LINSTOR resource named res0. Change storageClassName, capacity, and volumeHandle to match your cluster’s resource.

# cat << EOF > pv-the-hard-way.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pvc-the-hard-way
spec:
  accessModes:
  - ReadWriteOnce
  capacity:
    storage: 1Gi
  csi:
    driver: linstor.csi.linbit.com
    volumeAttributes:
      linstor.csi.linbit.com/mount-options: ""
      linstor.csi.linbit.com/post-mount-xfs-opts: ""
      linstor.csi.linbit.com/remote-access-policy: "true"
      linstor.csi.linbit.com/uses-volume-context: "true"
    volumeHandle: res0
  persistentVolumeReclaimPolicy: Recycle
  storageClassName: linstor-basic-storage-class
  volumeMode: Block
EOF

❗ IMPORTANT: volumeMode: Block implies that the volume should be attached to the container as a raw block device. This is different from volumeMode: Filesystem, which is the default volumeMode, which would result in a PV that would be mounted within the container. For file system mode, use volumeMounts rather than volumeDevices, and adjust volumeMode: Filesystem.

Apply the PV:

kubectl apply -f pv-the-hard-way.yaml

Create the PersistentVolumeClaim

This PVC must match the storage class, access mode, and volume mode defined in the PV.

# cat << EOF > pvc-the-hard-way.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-the-hard-way
spec:
  storageClassName: linstor-basic-storage-class
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1G
  volumeMode: Block
EOF

Apply the PVC:

kubectl apply -f pvc-the-hard-way.yaml

After you apply the configuration, the PVC should immediately bind to the manually defined PV.

3. Create a Pod that uses the persistent volume

Here is a simple Pod definition that attaches the PVC as a block device at /data:

# cat << EOF > pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: demo-pod-0
  namespace: default
spec:
  containers:
  - name: demo-pod-0
    image: busybox
    command: ["/bin/sh"]
    args: ["-c", "while true; do sleep 1000s; done"]
    volumeDevices:
    - devicePath: "/data"
      name: demo-vol
  volumes:
  - name: demo-vol
    persistentVolumeClaim:
      claimName: pvc-the-hard-way
EOF

❗ IMPORTANT: For file system mode, use volumeMounts rather than volumeDevices, and mountPath rather than devicePath.

Apply the Pod:

kubectl apply -f pod.yaml

Verify that the volume was attached:

kubectl describe pod demo-pod-0

Written by: MDK - 2025-07-15

Reviewed by: ASB - 2025-07-17