OpenShift Operator Administrators Guide

This article provides instructions for administrators deploying and managing the TrueNAS CSI driver through the OpenShift Operator.

Cluster administrators perform the one-time configuration that consists of:

• Verifying your cluster is properly configured
• Verifying your network firewall and DNS is correctly configured
• Configuring TrueNAS authentication and storage for the CSI driver
• Installing the OpenShift Operator in your cluster
• Adding the StorageClasses (NFS, iSCSI, or both)

The TrueNAS administrator does the one-time setup that consists of:

• Creating an API key for OpenShift authentication
• Setting up a pool to use for storage
• Turning on the appropriate service (nfs for file or iscsi for block storage requests)
• Supplying the cluster administrator with the API and IP address of the TrueNAS system

After receiving the authentication credentials from the TrueNAS administrator, establish communication with TrueNAS using the API authentication key provided by TrueNAS and the TrueNAS system IP address.

Each OpenShift cluster user (developer) creates a Persistent Volume Claim (PVC) YAML file that specifies the volume size, access mode, StorageClass, and other settings, then submits this PVC request in OpenShift using an oc command. TrueNAS receives the request and adds the requested volumes based on the StorageClass information received in the YAML file.

The OpenShift Operator communicates what is received from the cluster, passes it to TrueNAS, and then sends information from TrueNAS back to the cluster where users can mount the storage volume(s) requested.

• TrueNAS Requirements:

  • TrueNAS 25.10.0 or later
  • ZFS pool with available storage capacity
  • NFS and/or iSCSI service enabled and running
  • API key generated by a user with full administrative privileges
  • WebSocket API accessible on port 443

• OpenShift Cluster Requirements:

  • OpenShift 4.20 or later
  • Cluster running and accessible
  • kubeconfig with cluster-admin role
  • oc CLI installed and authenticated
  • DNS resolving correctly for cluster endpoints

• Network Requirements:

  • TCP 443 - OpenShift nodes to TrueNAS (WebSocket API)
  • TCP 2049 - OpenShift nodes to TrueNAS (NFS, if used)
  • TCP 3260 - OpenShift nodes to TrueNAS (iSCSI, if used)
  • Firewall that allows OpenShift pod network CIDR to reach TrueNAS

The CSI driver in the OpenShift Operator automatically creates datasets and NFS shares or iSCSI targets with UUID-based names, which are not human-readable. For example, a path like /mnt/Tank1/pvc-538b3b31-2619-4cda-837a-57a47c40e8df. Do not modify or delete these auto-created shares or targets.

Log in to TrueNAS as a user with full administration privileges:

1. Generate an API key for OpenShift.

   a. Click Settings on the top toolbar, then click My API Keys to open the User API Keys screen. b. Click Add, enter a name for the key, for example, OpenShift Operator. c. Click Save. d. Copy the key to a text file or a document kept secure and backed up regularly.

   Provide the API key to the cluster administrator, who should enter this key along with the TrueNAS IP address to establish authenticated communication with TrueNAS.

   For more information on TrueNAS API keys, see Managing API Keys.

   To locate the IP address for TrueNAS, go to System > Network. The primary network interface is listed in the Interfaces card.

2. Enable the NFS service if using NFS or enable the iSCSI service if using iSCSI.

   a. Go to System > Services. b. Edit the service settings to provide the required port access.

   • For the NFS service, set TCP port 2049, and set UDP port 2049.
   • For iSCSI, set TCP port 3260. c. Click Save. d. Click the enable-service toggle to turn on the NFS or iSCSI services, or both, based on your use case.

   Creating NFS or iSCSI shares is not necessary. Enable the services only.

3. Create a new pool or locate a pool with enough storage to accommodate the OpenShift cluster storage needs. Go to Storage Dashboard, identify a pool with enough storage capacity to suit your use case, or click Create Pool to add a new pool for OpenShift volumes.

   For more information on creating new pools, see Creating Pools. To increase storage in an existing pool, see Expanding a Pool in Managing Pools.

   Provide the pool name to the cluster administrator.

4. Verify the WebSocket API port is set to port 443.

   Go to System > General Settings. The GUI card should show the Web Interface HTTPS port set to 443, if not: a. Click Settings b. Locate and change the Web Interface HTTPS Port field value to 443. c. Click Save.

  This procedure covers adding the API key and TrueNAS IP address to the OpenShift Operator to establish communication, and setting up StorageClasses.

1. Install the Operator from OperatorHub.

   a. Log in to the OpenShift web console. b. Navigate to Operators > OperatorHub. c. Search for TrueNAS CSI, click the TrueNAS CSI Driver tile. d. Click Install. e. Select options:

   • Update channel: stable
   • Installation mode: All namespaces on the cluster
   • Installed Namespace: openshift-operators f. Click Install. Wait for the operator to install and show Succeeded.

2. Create the API credentials secret. Editing the YAML directly is not required. The cluster admin user installs the Operator from OperatorHub through the web console. The admin then uses the OpenShift console UI or the oc apply command to:

   a. Create the secret.

   apiVersion: v1
   kind: Secret
   metadata:
     name: truenas-api-credentials
     namespace: truenas-csi
   type: Opaque
   stringData:
     api-key: "YOUR-TRUENAS-API-KEY"
   

   b. Apply the secret.

   oc apply -f truenas-api-credentials.yaml
   

3. Create TrueNASCSI custom resource to deploy the TrueNAS CSI driver:

   apiVersion: csi.truenas.io/v1alpha1
   kind: TrueNASCSI
   metadata:
     name: truenas
   spec:
     # Required: TrueNAS WebSocket API URL
     truenasURL: "wss://your-truenas-ip/api/current"
   
     # Required: Name of the secret containing the API key
     credentialsSecret: "truenas-api-credentials"
   
     # Required: Default ZFS pool for volume provisioning
     defaultPool: "your-pool-name"
   
     # Optional: NFS server IP (required for NFS volumes)
     nfsServer: "your-truenas-ip"
   
     # Optional: iSCSI portal address (required for iSCSI volumes)
     iscsiPortal: "your-truenas-ip:3260"
   
     # Optional: Skip TLS verification (for self-signed certs)
     insecureSkipTLS: false
   

   Apply the resource:

   oc apply -f truenas-csi.yaml
   

4. Verify the installation.

   Check the status of the TrueNASCSI resource:

   oc get truenascsi truenas -o yaml
   

   Verify that controller and node pods are running:

   oc get pods -n truenas-csi
   

   You should see:

   • truenas-csi-controller-* - Controller deployment pod
   • truenas-csi-node-* - Node DaemonSet pods (one per node)

5. Create the StorageClasses for NFS and/or iSCSI.

   NFS StorageClass

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: truenas-nfs
   provisioner: csi.truenas.io
   parameters:
     protocol: nfs
     pool: tank
     # Optional parameters
     compression: "lz4"
     sync: "standard"
   reclaimPolicy: Delete
   allowVolumeExpansion: true
   volumeBindingMode: Immediate
   

   iSCSI StorageClass

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: truenas-iscsi
   provisioner: csi.truenas.io
   parameters:
     protocol: iscsi
     pool: tank
     fsType: ext4
     # Optional parameters
     compression: "lz4"
     sync: "standard"
   reclaimPolicy: Delete
   allowVolumeExpansion: true
   volumeBindingMode: Immediate
   

   Additional YAML Parameters

   The YAML record provided is complete, but you have the option to add additional parameters based on your use case:

   • iscsiIQNBase - Specifies the base IQN for iSCSI targets. Defaults to iqn.2005-10.org.freenas.ctl.
   • driverImage - Specifies a custom driver image version.
   • controllerReplicas - Specifies the number of controller pod replicas. Default is 1.
   • nodeSelector - Limits CSI pod scheduling to nodes matching the specified labels.
   • tolerations - Specifies pod tolerations for node conditions.

   For additional information, see OpenShift Operator Reference Guide

6. Test with a PVC.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: my-pvc
   spec:
     accessModes:
       - ReadWriteOnce  # Use ReadWriteMany for NFS
     storageClassName: truenas-iscsi  # or truenas-nfs
     resources:
       requests:
        storage: 10Gi
   

To uninstall the OpenShift Operator:

1. Delete TrueNASCSI resource.

   oc delete truenascsi truenas
   

2. Uninstall the Operator.

   a. Navigate to Operators > Installed Operators. b. Find TrueNAS CSI Driver. c. Click the three dots menu and select Uninstall Operator.

3. (Optional) Clean up after uninstalling by deleting the namespace and secrets:

   oc delete namespace truenas-csi