docs: create new doc for rawfile overview and storageclass

docs/main/quickstart-guide/installation.md

@@ -52,7 +52,7 @@ Verify helm is installed and helm repo is updated. You need helm 3.2 or more.
     helm install openebs --namespace openebs openebs/openebs --create-namespace
     ```
 
-    The above command will install OpenEBS Local PV Hostpath, OpenEBS Local PV LVM, OpenEBS Local PV ZFS, and OpenEBS Replicated Storage components in `openebs` namespace and chart name as `openebs`.
+    The above command will install OpenEBS Local PV Hostpath, OpenEBS Local PV LVM, OpenEBS Local PV ZFS, and OpenEBS Replicated Storage components in `openebs` namespace and chart name as `openebs`. OpenEBS Local PV Rawfile is not installed by default.
 
     :::important
     - The default OpenEBS helm chart will install both Local Storage and Replicated Storage. If you do not want to install OpenEBS Replicated Storage, use the following command:
@@ -61,6 +61,12 @@ Verify helm is installed and helm repo is updated. You need helm 3.2 or more.
       helm install openebs --namespace openebs openebs/openebs --set engines.replicated.mayastor.enabled=false --create-namespace
       ```
 
+    - OpenEBS Local PV Rawfile is disabled by default. To enable it during installation, use the following command:
+
+      ```
+      helm install openebs --namespace openebs openebs/openebs --set engines.local.rawfile.enabled=true --create-namespace
+      ```
+
     - If the CustomResourceDefinitions for CSI VolumeSnapshots are already present in your cluster, you may skip their creation by using the following option:
 
       ```

docs/main/user-guides/local-storage-user-guide/local-pv-rawfile/configuration/rawfile-create-storageclass.md

@@ -0,0 +1,172 @@
+---
+id: rawfile-create-storageclass
+title: Create StorageClass(s)
+keywords:
+ - OpenEBS Local PV Rawfile
+ - Local PV Rawfile
+ - Configuration
+ - Create StorageClass
+ - Create Local PV Rawfile StorageClass(s)
+description: This guide will help you to create Local PV Rawfile StorageClass.
+---
+
+# Create StorageClass(s)
+
+This document provides step-by-step instructions on creating a StorageClass for Local PV Rawfile, with examples covering different filesystem types, thin provisioning, and volume binding modes.
+
+The provisioner name for Local PV Rawfile is `rawfile.csi.openebs.io`. This must be set in every StorageClass so that provisioning requests are handled by the Rawfile driver.
+
+## Default StorageClass (ext4)
+
+The following is a basic StorageClass that provisions volumes formatted with ext4, which is the default filesystem:
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: rawfile-ext4
+provisioner: rawfile.csi.openebs.io
+volumeBindingMode: WaitForFirstConsumer
+allowVolumeExpansion: true
+parameters:
+  fsType: "ext4"
+```
+
+## StorageClass with XFS
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: rawfile-xfs
+provisioner: rawfile.csi.openebs.io
+volumeBindingMode: WaitForFirstConsumer
+allowVolumeExpansion: true
+parameters:
+  fsType: "xfs"
+```
+
+## StorageClass with Btrfs
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: rawfile-btrfs
+provisioner: rawfile.csi.openebs.io
+volumeBindingMode: WaitForFirstConsumer
+allowVolumeExpansion: true
+parameters:
+  fsType: "btrfs"
+```
+
+## StorageClass with Thin Provisioning
+
+Thin provisioning creates sparse backing files, meaning disk space is allocated on demand rather than upfront. When using thin provisioning, you must set `formatOptions` to disable block discard, otherwise the filesystem may reclaim space in a way that conflicts with the sparse file.
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: rawfile-thin
+provisioner: rawfile.csi.openebs.io
+volumeBindingMode: WaitForFirstConsumer
+allowVolumeExpansion: true
+parameters:
+  fsType: "ext4"
+  thinProvision: "true"
+  formatOptions: "-E nodiscard"
+```
+
+:::note
+For ext4 volumes, 5% of the capacity is reserved for the root user by default. To remove this reservation and make the full capacity available to applications, add `-m 0` to `formatOptions`:
+
+```yaml
+parameters:
+  fsType: "ext4"
+  formatOptions: "-m 0"
+```
+:::
+
+## StorageClass with Snapshots Enabled (Copy-on-Write)
+
+To enable block-level snapshots using copy-on-write (reflink), set `copyOnWrite` to `"true"`. The underlying filesystem must support reflinks (btrfs supports this natively; ext4 requires a reflink-capable filesystem).
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: rawfile-cow-snapshots
+provisioner: rawfile.csi.openebs.io
+volumeBindingMode: WaitForFirstConsumer
+allowVolumeExpansion: true
+parameters:
+  fsType: "btrfs"
+  copyOnWrite: "true"
+```
+
+## StorageClass with FreezeFS for In-Use Snapshots
+
+For volumes that need to be snapshotted while in use and where CoW is not available, enable `freezeFs`. This briefly freezes the filesystem during snapshot creation to ensure consistency.
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: rawfile-freezefs
+provisioner: rawfile.csi.openebs.io
+volumeBindingMode: WaitForFirstConsumer
+allowVolumeExpansion: true
+parameters:
+  fsType: "ext4"
+  freezeFs: "true"
+```
+
+## StorageClass Targeting a Specific Storage Pool
+
+If multiple storage pools are configured on the nodes, use the `storagePool` parameter to pin volumes to a named pool:
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: rawfile-fast-pool
+provisioner: rawfile.csi.openebs.io
+volumeBindingMode: WaitForFirstConsumer
+allowVolumeExpansion: true
+parameters:
+  fsType: "ext4"
+  storagePool: "fast-pool"
+```
+
+## StorageClass Parameters Conformance Matrix
+
+### Standard StorageClass Parameters
+
+| Parameter | Values |
+|---|---|
+| `allowVolumeExpansion` | `true` / `false` |
+| `volumeBindingMode` | `Immediate` / `WaitForFirstConsumer` |
+| `reclaimPolicy` | `Retain` / `Delete` |
+
+### Rawfile-Specific StorageClass Parameters
+
+| Parameter | Values | Description |
+|---|---|---|
+| `fsType` | `ext4` (default), `xfs`, `btrfs` | Filesystem used to format the volume |
+| `thinProvision` | `"true"` / `""` | Creates a sparse backing file instead of pre-allocating disk space |
+| `copyOnWrite` | `"true"` / `""` / `"false"` | Enables CoW reflink snapshots; leave empty to autodetect |
+| `freezeFs` | `"true"` / `""` | Freezes the filesystem during snapshot for in-use volume consistency |
+| `formatOptions` | Filesystem format flags (e.g. `-m 0`, `-E nodiscard`) | Passed to `mkfs` at volume creation time |
+| `mountOptions` | Mount flags (e.g. `noatime`) | Passed to `mount` when attaching the volume to a pod |
+| `storagePool` | Pool name string | Targets a specific named storage pool on the node |
+
+## Support
+
+If you encounter issues or have a question, file a [Github issue](https://github.com/openebs/openebs/issues/new), or talk to us on the [#openebs channel on the Kubernetes Slack server](https://kubernetes.slack.com/messages/openebs/).
+
+## See Also
+
+- [Installation](../../../../quickstart-guide/installation.md)
+- [StorageClass Parameters](rawfile-storageclass-parameters.md)
+- [Create PVC](rawfile-create-pvc.md)

docs/main/user-guides/local-storage-user-guide/local-pv-rawfile/rawfile-overview.md

@@ -0,0 +1,40 @@
+---
+id: rawfile-overview
+title: Local PV Rawfile Overview
+keywords:
+ - OpenEBS Local PV Rawfile
+ - Local PV Rawfile Overview
+ - Installation
+ - Prerequisites
+description: This section explains the overview of Local PV Rawfile.
+---
+
+OpenEBS Local PV Rawfile provisions persistent volumes backed by raw files on the host filesystem, exposed to pods as independent block devices via Linux loop devices. Each volume is a sparse or dense file formatted with its own filesystem (`ext4`, `btrfs`, or `xfs`), making it fully isolated from the host's filesystem. This approach delivers near-baremetal disk performance with hard-enforced capacity limits, real-time volume metrics, and per-volume filesystem customization addressing the core limitations of HostPath-based provisioning.
+
+## How It Works
+
+When a PVC is created, the driver allocates a raw file on the node's storage pool directory and attaches it to a Linux loop device. That loop device is then formatted with the requested filesystem and mounted into the pod. Since each volume is an independent block device, the operating system enforces size limits natively and usage metrics are available in O(1) via `df`.
+
+## Installation
+
+Refer to the [OpenEBS Installation documentation](../../../quickstart-guide/installation.md) to install Local PV Rawfile.
+
+## Advantages
+
+- Near-baremetal disk performance – Direct I/O via loop devices with near-zero overhead.
+- Hard-enforced volume size limits – Capacity is enforced by the OS, not just advisory quotas.
+- Real-time volume usage metrics – Per-volume disk usage readable in O(1) via `df`, with Prometheus metrics exposed per pool and node.
+- Per-volume filesystem customization – Each volume can use a different filesystem (ext4, btrfs, xfs) with independent format and mount options.
+- Dynamic provisioning – Volumes are created on demand without manual pre-allocation.
+- Volume snapshots and cloning – Block-level copy-on-write snapshots and same-node volume cloning.
+- Online volume expansion – Expand volumes without downtime on supported filesystems (ext4, btrfs, xfs).
+- Multiple storage pools per node – Independent pool configuration with reserved capacity management.
+
+## Support
+
+If you encounter issues or have a question, file a [Github issue](https://github.com/openebs/openebs/issues/new), or talk to us on the [#openebs channel on the Kubernetes Slack server](https://kubernetes.slack.com/messages/openebs/).
+
+## See Also
+
+- [Installation](../../../quickstart-guide/installation.md)
+- [Deploy an Application](../../../quickstart-guide/deploy-a-test-application.md)

docs/sidebars.ts

@@ -421,6 +421,39 @@ const sidebars: SidebarsConfig =
                 },
               ] 
             },   
+            {
+              collapsed: true,
+              type: "category",
+              label: "Local PV Rawfile",
+              customProps: {
+                icon: "Book"
+              },
+              items: [
+                {
+                  type: "doc",
+                  id: "user-guides/local-storage-user-guide/local-pv-rawfile/rawfile-overview",
+                  label: "Overview",
+                  key: "Rawfile_Overview",
+                },
+                {
+                  collapsed: true,
+                  type: "category",
+                  label: "Configuration",
+                  key: "Rawfile_Configuration",
+                  customProps: {
+                    icon: "Settings"
+                  },
+                  items: [
+                    {
+                      type: "doc",
+                      id: "user-guides/local-storage-user-guide/local-pv-rawfile/configuration/rawfile-create-storageclass",
+                      label: "Create StorageClass(s)",
+                      key: "rawfile-create-storageclass",
+                    },
+                  ]
+                },
+              ]
+            },
             {
               collapsed: true,
               type: "category",