{"id":50779555,"url":"https://github.com/nasty-project/nasty-csi","last_synced_at":"2026-06-12T02:03:52.699Z","repository":{"id":348382727,"uuid":"1180810684","full_name":"nasty-project/nasty-csi","owner":"nasty-project","description":"Kubernetes CSI driver for NASty","archived":false,"fork":false,"pushed_at":"2026-06-04T10:48:20.000Z","size":121652,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-04T12:19:33.142Z","etag":null,"topics":["bcachefs","csi","csi-driver","iscsi","kubernetes","nfs","nvme-of","persistent-volume","persistent-volume-claim","smb","storage"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nasty-project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"fenio","patreon":null,"open_collective":null,"ko_fi":"fenio","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-03-13T12:42:53.000Z","updated_at":"2026-06-04T10:48:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nasty-project/nasty-csi","commit_stats":null,"previous_names":["nasty-project/nasty-csi"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nasty-project/nasty-csi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasty-project%2Fnasty-csi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasty-project%2Fnasty-csi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasty-project%2Fnasty-csi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasty-project%2Fnasty-csi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nasty-project","download_url":"https://codeload.github.com/nasty-project/nasty-csi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasty-project%2Fnasty-csi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34225364,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bcachefs","csi","csi-driver","iscsi","kubernetes","nfs","nvme-of","persistent-volume","persistent-volume-claim","smb","storage"],"created_at":"2026-06-12T02:03:51.220Z","updated_at":"2026-06-12T02:03:52.687Z","avatar_url":"https://github.com/nasty-project.png","language":"Go","funding_links":["https://github.com/sponsors/fenio","https://ko-fi.com/fenio"],"categories":[],"sub_categories":[],"readme":"# NASty CSI Driver\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Go Version](https://img.shields.io/badge/Go-1.26.0-00ADD8?logo=go)](https://go.dev/)\n[![Go Report Card](https://goreportcard.com/badge/github.com/nasty-project/nasty-csi)](https://goreportcard.com/report/github.com/nasty-project/nasty-csi)\n[![CI](https://github.com/nasty-project/nasty-csi/actions/workflows/ci.yml/badge.svg)](https://github.com/nasty-project/nasty-csi/actions/workflows/ci.yml)\n[![Integration Tests](https://github.com/nasty-project/nasty-csi/actions/workflows/integration.yml/badge.svg)](https://github.com/nasty-project/nasty-csi/actions/workflows/integration.yml)\n[![Distro Compatibility](https://github.com/nasty-project/nasty-csi/actions/workflows/distro-compatibility.yml/badge.svg)](https://github.com/nasty-project/nasty-csi/actions/workflows/distro-compatibility.yml)\n[![GHCR](https://img.shields.io/badge/GHCR-nasty--csi-blue?logo=github)](https://github.com/nasty-project/nasty-csi/pkgs/container/nasty-csi)\n[![Driver](https://img.shields.io/github/v/release/nasty-project/nasty-csi?filter=v*\u0026label=driver\u0026logo=github)](https://github.com/nasty-project/nasty-csi/releases/latest)\n[![Plugin](https://img.shields.io/github/v/release/nasty-project/nasty-plugin?label=kubectl-nasty\u0026logo=github)](https://github.com/nasty-project/nasty-plugin/releases/latest)\n\nA Kubernetes CSI driver for [NASty](https://github.com/nasty-project/nasty) — a NAS appliance built on NixOS and bcachefs.\n\n## Important Disclaimer\n\n**This project is in early development phase and is NOT production-ready**\n- Use of this software is entirely at your own risk\n- Extensive testing and validation required before production use\n\n## Overview\n\nThis CSI driver enables Kubernetes to provision and manage persistent volumes on NASty. It currently supports:\n\n- **NFS** - Network File System for file-based storage\n- **NVMe-oF** - NVMe over Fabrics for high-performance block storage\n- **iSCSI** - Traditional block storage protocol with broad compatibility\n- **SMB/CIFS** - Authenticated file sharing with Windows compatibility\n\n## Dashboard and Observability\n\n\u003cimg width=\"1380\" height=\"914\" alt=\"image\" src=\"https://github.com/user-attachments/assets/5d2ce624-2031-442d-8f6f-5422bce9bab7\" /\u003e\n\nThe driver includes two dashboard options and a pre-built Grafana dashboard:\n\n- **In-cluster dashboard** — runs inside the controller pod (port 9090), enable with `controller.dashboard.enabled: true`\n- **kubectl plugin dashboard** — runs locally via `kubectl nasty dashboard` (port 2137)\n- **Grafana dashboard** — pre-built Prometheus dashboard, enable with `grafana.dashboards.enabled: true`\n\nSee [METRICS.md](docs/METRICS.md) for setup details.\n\n## Protocol Selection Guide\n\n- **NFS**: Shared file storage with ReadWriteMany support\n- **NVMe-oF**: High-performance block storage with the lowest latency — ideal for databases\n- **iSCSI**: Block storage with broad kernel and infrastructure support\n- **SMB/CIFS**: Authenticated file sharing with Windows compatibility\n\n## Features\n\n- Dynamic volume provisioning and deletion\n- Volume snapshots — create, delete, and restore (all protocols)\n- Volume cloning from snapshots\n- Online volume expansion (all protocols)\n- Volume retention — optional `deleteStrategy: retain` to preserve data on PVC deletion\n- Volume adoption — import orphaned volumes across clusters (see [Adoption Guide](docs/ADOPTION.md))\n- Access modes — RWO, RWOP, and RWX\n- Raw block RWX for KubeVirt live migration (NVMe-oF, iSCSI)\n- Configurable mount options via StorageClass\n- WebSocket connection resilience with automatic reconnection\n\n## kubectl Plugin\n\nA companion kubectl plugin for managing volumes from the command line is available at [nasty-project/nasty-plugin](https://github.com/nasty-project/nasty-plugin):\n\n```bash\n# Install via krew\nkubectl krew install nasty\n\n# Or download from GitHub releases\n```\n\n**Key Commands:**\n| Command | Description |\n|---------|-------------|\n| `kubectl nasty summary` | Dashboard overview of all resources |\n| `kubectl nasty list` | List all managed volumes |\n| `kubectl nasty list-snapshots` | List snapshots with source volumes |\n| `kubectl nasty health` | Check health of all volumes |\n| `kubectl nasty troubleshoot \u003cpvc\u003e` | Diagnose PVC issues |\n| `kubectl nasty cleanup` | Delete orphaned volumes |\n| `kubectl nasty dashboard` | Start web dashboard on http://localhost:2137 |\n\nThe plugin auto-discovers credentials from the installed driver, so it works out of the box on clusters with nasty-csi installed.\n\n## Kubernetes Distribution Compatibility\n\nThis driver is tested and verified to work on **6 Kubernetes distributions** with NFS, NVMe-oF, iSCSI, and SMB protocols:\n\n| Distribution | NFS | NVMe-oF | iSCSI | SMB | Description |\n|--------------|:---:|:-------:|:-----:|:---:|-------------|\n| K3s | ✅ | ✅ | ✅ | ✅ | Lightweight Kubernetes by Rancher |\n| K0s | ✅ | ✅ | ✅ | ✅ | Zero-friction Kubernetes by Mirantis |\n| KubeSolo | ✅ | ✅ | ✅ | ✅ | Single-node Kubernetes |\n| Minikube | ✅ | ✅ | ✅ | ✅ | Local Kubernetes for development |\n| Talos | ✅ | ✅ | ✅ | ✅ | Secure, immutable Kubernetes OS |\n| MicroK8s | ✅ | ✅ | ✅ | ✅ | Lightweight Kubernetes by Canonical |\n\nCompatibility tests run weekly and on-demand. See [Distro Compatibility Tests](docs/DISTRO-COMPATIBILITY.md) for details.\n\n**OpenShift** is also confirmed to work by community users. Set `openshift.enabled=true` in Helm values to create the required SecurityContextConstraints. See [DEPLOYMENT.md](docs/DEPLOYMENT.md#openshift) for details.\n\n## Prerequisites\n\n- Kubernetes 1.27+ (earlier versions may work but are not tested)\n- A running NASty server with API access\n- For NFS: NFS client utilities on all nodes (`nfs-common` on Debian/Ubuntu, `nfs-utils` on RHEL/CentOS)\n- For NVMe-oF:\n  - `nvme-cli` package installed on all Kubernetes nodes\n  - Kernel modules: `nvme-tcp`, `nvme-fabrics`\n  - Network connectivity from Kubernetes nodes to NASty on port 4420\n- For iSCSI:\n  - `open-iscsi` package installed on all Kubernetes nodes (`iscsid` service running)\n  - Network connectivity from Kubernetes nodes to NASty on port 3260\n- For SMB:\n  - `cifs-utils` package installed on all Kubernetes nodes\n  - Kubernetes Secret with SMB credentials (username/password)\n  - Network connectivity from Kubernetes nodes to NASty on port 445\n\n## Quick Start\n\nSee [DEPLOYMENT.md](docs/DEPLOYMENT.md) for detailed installation and configuration instructions.\n\n### Installation via Helm (Recommended)\n\nThe NASty CSI Driver is published to both Docker Hub and GitHub Container Registry as OCI artifacts:\n\n**Always use a specific version in production.** See [docs/VERSIONING.md](docs/VERSIONING.md) for details.\n\n```bash\nhelm install nasty-csi oci://ghcr.io/nasty-project/charts/nasty-csi-driver \\\n  --version 0.0.4 \\\n  --namespace kube-system \\\n  --create-namespace \\\n  --set nasty.url=\"wss://YOUR-NASTY-IP/api/current\" \\\n  --set nasty.apiKey=\"YOUR-API-KEY\" \\\n  --set storageClasses[0].name=nasty-csi-nfs \\\n  --set storageClasses[0].enabled=true \\\n  --set storageClasses[0].protocol=nfs \\\n  --set storageClasses[0].filesystem=\"YOUR-FILESYSTEM\" \\\n  --set storageClasses[0].server=\"YOUR-NASTY-IP\"\n```\n\n**NVMe-oF:**\n```bash\nhelm install nasty-csi oci://ghcr.io/nasty-project/charts/nasty-csi-driver \\\n  --version 0.0.4 \\\n  --namespace kube-system \\\n  --create-namespace \\\n  --set nasty.url=\"wss://YOUR-NASTY-IP/api/current\" \\\n  --set nasty.apiKey=\"YOUR-API-KEY\" \\\n  --set storageClasses[0].name=nasty-csi-nvmeof \\\n  --set storageClasses[0].enabled=true \\\n  --set storageClasses[0].protocol=nvmeof \\\n  --set storageClasses[0].filesystem=\"YOUR-FILESYSTEM\" \\\n  --set storageClasses[0].server=\"YOUR-NASTY-IP\" \\\n  --set storageClasses[0].transport=tcp \\\n  --set storageClasses[0].port=4420\n```\n\n**iSCSI:**\n```bash\nhelm install nasty-csi oci://ghcr.io/nasty-project/charts/nasty-csi-driver \\\n  --version 0.0.4 \\\n  --namespace kube-system \\\n  --create-namespace \\\n  --set nasty.url=\"wss://YOUR-NASTY-IP/api/current\" \\\n  --set nasty.apiKey=\"YOUR-API-KEY\" \\\n  --set storageClasses[0].name=nasty-csi-iscsi \\\n  --set storageClasses[0].enabled=true \\\n  --set storageClasses[0].protocol=iscsi \\\n  --set storageClasses[0].filesystem=\"YOUR-FILESYSTEM\" \\\n  --set storageClasses[0].server=\"YOUR-NASTY-IP\"\n```\n\n**SMB:**\n```bash\nhelm install nasty-csi oci://ghcr.io/nasty-project/charts/nasty-csi-driver \\\n  --version 0.0.4 \\\n  --namespace kube-system \\\n  --create-namespace \\\n  --set nasty.url=\"wss://YOUR-NASTY-IP/api/current\" \\\n  --set nasty.apiKey=\"YOUR-API-KEY\" \\\n  --set storageClasses[0].name=nasty-csi-smb \\\n  --set storageClasses[0].enabled=true \\\n  --set storageClasses[0].protocol=smb \\\n  --set storageClasses[0].filesystem=\"YOUR-FILESYSTEM\" \\\n  --set storageClasses[0].server=\"YOUR-NASTY-IP\" \\\n  --set storageClasses[0].smbCredentialsSecret.name=smb-credentials \\\n  --set storageClasses[0].smbCredentialsSecret.namespace=kube-system\n```\n\nSee the [Helm chart repository](https://github.com/nasty-project/nasty-chart) for detailed configuration options.\n\n## Configuration\n\n### Command-Line Flags\n\n- `--endpoint` - CSI endpoint (default: `unix:///var/lib/kubelet/plugins/nasty.csi.io/csi.sock`)\n- `--node-id` - Node identifier (typically the node name)\n- `--driver-name` - CSI driver name (default: `nasty.csi.io`)\n- `--api-url` - NASty API WebSocket URL (e.g., `wss://YOUR-NASTY-IP/api/current`)\n- `--api-key` - NASty API key\n- `--max-concurrent-nvme-connects` - Maximum concurrent NVMe-oF connect operations per node (default: `5`)\n\n### Storage Class Parameters\n\n**NFS Volumes:**\n```yaml\nparameters:\n  protocol: nfs\n  server: YOUR-NASTY-IP\n  filesystem: YOUR-FILESYSTEM\n```\n\n**NVMe-oF Volumes:**\n```yaml\nparameters:\n  protocol: nvmeof\n  server: YOUR-NASTY-IP\n  filesystem: YOUR-FILESYSTEM\n  fsType: ext4  # or xfs\n```\n\n**Optional parameters** (all protocols):\n\n| Parameter | Description |\n|-----------|-------------|\n| `compression` | Compression algorithm (`lz4`, `zstd`, `none`) |\n| `foregroundTarget` | Device group label for foreground writes |\n| `backgroundTarget` | Device group label for background moves |\n| `promoteTarget` | Device group label for read promotion (cache tier) |\n| `metadataTarget` | Device group label for metadata/btree writes |\n| `dataReplicas` | Number of data replicas (e.g., `\"1\"` for expendable data) |\n| `deleteStrategy` | `delete` (default) or `retain` |\n| `encryption` | `true` to require encrypted filesystem |\n| `markAdoptable` | `true` to allow cross-cluster volume adoption |\n\n## Testing\n\nThis driver is tested against a **real NASty server** with actual bcachefs storage — not mocks or simulators:\n\n- **QEMU VMs on GitHub-hosted runners** provision a fresh k3s cluster per test run\n- **Real NASty server** with bcachefs pools, NFS/SMB shares, NVMe-oF subsystems, and iSCSI targets\n- **Full protocol stack** — actual NFS mounts, NVMe-oF TCP connections, iSCSI sessions, and SMB shares\n\n### Automated Test Suite\n\nEvery commit triggers integration tests across all four protocols:\n\n**Core Functionality:**\n- Volume provisioning, deletion, and expansion\n- Snapshot creation, restoration, and cloning\n- Volume adoption for disaster recovery and GitOps workflows\n- StatefulSet volume management\n- Data persistence across pod restarts\n\n**Stress \u0026 Reliability:**\n- Concurrent volume creation\n- WebSocket connection resilience\n- Orphaned resource detection and cleanup\n\n**CSI Specification Compliance:**\n- [kubernetes-csi/csi-test](https://github.com/kubernetes-csi/csi-test) v5.4.0 sanity suite\n\n## Project Status\n\n**⚠️ This project is in early development and is not production-ready.**\n\nCore features (provisioning, snapshots, expansion, adoption) are functional and tested across all four protocols. Use in development and evaluation environments. Production deployments should proceed with caution — edge cases may exist.\n\n## Troubleshooting\n\nSee [DEPLOYMENT.md](docs/DEPLOYMENT.md#troubleshooting) for detailed troubleshooting steps.\n\n**Common Issues:**\n\n1. **Pods stuck in ContainerCreating**:\n   - For NFS: Check that NFS client utilities are installed on nodes\n   - For NVMe-oF: Check that nvme-cli is installed and kernel modules are loaded (`nvme-tcp`, `nvme-fabrics`)\n   - For SMB: Check that cifs-utils is installed and credentials Secret exists\n2. **Failed to create volume**: Verify NASty API credentials and network connectivity\n3. **Mount failed**: Ensure the corresponding service is running on NASty and the port is reachable\n\n**View Logs:**\n\n```bash\n# Controller logs\nkubectl logs -n kube-system -l app.kubernetes.io/name=nasty-csi-driver,app.kubernetes.io/component=controller\n\n# Node logs\nkubectl logs -n kube-system -l app.kubernetes.io/name=nasty-csi-driver,app.kubernetes.io/component=node\n\n# Check version\nkubectl logs -n kube-system deployment/nasty-csi-controller 2\u003e\u00261 | head -1\n```\n\n## Documentation\n\n- [Features Documentation](docs/FEATURES.md) - Comprehensive feature support reference\n- [Deployment Guide](docs/DEPLOYMENT.md) - Detailed installation and configuration\n- [kubectl Plugin](https://github.com/nasty-project/nasty-plugin) - Command-line tool for volume management\n- [Quick Start - NFS](docs/QUICKSTART.md) - Get started with NFS volumes\n- [Quick Start - NVMe-oF](docs/QUICKSTART-NVMEOF.md) - Get started with NVMe-oF volumes\n- [Quick Start - iSCSI](docs/QUICKSTART-ISCSI.md) - Get started with iSCSI volumes\n- [Quick Start - SMB](docs/QUICKSTART-SMB.md) - Get started with SMB volumes\n- [Snapshots Guide](docs/SNAPSHOTS.md) - Volume snapshots and cloning\n- [Versioning](docs/VERSIONING.md) - Version management and checking installed version\n- [Distro Compatibility](docs/DISTRO-COMPATIBILITY.md) - Kubernetes distribution compatibility testing\n- [Metrics Guide](docs/METRICS.md) - Prometheus metrics and monitoring\n- [Kind Setup](docs/KIND.md) - Local development with Kind\n- [Comparison with Democratic-CSI](docs/COMPARISON-DEMOCRATIC-CSI.md) - vs democratic-csi\n\n## Volume Adoption\n\nThe driver supports **cross-cluster volume adoption** — importing existing nasty-csi managed volumes into a new Kubernetes cluster. This is useful for:\n- Disaster recovery scenarios\n- Cluster migrations\n- Re-importing retained volumes after upgrades\n\nVolumes are adoptable if they have proper `nasty-csi:*` xattr properties set. See [Volume Adoption](docs/FEATURES.md#volume-adoption-cross-cluster) in the Features documentation for details.\n\n## Development\n\n### Prerequisites\n\n- Go 1.26+\n- Docker (for building images)\n- Kubernetes cluster for testing\n\n### Building\n\n```bash\nmake build\n```\n\n### Testing\n\n```bash\n# Unit tests\nmake test\n\n# CSI sanity tests\nmake test-sanity\n\n# E2E tests (requires NASty server and Kubernetes cluster)\nginkgo -v --timeout=55m ./tests/e2e/nfs/...\nginkgo -v --timeout=90m ./tests/e2e/nvmeof/...\nginkgo -v --timeout=90m ./tests/e2e/iscsi/...\nginkgo -v --timeout=55m ./tests/e2e/smb/...\n```\n\nSee [docs/TESTING.md](docs/TESTING.md) for details.\n\n### Building Container Image\n\n```bash\nmake docker-build\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 (GPL-3.0) - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasty-project%2Fnasty-csi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnasty-project%2Fnasty-csi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasty-project%2Fnasty-csi/lists"}