headlamp-tns-csi-plugin/docs/architecture/adr/002-read-only-benchmark-exception.md

ADR 002: Read-Only Plugin with Benchmark Exception

Status: Accepted

Date: 2026-03-05

Deciders: Development Team

---

Context

The plugin is primarily a read-only observability tool for TNS CSI storage. However, it includes a Benchmark feature that runs kbench (FIO-based storage benchmarks) against storage classes. Running benchmarks requires creating temporary Kubernetes resources: a PVC for the test volume and a Job running the kbench container.

These resources are tagged with app.kubernetes.io/managed-by=headlamp-tns-csi-plugin for lifecycle tracking. The benchmark workflow includes:

1. buildPvcManifest() — Create PVC spec for test volume
2. createPvc() — Create the PVC in the cluster
3. buildJobManifest() — Create Job spec for kbench container
4. createJob() — Create the Job in the cluster
5. Poll for Job completion
6. fetchKbenchLogs() — Retrieve benchmark output from pod logs
7. parseKbenchLog() — Parse FIO results from kbench output
8. deleteJob() — Clean up the benchmark Job
9. deletePvc() — Clean up the test PVC

---

Decision

The plugin is read-only for all storage observability features. The sole exception is the Benchmark feature, which creates and deletes temporary PVC + Job resources. All created resources are labeled for identification and cleaned up after benchmark completion. The benchmark is triggered explicitly by user action (button on StorageClass detail page via registerDetailsViewHeaderAction).

---

Consequences

• ✅ Minimal RBAC requirements for normal operation (read-only)
• ✅ Benchmark is opt-in and requires explicit user action
• ✅ Resources are auto-cleaned after benchmark completion
• ✅ managed-by label enables easy identification of plugin-created resources
• ⚠️ Requires additional RBAC permissions (create/delete Jobs and PVCs) for benchmark feature
• ⚠️ Failed cleanup leaves orphaned resources — mitigated by listKbenchJobs() which finds orphaned resources by label for manual cleanup

---

Alternatives Considered

1. No benchmark feature (fully read-only) — Rejected. Storage performance testing is a key use case for storage administrators evaluating CSI drivers.

2. External benchmark tool with results import — Rejected. Poor user experience requiring context-switching between tools.

3. Benchmark as a separate plugin — Rejected. Benchmark results are tied to storage class context and benefit from shared data in the plugin.

---

Changelog

Date	Change
2026-03-05	Initial decision