privilegedescalation/headlamp-tns-csi-plugin

Files

T

Chris Farhood f1feb5c2f7 feat: native Headlamp integration, TrueNAS API, docs, and CI for v0.2.0

Native Headlamp integrations:
- registerResourceTableColumnsProcessor: add Protocol/Pool/Server columns to
  native StorageClass table and Protocol/Volume Handle to PV table
- registerDetailsViewSection: inject TNS-CSI section into PV detail pages
- registerDetailsViewSection: inject driver role/status into tns-csi Pod pages
- registerDetailsViewHeaderAction: Benchmark shortcut on StorageClass detail
- registerAppBarAction: driver health badge (N/Nc M/Mn, color-coded)
- Trim sidebar from 6 → 4 entries (Overview, Snapshots, Metrics, Benchmark)

TrueNAS API integration:
- src/api/truenas.ts: ConfigStore-backed settings, WebSocket JSON-RPC client
  for pool.query (auth.login_with_api_key + pool.query)
- src/components/TnsCsiSettings.tsx: API key + server override settings UI
  with connection test button
- TnsCsiDataContext: fetch real pool stats (size/allocated/free/status)
- OverviewPage: three-tier pool capacity display (real data → error → metrics
  fallback)

Documentation:
- README, CHANGELOG, CONTRIBUTING, SECURITY
- docs/: architecture, deployment (Helm), getting-started, user-guide,
  troubleshooting

CI:
- .github/workflows/ci.yaml: lint + type-check + test on PR/push
- .github/workflows/release.yaml: workflow_dispatch versioned release

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

2026-02-18 16:37:56 -05:00

2.8 KiB

Raw Blame History

Quick Start

Get the TNS-CSI plugin running in Headlamp in about 5 minutes.

Prerequisites

Headlamp v0.20+ running in your cluster
tns-csi driver installed in kube-system
kubectl access to your cluster

Step 1: Install the Plugin

Via Headlamp UI (Easiest)

Open Headlamp and navigate to Settings → Plugins → Catalog
Search for "TNS CSI" or "TrueNAS"
Click Install
Refresh the browser

Via Helm

Add the plugin source to your Headlamp Helm values:

config:
  pluginsDir: /headlamp/plugins

pluginsManager:
  sources:
    - name: headlamp-tns-csi-plugin
      url: https://github.com/privilegedescalation/headlamp-tns-csi-plugin/releases/download/v0.1.0/headlamp-tns-csi-plugin-0.1.0.tar.gz

Then upgrade your Headlamp release:

helm upgrade headlamp headlamp/headlamp -f values.yaml -n kube-system

Step 2: Configure RBAC

The plugin needs read access to storage resources and the tns-csi controller pod's metrics endpoint.

Apply the minimal RBAC:

kubectl apply -f - <<'EOF'
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: headlamp-tns-csi-reader
rules:
  - apiGroups: [""]
    resources: ["persistentvolumes", "persistentvolumeclaims", "pods"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["storage.k8s.io"]
    resources: ["storageclasses", "csidrivers"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["snapshot.storage.k8s.io"]
    resources: ["volumesnapshots", "volumesnapshotclasses"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["pods/log", "pods/proxy"]
    verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: headlamp-tns-csi
subjects:
  - kind: ServiceAccount
    name: headlamp
    namespace: kube-system
roleRef:
  kind: ClusterRole
  name: headlamp-tns-csi-reader
  apiGroup: rbac.authorization.k8s.io
EOF

Adjust name: headlamp and namespace: kube-system to match your Headlamp service account.

Step 3: Verify

Open Headlamp — you should see TrueNAS (tns-csi) in the left sidebar
Click Overview — you should see the driver health card and storage summary
Click Storage Classes — your tns-csi StorageClasses should appear with Protocol, Pool, and Server filled in

Troubleshooting

Problem	Fix
No sidebar entry	Hard-refresh browser (Cmd+Shift+R)
Driver shows "Not installed"	Run `kubectl get csidriver tns.csi.io`
StorageClasses empty	Check `kubectl get sc` for `tns.csi.io` provisioner
Protocol/Pool/Server show "—"	Check `kubectl get sc <name> -o yaml` for `.parameters`
Metrics page empty	Verify controller pod exposes port 8080

For more detail see Troubleshooting.

2.8 KiB Raw Blame History