1. Documentation
×

Configuring shared volumes for virtual machines

You can configure shared disks to allow multiple virtual machines (VMs) to share the same underlying storage. A shared disk’s volume must be block mode.

You configure disk sharing by exposing the storage as either of these types:

  • An ordinary VM disk

  • A logical unit number (LUN) disk with an SCSI 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.

Configuring disk sharing by using virtual machine disks

You can configure block volumes so that multiple virtual machines (VMs) can share storage.

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.

    If the VMs that are sharing disks are running on the same node, ReadWriteOnce (RWO) volume access mode is sufficient.

  • The storage provider must support the required Container Storage Interface (CSI) driver.

Procedure

  1. Create the VirtualMachine manifest for your VM to set the required values, as shown in the following example:

    apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: <vm_name>
spec:
  template:
# ...
    spec:
      domain:
        devices:
          disks:
          - disk:
              bus: virtio
            name: rootdisk
            errorPolicy: report (1)
            disk1: disk_one (2)
          - disk:
              bus: virtio
            name: cloudinitdisk
            disk2: disk_two
            shareable: true (3)
          interfaces:
          - masquerade: {}
            name: default
    1 Identifies the error policy.
    2 Identifies a device as a disk.
    3 Identifies a shared disk.

  2. Save the VirtualMachine manifest file to apply your changes.

Configuring disk sharing by using LUN

To secure data on your VM from outside access, you can enable SCSI persistent reservation and configure a LUN-backed virtual machine disk to be shared among multiple virtual machines. By enabling the shared option, you can use advanced SCSI commands, such as those required for a Windows failover clustering implementation, for managing the underlying storage.

When a storage volume is configured as the LUN disk type, a VM can use the volume as a logical unit number (LUN) device. As a result, the VM can deploy and manage the disk by using SCSI commands.

You reserve a LUN through the SCSI persistent reserve options. To enable the reservation:

  1. Configure the feature gate option

  2. Activate the feature gate 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.

  • The volume access mode must be ReadWriteMany (RWX) if the VMs that are sharing disks are running on different nodes.

    If the VMs that are sharing disks are running on the same node, ReadWriteOnce (RWO) volume access mode is sufficient.

  • The storage provider must support a Container Storage Interface (CSI) driver that uses the SCSI protocol.

  • If you are a cluster administrator and intend to configure disk sharing by using LUN, you must enable the cluster’s feature gate on the HyperConverged custom resource (CR).

  • Disks that you want to share must be in block mode.

Procedure

  1. Edit or create the VirtualMachine manifest for your VM to set the required values, as shown in the following example:

    apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: vm-0
spec:
  template:
    spec:
      domain:
        devices:
          disks:
          - disk:
              bus: sata
            name: rootdisk
          - errorPolicy: report (1)
            lun: (2)
              bus: scsi
              reservation: true (3)
            name: na-shared
            serial: shared1234
      volumes:
      - dataVolume:
          name: vm-0
        name: rootdisk
      - name: na-shared
        persistentVolumeClaim:
          claimName: pvc-na-share
    1 Identifies the error policy.
    2 Identifies a LUN disk.
    3 Identifies that the persistent reservation is enabled.

  2. Save the VirtualMachine manifest file to apply your changes.

Configuring disk sharing by using LUN and the web console

You can use the OKD web console to configure disk sharing by using LUN.

Prerequisites

  • The cluster administrator must enable the persistentreservation feature gate setting.

Procedure

  1. Click Virtualization → VirtualMachines in the web console.

  2. Select a VM to open the VirtualMachine details page.

  3. Expand Storage.

  4. On the Disks tab, click Add disk.

  5. Specify the Name, Source, Size, Interface, and Storage Class.

  6. Select LUN as the Type.

  7. Select Shared access (RWX) as the Access Mode.

  8. Select Block as the Volume Mode.

  9. Expand Advanced Settings, and select both checkboxes.

  10. Click Save.

Configuring disk sharing by using LUN and the command line

You can use the command line to configure disk sharing by using LUN.

Procedure

  1. Edit or create the VirtualMachine manifest for your VM to set the required values, as shown in the following example:

    apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: vm-0
spec:
  template:
    spec:
      domain:
        devices:
          disks:
          - disk:
              bus: sata
            name: rootdisk
          - errorPolicy: report
            lun: (1)
              bus: scsi
              reservation: true (2)
            name: na-shared
            serial: shared1234
      volumes:
      - dataVolume:
          name: vm-0
        name: rootdisk
      - name: na-shared
        persistentVolumeClaim:
          claimName: pvc-na-share
    1 Identifies a LUN disk.
    2 Identifies that the persistent reservation is enabled.

  2. Save the VirtualMachine manifest file to apply your changes.

Enabling the PersistentReservation feature gate

You can enable the SCSI persistentReservation feature gate and allow a LUN-backed block mode virtual machine (VM) disk to be shared among multiple virtual machines.

The persistentReservation feature gate is disabled by default. You can enable the persistentReservation feature gate by using the web console or the command line.

Prerequisites

  • Cluster administrator privileges are required.

  • The volume access mode ReadWriteMany (RWX) is required if the VMs that are sharing disks are running on different nodes. If the VMs that are sharing disks are running on the same node, the ReadWriteOnce (RWO) volume access mode is sufficient.

  • The storage provider must support a Container Storage Interface (CSI) driver that uses the SCSI protocol.

Enabling the PersistentReservation feature gate by using the web console

You must enable the PersistentReservation feature gate to allow a LUN-backed block mode virtual machine (VM) disk to be shared among multiple virtual machines. Enabling the feature gate requires cluster administrator privileges.

Procedure

  1. Click Virtualization → Overview in the web console.

  2. Click the Settings tab.

  3. Select Cluster.

  4. Expand SCSI persistent reservation and set Enable persistent reservation to on.

Enabling the PersistentReservation feature gate by using the command line

You enable the persistentReservation feature gate by using the command line. Enabling the feature gate requires cluster administrator privileges.

Procedure

  1. Enable the persistentReservation feature gate by running the following command:

    $ oc patch hyperconverged kubevirt-hyperconverged -n openshift-cnv --type json -p \
'[{"op":"replace","path":"/spec/featureGates/persistentReservation", "value": true}]'
Additional resources