docs: add complete Local PV Rawfile documentation by balaharish7 · Pull Request #619 · openebs/website

balaharish7 · 2026-07-24T10:52:07Z

This PR adds full user facing documentation for the Local PV Rawfile storage engine in OpenEBS, following the same structure and style as existing storage docs (Hostpath, LVM, ZFS, Mayastor).

New Docs - Configuration (4 Docs)

Overview - Architecture, how loop devices work, DaemonSet/controller/Task Manager internals, advantages
Create StorageClass(s) - Examples for ext4, xfs, btrfs, thin provisioning, CoW, freezeFs, storage pool targeting, VolumeSnapshotClass, conformance matrix
StorageClass Parameters - Full per-parameter reference with YAML examples, notes, and warnings
Create PVC - Filesystem and block mode PVCs, pod consumption, deprovisioning, troubleshooting
Deploy an Application - Pod YAML using an existing rawfile PVC with verification steps

New Docs - Advanced Operations (7 Docs)

Storage Pools - Multi-pool Helm config, naming rules, reserved capacity modes (plain vs subtract-from-total), CoW-capable pools, per-tier StorageClasses
Snapshots - VolumeSnapshotClass creation, snapshot lifecycle, CoW vs freezeFs consistency, rollback pattern, cleanup order
Volume Restore (Cloning) - PVC clone, snapshot restore, clone vs snapshot comparison, consistency guarantees
Volume Resize - Online expansion, allowVolumeExpansion requirement, block mode expansion behavior
Monitoring - Full Prometheus metrics reference (node/pool/volume level), ServiceMonitor config, PromQL examples
Raw Block Volumes - Block mode PVC/pod setup, ignored parameters, use cases
Thin Provisioning - Thick vs thin comparison, sparse file behavior, overprovisioning, monitoring overcommit ratio

Updated Existing Docs

Installation - Added note that rawfile is disabled by default; added --set engines.local.rawfile.enabled=true install command
Prerequisites - Added Local PV Rawfile Prerequisites section (loop device support, filesystem tools, storage pool directory)
Upgrades - Added note that rawfile is a separate Helm release not covered by kubectl openebs upgrade, with separate helm upgrade command
Uninstallation - Added rawfile uninstall section with required pre-uninstall order (VolumeSnapshots → PVCs → PVs) to avoid leaked loop devices
Sidebars - Added full Local PV Rawfile navigation tree with Configuration and Advanced Operations categories

Note:
All content sourced from the rawfile-localpv develop branch docs

- Add 12 new docs: overview, configuration (Create StorageClass, StorageClass Parameters, Create PVC, Deploy an Application), and advanced operations (Storage Pools, Snapshots, Volume Restore, Volume Resize, Monitoring, Raw Block Volumes, Thin Provisioning) - Update installation, prerequisites, upgrades, and uninstallation docs with rawfile-specific instructions - Add rawfile navigation to sidebars.ts with Configuration and Advanced Operations categories Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Bala Harish A <bala.harish@datacore.com>

- Remove incorrect host-level prerequisites (losetup, filesystem tools are bundled in the driver container image) - Add CoW filesystem dependency note in overview with link to Storage Pools doc Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Bala Harish A <bala.harish@datacore.com>

tiagolobocastro · 2026-07-25T08:37:07Z

+Local PV Rawfile is disabled by default in the OpenEBS Helm chart. These prerequisites apply only if you intend to enable and use it.
+:::
+
+The Rawfile driver container image bundles all required tools (`losetup`, `mkfs.ext4`, `mkfs.xfs`, `mkfs.btrfs`) — no host-level installation of these tools is needed.


Should we mention the COW prerequisites on the host filesystem?

tiagolobocastro · 2026-07-25T08:40:28Z

+
+### CoW-Capable Pools (Recommended)
+
+Storage pools backed by btrfs or XFS with reflink produce space-efficient, nearly instant snapshots. No freeze is required.


I think ext4 also supports reflink, so maybe make reflink the major with examples, ie:

Suggested change

Storage pools backed by btrfs or XFS with reflink produce space-efficient, nearly instant snapshots. No freeze is required.

Storage pools backed by filesystems which support reflink (i.e. btrfs or XFS) produce space-efficient, nearly instant snapshots. No freeze is required.

tiagolobocastro · 2026-07-25T08:41:40Z

+
+### freezeFs
+
+For pools without CoW support (e.g. ext4), add `freezeFs: "true"` to the StorageClass. The filesystem is briefly frozen during the snapshot to ensure crash consistency:


Well, not really "briefly", the volume is frozen and then we copy the ENTIRE volume to a new file, and only then do we unfreeze

tiagolobocastro · 2026-07-25T08:42:34Z

+
+## Capacity Considerations
+
+- CoW-capable pools (btrfs, XFS reflink): snapshots consume only the changed blocks after the snapshot point.


Suggested change

- CoW-capable pools (btrfs, XFS reflink): snapshots consume only the changed blocks after the snapshot point.

- CoW-capable pools (filesystems with reflink enabled): snapshots consume only the changed blocks after the snapshot point.

tiagolobocastro · 2026-07-25T08:42:47Z

+## Capacity Considerations
+
+- CoW-capable pools (btrfs, XFS reflink): snapshots consume only the changed blocks after the snapshot point.
+- Non-CoW pools (ext4): each snapshot is a full copy of the volume and consumes the same amount of space as the original.


Suggested change

- Non-CoW pools (ext4): each snapshot is a full copy of the volume and consumes the same amount of space as the original.

- Non-CoW pools: each snapshot is a full copy of the volume and consumes the same amount of space as the original.

tiagolobocastro · 2026-07-25T08:57:30Z

+
+## 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/).


Suggested change

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/).

If you encounter issues or have a question, file a [Github issue](https://github.com/openebs/rawfile-localpv/issues/new), or talk to us on the [#openebs channel on the Kubernetes Slack server](https://kubernetes.slack.com/messages/openebs/).

tiagolobocastro · 2026-07-25T08:57:55Z

+
+## 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/).


Suggested change

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/).

If you encounter issues or have a question, file a [Github issue](https://github.com/openebs/rawfile-localpv/issues/new), or talk to us on the [#openebs channel on the Kubernetes Slack server](https://kubernetes.slack.com/messages/openebs/).

tiagolobocastro · 2026-07-25T08:58:10Z

+
+## 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/).


Suggested change

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/).

If you encounter issues or have a question, file a [Github issue](https://github.com/openebs/rawfile-localpv/issues/new), or talk to us on the [#openebs channel on the Kubernetes Slack server](https://kubernetes.slack.com/messages/openebs/).

tiagolobocastro · 2026-07-25T08:58:28Z

+
+## 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/).


Suggested change

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/).

If you encounter issues or have a question, file a [Github issue](https://github.com/openebs/rawfile-localpv/issues/new), or talk to us on the [#openebs channel on the Kubernetes Slack server](https://kubernetes.slack.com/messages/openebs/).

tiagolobocastro · 2026-07-25T08:58:39Z

+
+## 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/).


Suggested change

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/).

If you encounter issues or have a question, file a [Github issue](https://github.com/openebs/rawfile-localpv/issues/new), or talk to us on the [#openebs channel on the Kubernetes Slack server](https://kubernetes.slack.com/messages/openebs/).

balaharish7 requested review from Abhinandan-Purkait and tiagolobocastro July 24, 2026 10:52

balaharish7 requested a review from a team as a code owner July 24, 2026 10:52

balaharish7 mentioned this pull request Jul 24, 2026

docs: create complete Local PV Rawfile documentation #604

Closed

balaharish7 force-pushed the rawfileoverview-clean branch from b53e854 to 099de58 Compare July 24, 2026 11:07

Abhinandan-Purkait approved these changes Jul 24, 2026

View reviewed changes

tiagolobocastro reviewed Jul 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add complete Local PV Rawfile documentation#619

docs: add complete Local PV Rawfile documentation#619
balaharish7 wants to merge 2 commits into
openebs:mainfrom
balaharish7:rawfileoverview-clean

balaharish7 commented Jul 24, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

tiagolobocastro Jul 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		### CoW-Capable Pools (Recommended)

		Storage pools backed by btrfs or XFS with reflink produce space-efficient, nearly instant snapshots. No freeze is required.

	Storage pools backed by btrfs or XFS with reflink produce space-efficient, nearly instant snapshots. No freeze is required.
	Storage pools backed by filesystems which support reflink (i.e. btrfs or XFS) produce space-efficient, nearly instant snapshots. No freeze is required.


		### freezeFs

		For pools without CoW support (e.g. ext4), add `freezeFs: "true"` to the StorageClass. The filesystem is briefly frozen during the snapshot to ensure crash consistency:


		## Capacity Considerations

		- CoW-capable pools (btrfs, XFS reflink): snapshots consume only the changed blocks after the snapshot point.

	- CoW-capable pools (btrfs, XFS reflink): snapshots consume only the changed blocks after the snapshot point.
	- CoW-capable pools (filesystems with reflink enabled): snapshots consume only the changed blocks after the snapshot point.

	- Non-CoW pools (ext4): each snapshot is a full copy of the volume and consumes the same amount of space as the original.
	- Non-CoW pools: each snapshot is a full copy of the volume and consumes the same amount of space as the original.


		## 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/).

Uh oh!

Conversation

balaharish7 commented Jul 24, 2026

New Docs - Configuration (4 Docs)

New Docs - Advanced Operations (7 Docs)

Updated Existing Docs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants