docs(lvm-local-storage): considerations for striped vs dm-thin

docs/advanced/addons/lvm-local-storage.md

@@ -104,6 +104,16 @@ You can only use one type of local volume in each volume group. If necessary, cr
 
     ![](/img/v1.4/csi-driver-lvm/create-lvm-sc-05.png)
 
+### Considerations: `striped` vs `dm-thin`
+
+Both volume group types are fully supported. The choice depends on how the workload will use snapshots and how the pool capacity will be shared.
+
+- **`striped`** is a good fit for workloads that mostly need direct volume performance across the physical devices in the volume group. Each logical volume gets its full requested capacity at provision time. Snapshots are provisioned as separate LVs sized to the origin's full capacity — a snapshot of a 100 GiB volume reserves an additional 100 GiB of volume group space at creation, regardless of how much data has actually been written to the origin.
+
+- **`dm-thin`** is a good fit for virtual machine workloads that take snapshots or clones, and for environments that want to over-provision pool capacity. Thin volumes consume physical space only as blocks are written to them, and snapshots are true copy-on-write at the thin-pool chunk level — a fresh snapshot of a 100 GiB volume adds effectively zero pool capacity at creation and only grows as changed blocks accumulate.
+
+If regular snapshots are expected, `dm-thin` is generally the right choice for VM workloads.
+
 For more information, see [StorageClass](../storageclass.md).
 
 ## Creating a Volume with LVM
@@ -177,4 +187,45 @@ You can also create a new virtual machine with the volume of the LVM StorageClas
 
 Backup creation is currently not supported. This limitation will be addressed in a future release.
 
-:::
+:::
+
+## Additional Notes
+
+### Tuning the `dm-thin` Pool
+
+When the first PersistentVolumeClaim is created against a `dm-thin` StorageClass, the driver creates an LVM thin-pool named `<vgName>-thinpool` at `-l 90%FREE` of the volume group. Two settings are worth knowing about:
+
+- **Chunk zeroing.** By default, the pool writes zeros to each newly-allocated chunk before handing it to the writer. On single-tenant clusters this can be disabled to reduce write amplification on first-touch allocations:
+
+  ```
+  sudo lvchange --zero n <vgName>/<vgName>-thinpool
+  ```
+
+  The change is fully reversible with `--zero y`.
+
+- **Pool metadata size.** LVM auto-sizes the thin-pool metadata LV at pool creation. For pools that will hold many snapshots or many thin volumes over time, extending the metadata proactively avoids running short later:
+
+  ```
+  sudo lvextend --poolmetadatasize +1G <vgName>/<vgName>-thinpool
+  ```
+
+### Choosing a VM Disk Bus
+
+When attaching an LVM CSI PersistentVolumeClaim to a VirtualMachine, `virtio-scsi` (`bus: scsi`) generally performs better than the default `virtio-blk` (`bus: virtio`) for sustained-write workloads on thin-provisioned pools, particularly on RAID-backed storage. `virtio-scsi` supports multiple queues and has a more efficient DISCARD path.
+
+### Coexistence with Longhorn v2 Block-Mode Disks
+
+If the same node hosts a Longhorn v2 disk in block mode, the underlying device is held exclusively by the SPDK instance manager. Adding that device to the LVM `global_filter` prevents LVM's device scan from attempting to open it. Example, in `/etc/lvm/lvmlocal.conf`:
+
+```
+devices {
+    global_filter = [
+      "r|/dev/loop.*|",
+      "r|/dev/disk/by-path/.*longhorn.*|",
+      "r|/dev/mapper/pvc-.*|",
+      "r|/dev/disk/by-id/wwn-<lhv2-disk-wwn>|",
+    ]
+}
+```
+
+On Harvester's immutable OS, persist the change through an `/oem/*.yaml` cloud-config file so it survives reboots. For background, see [harvester/harvester#11098](https://github.com/harvester/harvester/issues/11098).

versioned_docs/version-v1.8/advanced/addons/lvm-local-storage.md

@@ -104,6 +104,16 @@ You can only use one type of local volume in each volume group. If necessary, cr
 
     ![](/img/v1.4/csi-driver-lvm/create-lvm-sc-05.png)
 
+### Considerations: `striped` vs `dm-thin`
+
+Both volume group types are fully supported. The choice depends on how the workload will use snapshots and how the pool capacity will be shared.
+
+- **`striped`** is a good fit for workloads that mostly need direct volume performance across the physical devices in the volume group. Each logical volume gets its full requested capacity at provision time. Snapshots are provisioned as separate LVs sized to the origin's full capacity — a snapshot of a 100 GiB volume reserves an additional 100 GiB of volume group space at creation, regardless of how much data has actually been written to the origin.
+
+- **`dm-thin`** is a good fit for virtual machine workloads that take snapshots or clones, and for environments that want to over-provision pool capacity. Thin volumes consume physical space only as blocks are written to them, and snapshots are true copy-on-write at the thin-pool chunk level — a fresh snapshot of a 100 GiB volume adds effectively zero pool capacity at creation and only grows as changed blocks accumulate.
+
+If regular snapshots are expected, `dm-thin` is generally the right choice for VM workloads.
+
 For more information, see [StorageClass](../storageclass.md).
 
 ## Creating a Volume with LVM
@@ -177,4 +187,45 @@ You can also create a new virtual machine with the volume of the LVM StorageClas
 
 Backup creation is currently not supported. This limitation will be addressed in a future release.
 
-:::
+:::
+
+## Additional Notes
+
+### Tuning the `dm-thin` Pool
+
+When the first PersistentVolumeClaim is created against a `dm-thin` StorageClass, the driver creates an LVM thin-pool named `<vgName>-thinpool` at `-l 90%FREE` of the volume group. Two settings are worth knowing about:
+
+- **Chunk zeroing.** By default, the pool writes zeros to each newly-allocated chunk before handing it to the writer. On single-tenant clusters this can be disabled to reduce write amplification on first-touch allocations:
+
+  ```
+  sudo lvchange --zero n <vgName>/<vgName>-thinpool
+  ```
+
+  The change is fully reversible with `--zero y`.
+
+- **Pool metadata size.** LVM auto-sizes the thin-pool metadata LV at pool creation. For pools that will hold many snapshots or many thin volumes over time, extending the metadata proactively avoids running short later:
+
+  ```
+  sudo lvextend --poolmetadatasize +1G <vgName>/<vgName>-thinpool
+  ```
+
+### Choosing a VM Disk Bus
+
+When attaching an LVM CSI PersistentVolumeClaim to a VirtualMachine, `virtio-scsi` (`bus: scsi`) generally performs better than the default `virtio-blk` (`bus: virtio`) for sustained-write workloads on thin-provisioned pools, particularly on RAID-backed storage. `virtio-scsi` supports multiple queues and has a more efficient DISCARD path.
+
+### Coexistence with Longhorn v2 Block-Mode Disks
+
+If the same node hosts a Longhorn v2 disk in block mode, the underlying device is held exclusively by the SPDK instance manager. Adding that device to the LVM `global_filter` prevents LVM's device scan from attempting to open it. Example, in `/etc/lvm/lvmlocal.conf`:
+
+```
+devices {
+    global_filter = [
+      "r|/dev/loop.*|",
+      "r|/dev/disk/by-path/.*longhorn.*|",
+      "r|/dev/mapper/pvc-.*|",
+      "r|/dev/disk/by-id/wwn-<lhv2-disk-wwn>|",
+    ]
+}
+```
+
+On Harvester's immutable OS, persist the change through an `/oem/*.yaml` cloud-config file so it survives reboots. For background, see [harvester/harvester#11098](https://github.com/harvester/harvester/issues/11098).