privilegedescalation/headlamp-tns-csi-plugin

Files

T

Chris Farhood 72ce7fa585 docs: update install docs to headlamp namespace (PRI-434)

- Update Helm/plugin install URLs from v0.2.4 to v1.0.0
- README: add pods/proxy RBAC scope, clarify controller is in kube-system
- docs/getting-started/*: update all download URLs to v1.0.0
- docs/deployment/helm.md: update install URLs to v1.0.0
- docs/architecture/overview.md: Headlamp Pod label → headlamp namespace
- docs/README.md: fix ArtifactHub URL
- CHANGELOG.md: add [Unreleased] entry

Note: driver/API-path references to kube-system are preserved
as they describe where the tns-csi controller workload runs,
not where Headlamp is installed.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

2026-05-06 14:26:28 +00:00

2.7 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: tns-csi
      url: https://github.com/privilegedescalation/headlamp-tns-csi-plugin/releases/download/v1.0.0/tns-csi-1.0.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.7 KiB Raw Blame History