### Quick Install Agent

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Installs the agent using a curl script. This is the recommended method for a fast setup. It handles prerequisite installation, configuration, and service setup.

```bash
# The agent runs as a privileged Podman container with host networking -
# it listens on port 8080 and manages the host's NFS exports directly.
#
# Environment variables (defaults shown - adjust as needed):
# export AGENT_BASE_PATH=/export/data  # must be a btrfs filesystem
# export AGENT_TENANTS=default:$(openssl rand -hex 16)
# export AGENT_LISTEN_ADDR=:8080
# export AGENT_BLOCK_DISK=/dev/sdX  # optional, auto-format as btrfs + mount to AGENT_BASE_PATH 
# export VERSION=0.11.2
# export IMAGE=ghcr.io/erikmagkekse/btrfs-nfs-csi:0.11.2  # override full image ref
# export SKIP_PACKAGE_INSTALL=1

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

# Save the tenant token printed at the end!

```

--------------------------------

### Install btrfs-nfs-csi Agent

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/README.md

Installs the agent, Podman, NFS, btrfs-progs, enables quotas, and starts the agent as a Quadlet container. Save the tenant token printed at the end.

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

--------------------------------

### Install btrfs-nfs-csi Agent with Auto-Formatting Block Device

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/README.md

Installs the agent and auto-formats a specified block device as btrfs. This script also installs Podman, NFS, btrfs-progs, enables quotas, and starts the agent as a Quadlet container.

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

--------------------------------

### Manual Agent Configuration and Service Start

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Manually configure the agent's environment file and start the systemd service. This method is useful for non-NixOS systems or for direct control over the agent's configuration.

```bash
install -d -m 700 /etc/btrfs-nfs-csi
cat > /etc/btrfs-nfs-csi/agent.env <<EOF
AGENT_BASE_PATH=/export/data
AGENT_TENANTS=default:$(openssl rand -hex 16)
AGENT_LISTEN_ADDR=:8080
EOF
chmod 600 /etc/btrfs-nfs-csi/agent.env

systemctl daemon-reload  # Quadlet generator creates the service, autostart via [Install] WantedBy=multi-user.target
systemctl start btrfs-nfs-csi-agent

```

--------------------------------

### Install NFS Server

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Installs the NFS kernel server package on Debian/Ubuntu systems and enables the service to start on boot.

```bash
apt install nfs-kernel-server   # Debian/Ubuntu
systemctl enable --now nfs-server
```

--------------------------------

### Install Ansible and Hetzner Cloud Collection

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/setup-examples/ansible-examples/README.md

Installs the necessary Ansible collection and Python libraries for interacting with Hetzner Cloud.

```bash
pip install ansible hcloud
ansible-galaxy collection install hetzner.hcloud
```

--------------------------------

### Install btrfs-nfs-csi Helm Chart

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/charts/btrfs-nfs-csi/README.md

Installs the btrfs-nfs-csi Helm chart from a specified OCI registry. Ensure you have Helm v3.10+ and the necessary prerequisites.

```bash
helm install btrfs-nfs-csi oci://ghcr.io/erikmagkekse/charts/btrfs-nfs-csi \
  -n btrfs-nfs-csi --create-namespace \
  -f values.yaml
```

--------------------------------

### Deploy CSI Driver with Static Manifests

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/README.md

Deploy the btrfs-nfs-csi driver using static Kubernetes manifests. Apply the setup YAML, then download, edit, and apply the storageclass.yaml.

```bash
kubectl apply -f https://raw.githubusercontent.com/erikmagkekse/btrfs-nfs-csi/main/deploy/driver/setup.yaml
# Download storageclass.yaml, edit it: set nfsServer, agentURL, agentToken
# Each StorageClass binds one agent + one tenant (via agentToken secret).
curl -LO https://raw.githubusercontent.com/erikmagkekse/btrfs-nfs-csi/main/deploy/driver/storageclass.yaml
# edit storageclass.yaml
kubectl apply -f storageclass.yaml
```

--------------------------------

### Copy Agent Binary and Systemd Service

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Copies the compiled agent binary to the system's executable path and downloads the systemd service file for manual setup.

```bash
cp btrfs-nfs-csi /usr/local/bin/
chmod +x /usr/local/bin/btrfs-nfs-csi
curl -Lo /etc/systemd/system/btrfs-nfs-csi-agent.service \
  https://raw.githubusercontent.com/erikmagkekse/btrfs-nfs-csi/main/deploy/agent/agent.service
```

--------------------------------

### Install btrfs-progs

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Installs the btrfs-progs package on Debian/Ubuntu systems. This is a prerequisite for managing btrfs filesystems.

```bash
apt install btrfs-progs   # Debian/Ubuntu
```

--------------------------------

### Deploy CSI Driver with Helm

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/README.md

Install the btrfs-nfs-csi driver using Helm. Configure storage classes, NFS server details, and agent connection information in values.yaml.

```yaml
storageClasses:
  - name: btrfs-nfs
    nfsServer: "10.0.0.5"             # your agent's IP
    agentURL: "http://10.0.0.5:8080"
    agentToken: "your-tenant-token"   # from agent install
    isDefault: true
```

```bash
cat > values.yaml <<EOF
storageClasses:
  - name: btrfs-nfs
    nfsServer: "10.0.0.5"             # your agent's IP
    agentURL: "http://10.0.0.5:8080"
    agentToken: "your-tenant-token"   # from agent install
    isDefault: true
EOF

helm install btrfs-nfs-csi oci://ghcr.io/erikmagkekse/charts/btrfs-nfs-csi \
  -n btrfs-nfs-csi --create-namespace -f values.yaml
```

--------------------------------

### Minimal values.yaml Configuration

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/charts/btrfs-nfs-csi/README.md

Configures a single storage class with basic NFS server and agent details. This is a starting point for most deployments.

```yaml
storageClasses:
  - name: btrfs-nfs
    nfsServer: "10.0.0.5"
    agentURL: "http://10.0.0.5:8080"
    existingSecret: "btrfs-nfs-creds"
    isDefault: true
```

--------------------------------

### Get Volume Details

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Retrieves and displays detailed information about a specific volume.

```bash
btrfs-nfs-csi volume get my-vol
```

--------------------------------

### Get Vendor Hash for Nix Build

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/release.md

Command to build the project with Nix to obtain the current vendor hash. This is used when go.mod or go.sum have changed since the last release.

```bash
# Build with nix to get the new hash (it will fail and print the expected hash)
nix build .# 2>&1 | grep 'got:' | awk '{print $2}'
# Update package.nix with the new hash
```

--------------------------------

### Example of AGENT_TENANTS with Bcrypt Hash

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/rbac.md

When using bcrypt hashes for tokens, ensure the value is single-quoted to prevent shell interpretation of special characters like '$'.

```bash
AGENT_TENANTS='ops:$2y$12$...:admin'
```

--------------------------------

### Get task details

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Retrieves detailed information about a specific task using its ID.

```bash
btrfs-nfs-csi task get <id>
```

--------------------------------

### Start Btrfs Quota Rescan Task

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Rebuilds qgroup accounting from scratch. This is useful for resolving inconsistencies in quota tracking. This operation is not supported for simple quotas (squota).

```bash
btrfs-nfs-csi task create quota-rescan -W

```

--------------------------------

### NixOS Flake Configuration for Btrfs NFS CSI

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Example NixOS flake configuration to integrate the btrfs-nfs-csi module. Ensure to specify the agent configuration options within your system's modules.

```nix
{ 
  inputs = {
    ... 
    btrfs-nfs-csi.url = "github:erikmagkekse/btrfs-nfs-csi";
  };

  outputs = { 
    nixpkgs,
    ...,
    btrfs-nfs-csi
  }: {
    nixosConfigurations."demo" = nixpkgs.lib.nixosSystem { 
      system = "x86_64-linux";
      modules = [
        btrfs-nfs-csi.nixosModules.btrfs-nfs-csi
        {
          services.btrfs-nfs-csi.agent.example = {
            basePath = "/export/data";
            listenAddr = ":8080";
            metricsAddr = "127.0.0.1:9090";

            environmentFile = ./envfile.env;
          };
        }
      ];
    };
  };
}

```

--------------------------------

### User Labels via Annotations

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/configuration.md

Example of how to set user-defined labels for a PersistentVolumeClaim (PVC) using annotations. These labels are applied directly to the PVC and override any default labels.

```yaml
annotations:
  btrfs-nfs-csi/labels: "env=prod,team=backend"
```

--------------------------------

### Start Btrfs Scrub Task

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Initiates a scrub task to verify data integrity. Use the --readonly flag for an audit-only scan without repairs. The --ioprio-class flag can be used to set the IO priority for the scrub operation.

```bash
btrfs-nfs-csi task create scrub -W                  # start and wait

```

```bash
btrfs-nfs-csi task create scrub --readonly -W       # audit only, no repair attempt

```

```bash
btrfs-nfs-csi task create scrub --ioprio-class=3 -W # idle IO priority (good for scheduled scrubs)

```

--------------------------------

### Create and Export a Volume using Go Client

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/README.md

Demonstrates creating a volume with specific settings and then creating an NFS export for it using the Go client library.

```go
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",
})
```

--------------------------------

### Build and Push Local Image, Deploy with Custom Image

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/setup-examples/ansible-examples/README.md

Builds a local container image, pushes it to a registry, and then deploys the btrfs-nfs-csi using the custom image for both the agent and the CSI driver.

```bash
# Build and push your dev image
podman build -t ghcr.io/youruser/btrfs-nfs-csi:edge .
podman push ghcr.io/youruser/btrfs-nfs-csi:edge

# Deploy with custom image for both agent and driver
ansible-playbook simple.yaml \
  -e agent_image=ghcr.io/erikmagkekse/btrfs-nfs-csi:edge \
  -e driver_image=ghcr.io/erikmagkekse/btrfs-nfs-csi:edge
```

--------------------------------

### Set Hetzner Cloud Token and Run Playbook

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/setup-examples/ansible-examples/README.md

Sets the Hetzner Cloud API token as an environment variable and then executes the main deployment playbook.

```bash
export HCLOUD_TOKEN="your-token-here"
ansible-playbook simple.yaml
```

--------------------------------

### Create and Mount btrfs Filesystem

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Formats a block device as btrfs, creates a mount point, and mounts the filesystem. It also enables quotas, which are recommended for managing storage.

```bash
# Find your disk
lsblk -f

mkfs.btrfs /dev/sdX
mkdir -p /export/data
mount /dev/sdX /export/data
# simple quotas (squota), recommended, requires kernel 6.7+ and btrfs-progs 6.7+
btrfs quota enable -s /export/data

# classic quotas, fallback for older kernels
# btrfs quota enable /export/data
```

--------------------------------

### Volume Lifecycle API Calls and Mount Commands

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/architecture.md

Illustrates the sequence of API calls and shell commands for managing the volume lifecycle, from creation to deletion.

```bash
CreateVolume   --> POST /v1/volumes
Publish        --> POST /v1/volumes/:name/export
NodeStage      --> mount -t nfs server:path staging
NodePublish    --> mount --bind staging/data target
NodeUnpublish  --> umount target
NodeUnstage    --> umount staging
Unpublish      --> DELETE /v1/volumes/:name/export
DeleteVolume   --> DELETE /v1/volumes/:name
```

--------------------------------

### List all snapshots

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists all available snapshots.

```bash
btrfs-nfs-csi snapshot list
```

--------------------------------

### List all tasks

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists all background tasks managed by the system.

```bash
btrfs-nfs-csi task list
```

--------------------------------

### Watch system statistics live

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Enables live-refresh mode to monitor system statistics in real-time.

```bash
btrfs-nfs-csi stats -w
```

--------------------------------

### Kubernetes Secret for Agent Credentials

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/configuration.md

Example of a Kubernetes Secret manifest used to store credentials for the agent token. Ensure the agentToken value matches the AGENT_TENANTS token.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: btrfs-nfs-creds
  namespace: btrfs-nfs-csi
type: Opaque
stringData:
  agentToken: "changeme"  # must match AGENT_TENANTS token
```

--------------------------------

### List Volumes with Environment Variables

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists all volumes. This command falls back to using environment variables (AGENT_URL, AGENT_TOKEN) if no agent is saved.

```bash
# When no agent is saved, fall back to env vars:
export AGENT_URL=http://10.0.0.5:8080
export AGENT_TOKEN=changeme
export AGENT_CSI_IDENTITY=cli              # optional, default: cli

btrfs-nfs-csi volume list
```

--------------------------------

### Configure Kubelet Directory for NixOS

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/README.md

When using NixOS, the kubelet root directory differs. Set `kubeletDir` in Helm values or via `--set` to ensure correct hostPath volume mounting.

```yaml
kubeletDir: /var/lib/kubernetes
```

```bash
helm install btrfs-nfs-csi --set kubeletDir=/var/lib/kubernetes ...
```

--------------------------------

### Delete CLI-created volumes matching a pattern

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

This pipeline deletes all volumes whose names start with 'test-'. It first lists all volumes, filters them by name, and then pipes the names to the delete command.

```bash
btrfs-nfs-csi volume ls -c name | grep '^test-' | xargs btrfs-nfs-csi volume delete
```

--------------------------------

### List all exports

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists all configured NFS exports.

```bash
btrfs-nfs-csi export list
```

--------------------------------

### Manage Btrfs NFS CSI Volumes and Snapshots

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/README.md

Common CLI commands for creating, listing volumes, and creating snapshots.

```bash
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
```

--------------------------------

### CI Pipeline Configuration (Go, Containerfile, VERSION)

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/release.md

Defines the CI workflow for Go code, Containerfile, and VERSION changes. Includes stages for linting, testing, integration, sanity, e2e, and building.

```yaml
ci.yml (Go code, Containerfile, VERSION changes)
  lint         format check + golangci-lint
  test         go test -race ./... (needs: lint)
  integration  btrfs + NFS integration tests (needs: lint, parallel with test)
  sanity       CSI sanity tests (planned, not yet implemented)
  e2e          end-to-end tests (planned, not yet implemented)
  build        container image build check, no push (needs: test + integration)
```

--------------------------------

### Create a snapshot with a label

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Creates a new snapshot for a given volume and assigns a label to it.

```bash
btrfs-nfs-csi snapshot create my-vol snap-1 --label env=prod
```

--------------------------------

### Create Volume with Labels

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Creates a new volume and assigns labels for metadata or filtering purposes.

```bash
btrfs-nfs-csi volume create my-vol 10Gi --label env=prod --label team=backend
```

--------------------------------

### Build Agent from Source

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Compiles the btrfs-nfs-csi agent from source code using Go. This command produces a static binary suitable for deployment.

```bash
CGO_ENABLED=0 go build -o btrfs-nfs-csi ./cmd/btrfs-nfs-csi
```

--------------------------------

### Download Podman Quadlet Container File

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Downloads the agent's Podman Quadlet container definition file to the system's container configuration directory.

```bash
curl -Lo /etc/containers/systemd/btrfs-nfs-csi-agent.container \
  https://raw.githubusercontent.com/erikmagkekse/btrfs-nfs-csi/main/deploy/agent/btrfs-nfs-csi-agent.container
```

--------------------------------

### Create Volume with Compression

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Creates a new volume with a specified size and compression algorithm (e.g., zstd).

```bash
btrfs-nfs-csi volume create my-vol 10Gi --compression zstd
```

--------------------------------

### Create btrfs-nfs-csi Volume with Compression

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Create a new volume with specified compression algorithm and optional level.

```bash
btrfs-nfs-csi volume create logs 5Gi --compression zstd
```

--------------------------------

### Configure Compression and NoCOW via Annotations

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/operations.md

Applies Btrfs compression and NoCOW settings to a volume using annotations. These annotations override StorageClass defaults.

```yaml
annotations:
  btrfs-nfs-csi/compression: "zstd"
  btrfs-nfs-csi/nocow: "true"
```

--------------------------------

### Verify Deployment with kubectl

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/setup-examples/ansible-examples/README.md

Sets the KUBECONFIG environment variable and then uses kubectl to check the status of nodes and storage classes.

```bash
export KUBECONFIG=/tmp/btrfs-nfs-csi-tmp/rke2-kubeconfig
kubectl get nodes
kubectl get sc
```

--------------------------------

### List Volumes in JSON Format

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists volumes and formats the output as JSON.

```bash
btrfs-nfs-csi volume ls -o json
```

--------------------------------

### Create and wait for scrub task completion

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Initiates a scrub task and waits for it to complete before returning.

```bash
btrfs-nfs-csi task create scrub -W
```

--------------------------------

### Watch tasks live

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Enables live-refresh mode to monitor task status in real-time.

```bash
btrfs-nfs-csi task ls -w
```

--------------------------------

### Manage btrfs-nfs-csi Snapshots

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Commands for creating, listing, and cloning read-only btrfs snapshots.

```bash
btrfs-nfs-csi snapshot create my-app before-deploy
btrfs-nfs-csi snapshot list
btrfs-nfs-csi snapshot clone before-deploy my-app-restored
```

--------------------------------

### CLI Commands for Token Information

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/rbac.md

Use these CLI commands to retrieve information about your current token or list all configured tokens for your tenant. The `-o wide` flag shows the full fingerprint, while `-o json` provides the raw API response.

```bash
btrfs-nfs-csi whoami
btrfs-nfs-csi tokens
```

--------------------------------

### Display version information

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Shows the current version of the btrfs-nfs-csi CLI.

```bash
btrfs-nfs-csi version
```

--------------------------------

### View detailed system statistics

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Displays extended system statistics, including per-device IO and error details.

```bash
btrfs-nfs-csi stats -o wide
```

--------------------------------

### Tagging a Stable Release

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/release.md

Commands to create and push a Git tag for a stable release from the 'main' branch.

```bash
git tag v0.11.2
git push origin v0.11.2
```

--------------------------------

### Perform Routine Balance

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Consolidates sparsely-filled data and metadata chunks. This is useful for routine maintenance and reclaiming space.

```bash
btrfs-nfs-csi task create balance --dusage=75 --musage=30 -W
```

--------------------------------

### Configure UID, GID, and Mode via Annotations

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/operations.md

Sets the user ID, group ID, and file mode for a volume using annotations. These are applied at creation and updated on attach if annotations change.

```yaml
annotations:
  btrfs-nfs-csi/uid: "1000"
  btrfs-nfs-csi/gid: "1000"
  btrfs-nfs-csi/mode: "0750"
```

--------------------------------

### Tagging an Edge Pre-release

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/release.md

Commands to create and push a Git tag for an edge pre-release from the 'edge' branch.

```bash
git tag v0.11.2-edge
git push origin v0.11.2-edge
```

--------------------------------

### Clone a snapshot to a new volume with a label

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Clones an existing snapshot to create a new volume, applying a specified label.

```bash
btrfs-nfs-csi snapshot clone snap-1 new-vol --label env=dev
```

--------------------------------

### Create a scrub task

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Initiates a scrub task to check for data integrity.

```bash
btrfs-nfs-csi task create scrub
```

--------------------------------

### Level 2 RBAC Configuration with Multiple Roles

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/rbac.md

Sets up multiple tokens within a single tenant, each assigned a specific role (admin, user, mounter, readonly) to restrict endpoint access. This allows for differentiated duties within a tenant.

```bash
AGENT_TENANTS=ops:tok-ops:admin,ci:tok-ci:user,dash:tok-dash:readonly,node1:tok-n1:mounter
```

--------------------------------

### Watch Volumes with Default Refresh

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Continuously lists volumes, refreshing the output every 2 seconds. Use Ctrl+C to exit.

```bash
btrfs-nfs-csi volume ls -w
```

--------------------------------

### View system statistics

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Displays general system statistics.

```bash
btrfs-nfs-csi stats
```

--------------------------------

### Create btrfs-nfs-csi Volume with NoCOW

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Create a new volume with the NoCOW attribute enabled, suitable for databases and VM images.

```bash
btrfs-nfs-csi volume create postgres-data 50Gi --nocow
```

--------------------------------

### List labels for a snapshot

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Displays all labels associated with a given snapshot.

```bash
btrfs-nfs-csi snapshot label list snap-1
```

--------------------------------

### List Selected Volume Columns

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists volumes and displays only the specified columns (e.g., name and size).

```bash
btrfs-nfs-csi volume ls -c name,size
```

--------------------------------

### Agent Base Directory Structure

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/architecture.md

Illustrates the directory layout on the storage host managed by the agent, including metadata, tasks, and tenant-specific volume/snapshot data.

```text
{AGENT_BASE_PATH}/
├── metadata/
│   ├── root_secret         <-- per-installation crypto root (mode 0600)
│   └── root_secret.bak     <-- replica, primary/backup mismatch aborts startup
├── tasks/
│   └── {id}.json           <-- persisted task state
└── {tenant}/
    ├── {volume}/
    │   ├── data/           <-- btrfs subvolume
    │   └── metadata.json
    ├── snapshots/{name}/
    │   ├── data/           <-- read-only btrfs snapshot
    │   └── metadata.json
    └── {clone}/
        ├── data/           <-- writable btrfs snapshot
        └── metadata.json
```

--------------------------------

### CI Pipeline Configuration (Helm Charts)

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/release.md

Defines the CI workflow for changes in the charts directory. Includes linting and templating stages for Helm charts.

```yaml
ci-helm.yml (charts/** changes)
  lint         helm lint + helm template
```

--------------------------------

### Configure fsGroup via SecurityContext

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/operations.md

Sets the fsGroup in the pod's security context. This is handled by kubelet, which applies recursive chown and setgid after bind mounting.

```yaml
spec:
  securityContext:
    fsGroup: 1000
```

--------------------------------

### Build Btrfs NFS CSI Binary

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/README.md

Builds the btrfs-nfs-csi binary, embedding version and commit information.

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

--------------------------------

### Verify All Saved Agents

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Verifies the credentials and connectivity for all saved agents.

```bash
btrfs-nfs-csi agents verify --all
```

--------------------------------

### Release Pipeline Configuration

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/release.md

Defines the release workflow triggered on tag creation. Includes stages for version validation, container image building, and Helm chart packaging/publishing.

```yaml
release.yml (on tag v*)
  check    version validation + bump verification
  build    container image (needs: check)
  helm     chart package + push (needs: check + build)
```

--------------------------------

### Multiple Agents Configuration

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/charts/btrfs-nfs-csi/README.md

Sets up multiple storage classes, each pointing to a different NFS server and agent. Useful for high availability or segmented storage.

```yaml
storageClasses:
  - name: btrfs-nfs
    nfsServer: "10.0.0.5"
    agentURL: "http://10.0.0.5:8080"
    existingSecret: "agent-1-creds"
    isDefault: true

  - name: btrfs-nfs-backup
    nfsServer: "10.0.0.6"
    agentURL: "http://10.0.0.6:8080"
    existingSecret: "agent-2-creds"
    reclaimPolicy: Retain
```

--------------------------------

### Generating a bcrypt Token Hash

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/rbac.md

Use the bundled CLI tool to generate a bcrypt hash for a token. The `--cost` flag controls the computational complexity of the hash. The token itself is not echoed to the console for security; it can be piped via stdin.

```bash
btrfs-nfs-csi hash-token --cost 12
# Token: ********           (no echo, or pipe via stdin)
```

--------------------------------

### Watch Volumes with Custom Interval

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Continuously lists volumes, refreshing the output with a custom interval (e.g., 500 milliseconds).

```bash
btrfs-nfs-csi volume ls -w 500ms
```

--------------------------------

### Verify CSI Driver Controller Logs

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/README.md

Check the logs of the btrfs-nfs-csi-controller pod to confirm a successful agent connection. Look for the 'agent healthy' message.

```bash
kubectl logs -n btrfs-nfs-csi deploy/btrfs-nfs-csi-controller -c csi-driver
```

```text
INF agent healthy - vibes immaculate, bits aligned, absolutely bussin sc=btrfs-nfs version=0.11.2
```

--------------------------------

### Add btrfs Mount to fstab

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Configures the system to automatically mount the btrfs filesystem on boot by adding an entry to `/etc/fstab`. Uses UUID for stable device identification.

```bash
UUID=$(blkid -s UUID -o value /dev/sdX)
echo "UUID=$UUID  /export/data  btrfs  defaults  0  0" >> /etc/fstab
```

--------------------------------

### List Volume Labels

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Displays all labels associated with a specific volume.

```bash
btrfs-nfs-csi volume label list my-vol
```

--------------------------------

### PromQL: Alert for missing devices

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/metrics.md

This query checks for devices that are not present. A value of 0 indicates a missing device, which can be used for alerting.

```promql
# Missing device alert
btrfs_nfs_csi_agent_device_present == 0
```

--------------------------------

### List snapshots with a specific label

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Filters and lists snapshots that have a specific label, such as 'env=prod'.

```bash
btrfs-nfs-csi snapshot ls -l env=prod
```

--------------------------------

### Filter Volumes by Label

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists volumes that match a specific label.

```bash
btrfs-nfs-csi volume ls -l env=prod
```

--------------------------------

### Login and List Saved CLI Agents

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/RELEASE.md

Log in to an agent endpoint, list available agents, and set an active agent for subsequent CLI commands. The token is piped from stdin to avoid shell history exposure.

```bash
echo "$TOKEN" | btrfs-nfs-csi agents login prod --url https://agent.example.com:8080
btrfs-nfs-csi agents ls
btrfs-nfs-csi agents use prod
btrfs-nfs-csi volume list
btrfs-nfs-csi agents verify --all
```

--------------------------------

### List Volumes with Wide Output

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists volumes with extended information. Use `-o wide` for a more detailed view.

```bash
btrfs-nfs-csi volume ls -o wide
```

--------------------------------

### Expand PersistentVolumeClaim

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/operations.md

Online volume expansion by increasing the requested storage in the PersistentVolumeClaim. Requires `allowVolumeExpansion: true` in the StorageClass.

```yaml
# Just increase storage in the PVC
resources:
  requests:
    storage: 20Gi  # was 10Gi
```

--------------------------------

### Configuring AGENT_TENANTS with Hashed Tokens

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/rbac.md

The AGENT_TENANTS environment variable can accept either plaintext tokens or bcrypt password hashes. The agent identifies hashes by the '$2a$', '$2b$', or '$2y$' prefix. Plaintext is used for backward compatibility if no such prefix is found.

```bash
AGENT_TENANTS=ops:$2y$12$KIXp.../iZ8eqwjN12iKy:admin,ci:plain-tok:user:ci-bot
```

--------------------------------

### Set Volume Compression

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Changes the compression algorithm for an existing volume.

```bash
btrfs-nfs-csi volume set my-vol --compression zstd
```

--------------------------------

### Manage btrfs-nfs-csi NFS Exports

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Commands for adding, listing, and removing NFS export configurations.

```bash
btrfs-nfs-csi export add my-app 10.0.1.1
btrfs-nfs-csi export list
btrfs-nfs-csi export remove my-app 10.0.1.1
```

--------------------------------

### Dedicated Storage Network Configuration

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/charts/btrfs-nfs-csi/README.md

Configures the driver to use a specific network interface or CIDR for storage traffic. Requires `hostNetwork` to be enabled.

```yaml
driver:
  storageInterface: "eth1"    # or storageCIDR: "10.10.0.0/24"
```

--------------------------------

### Clone btrfs-nfs-csi Snapshot

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Create a writable clone from a read-only snapshot, optionally with labels.

```bash
btrfs-nfs-csi snapshot clone before-deploy my-app-restored --label env=dev
```

--------------------------------

### Expand Volume by Relative Amount

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Expands an existing volume by a relative amount (e.g., adding 5Gi to its current size).

```bash
btrfs-nfs-csi volume expand my-vol +5Gi
```

--------------------------------

### Login to Saved Agent

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Logs in to a saved agent endpoint, verifying the provided token and persisting it to the configuration file. Subsequent commands will use this agent configuration.

```bash
echo "$TOKEN" | btrfs-nfs-csi agents login prod --url https://agent.example.com:8080
```

--------------------------------

### List Volume Names (Pipeable)

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists only the names of the volumes, without a header, suitable for piping to other commands.

```bash
btrfs-nfs-csi volume ls -c name
```

--------------------------------

### Expand Volume to Absolute Size

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Expands an existing volume to a new, absolute target size.

```bash
btrfs-nfs-csi volume expand my-vol 20Gi
```

--------------------------------

### Clone Volume

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Creates a clone of an existing volume, optionally assigning labels to the new clone.

```bash
btrfs-nfs-csi volume clone source-vol new-vol --label env=staging
```

--------------------------------

### Create Volume Snapshot

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/operations.md

Defines a VolumeSnapshot resource to create a snapshot of a PersistentVolumeClaim.

```yaml
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: my-snap
spec:
  volumeSnapshotClassName: btrfs-nfs
  source:
    persistentVolumeClaimName: my-pvc
```

--------------------------------

### List Saved Agents

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists all saved agents. Use `-o wide` for a wider view or `-o json` for JSON output.

```bash
btrfs-nfs-csi agents ls
```

--------------------------------

### Cleanup Deployment

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/setup-examples/ansible-examples/README.md

Runs the Ansible playbook with the 'absent' state to remove the deployed resources.

```bash
ansible-playbook simple.yaml -e state=absent
```

--------------------------------

### Filter Volumes by Multiple Labels

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Lists volumes that match all specified labels (comma-separated implies AND).

```bash
btrfs-nfs-csi volume ls -l env=prod,team=be
```

--------------------------------

### List tasks created by a specific entity

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Filters and lists tasks based on who or what created them, e.g., 'cron'.

```bash
btrfs-nfs-csi task ls -l created-by=cron
```

--------------------------------

### Log into Btrfs NFS CSI Agent

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/README.md

Logs into a btrfs-nfs-csi agent, saving the endpoint configuration. The token can be entered at a prompt or piped in.

```bash
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
```

--------------------------------

### P99 NFS Mount Latency PromQL Query

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/metrics.md

Calculates the 99th percentile latency for NFS mount operations over a 5-minute window. This helps in understanding the worst-case performance of NFS mounts.

```promql
histogram_quantile(0.99, rate(btrfs_nfs_csi_node_mount_duration_seconds_bucket{operation="nfs_mount"}[5m]))
```

--------------------------------

### Level 1 RBAC Configuration

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/rbac.md

Configures a single tenant with a secret token, granting administrative access to all endpoints within that tenant's scope. Suitable for single-tenant or homelab environments.

```bash
AGENT_TENANTS=default:s3cret
```

--------------------------------

### Level 3 RBAC Configuration with Identities

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/rbac.md

Configures tokens with specific identities, enabling per-identity ownership of resources. The agent enforces that only the creating identity can modify resources, enhancing security within a tenant.

```bash
AGENT_TENANTS=ci:tok-ci:user:ci-bot,ops:tok-ops:admin:ansible,node1:tok-n1:mounter:node-1
```

--------------------------------

### Uninstall Agent

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/installation.md

Removes the agent's configuration and service files. This process keeps your data intact.

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

--------------------------------

### NFS Mount Failures PromQL Query

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/integrations/kubernetes/metrics.md

Calculates the rate of NFS mount operations that failed over a 5-minute window. This is useful for identifying issues with mounting NFS volumes.

```promql
rate(btrfs_nfs_csi_node_mount_ops_total{operation="nfs_mount",status="error"}[5m])
```

--------------------------------

### List snapshots for a specific volume

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Filters and lists snapshots associated with a particular volume.

```bash
btrfs-nfs-csi snapshot ls my-vol
```

--------------------------------

### PromQL: High device allocation

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/metrics.md

This query identifies devices where the allocated space exceeds 90% of the total device size. It helps in proactively managing storage.

```promql
# Device allocation > 90%
btrfs_nfs_csi_agent_device_allocated_bytes / btrfs_nfs_csi_agent_device_size_bytes > 0.9
```

--------------------------------

### PromQL: Task queue depth

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/metrics.md

This query calculates the total number of tasks currently queued and waiting for a worker slot. It's useful for understanding potential bottlenecks.

```promql
# Task queue depth (tasks waiting for a worker slot)
sum(btrfs_nfs_csi_agent_tasks_queued)
```

--------------------------------

### PromQL: 403 HTTP errors by reason

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/metrics.md

This query aggregates and counts 403 Forbidden HTTP requests over the last 5 minutes, grouped by the denial reason. It's crucial for monitoring RBAC-related access issues.

```promql
# 403s grouped by denial reason (RBAC visibility)
sum by (reason) (rate(btrfs_nfs_csi_agent_http_requests_total{code="403"}[5m]))
```

--------------------------------

### Create a no-op smoke test task

Source: https://github.com/erikmagkekse/btrfs-nfs-csi/blob/main/docs/operations.md

Creates a no-operation task with a specified sleep duration, useful for testing task plumbing. It waits for completion.

```bash
btrfs-nfs-csi task create test --sleep 10s -W
```