Complete Guide to TrueNAS Integration with Red Hat OpenShift

This guide explains how to integrate TrueNAS with Red Hat OpenShift, leveraging the recent certification that makes TrueNAS a certified storage backend for Kubernetes and OpenShift. This integration is useful for organizations needing a supported and automated storage system for containerized applications.

TrueNAS 25.10 introduces the new TrueNAS CSI driver, available through Red Hat's ecosystem catalog. This driver is compatible with OpenShift 4.20 and later versions, offering a standardized way to manage the persistent storage required by many Kubernetes applications.

OpenShift is Red Hat's enterprise Kubernetes platform, designed to run, manage, and scale containerized applications in hybrid, cloud, and server environments. TrueNAS certification ensures that organizations can use an officially supported storage backend, eliminating the need for unofficial or manually maintained components.

The main technical change is the shift from the previous democratic-csi driver to an API-first implementation, based on the versioned TrueNAS API introduced with version 25.10. This new driver automatically handles the provisioning, resizing, snapshots, and deletion of storage based on Kubernetes storage requests.

Protocol support includes NFS v3/v4 and iSCSI, offering options for shared file storage and block-level storage for performance-sensitive applications. The driver supports both ReadWriteOnce and ReadWriteMany access modes, depending on the application's needs and storage configuration.

Key features include dynamic provisioning and deletion, online volume resizing without downtime, snapshots via Kubernetes' standard CSI API, automatic snapshot scheduling, cloning new volumes from snapshots, thin provisioning for iSCSI volumes, volume health status reporting, and capacity reporting.

On the security front, the system supports iSCSI CHAP authentication, iSCSI initiator allow-listing, NFS host and network allow-listing, and NFS user and group mapping. The certification covers Kubernetes starting from version 1.26 and OpenShift 4.20 and later versions.

Prerequisites

• Hardware: A system compatible with TrueNAS 25.10
• Software:
  • TrueNAS 25.10
  • Red Hat OpenShift 4.20 or later version
  • TrueNAS CSI Operator available through the Red Hat’s Ecosystem Catalog

Procedure: Configuring the TrueNAS CSI Driver with Red Hat OpenShift

By the end of this guide, you will have configured and integrated the TrueNAS CSI Driver with Red Hat OpenShift, allowing you to use TrueNAS as a certified storage backend for your Kubernetes workloads.

• Access the TrueNAS CSI Operator through the Red Hat catalog.
• Download the TrueNAS CSI Operator.
• Install the TrueNAS CSI Operator in your OpenShift cluster.
• Configure the TrueNAS CSI Driver following the instructions specific to your environment.
• Verify the integration between TrueNAS and OpenShift.
• Configure the storage volumes needed for your workloads.
• Test the creation, resizing, snapshotting, and deletion of storage volumes.
• Configure security options such as iSCSI CHAP authentication, NFS host and network allow-listing, and NFS user and group mapping.
• Monitor the status and performance of storage volumes.

Verification and Troubleshooting

By the end of this guide, you will be able to test the functionality of the TrueNAS CSI driver with Red Hat OpenShift and resolve any issues.

Functionality Testing

• Installation Verification: Access the OpenShift interface and verify that the TrueNAS CSI Operator is correctly installed. You can do this using the command:

  oc get pods -n openshift-storage

• Provisioning Test: Create a PersistentVolumeClaim (PVC) to test automatic provisioning. Use a YAML file as an example:

  apiVersion: v1
  kind: PersistentVolumeClaim
  metadata: name: test-pvc
  spec: accessModes: - ReadWriteOnce resources: requests: storage: 1Gi storageClassName: truenas-csi

• Snapshot Verification: Create a snapshot of the PVC to test the snapshot functionality. Use the command:

  oc create -f snapshot.yaml

  where snapshot.yaml contains the snapshot definition.
• Resizing Test: Modify the PVC to test online resizing. Increase the requested size and verify that the volume resizes correctly.

  oc patch pvc test-pvc -p '{"spec":{"resources":{"requests":{"storage":"2Gi"}}}}'

Troubleshooting

• Connectivity Issues: If the driver fails to connect to TrueNAS, verify that the API URL and credentials are correct. Also, check that the firewall is not blocking connections between OpenShift and TrueNAS.
• Provisioning Errors: If provisioning fails, verify that the StorageClass is correctly configured. Also, check the CSI driver logs for any errors.

  oc logs -n openshift-storage -l app=truenas-csi-driver

• Authentication Problems: If authentication errors occur, verify that the CHAP credentials for iSCSI are correctly configured. Also, check the allow-listing rules for NFS and iSCSI.
• Performance Issues: If performance problems are encountered, verify that the volume is correctly configured for the type of workload. Also, check the performance statistics of TrueNAS.

By the end of this guide, you will have understood how to integrate TrueNAS with Red Hat OpenShift, leveraging the new certified CSI driver for automated and secure storage management.

To apply what you have learned, follow these steps:

• Verify that your OpenShift environment is compatible with version 4.20 or later.
• Update TrueNAS to version 25.10 to use the new CSI driver.
• Configure storage using NFS or iSCSI based on the needs of your applications.
• Take advantage of advanced features such as dynamic provisioning, automated snapshots, and online resizing.

For more details, consult the official announcement.