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>
This commit is contained in:
@@ -0,0 +1,135 @@
|
||||
# Installation Guide
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Method 1: Headlamp Plugin Manager (Recommended)
|
||||
|
||||
The plugin is published on [Artifact Hub](https://artifacthub.io/packages/headlamp/headlamp-tns-csi-plugin/headlamp-tns-csi-plugin).
|
||||
|
||||
**Via Headlamp UI:**
|
||||
|
||||
1. Navigate to **Settings → Plugins → Catalog**
|
||||
2. Search for "TNS CSI" or "TrueNAS"
|
||||
3. Click **Install**
|
||||
4. Refresh the page
|
||||
|
||||
**Via Helm values:**
|
||||
|
||||
```yaml
|
||||
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:**
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
npx @kinvolk/headlamp-plugin extract . /headlamp/plugins
|
||||
```
|
||||
|
||||
## Post-Installation
|
||||
|
||||
After installing the plugin:
|
||||
|
||||
1. **Configure RBAC** — see [RBAC Permissions](../user-guide/rbac.md)
|
||||
2. **Verify the plugin loads** — refresh browser and look for "TrueNAS (tns-csi)" in the sidebar
|
||||
3. **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:
|
||||
|
||||
```bash
|
||||
rm -rf /headlamp/plugins/headlamp-tns-csi-plugin/
|
||||
```
|
||||
|
||||
Or via the Headlamp UI: **Settings → Plugins → headlamp-tns-csi-plugin → Uninstall**.
|
||||
@@ -0,0 +1,99 @@
|
||||
# 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)
|
||||
|
||||
1. Open Headlamp and navigate to **Settings → Plugins → Catalog**
|
||||
2. Search for **"TNS CSI"** or **"TrueNAS"**
|
||||
3. Click **Install**
|
||||
4. Refresh the browser
|
||||
|
||||
### Via Helm
|
||||
|
||||
Add the plugin source to your Headlamp Helm values:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
1. Open Headlamp — you should see **TrueNAS (tns-csi)** in the left sidebar
|
||||
2. Click **Overview** — you should see the driver health card and storage summary
|
||||
3. 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](../troubleshooting/README.md).
|
||||
Reference in New Issue
Block a user