.. _rst_gdeploylvm:

LVM
^^^

gdeploy allows to setup backend for GlusterFS in two ways.

  a. Using the modules: *pv*, *vg*, and *lv*
  b. Using the *backend-setup* module.

The *backend-setup* module sets up a thin-pool by default and applies default
performance recommendations. However, if the user has a different use case which
demands more than one LV, and a combination of thin and thick pools then
*backend-setup* is of no help. The user can use PV, VG, and LV modules to
achieve this.

Both the methods are explained below:

a. `[backend-setup]`_
b. `PV`_
c. `VG`_
d. `LV`_

[backend-setup]
---------------

*backend-setup* module allows the user to create bricks for GlusterFS nodes. If
the user needs more control on creating PV, VG, and LV refer the documentation
on respective sections.

In the below example, the module creates a thinpool LV using devices sdb, sdc on
all the nodes listed in the hosts section. Refer example `2x2-volume-create.conf
<https://github.com/gluster-deploy/gdeploy/blob/2.0/examples/2x2-volume-create.conf>`_
for more complete example.::

  [backend-setup]
  devices=sdb,sdc
  vgs=vg1,vg2
  pools=pool1,pool2
  lvs=lv1,lv2
  mountpoints=/mnt/data1,/mnt/data2
  brick_dirs=/mnt/data1/1,/mnt/data2/2

If *backend-setup* has to be done for particular hosts in the *inventory* then
the section would be written like::

  [backend-setup:10.0.0.100]    # Backend would be setup on just 10.0.0.100
  devices=sdb,sdc
  vgs=vg1,vg2
  pools=pool1,pool2
  lvs=lv1,lv2
  mountpoints=/mnt/data1,/mnt/data2
  brick_dirs=/mnt/data1/1,/mnt/data2/2

  [backend-setup:10.0.0.{1..10}]    # Backend would be setup on hosts 10.0.0.1
                                      through 10.0.0.10
  devices=sdb,sdc
  vgs=vg1,vg2
  pools=pool1,pool2
  lvs=lv1,lv2
  mountpoints=/mnt/data1,/mnt/data2
  brick_dirs=/mnt/data1/1,/mnt/data2/2


*backend-setup* section supports the following variables:

1. devices - List of comma separated devices to use.
2. vgs - Names of the vgs. The number of vg names should match the number of
   devices. If name is not mentioned, default names will be generated by gdeploy.
3. pools - Name of the thinpools. If name is not mentioned, default names will
   be generated by gdeploy.
4. lvs - Logical volume names. If name is not mentioned, default names will be
   generated by gdeploy.
5. size - Size of the logical volume
6. mountpoints - Mountpoint directories. Where the logical volumes have to be
   mounted.
7. brick_dirs - The brick directories to use for creating the volume.
8. ssd - This variable is set if caching has to be added.

PV
---

The [pv] section allows user to create physical volumes on the given disks.

Example 1: Create a few physical volumes::

  [pv]
  action=create
  devices=vdb,vdc,vdd

Example 2: Create a few physical volumes on a certain host::

  [pv:10.0.5.2]
  action=create
  devices=vdb,vdc,vdd

Example 1: Wipe signature from the device and create physical volumes::

  [pv]
  action=create
  devices=vdb,vdc,vdd
  wipefs=yes

Note: By default wipefs is set to 'no'.

Example 3: Expand an already created pv::

  [pv]
  action=resize
  devices=vdb
  expand=yes

Example 4: Shrink an already created pv::

  [pv]
  action=resize
  devices=vdb
  shrink=100G

VG
---
VG module currently supports two actions 'create' and 'extend'.

The 'create' action supports four variables:

1. pvname - The pv to be used.
2. vgname - Name of the vg, if variable is ommitted default name GLUSTER_vg will
   be used.
3. one-to-one - If set to yes, one-to-one mapping will be done between pv and vg.
4. ignore_vg_errors - If set to 'no', gdeploy exits if an error is encountered.

Example1: Create a vg named images_vg with two PVs::

  [vg]
  action=create
  vgname=images_vg
  pvname=sdb,sdc

Example2: Create two vgs named rhgs_vg1 and rhgs_vg2 with two PVs exit gdeploy
in case of any errors::

  [vg]
  action=create
  vgname=rhgs_vg
  pvname=sdb,sdc
  one-to-one=yes
  ignore_vg_errors=no

The 'extend' action is used to extend volume groups. The following variables are
supported if action=extend:

1. pvname - The pv to be used, for more than one pv, comma separate them.
2. vgname - Name of the vg, if variable is ommitted default name GLUSTER_vg will
   be used.
3. ignore_vg_errors - If set to 'no', gdeploy exits if an error is encountered.

Example1: Extend an existing vg with the given disk::

  [vg]
  action=extend
  vgname=rhgs_images
  pvname=sdc

Example2: Extend a vg, exit gdeploy in case of errors::

  [vg]
  action=extend
  vgname=rhgs_images
  pvname=sdc
  ignore_vg_errors=no

Refer `hc.conf
<https://github.com/gluster-deploy/gdeploy/blob/2.0/examples/hc.conf>`_ for
complete example.


LV
---
This module is used to create, setup-cache, and convert logical volumes. The lv
module supports the following variables:

  1. action - The action variable allows four values *create*, *setup-cache*,
     *convert*, and *change*.

If the action is create, the following options are supported:

  1. lvname - The name of the logical volume, this is an optional field. Default
     is GLUSTER_lv
  2. poolname - Name of the thinpool volume name, this is an optional
     field. Default is GLUSTER_pool
  3. lvtype - Type of the logical volume to be created, allowed values are
     *thin* and *thick*. This is an optional field, default is thick.
  4. size - Size of the logical volume volume. Default is to take all available
     space on the vg.
  5. extent - Extent size, default is 100%FREE
  6. force - Force lv create, do not ask any questions. Allowed values *yes*,
     *no*. This is an optional field, default is yes.
  7. vgname - Name of the volume group to use.
  8. pvname - Name of the physical volume to use.
  9. chunksize - Size of chunk for snapshot.
  10. poolmetadatasize - Sets the size of pool's metadata logical volume.
  11. virtualsize - Creates a thinly provisioned device or a sparse device of
      the given size.
  12. mkfs - Creates a filesystem of the given type. Default is to use xfs.
  13. mkfs-opts - mkfs options.
  14. mount - Mount the logical volume.
  15. ignore_lv_errors - If set to no, gdeploy exits if errors are encountered.

If the action is setup-cache, the below options are supported:

  1. ssd - Name of the ssd device. For example sda/vda/ … to setup cache.
  2. vgname - Name of the volume group.
  3. poolname - Name of the pool.
  4. cache_meta_lv - Due to requirements from dm-cache (the kernel driver), LVM
     further splits the cache pool LV into two devices - the cache data LV and
     cache metadata LV. Provide the cache_meta_lv name here.
  5. cache_meta_lvsize - Size of the cache meta lv.
  6. cache_lv - Name of the cache data lv.
  7. cache_lvsize - Size of the cache data.
  8. force - Force
  9. cachemode - Provides provision to setup cache while creating lv. Allowed values writeback, writethrough. Default is writethrough.
  9. ignore_lv_errors - If set to no, gdeploy exits if errors are encountered.


If the action is convert, the below options are supported:

  1. lvtype - type of the lv, available options are thin and thick
  2. force - Force the lvconvert, default is yes.
  3. vgname - Name of the volume group.
  4. poolmetadata - Specifies  cache  or thin pool metadata logical volume.
  5. cachemode - Allowed values writeback, writethrough. Default is writethrough.
  6. cachepool - This  argument  is  necessary when converting a logical volume
     to a cache LV. Name of the cachepool.
  7. lvname - Name of the logical volume.
  8. chunksize - Gives the size of chunk for snapshot, cache pool and thin pool
     logical volumes. Default unit is in kilobytes.
  9. poolmetadataspare - Controls creation and maintanence of pool metadata
     spare logical volume that will be used for automated  pool  recovery.
  10. thinpool - Specifies or converts logical volume into a thin pool's data
      volume. Volume’s name or path has to be given.
  11. ignore_lv_errors - If set to no, gdeploy exits if errors are encountered.

If the action is change, the below options are supported:

  1. lvname - Name of the logical volume.
  2. vgname - Name of the volume group.
  3. zero - Set  zeroing mode for thin pool.
  4. ignore_lv_errors - If set to no, gdeploy exits if errors are encountered.

Example 1: Create a thin LV::

  [lv]
  action=create
  vgname=RHGS_vg1
  poolname=lvthinpool
  lvtype=thinpool
  poolmetadatasize=10MB
  chunksize=1024k
  size=30GB

Example 2: Create a thick LV::

  [lv]
  action=create
  vgname=RHGS_vg1
  lvname=engine_lv
  lvtype=thick
  size=10GB
  mount=/rhgs/brick1


If there are more than one LV, the LVs can be created by numbering the LV
sections, like [lv1], [lv2] ...

Refer `hc.conf
<https://github.com/gluster-deploy/gdeploy/blob/2.0/examples/hc.conf>`_ for
complete example.
