Merge pull request #77517 from aspauldi/CNV-40296

CNV#40296: DOC: Update docs to recommend changing the error policy when using persistent reservation

Author: jeana-redhat

modules/virt-configuring-disk-sharing-lun.adoc

@@ -6,12 +6,16 @@
 [id="virt-configuring-disk-sharing-lun_{context}"]
 = Configuring disk sharing by using LUN
 
-You can configure a LUN-backed virtual machine disk to be shared among multiple virtual machines by enabling SCSI persistent reservation. Enabling the shared option allows you to use advanced SCSI commands, such as those required for a Windows failover clustering implementation, against the underlying storage. Any disk to be shared must be in block mode.
+You can configure a LUN-backed virtual machine (VM) disk to be shared among multiple virtual machines by enabling SCSI persistent reservation. Enabling the shared option allows you to use advanced SCSI commands, such as those required for a Windows failover clustering implementation, against the underlying storage. Any disk to be shared must be in block mode.
 
 A disk of type `LUN` exposes the volume as a LUN device to the VM. This allows the VM to execute arbitrary iSCSI command passthrough on the disk.
 
 You reserve a LUN through the SCSI persistent reserve options to protect data on the VM from outside access. To enable the reservation, you configure the feature gate option. You then activate the option on the LUN disk to issue SCSI device-specific input and output controls (IOCTLs) that the VM requires.
 
+You can set an error policy for each LUN disk. The error policy controls how the hypervisor behaves when an input/output error occurs on a disk Read or Write. The default behavior stops the guest and generates a Kubernetes event.
+
+For a LUN disk with an iSCSi connection and a persistent reservation, as required for Windows Failover Clustering for shared volumes, you set the error policy to `report`.
+
 .Prerequisites
 
 * You must have cluster administrator privileges to configure the feature gate option.
@@ -41,10 +45,10 @@ spec:
           - disk:
               bus: sata
             name: rootdisk
-          - errorPolicy: report
-            lun: <1>
+          - errorPolicy: report <1>
+            lun: <2>
               bus: scsi
-              reservation: true <2>
+              reservation: true <3>
             name: na-shared
             serial: shared1234
       volumes:
@@ -55,7 +59,8 @@ spec:
         persistentVolumeClaim:
           claimName: pvc-na-share
 ----
-<1> Identifies a LUN disk.
-<2> Identifies that the persistent reservation is enabled.
+<1> Identifies the error policy.
+<2> Identifies a LUN disk.
+<3> Identifies that the persistent reservation is enabled.
 
 . Save the `VirtualMachine` manifest file to apply your changes.

modules/virt-configuring-vm-disk-sharing.adoc

@@ -10,6 +10,14 @@ You can configure block volumes so that multiple virtual machines (VMs) can shar
 
 The application running on the guest operating system determines the storage option you must configure for the VM. A disk of type `disk` exposes the volume as an ordinary disk to the VM.
 
+You can set an error policy for each disk. The error policy controls how the hypervisor behaves when an input/output error occurs while a disk is being written to or read. The default behavior stops the VM and generates a Kubernetes event.
+
+You can accept the default behavior, or you can set the error policy to one of the following options:
+
+* `report`, which reports the error in the guest.
+* `ignore`, which ignores the error. The Read or Write failure is undetected.
+* `enospace`, which produces an error indicating that there is not enough disk space.
+
 .Prerequisites
 
 * The volume access mode must be `ReadWriteMany` (RWX) if the VMs that are sharing disks are running on different nodes.
@@ -38,17 +46,19 @@ spec:
           - disk:
               bus: virtio
             name: rootdisk
-            disk1: disk_one <1>
+            errorPolicy: report <1>
+            disk1: disk_one <2>
           - disk:
               bus: virtio
             name: cloudinitdisk
             disk2: disk_two
-            shareable: true <2>
+            shareable: true <3>
           interfaces:
           - masquerade: {}
             name: default
 ----
-<1> Identifies a device as a disk.
-<2> Identifies a shared disk.
+<1> Identifies the error policy.
+<2> Identifies a device as a disk.
+<3> Identifies a shared disk.
 
 . Save the `VirtualMachine` manifest file to apply your changes.

virt/virtual_machines/virtual_disks/virt-configuring-shared-volumes-for-vms.adoc

@@ -10,8 +10,10 @@ You can configure shared disks to allow multiple virtual machines (VMs) to share
 
 You configure disk sharing by exposing the storage as either of these types:
 
-* An ordinary virtual machine disk
-* A logical unit number (LUN) device with an iSCSi connection and raw device mapping, as required for Windows Failover Clustering for shared volumes
+* An ordinary VM disk
+* A logical unit number (LUN) disk with an iSCSi connection and raw device mapping, as required for Windows Failover Clustering for shared volumes
+
+In addition to configuring disk sharing, you can also set an error policy for each ordinary VM disk or LUN disk. The error policy controls how the hypervisor behaves when an input/output error occurs on a disk Read or Write.
 
 include::modules/virt-configuring-vm-disk-sharing.adoc[leveloffset=+1]