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

3.6 KiB

Raw Blame History

Installation Guide

Installation Methods

Method 1: Headlamp Plugin Manager (Recommended)

The plugin is published on Artifact Hub.

Via Headlamp UI:

Navigate to Settings → Plugins → Catalog
Search for "TNS CSI" or "TrueNAS"
Click Install
Refresh the page

Via 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

Via FluxCD HelmRelease:

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: headlamp
  namespace: kube-system
spec:
  chart:
    spec:
      chart: headlamp
      sourceRef:
        kind: HelmRepository
        name: headlamp
  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

Method 2: Manual Tarball Install

Download and extract the plugin directly:

# Download the release tarball
wget https://github.com/privilegedescalation/headlamp-tns-csi-plugin/releases/download/v0.1.0/headlamp-tns-csi-plugin-0.1.0.tar.gz

# Verify the checksum
echo "14a3e8c13d0b894a41aa1cfccbcb1f6af09dcbb8fd95c7040a540987ea2096a7  headlamp-tns-csi-plugin-0.1.0.tar.gz" | sha256sum --check

# Extract into your Headlamp plugins directory
tar xzf headlamp-tns-csi-plugin-0.1.0.tar.gz -C /headlamp/plugins/

The plugin directory should appear as /headlamp/plugins/headlamp-tns-csi-plugin/.

Restart Headlamp (or the pod) after extracting.

Method 3: Sidecar Container

For Headlamp deployments where you prefer managing plugins as container init sidecars:

initContainers:
  - name: install-tns-csi-plugin
    image: alpine:3
    command:
      - sh
      - -c
      - |
        wget -O /tmp/plugin.tar.gz \
          https://github.com/privilegedescalation/headlamp-tns-csi-plugin/releases/download/v0.1.0/headlamp-tns-csi-plugin-0.1.0.tar.gz
        tar xzf /tmp/plugin.tar.gz -C /headlamp/plugins/
    volumeMounts:
      - name: plugins
        mountPath: /headlamp/plugins

Method 4: Build from Source

For development or to test unreleased changes:

git clone https://github.com/privilegedescalation/headlamp-tns-csi-plugin.git
cd headlamp-tns-csi-plugin
npm install
npm run build
npm run package
# Produces headlamp-tns-csi-plugin-0.1.0.tar.gz

# Extract to your Headlamp plugins directory
tar xzf headlamp-tns-csi-plugin-0.1.0.tar.gz -C /headlamp/plugins/

Or use headlamp-plugin extract for automatic placement:

npx @kinvolk/headlamp-plugin extract . /headlamp/plugins

Post-Installation

After installing the plugin:

Configure RBAC — see RBAC Permissions
Verify the plugin loads — refresh browser and look for "TrueNAS (tns-csi)" in the sidebar
Check the Overview page — driver health card should show tns-csi status

Upgrading

To upgrade to a new version, repeat the installation method you used. The new tarball replaces the old plugin directory.

For Plugin Manager installs, the catalog will show available updates.

Uninstalling

Remove the plugin directory from your Headlamp plugins directory:

rm -rf /headlamp/plugins/headlamp-tns-csi-plugin/

Or via the Headlamp UI: Settings → Plugins → headlamp-tns-csi-plugin → Uninstall.

3.6 KiB Raw Blame History