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,79 @@
|
||||
# Benchmark Page
|
||||
|
||||
The Benchmark page provides an interactive storage benchmark runner using [kbench](https://github.com/longhorn/kbench) (the Longhorn storage benchmark tool based on FIO).
|
||||
|
||||
## What It Does
|
||||
|
||||
1. You select a tns-csi StorageClass, a namespace, a PVC capacity, and an access mode
|
||||
2. The plugin creates a PVC and a Kubernetes Job that runs `yasker/kbench:latest`
|
||||
3. FIO log output streams in real-time from the kbench pod
|
||||
4. When complete, results are parsed and displayed as IOPS, bandwidth (MB/s), and latency (µs) cards
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- RBAC permissions for Jobs and PVCs — see [RBAC Permissions](rbac.md)
|
||||
- The target namespace must exist
|
||||
- The selected StorageClass must support the chosen access mode
|
||||
|
||||
## Running a Benchmark
|
||||
|
||||
1. Navigate to **TrueNAS (tns-csi) → Benchmark**
|
||||
2. Select a StorageClass from the dropdown (only tns-csi classes are listed)
|
||||
3. Enter the target namespace (defaults to `default`)
|
||||
4. Set PVC capacity (e.g., `10Gi`)
|
||||
5. Choose access mode (`ReadWriteOnce`, `ReadWriteMany`, etc.)
|
||||
6. Click **Run Benchmark**
|
||||
|
||||
The benchmark progress shows:
|
||||
- Benchmark state (Starting, Running, Parsing Results, Complete, Failed)
|
||||
- Live FIO log output as it streams from the pod
|
||||
- Result cards once FIO completes
|
||||
|
||||
## Result Cards
|
||||
|
||||
When the benchmark completes, the plugin displays:
|
||||
|
||||
| Card | Metric |
|
||||
| ---- | ------ |
|
||||
| Read IOPS | Random 4K read I/O operations per second |
|
||||
| Write IOPS | Random 4K write I/O operations per second |
|
||||
| Read Bandwidth | Sequential read throughput (MB/s) |
|
||||
| Write Bandwidth | Sequential write throughput (MB/s) |
|
||||
| Read Latency | Average read latency (µs) |
|
||||
| Write Latency | Average write latency (µs) |
|
||||
|
||||
## Stopping a Benchmark
|
||||
|
||||
Click **Stop** to cancel the running benchmark. The plugin will delete the Job and PVC.
|
||||
|
||||
If the page is closed or navigated away from during a benchmark, the Job and PVC will remain in the cluster with the label:
|
||||
|
||||
```
|
||||
app.kubernetes.io/managed-by=headlamp-tns-csi-plugin
|
||||
```
|
||||
|
||||
Clean them up manually:
|
||||
|
||||
```bash
|
||||
kubectl delete jobs,pvc -n <namespace> \
|
||||
-l app.kubernetes.io/managed-by=headlamp-tns-csi-plugin
|
||||
```
|
||||
|
||||
## Resource Cleanup
|
||||
|
||||
The plugin automatically deletes the benchmark Job and PVC when:
|
||||
- The benchmark completes successfully
|
||||
- You click Stop
|
||||
- The page component unmounts
|
||||
|
||||
## Protocol Notes
|
||||
|
||||
Different protocols have different performance characteristics:
|
||||
|
||||
| Protocol | Typical Use Case | Access Modes |
|
||||
| -------- | ---------------- | ------------ |
|
||||
| NFS | Shared storage, RWX workloads | RWO, RWX, RWOP |
|
||||
| NVMe-oF | High-performance block storage | RWO, RWOP |
|
||||
| iSCSI | Block storage | RWO, RWOP |
|
||||
|
||||
For NVMe-oF benchmarks, ensure nodes have the `nvme-tcp` kernel module loaded and the controller has a static IP.
|
||||
@@ -0,0 +1,121 @@
|
||||
# RBAC Permissions
|
||||
|
||||
## Overview
|
||||
|
||||
The plugin requires different permissions depending on which features you use. Start with the read-only set and add the benchmark write permissions only if needed.
|
||||
|
||||
## Read-Only Permissions (All Pages Except Benchmark)
|
||||
|
||||
```yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRole
|
||||
metadata:
|
||||
name: headlamp-tns-csi-reader
|
||||
rules:
|
||||
# StorageClasses and CSIDriver
|
||||
- apiGroups: ["storage.k8s.io"]
|
||||
resources: ["storageclasses", "csidrivers"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
|
||||
# PersistentVolumes (cluster-scoped)
|
||||
- apiGroups: [""]
|
||||
resources: ["persistentvolumes"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
|
||||
# PersistentVolumeClaims (all namespaces)
|
||||
- apiGroups: [""]
|
||||
resources: ["persistentvolumeclaims"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
|
||||
# tns-csi driver pods and their logs/proxy (for metrics)
|
||||
- apiGroups: [""]
|
||||
resources: ["pods"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
- apiGroups: [""]
|
||||
resources: ["pods/log", "pods/proxy"]
|
||||
verbs: ["get"]
|
||||
|
||||
# VolumeSnapshots (optional — gracefully degraded if absent)
|
||||
- apiGroups: ["snapshot.storage.k8s.io"]
|
||||
resources: ["volumesnapshots", "volumesnapshotclasses"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRoleBinding
|
||||
metadata:
|
||||
name: headlamp-tns-csi
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: headlamp # adjust to your Headlamp service account name
|
||||
namespace: kube-system # adjust to your Headlamp namespace
|
||||
roleRef:
|
||||
kind: ClusterRole
|
||||
name: headlamp-tns-csi-reader
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
```
|
||||
|
||||
## Additional Permissions for Benchmark Page
|
||||
|
||||
The Benchmark page creates and deletes a Job and PVC. These rules can be added to the ClusterRole above, or bound as a separate namespaced Role scoped to a dedicated benchmark namespace.
|
||||
|
||||
```yaml
|
||||
# Benchmark: create/delete kbench Job
|
||||
- apiGroups: ["batch"]
|
||||
resources: ["jobs"]
|
||||
verbs: ["get", "list", "watch", "create", "delete"]
|
||||
|
||||
# Benchmark: create/delete kbench PVC
|
||||
- apiGroups: [""]
|
||||
resources: ["persistentvolumeclaims"]
|
||||
verbs: ["get", "list", "watch", "create", "delete"]
|
||||
```
|
||||
|
||||
## Scoping Benchmark Permissions to a Namespace
|
||||
|
||||
For tighter security, restrict benchmark write permissions to a dedicated namespace using a Role + RoleBinding instead of ClusterRole:
|
||||
|
||||
```yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: headlamp-tns-csi-benchmark
|
||||
namespace: storage-benchmarks # dedicated benchmark namespace
|
||||
rules:
|
||||
- apiGroups: ["batch"]
|
||||
resources: ["jobs"]
|
||||
verbs: ["get", "list", "watch", "create", "delete"]
|
||||
- apiGroups: [""]
|
||||
resources: ["persistentvolumeclaims"]
|
||||
verbs: ["get", "list", "watch", "create", "delete"]
|
||||
- apiGroups: [""]
|
||||
resources: ["pods", "pods/log"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: RoleBinding
|
||||
metadata:
|
||||
name: headlamp-tns-csi-benchmark
|
||||
namespace: storage-benchmarks
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: headlamp
|
||||
namespace: kube-system
|
||||
roleRef:
|
||||
kind: Role
|
||||
name: headlamp-tns-csi-benchmark
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
```
|
||||
|
||||
With this configuration, benchmark jobs can only be created in the `storage-benchmarks` namespace.
|
||||
|
||||
## Permission Summary by Feature
|
||||
|
||||
| Feature | Permissions Required |
|
||||
| ------- | -------------------- |
|
||||
| Overview | `storageclasses list`, `persistentvolumes list`, `persistentvolumeclaims list`, `pods list` (kube-system), `csidrivers get` |
|
||||
| Storage Classes | `storageclasses list` |
|
||||
| Volumes | `persistentvolumes list` |
|
||||
| Snapshots | `volumesnapshots list`, `volumesnapshotclasses list` |
|
||||
| Metrics | `pods/proxy get` (kube-system controller pod) |
|
||||
| Benchmark | `jobs create/delete`, `persistentvolumeclaims create/delete` |
|
||||
| PVC Detail Injection | `persistentvolumeclaims get`, `persistentvolumes get` |
|
||||
Reference in New Issue
Block a user