Introducing tns-csi: A Modern Kubernetes CSI Driver for TrueNAS Scale

TrueNAS General
, , ,
1

Hey everyone,

I wanted to share a project I’ve been working on: tns-csi - a Kubernetes Container Storage Interface (CSI) driver specifically designed for TrueNAS Scale 25.10+.

What is it?

tns-csi allows you to dynamically provision persistent volumes on your TrueNAS Scale server directly from Kubernetes. It supports two storage protocols:

  • NFS - For shared file storage (ReadWriteMany)
  • NVMe-oF (TCP) - For high-performance block storage

Why another CSI driver?

While GitHub - democratic-csi/democratic-csi: csi storage for container orchestration systems has served the community well, I wanted to build something with a different approach:

  1. Native WebSocket API Only
    Unlike democratic-csi which relies on SSH for ZFS operations, tns-csi communicates exclusively through TrueNAS’s native WebSocket API. This means:
  • No SSH keys to manage
  • No shell command injection concerns
  • Cleaner integration with TrueNAS’s internal APIs
  • Better alignment with how TrueNAS itself works

  1. NVMe-oF Instead of iSCSI
    tns-csi intentionally skips iSCSI in favor of NVMe-oF. NVMe-oF over TCP offers better performance and is the modern direction for block storage. If you have a 10GbE+ network, the performance difference is noticeable.

  2. Built-in kubectl Plugin
    The driver comes with a kubectl plugin (kubectl tns-csi) that helps you:

  • List all managed volumes and snapshots
  • Find orphaned volumes (volumes on TrueNAS with no matching PVC)
  • Discover unmanaged volumes for migration
  • Import existing datasets into tns-csi management
  • Adopt volumes across cluster rebuilds
  • Troubleshoot connectivity and volume health
  1. ZFS Properties as Source of Truth
    All volume metadata is stored in ZFS user properties (tns-csi:*). This means:
  • No external database or state to manage
  • Volumes are self-describing
  • Easy disaster recovery - just query TrueNAS
  • Supports volume adoption across cluster migrations
  1. Detached Snapshots
    Regular CSI snapshots are tied to their source volume. tns-csi supports “detached snapshots” that use zfs send/receive to create independent copies. These survive even if you delete the original volume - useful for backup and DR scenarios.

Current Status

This is still early-stage software. I’m running it on my homelab and it’s working well, but it hasn’t seen wide production use yet. I’d classify it as:

  • :white_check_mark: NFS provisioning - stable, well-tested
  • :white_check_mark: NVMe-oF provisioning - stable, well-tested
  • :white_check_mark: Volume expansion - working
  • :white_check_mark: Snapshots (attached & detached) - working
  • :white_check_mark: Volume cloning - working
  • :warning: Not yet battle-tested at scale

Requirements

  • TrueNAS Scale 25.10+ (uses WebSocket API)
  • Kubernetes 1.25+
  • For NVMe-oF: Linux nodes with nvme-tcp kernel module

Links

Looking for Feedback

If you’re comfortable running early-stage software and want to help test, I’d love feedback on:

  • Installation experience
  • Any edge cases or bugs you encounter
  • Feature requests
  • Documentation gaps

Feel free to open issues on GitHub or reply here.

Note: This is a personal project, not affiliated with or endorsed by iXsystems.

1 Like