# localdisk vdsm hook

## Overview

This hook adds the ability to use fast local storage instead of shared
storage, while using shared storage for managing VM templates.  In the
current system, a user have to choose between fast local storage sharing
nothing with other hosts, or shared storage, where everything is shared
between the hosts and fast local storage cannot be used.  This feature
try to mix both local and shared storage.


## Warning

VM using local disk must be pinned to a specific host and cannot be
migrated between hosts.

No storage operations on a VM using local disks are allowed.  For
example, creating/deleting snapshots, moving disks, create template from
the VM and more.

The VM disks on the shared storage should not be deleted, and the
storage domain needs to be active and accessible.


## How it works

A user will create a VM normally on shared storage of any type.  To use
the VM with local storage, the user will have to pin the VM to a certain
host, and enable the localdisk hook.

When starting the VM on the pinned host, the localdisk hook will copy
the VM disks from shared storage into the host local storage, and modify
the disk path to use the local copy of the disk.

The original disk may be a single volume or a chain of volumes based on
a template. The local copy is a raw preallocated volume using a LVM
logical volume on the special "ovirt-local" volume group.

Most operations are not supported on a VM using the localdisk hook.  For
example, the VM cannot be migrated to another host, cannot create
snapshots, copy the local disk to other storage, etc.

To change storage on a VM using local storage, the localdisk hook must
be disabled.


## Backends

The backends supported are "lvm" and "lvmthin":

- "lvm" backend uses regular logical volumes.
- "lvmthin" backend uses logical volumes on top of thin pool.

The system administrator is responsible for creating the host
"ovirt-local" volume group and extending it with new devices if needed.

The localdisk hook uses temporary files in /var/tmp when converting images from
shared storage. The system administrator is responsible for having enough space
in this directory.

For "lvmthin", the system administrator needs to create a thin pool
named "pool0" in the "ovirt-local" volume group, and extending the pool
if needed.


## Engine configuration

The system administrator need to configure the engine
UserDefinedVMProperties to support the 'localdisk' hook:

    engine-config -s UserDefinedVMProperties='localdisk=^(lvm|lvmthin)$'

Restart the engine.


## VM configuration

On the VM configuration UI:

- Add custom VM property of "localdisk" with "lvm" or "lvmthin".
- On the "Host" tab, enable "Start Running On:" and select a host with a
  "ovirt-local" volume group.
- On the "Host" tab, in "Migration mode :" select  "Do not allow
  migration".


## Detailed Flow

Here a description of the hook flow:

- If a matching local LV exists without the "UPDATING" tag:
  - activate the LV
  - update the disk path and format and return.
- If no matching local LV exists:
  - create a new LV with "UPDATING" tag.
  - copy the data from the shared storage disk/template.
  - once the copy operation is done, remove the "UPDATING" tag.
  - update the disk path and format and return.
- If a matching local LV exists with the "UPDATING":
  - delete the LV
  - create a new LV with "UPDATING" tag.
  - copy the data from the shared storage disk/template.
  - once the copy operation is done, remove the "UPDATING" tag.
  - update the disk path and format and return.
