Techcle Wiki

Requirements

5 min read

Requirements Document

Introduction

This specification addresses the integration of ZFS-backed persistent storage into the k8s-lab cluster. The Proxmox host running the cluster exposes a ZFS drive that provides better performance, reliability, and data management capabilities compared to the current local-path storage solution. This infrastructure will be available for any workload requiring persistent storage, with code-server being the initial consumer.

Glossary

  • ZFS: Zettabyte File System - an advanced file system with built-in volume management, snapshots, and data integrity features
  • Proxmox: Virtualization platform hosting the k8s-lab Kubernetes cluster
  • Local_Path_Provisioner: Current default storage provisioner using local node directories
  • CSI: Container Storage Interface - Kubernetes standard for storage plugins
  • CSI_Driver: Implementation of CSI specification for a specific storage backend
  • PV: PersistentVolume - Kubernetes storage resource
  • PVC: PersistentVolumeClaim - Request for storage by a pod
  • StorageClass: Kubernetes resource defining storage provisioner and parameters
  • Dynamic_Provisioning: Automatic PV creation when a PVC is created
  • Static_Provisioning: Manual PV creation before PVC binding

Requirements

Requirement 1: ZFS Storage Class Configuration

User Story: As a cluster administrator, I want a ZFS-backed storage class available in the cluster, so that workloads can request persistent storage backed by the Proxmox ZFS drive.

Acceptance Criteria

  1. WHEN the cluster is initialized, THE System SHALL create a StorageClass resource configured for ZFS storage
  2. WHEN a PVC references the ZFS storage class, THE System SHALL provision a volume from the Proxmox ZFS drive
  3. THE System SHALL support ReadWriteOnce (RWO) access mode allowing multiple pods on the same node to share the volume
  4. THE System SHALL use appropriate ZFS parameters for optimal performance (compression, recordsize, etc.)
  5. THE System SHALL configure the storage class with Retain reclaim policy to preserve data when PVCs are deleted

Requirement 2: Dynamic Volume Provisioning

User Story: As a workload developer, I want to request ZFS-backed storage by creating a PVC, so that volumes are automatically provisioned without manual intervention.

Acceptance Criteria

  1. WHEN a PVC is created with the ZFS storage class, THE System SHALL automatically provision a PV from the ZFS pool
  2. WHEN the PVC specifies a capacity, THE System SHALL create a volume with at least that capacity
  3. WHEN the PVC is deleted with Retain policy, THE System SHALL preserve the underlying ZFS volume for data recovery
  4. WHEN multiple PVCs are created, THE System SHALL provision independent volumes for each
  5. THE System SHALL support standard Kubernetes volume lifecycle operations (create, bind, release)

Requirement 3: Storage Performance and Reliability

User Story: As a developer using code-server, I want fast and reliable storage for my workspace, so that file operations are responsive and my data is protected.

Acceptance Criteria

  1. WHEN files are written to the workspace, THE System SHALL use ZFS compression to optimize storage efficiency
  2. WHEN the ZFS volume is configured, THE System SHALL enable appropriate ZFS features (checksums, compression)
  3. THE System SHALL provide at least equivalent or better I/O performance compared to local-path storage
  4. THE System SHALL ensure data persistence across pod restarts and node reboots
  5. THE System SHALL support standard filesystem operations (read, write, delete, rename) without errors

Requirement 4: GitOps Integration

User Story: As a cluster operator, I want the ZFS storage infrastructure integrated into the GitOps workflow, so that storage provisioning is automated and version-controlled.

Acceptance Criteria

  1. WHEN the k8s-lab cluster is bootstrapped, THE System SHALL automatically deploy the ZFS CSI driver
  2. WHEN the ZFS storage class is applied, THE System SHALL make it available for workloads to use
  3. THE System SHALL include ZFS storage configuration in the appropriate kustomization structure
  4. THE System SHALL document the ZFS storage setup and usage in component documentation
  5. WHEN the cluster is reset to a clean state, THE System SHALL be able to recreate the ZFS storage infrastructure

Requirement 5: Code-Server Shared Workspace Implementation

User Story: As a code-server user, I want both code-server and codev pods to access the same ZFS-backed workspace, so that I can use both development environments with shared files.

Acceptance Criteria

  1. WHEN the ZFS-backed PVC is created, THE System SHALL allow both code-server and codev pods to mount it simultaneously
  2. WHEN both pods are scheduled, THE System SHALL ensure they run on the same node (required for RWO volumes)
  3. WHEN files are written by either pod, THE System SHALL make them immediately visible to the other pod
  4. THE System SHALL configure the PVC with appropriate capacity (10Gi or larger) for development workspaces
  5. THE System SHALL verify both pods can read and write to the shared workspace without conflicts

Requirement 6: Storage Class Coexistence

User Story: As a cluster operator, I want both local-path and ZFS storage classes available, so that workloads can choose the appropriate storage backend for their needs.

Acceptance Criteria

  1. WHEN both storage classes exist, THE System SHALL allow workloads to specify which storage class to use
  2. THE System SHALL maintain local-path as the default storage class for backward compatibility
  3. WHEN a PVC explicitly requests ZFS storage, THE System SHALL provision from the ZFS pool
  4. THE System SHALL support workloads using different storage classes in the same namespace
  5. THE System SHALL clearly document when to use each storage class (performance, reliability, capacity considerations)

Graph View