TNS CSI Driver

A Kubernetes CSI (Container Storage Interface) driver for TrueNAS Scale 25.10+.

Important Disclaimer

This project is in early development phase and is NOT production-ready

Use of this software is entirely at your own risk
Extensive testing and validation required before production use

Overview

This CSI driver enables Kubernetes to provision and manage persistent volumes on TrueNAS Scale 25.10+. It currently supports:

NFS - Network File System for file-based storage
NVMe-oF - NVMe over Fabrics for high-performance block storage
iSCSI - Traditional block storage protocol with broad compatibility

Comparison with Other Drivers

	TNS-CSI	truenas-csi (Official)	Democratic-CSI
Best for	Modern TrueNAS with NVMe-oF	Scheduled snapshots, CHAP auth	Broad compatibility
Block protocols	NVMe-oF, iSCSI	iSCSI	iSCSI (+ NVMe-oF for ZoL)
Unique strength	kubectl plugin, metrics, adoption, encryption	Scheduled snapshots	Multi-backend, Windows
Trade-off	WebSocket API only	No NVMe-oF, no plugin	SSH complexity
Maturity	Early development	Very new (Dec 2025)	Mature, production-ready

See detailed comparisons:

Protocol Selection Guide

This driver supports three storage protocols:

NFS: Best for shared file storage where multiple pods need concurrent access (ReadWriteMany)
NVMe-oF: Best for high-performance block storage with lowest latency and highest IOPS - ideal for databases and latency-sensitive workloads
iSCSI: Traditional block storage with broad compatibility - useful when NVMe-oF is not available or for environments already using iSCSI

Note: SMB/CIFS is not supported due to the Linux-focused nature of this driver. If you need Windows file sharing, consider the Democratic-CSI driver.

Features

Dynamic volume provisioning - Automatically create and delete storage volumes
Multiple protocol support - NFS for file storage, NVMe-oF and iSCSI for block storage
Volume lifecycle management - Full create, delete, attach, detach, mount, unmount operations
Volume snapshots - Create, delete, and restore from snapshots (NFS, NVMe-oF, and iSCSI)
Volume cloning - Create new volumes from existing snapshots
Volume expansion - Resize volumes dynamically (NFS, NVMe-oF, and iSCSI)
Volume retention - Optional deleteStrategy: retain to keep volumes on PVC deletion
Volume adoption - Automatically adopt orphaned volumes for GitOps and disaster recovery workflows (see Adoption Guide)
Configurable mount options - Customize NFS/NVMe-oF/iSCSI mount options via StorageClass
Configurable ZFS properties - Set compression, dedup, recordsize, etc. via StorageClass parameters
Access modes - ReadWriteOnce (RWO), ReadWriteOncePod (RWOP), and ReadWriteMany (RWX) support
Storage classes - Flexible configuration via Kubernetes storage classes
Connection resilience - Automatic reconnection with exponential backoff for WebSocket API

kubectl Plugin

The project includes a kubectl plugin (kubectl tns-csi) for managing volumes directly from the command line:

# Install via krew (recommended)
kubectl krew install tns-csi

# Or download from GitHub releases

Key Commands:

Command	Description
`kubectl tns-csi summary`	Dashboard overview of all resources
`kubectl tns-csi list`	List all managed volumes
`kubectl tns-csi list-snapshots`	List snapshots with source volumes
`kubectl tns-csi health`	Check health of all volumes
`kubectl tns-csi troubleshoot <pvc>`	Diagnose PVC issues
`kubectl tns-csi cleanup`	Delete orphaned volumes
`kubectl tns-csi serve`	Start web dashboard on http://localhost:8080

The plugin auto-discovers credentials from the installed driver, so it works out of the box on clusters with tns-csi installed.

See kubectl Plugin Documentation for full details.

Kubernetes Distribution Compatibility

This driver is tested and verified to work on 6 Kubernetes distributions with NFS, NVMe-oF, and iSCSI protocols:

Distribution	NFS	NVMe-oF	iSCSI	Description
K3s	✅	✅	✅	Lightweight Kubernetes by Rancher
K0s	✅	✅	✅	Zero-friction Kubernetes by Mirantis
KubeSolo	✅	✅	✅	Single-node Kubernetes
Minikube	✅	✅	✅	Local Kubernetes for development
Talos	✅	✅	✅	Secure, immutable Kubernetes OS
MicroK8s	✅	✅	✅	Lightweight Kubernetes by Canonical

Compatibility tests run weekly and on-demand. See Distro Compatibility Tests for details.

Prerequisites

Kubernetes 1.27+ (earlier versions may work but are not tested)
TrueNAS Scale 25.10 or later (required for full feature support including NVMe-oF)
For NFS: NFS client utilities on all nodes (nfs-common on Debian/Ubuntu, nfs-utils on RHEL/CentOS)
For NVMe-oF:
- TrueNAS Scale 25.10+
- TrueNAS must have a static IP configured (DHCP not supported for NVMe-oF)
- At least one NVMe-oF TCP port configured in TrueNAS (Shares > NVMe-oF Targets > Ports, default: 4420)
- nvme-cli package installed on all Kubernetes nodes
- Kernel modules: nvme-tcp, nvme-fabrics
- Network connectivity from Kubernetes nodes to TrueNAS on port 4420
For iSCSI:
- TrueNAS Scale 25.10+
- iSCSI service enabled in TrueNAS (System > Services > iSCSI)
- open-iscsi package installed on all Kubernetes nodes (iscsid service running)
- Network connectivity from Kubernetes nodes to TrueNAS on port 3260

Quick Start

See DEPLOYMENT.md for detailed installation and configuration instructions.

Installation via Helm (Recommended)

The TNS CSI Driver is published to both Docker Hub and GitHub Container Registry as OCI artifacts:

Always use a specific version in production. See docs/VERSIONING.md for details.

Docker Hub (recommended)

helm install tns-csi oci://registry-1.docker.io/bfenski/tns-csi-driver \
  --version 0.9.2 \
  --namespace kube-system \
  --create-namespace \
  --set truenas.url="wss://YOUR-TRUENAS-IP:443/api/current" \
  --set truenas.apiKey="YOUR-API-KEY" \
  --set storageClasses.nfs.enabled=true \
  --set storageClasses.nfs.pool="YOUR-POOL-NAME" \
  --set storageClasses.nfs.server="YOUR-TRUENAS-IP"

NVMe-oF Example:

helm install tns-csi oci://registry-1.docker.io/bfenski/tns-csi-driver \
  --version 0.9.2 \
  --namespace kube-system \
  --create-namespace \
  --set truenas.url="wss://YOUR-TRUENAS-IP:443/api/current" \
  --set truenas.apiKey="YOUR-API-KEY" \
  --set storageClasses.nvmeof.enabled=true \
  --set storageClasses.nvmeof.pool="YOUR-POOL-NAME" \
  --set storageClasses.nvmeof.server="YOUR-TRUENAS-IP" \
  --set storageClasses.nvmeof.transport=tcp \
  --set storageClasses.nvmeof.port=4420

Note: NVMe-oF requires a TCP port to be pre-configured in TrueNAS (Shares > NVMe-oF Targets > Ports). Subsystems are automatically created per volume.

iSCSI Example:

helm install tns-csi oci://registry-1.docker.io/bfenski/tns-csi-driver \
  --version 0.9.2 \
  --namespace kube-system \
  --create-namespace \
  --set truenas.url="wss://YOUR-TRUENAS-IP:443/api/current" \
  --set truenas.apiKey="YOUR-API-KEY" \
  --set storageClasses.iscsi.enabled=true \
  --set storageClasses.iscsi.pool="YOUR-POOL-NAME" \
  --set storageClasses.iscsi.server="YOUR-TRUENAS-IP"

Note: iSCSI requires the iSCSI service to be enabled in TrueNAS (System > Services). Targets and extents are automatically created per volume.

See the Helm chart README for detailed configuration options.

Configuration

The driver is configured via command-line flags and Kubernetes secrets:

Command-Line Flags

--endpoint - CSI endpoint (default: unix:///var/lib/kubelet/plugins/tns.csi.io/csi.sock)
--node-id - Node identifier (typically the node name)
--driver-name - CSI driver name (default: tns.csi.io)
--api-url - TrueNAS API URL (e.g., ws://YOUR-TRUENAS-IP/api/v2.0/websocket)
--api-key - TrueNAS API key

Storage Class Parameters

NFS Volumes:

parameters:
  protocol: nfs
  server: YOUR-TRUENAS-IP
  pool: tank
  path: /mnt/tank/k8s

NVMe-oF Volumes:

parameters:
  protocol: nvmeof
  server: YOUR-TRUENAS-IP
  pool: tank
  path: /mnt/tank/k8s/nvmeof
  fsType: ext4  # or xfs

Note: Subsystems are automatically created per volume. Ensure an NVMe-oF TCP port is configured in TrueNAS (Shares > NVMe-oF Targets > Ports).

Testing

Comprehensive Testing on Real Infrastructure

This driver is tested extensively using real hardware and software - not mocks or simulators:

Self-hosted GitHub Actions runner on dedicated OVH infrastructure
Real Kubernetes cluster (k3s) provisioned for each test run
Real TrueNAS Scale server with actual storage pools and network services on dedicated sponsored by Akamai/Linode infrastructure
Full protocol stack testing - NFS mounts, NVMe-oF connections, actual I/O operations

Automated Test Suite

Every commit triggers comprehensive integration tests:

Core Functionality Tests:

Basic volume provisioning and deletion (NFS, NVMe-oF & iSCSI)
Volume expansion (dynamic resizing)
Snapshot creation and restoration
Volume cloning from snapshots
Volume adoption (GitOps workflows)
StatefulSet volume management
Data persistence across pod restarts

Stress & Reliability Tests:

Concurrent volume creation (5 simultaneous volumes)
Connection resilience (WebSocket reconnection)
Orphaned resource detection and cleanup

CSI Specification Compliance:

Passes Kubernetes CSI sanity tests (v5.4.0)
Full CSI spec compliance verified

View test results and history:

Project Status and Limitations

⚠️ EARLY DEVELOPMENT - NOT PRODUCTION READY

This driver is in early development and requires extensive testing before production use. Key considerations:

Development Phase: Active development with ongoing testing and validation
Protocol Support: Currently supports NFS, NVMe-oF, and iSCSI. SMB is not planned (Linux-focused driver).
Volume Expansion: Implemented and functional for NFS, NVMe-oF, and iSCSI protocols when allowVolumeExpansion: true is set in the StorageClass (Helm chart enables this by default)
Snapshots: Implemented for NFS, NVMe-oF, and iSCSI protocols, functional and tested
Testing: Comprehensive automated testing on real infrastructure (see Testing section above)
Stability: Core features functional but may have undiscovered edge cases or bugs

Recommended Use: Development, testing, and evaluation environments only. Use at your own risk.

Troubleshooting

See DEPLOYMENT.md for detailed troubleshooting steps.

Common Issues:

Pods stuck in ContainerCreating:
- For NFS: Check that NFS client utilities are installed on nodes
- For NVMe-oF: Check that nvme-cli is installed and kernel modules are loaded
Failed to create volume: Verify storage API credentials and network connectivity
Mount failed:
- For NFS: Ensure NFS service is running on TrueNAS and accessible from nodes
- For NVMe-oF: Ensure NVMe-oF service is enabled and firewall allows port 4420

View Logs:

# Controller logs
kubectl logs -n kube-system -l app.kubernetes.io/name=tns-csi-driver,app.kubernetes.io/component=controller

# Node logs
kubectl logs -n kube-system -l app.kubernetes.io/name=tns-csi-driver,app.kubernetes.io/component=node

# Check version
kubectl logs -n kube-system deployment/tns-csi-controller 2>&1 | head -1

Documentation

Features Documentation - Comprehensive feature support reference
Deployment Guide - Detailed installation and configuration
kubectl Plugin - Command-line tool for volume management
Quick Start - NFS - Get started with NFS volumes
Quick Start - NVMe-oF - Get started with NVMe-oF volumes
Quick Start - iSCSI - Get started with iSCSI volumes
Snapshots Guide - Volume snapshots and cloning
Versioning - Version management and checking installed version
Distro Compatibility - Kubernetes distribution compatibility testing
Metrics Guide - Prometheus metrics and monitoring
Kind Setup - Local development with Kind
Comparison with truenas-csi - vs official TrueNAS CSI driver
Comparison with Democratic-CSI - vs democratic-csi

Volume Adoption

The driver supports cross-cluster volume adoption - importing existing tns-csi managed volumes into a new Kubernetes cluster. This is useful for:

Disaster recovery scenarios
Cluster migrations
Re-importing retained volumes after upgrades

Volumes are adoptable if they have proper tns-csi:* ZFS user properties set. See Volume Adoption in the Features documentation for details.

Development

Prerequisites

Go 1.21+
Docker (for building images)
Kubernetes cluster for testing

Building

make build

Testing

Tests are automated via GitHub Actions CI/CD running on self-hosted infrastructure with real TrueNAS hardware. See .github/workflows/ for workflow configuration.

Local Testing:

# Run unit tests
make test

# Run specific test
go test -v ./pkg/driver/...

# Run CSI sanity tests (requires TrueNAS connection)
cd tests/sanity && ./test-sanity.sh

# Run Ginkgo E2E tests (requires TrueNAS and Kubernetes cluster)
ginkgo -v --timeout=25m ./tests/e2e/nfs/...
ginkgo -v --timeout=40m ./tests/e2e/nvmeof/...
ginkgo -v --timeout=40m ./tests/e2e/iscsi/...

See docs/TESTING.md for comprehensive testing documentation.

Building Container Image

make docker-build

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0) - see the LICENSE file for details.

Acknowledgments

This driver is designed to work with TrueNAS Scale 25.10+.

Name		Name	Last commit message	Last commit date
Latest commit History 762 Commits
.github		.github
charts/tns-csi-driver		charts/tns-csi-driver
cmd		cmd
dashboard		dashboard
deploy		deploy
docs		docs
pkg		pkg
plugins/krew		plugins/krew
scripts		scripts
tests		tests
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
cliff.toml		cliff.toml
go.mod		go.mod
go.sum		go.sum
kind-config.yaml		kind-config.yaml
sonar-project.properties		sonar-project.properties

License

fenio/tns-csi

Folders and files

Latest commit

History

Repository files navigation

TNS CSI Driver

Important Disclaimer

Overview

Comparison with Other Drivers

Protocol Selection Guide

Features

kubectl Plugin

Kubernetes Distribution Compatibility

Prerequisites

Quick Start

Installation via Helm (Recommended)

Docker Hub (recommended)

Configuration

Command-Line Flags

Storage Class Parameters

Testing

Automated Test Suite

Project Status and Limitations

Troubleshooting

Documentation

Volume Adoption

Development

Prerequisites

Building

Testing

Building Container Image

Contributing

License

Acknowledgments

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 18

Packages 0

Uh oh!

Uh oh!

Contributors 5

Uh oh!

Languages

Packages