OpenShift Operator User Guide

This guide is for developers/users requesting storage through the OpenShift Operator that packages and manages the TrueNAS CSI driver. These storage requests use PersistentVolumeClaim (PVC) YAML files submitted with the oc apply command to add volumes to OpenShift projects.

It covers creating PersistentVolumeClaims, mounting storage volumes, and using the features available to TrueNAS storage users.

For an overview of the OpenShift Operator/CSI driver integration see OpenShift Operator.

For StorageClass configuration and Operator installation, see OpenShift Operator Administrators Guide.

For reference material including a glossary of terms, see OpenShift Operator Reference.

The OpenShift Operator sends storage requests to TrueNAS via the CSI driver. TrueNAS creates the storage volume based on the information in the PVC yaml file and returns volume information to OpenShift, where it can be mounted and used in a project.

Developers/users should follow this process to set up storage they can mount in their cluster pods within their project.

Replace my-app-data with the name of your PVC in the commands in this section.

1. Create a PersistentVolumeClaim.

   YAML Code Block

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: my-app-data
     namespace: default
   spec:
     accessModes:
       - ReadWriteMany  # For NFS (multiple pods can access)
     storageClassName: truenas-nfs
     resources:
       requests:
         storage: 10Gi  # Request 10GB of storage
   

2. Apply the PersistentVolumeClaim.

   oc apply -f my-app-data.yaml

   Where my-app-data is the name of the yaml file (and PVC) created locally by the developer/user.

3. Check the PVC status.

   oc get pvc my-app-data
   

NAME          STATUS   VOLUME                                     CAPACITY   ACCESS MODES
my-app-data   Bound    pvc-a1b2c3d4-e5f6-7890-abcd-ef1234567890   10Gi       RWX

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  namespace: default
spec:
  containers:
  - name: app
    image: nginx
    volumeMounts:
    - name: data
      mountPath: /usr/share/nginx/html  # Where to mount in container
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: my-app-data  # Reference the PVC

Then to apply a volume in a pod:

oc apply -f pod.yaml

These commands check if a pod is running, verify a mount inside a container, and then write test data to and read it back from the container.

# Check pod is running
oc get pod my-app

# Verify mount inside container
oc exec my-app -- df -h /usr/share/nginx/html

# Write test data
oc exec my-app -- sh -c "echo 'Hello from TrueNAS' > /usr/share/nginx/html/index.html"

# Read it back
oc exec my-app -- cat /usr/share/nginx/html/index.html

1. Check the current size. The CAPACITY shows current size.

   oc get pvc my-app-data
   

2. Edit a PVC to request a larger size. Change the storage size, then save and exit.

   oc edit pvc my-app-data
   
   # Change:
     resources:
         requests:
               storage: 10Gi
   
   # To:
     resources:
         requests:
               storage: 20Gi
   
   # Save and exit
   

   Alternatively, use oc patch:

   oc patch pvc my-app-data -p '{"spec":{"resources":{"requests":{"storage":"20Gi"}}}}'
   

3. Wait for the expansion. Watch the CAPACITY column increase in size.

   oc get pvc my-app-data -w
   
   # Watch CAPACITY column increase to 20Gi
   

   For iSCSI volumes, you might need to restart the pod for the file system resize to take effect.

1. Create a VolumeSnapshot, and then apply it.

   YAML Code Block

   apiVersion: snapshot.storage.k8s.io/v1
   kind: VolumeSnapshot
   metadata:
     name: my-app-snapshot-20250102
     namespace: default
   spec:
     volumeSnapshotClassName: truenas-snapclass
     source:
       persistentVolumeClaimName: my-app-data
   

   Apply it:

   oc apply -f snapshot.yaml
   

2. Verify the snapshot.

   oc get volumesnapshot my-app-snapshot-20250102
   

   Expected Result

   # Expected:
   # NAME                        READYTOUSE   SOURCEPVC     RESTORESIZE
   # my-app-snapshot-20250102    true         my-app-data   10Gi
   

3. Check in TrueNAS.

   Navigate to Datasets, locate and select the dataset on the table, then click View Snapshots on the Data Protection card to open the Snapshots screen. Search for the snapshot. The snapshot name format is pool/dataset@snapshot-name

You can restore from a snapshot by creating a new volume from a snapshot, or cloning an existing volume.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-app-restore
  namespace: default
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: truenas-nfs
  resources:
    requests:
      storage: 10Gi
  dataSource:
    name: my-app-snapshot-20250102
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io

Apply it:

oc apply -f restore-pvc.yaml
oc wait --for=jsonpath='{.status.phase}'=Bound pvc/my-app-restore --timeout=120s

This creates a new volume with the data from the snapshot.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-app-clone
  namespace: default
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: truenas-nfs
  resources:
    requests:
      storage: 10Gi
  dataSource:
    name: my-app-data  # Source PVC to clone
    kind: PersistentVolumeClaim

Apply it:

oc apply -f clone-pvc.yaml
oc wait --for=jsonpath='{.status.phase}'=Bound pvc/my-app-clone --timeout=120s

This creates a new, independent volume with a copy of the source data.

The TrueNAS CSI driver supports advanced storage operations including snapshot-based backup and restore, volume cloning, and multi-protocol deployments. These features are available to all cluster users with the appropriate StorageClass configured by the cluster administrator.

The following is a backup workflow:

1. Create a pre-upgrade snapshot YAML file and apply it.

   YAML Code Block

   apiVersion: snapshot.storage.k8s.io/v1
   kind: VolumeSnapshot
   metadata:
     name: db-before-upgrade
     namespace: production
   spec:
     volumeSnapshotClassName: truenas-snapclass
     source:
       persistentVolumeClaimName: postgres-data
   

   oc apply -f snapshot.yaml
   

2. Perform Application Upgrade.

   oc set image deployment/postgres postgres=postgres:15
   

3. Restore if upgrade fails. Stop the application and then create a new volume from a snapshot. Next update the deployment to use the restored volume and then restart the application.

   Stop the application:

   oc scale deployment postgres --replicas=0
   

   Create new volume from snapshot

   Command and YAML Code

   oc apply -f - <<EOF
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: postgres-data-restored
     namespace: production
   spec:
     accessModes: [ReadWriteOnce]
     storageClassName: truenas-iscsi
     resources:
       requests:
         storage: 100Gi
     dataSource:
       name: db-before-upgrade
       kind: VolumeSnapshot
       apiGroup: snapshot.storage.k8s.io
   EOF
   

   Update deployment to use restored volume

   oc set volume deployment/postgres --add --name=data --claim-name=postgres-data-restored
   

   Restart application

   oc scale deployment postgres --replicas=1
   

Volume cloning creates an instant copy of an existing volume using ZFS copy-on-write, making it ideal for spinning up staging or test environments with real production data.

Cloning a volume to staging provides these benefits:

• Instant copy via ZFS clones
• Minimal storage overhead (copy-on-write)
• Staging has real production data for testing
• No impact on production volume

# Clone production volume
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data-staging
  namespace: staging
spec:
  accessModes: [ReadWriteMany]
  storageClassName: truenas-nfs
  resources:
    requests:
      storage: 50Gi
  dataSource:
    name: app-data-prod
    kind: PersistentVolumeClaim
EOF

Some applications benefit from using both protocols. Example content management system:

# Media files - NFS for shared access
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: cms-media
spec:
  accessModes: [ReadWriteMany]
  storageClassName: truenas-nfs
  resources:
    requests:
      storage: 100Gi

---
# Database - iSCSI for performance
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: cms-database
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: truenas-iscsi
  resources:
    requests:
      storage: 20Gi