btrfs-nfs-csi

Turn any Linux box with a btrfs disk into a very capable storage backend. Instant snapshots, writable clones, per-volume quotas, compression, NoCOW (no copy-on-write) for databases, and automatic NFS exports. All from a single Go binary and a REST API.

Successor: Active development moves to a hard fork named ButterStore, which reframes the project around what it has actually become: a general-purpose btrfs storage backend where the Kubernetes CSI driver is one of several integrations. Migration is a drop-in: tokens, REST API, CLI, Helm values, StorageClasses, PVCs, and VolumeSnapshots all keep working. A migration guide ships with the first ButterStore release. Once ButterStore ships, this repo gets archived. Published artifacts (container images, Helm charts) stay available.

The name plays on the colloquial pronunciation of btrfs as "butter-FS" plus its role as a storage backend.

Why btrfs-nfs-csi?

Most storage solutions are built for the data center. Ceph, Longhorn, and OpenEBS bring clustering overhead that doesn't make sense when you have one server (or two for HA) and a btrfs filesystem.

• Minimal footprint. Single Go binary, multiple integrations, runs on minimal hardware.
• Zero infrastructure. No etcd, no database, no distributed consensus.
• Leverages btrfs. Subvolumes become volumes, snapshots stay snapshots, qgroups enforce quotas.
• Data integrity. btrfs checksums every block, scrub detects silent corruption.
• NFS just works. ReadWriteMany out of the box, not a special case.
• Multi-tenant. One agent serves multiple teams or clusters, token-isolated.
• Homelab HA. Optional active/passive failover with DRBD + Pacemaker.

btrfs-nfs-csi is not a distributed storage system. If you need data replication across many nodes, look at Longhorn or Ceph. If you have one server with good disks and want storage that stays out of your way, this is it.

Know your filesystem. btrfs is powerful but has trade-offs. RAID 5/6 is not production-ready. Quotas (qgroups) add overhead on write-heavy workloads, use simple quotas (btrfs quota enable -s, kernel 6.7+) to reduce it. CoW causes fragmentation over time (use NoCOW for databases). Regular scrubs are recommended to catch silent corruption early. None of these are deal-breakers, but you should be aware of them.

Your Classic Kubernetes Storage Options

* If you don't care about redundancy and security, you can install the agent directly on your single master node and your workers can use it. This also gives you a migration path if you later want to move the agent to a dedicated Linux box.

This comparison represents my personal point of view. No offense intended to any of these great projects. Improvements are welcome.

Features

Storage

• Instant snapshots & writable clones. btrfs copy-on-write, zero-copy.
• Online volume expansion. Absolute or relative (+5Gi).
• Per-volume quotas. Enforced at the filesystem level via btrfs qgroups.
• Compression. zstd, lzo, zlib with levels, configurable per volume.
• NoCOW mode. chattr +C for databases (PostgreSQL, MySQL, etcd).
• Multi-device. RAID 0/1/10 with per-device I/O stats and error tracking.

Networking

• Automatic NFS exports. Managed per volume, per client.
• ReadWriteMany. The default access mode, not a special case.
• Dedicated storage network. Select NIC by name or subnet CIDR.

Operations

• Labels. On volumes, snapshots, clones, exports, and tasks.
• Multi-tenant. Token-isolated tenants, one agent serves many consumers.
• RBAC. Four roles (readonly, mounter, user, admin) and optional per-token identity. created-by ownership scopes mutations to the creator within a tenant. See rbac.md.
• Background tasks. Scrub, progress tracking, configurable timeouts.
• Prometheus metrics. On all components.
• TLS & Swagger. API with OpenAPI spec.
• HA. DRBD + Pacemaker active/passive failover.

CLI

• Saved agents. agents login once.
• Watch mode (-w). Auto-refreshing output for any list/get command.
• Column filter (-c name,size,used). Show only what you need.
• Label filter (-l env=prod). Filter resources by label.
• Output formats. Table, wide, JSON.
• Relative resize. expand my-vol +5Gi.
• Identity switching. Switch between identities via AGENT_CSI_IDENTITY to view or manage resources created by other integrations. Names stay unique across identities.

Quick Start

1. Install the agent

One command on any Linux host with a btrfs filesystem (Debian, RHEL, Arch, SUSE):

curl -fsSL https://raw.githubusercontent.com/erikmagkekse/btrfs-nfs-csi/main/scripts/quickstart-agent.sh \
  | sudo -E bash

The script installs Podman, NFS, btrfs-progs, enables quotas, and starts the agent as a Quadlet container. Save the tenant token printed at the end. For advanced setups see the Installation docs.

To auto-format a block device as btrfs:

AGENT_BLOCK_DISK=/dev/sdb curl -fsSL \
  https://raw.githubusercontent.com/erikmagkekse/btrfs-nfs-csi/main/scripts/quickstart-agent.sh \
  | sudo -E bash

Environment variables

2. Use the CLI

Log into the agent once, the CLI saves the endpoint to ~/.btrfs-nfs-csi/config.json (file 0600) and uses it as the default for every subsequent command:

btrfs-nfs-csi agents login prod --url http://10.0.0.5:8080
# enter token at the no-echo prompt, or pipe it in (Docker-style):
# echo "$AGENT_TOKEN" | btrfs-nfs-csi agents login prod --url http://10.0.0.5:8080

btrfs-nfs-csi volume create my-app 10Gi
btrfs-nfs-csi volume list
btrfs-nfs-csi snapshot create my-app before-deploy
btrfs-nfs-csi stats

For one-off shells or CI, AGENT_URL and AGENT_TOKEN env vars (or --agent-url/--agent-token flags) still work and take precedence over the saved agent. See Operations: Saved Agents for agents ls/use/verify.

That's it. The agent manages btrfs subvolumes, NFS exports, and quotas. The CLI talks to the agent via REST API. Everything else (container orchestrator integrations, automation, custom tooling) builds on top.

See It in Action

Volumes

Create, expand, compress, and label volumes with per-volume quotas and NoCOW for databases.

Snapshots & Clones

Instant btrfs snapshots. Writable clones from snapshots or volumes, zero-copy and zero-wait.

NFS Exports

Add and remove NFS exports per volume, per client, directly from the CLI.

Stats & Health

Per-device I/O stats, error tracking, and filesystem scrubs, all from the CLI.

Or choose an Integration

The agent exposes a REST API. Any system that can make HTTP calls can manage volumes, snapshots, and exports. The CLI and all integrations use the same API.

API Example

The Go client makes it easy to build your own integrations:

import (
  "github.com/erikmagkekse/btrfs-nfs-csi/agent/api/v1/client"
  "github.com/erikmagkekse/btrfs-nfs-csi/agent/api/v1/models"
)

c, _ := client.NewClient("http://10.0.0.5:8080", "your-token", "my-app")

vol, _ := c.CreateVolume(ctx, models.VolumeCreateRequest{
  Name:        "my-volume",
  SizeBytes:   10 * 1024 * 1024 * 1024,
  Compression: "zstd",
  Labels:      map[string]string{"env": "prod"},
})

c.CreateVolumeExport(ctx, vol.Name, models.ExportCreateRequest{
  Client: "10.0.1.1",
})

Enable AGENT_API_SWAGGER_ENABLED=true and the agent serves the full spec at /swagger.json. Want to build an integration? We'd love a PR.

Roadmap

Planned for v1.0

• [ ] Stable API with no more breaking changes
• [ ] CSI sanity test suite
• [ ] End-to-end test suite
• [ ] Supply Chain protection (via capslock)
• [ ] Cosign Helm CHart & Container
• [ ] Grafana dashboards and Prometheus alerting rules

Under Consideration

• [ ] VolumeGroupSnapshot. Consistent multi-volume snapshots with fsfreeze via API and CLI, including Kubernetes CRD support.
• [ ] FUSE mount backend. Mount volumes via WebSocket or REST-FUSE through agent API and CLI, no kernel NFS required.
• [ ] mTLS. Mutual TLS authentication between agent, CLI, and integrations.
• [ ] Multi-agent manager. Central control plane for managing multiple agents across hosts.
• [ ] btrfs send/receive. Stream snapshots between agents via CLI and API.
• [ ] Replication. Scheduled, recurring send/receive to a second agent via task system.

Have an idea or want to build an integration? Open an issue or submit a PR.

Documentation

Handbook

Work in progress.

The handbook will cover real-world recipes, best practices, and operational guides. Stay tuned.

Building

go build -ldflags "-X main.version=$(cat VERSION) -X main.commit=$(git rev-parse --short HEAD)" \
  -o btrfs-nfs-csi ./cmd/btrfs-nfs-csi

Contributing

Contributions are herzlich willkommen! Whether it's a bug fix, a new integration, or improved docs, feel free to open an issue or submit a PR.

See docs/release.md for the release process and CI pipeline.