lvm-formula

Travis CI Build Status Semantic Release

Linux logical volume management (LVM2) state API.

note

The lvm.conf(5) is indirectly managed via LVM profiles.

1. General notes

See the full SaltStack Formulas installation and usage instructions.

If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.

If you want to use this formula, please pay attention to the FORMULA file and/or git tag, which contains the currently released version. This formula is versioned according to Semantic Versioning.

See Formula Versioning Section for more details.

1.1. Todo

  • global filter support is important

  • test some advanced LV/RAID scenarios

  • file systems mngt

1.2. Good pillar data

Bad configuration causes problems. Sanity check pillar data when troubleshooting “unable to” state failures.

1.3. OS families

All Linux distributions supported.

2. Contributing to this repo

Commit message formatting is significant!!

Please see How to contribute for more details.

3. Available Meta states

3.1. lvm

Meta-state to run all states in sequence: 'install', 'profiles', 'files', 'pv', 'vg', and 'lv'.

3.2. lvm.profiles

Meta-state to manage lvm profiles in sequence: 'remove', followed by 'create'.

3.3. lvm.files

Meta-state to run loopback file device states in sequence: 'remove', followed by 'create'. Included by lvm.pv state.

3.4. lvm.pv

Meta-state to run physical volume (PV) states in sequence: 'remove', 'change', 'resize', 'move', and finally 'create'.

3.5. lvm.vg

Meta-state to run all volume group states in sequence: 'cfgbackup', 'import', 'remove', 'change' 'reduce', 'extend', 'split', 'merge', 'rename', 'create', 'export' & 'cfgrestore'.

3.6. lvm.lv

Meta-state to run all logical volume states in sequence: Order 'remove', 'change', 'reduce', 'extend', 'rename', 'create', 'convert', and 'create' again.

3.7. lvm.clean

Meta-state to run all clean states provided by this formula.

4. Available substates

4.1. lvm.install

Install lvm2 package.

4.2. lvm.profiles.clean

Remove custom lvm profile(s):

profiles:
  remove:
    - sillyprofile

4.3. lvm.profiles.create

Create custom lvm profile(s):

lvm:
  profiles:
    create:
      thin-generic-autoextend:
        activation:
          thin_pool_autoextend_threshold: 70
          thin_pool_autoextend_percent: 20

4.4. lvm.files.clean

Remove LVM backing files from the file system.

4.5. lvm.files.create

LVM Loopback HOW-TO support. Creates backing files (in /tmp by defaults) and loopback devices per pillars:

lvm:
  files:
    #loopbackdir: /tmp         #Where to create backing files? Default is /tmp anyway.
    remove:
      - /tmp/testfile1.img
      - /tmp/testfile2.img
    create:
      truncate:                #Shrink or extend the size of each FILE to the specified size
        testfile1.img:
          options:
            size: 100M
      dd:                      #copy a file, converting and formatting according to the operands
        testfile2.img:
          options:
            if: /dev/urandom
            bs: 1024
            count: 204800
      losetup:                 #set up and control loop devices
        testfile1.img:
        testfile2.img:
  pv:
    create:
      /dev/loop0:               #hopefully /tmp/testfile1.img (run 'sudo losetup -D' first for certainty)
      /dev/loop1:               #hopefully /tmp/testfile2.img (run 'sudo losetup -D' first for certainty)

4.6. lvm.pv.clean

Remove physical volumes (PVs):

remove:
  /dev/sdb:
    options:
      verbose: True
  /dev/sdc:
    options:
      debug: True
  /dev/sdd:
  /dev/sde:
  /dev/sdf:

4.7. lvm.pv.change

Change attributes of physical volume(s) (PVs):

pv:
  change:
    ##Named PV must belong to VG; i.e. PV must be allocatable
    /dev/sdd:
      options:
        addtag: 'goodpvs'
        deltag: 'badpvs'
        debug: 1

4.8. lvm.pv.resize

Resize disk(s) or partition(s) in use by LVM2:

pv:
  resize:
    /dev/sdd:
      options:
        setphysicalvolumesize: 1G

4.9. lvm.pv.move

Move allocated physical extents (PEs) from Source PV to other PV(s):

pv:
  move:
    /dev/sdd:
      dest: /dev/sde
      options:
        name: vg00/lv1
        noudevsync: True

4.10. lvm.pv.create

Initialize disk(s) or partition(s) for use by LVM:

pv:
  create:
    /dev/sdb:
    /dev/sdc:
    /dev/sdd:
    /dev/sde:
      options:
        override: True
        dataalignmentoffset: 7s
        metadatacopies: 1
        metadatasize: 40MiB
    /dev/sdf:
      options:
        metadatacopies: 1

4.11. lvm.vg.cfgbackup

Backup the metadata of your volume groups:

vg:
  cfgbackup:
    vg00:
      file: vg00_backup_today
      options:
        ignorelockingfailure: True
        readonly: True

4.12. lvm.vg.import

Make volume groups known to the system:

vg:
  import:
    i_do_not_exist:
      options:
        verbose: True

4.13. lvm.vg.clean

Remove volume group(s):

vg:
  remove:
    vg00:
      options:
        noudevsync: True

4.14. lvm.vg.change

Change attributes of volume group(s):

vg:
  change:
    vg00:
      options:
        available: True
        syncronize: False
        addtag: 'goodvgs'
        deltag: 'badvgs'

4.15. lvm.vg.reduce

Remove one or more unused physical volumes from a volume group:

vg:
  reduce:
    vg00:
      devices:
        - /dev/sdb
      options:
        removemissing: True

4.16. lvm.vg.extend

Add physical volumes to a volume group(s):

vg:
  extend:
    vg00:
      devices:
        - /dev/sdd
      options:
        restoremissing: True

4.17. lvm.vg.split

Split volume group(s) into two:

vg:
  split:
    vg00:
      newvg: smallvg
      devices:
        - /dev/sdf
      options:
        shared: n
        maxphysicalvolumes: 0
        maxlogicalvolumes: 0

4.18. lvm.vg.merge

Merge two volume groups:

vg:
  merge:
    vg00:
      withvg: vg001

4.19. lvm.vg.rename

Rename volume group(s):

vg:
  rename:
    vg002:
      newname: vg002old

4.20. lvm.vg.create

Create volume group(s):

vg:
  create:
    vg00:
      devices:
        - /dev/sdb
        - /dev/sdc
      options:
        shared: n
        maxlogicalvolumes: 0
        maxphysicalvolumes: 0
        physicalextentsize: 1024
    vg_large:
      devices:
        - /dev/sdd
        - /dev/sde
        - /dev/sdf

4.21. lvm.vg.export

Make volume groups unknown to the system:

vg:
  export:
    vg_tmp:
      options:
        verbose: True
        commandprofile: command_profile_template

4.22. lvm.vg.cfgrestore

Restore the metadata of VG(s) from text backup files produced by lvm.vg.cfgbackup state:

vg:
  cfgrestore:
    vg00:
      file: vg00_backup_today
      options:
        debug: True

4.23. lvm.lv.clean

Remove LV(s):

lv:
  remove:
    lv_pool1:
      vgname: vg_large
    lv_pool1_meta:
      vgname: vg_large
    lvol0:
      vgname: vg_large
    lvol1:
      vgname: vg_large
    lvol2:
      vgname: vg_large
    lvol3:
      vgname: vg_large
    lvol4:
      vgname: vg_large
    lvol5:
      vgname: vg_large
    lvol6:
      vgname: vg_large
    my_raid1:
      vgname: vg_large
      options:
        force: True

4.24. lvm.lv.change

Change attributes of logical volume(s):

lv:
  change:
    vg00/lv1:
      options:
        permission: r
        activate: n
        addtag: 'goodlvs'
        deltag: 'badlvs'

4.25. lvm.lv.reduce

Reduce size of logical volume(s):

lv:
  reduce:
    vg00/lv1:
      options:
        extents: -2
    vg00/lv2:
      options:
        size: -20MiB

4.26. lvm.lv.extend

Extend size of logical volume(s):

lv:
  extend:
    vg00/lv1:
      options:
        #extents: +100%PVS
        extents: 2
      devices:
        - /dev/sdf

4.27. lvm.lv.rename

Rename LV(s):

lv:
  rename:
    vg00/lv1:
      vgname: vg00
      newname: lvolvo

4.28. lvm.lv.create

Create logical volume(s) in existing volume group(s):

lv:
  create:
    lv1:
      vgname: vg00
      size: 200MiB
      options:
        addtag: 'Coolvolume'
        contiguous: y
        monitor: y
    lv_stripe1:
      vgname: vg00
      size: 100MiB
      options:
        stripes: 2
        stripesize: 4096
    #On-demand snapshots, workaround: https://github.com/saltstack/salt/issues/48808
    sparse:
      vgname: vg00
      snapshot: True
      sourcelv: lv1
      size: '+10%ORIGIN'
      options:
        virtualsize: 200MiB
    lv2_snap:
      vgname: vg00
      snapshot: True
      sourcelv: lv2
      size: '+10%ORIGIN'
Note

Thin provisioning needs two create states to run (create, convert, and create).

4.29. lvm.lv.convert

Change LV type and other utilities:

lv:
  convert:
    ##thin pool logical volume
    vg_large/lv_thinpool1:
      options:
        type: thin-pool
        ##data and metadata LVs in a thin pool are best created on separate physical devices
        poolmetadata:
          - lv_pool1_meta
          - lv_pool1
    vg_large/lv_1:
      options:
        mirrors: 1
        mirrorlog: core
      devices:
        - /dev/sdd:0-15
        - /dev/sdd:0-15
    vg_large/lv_mirror1:
      options:
        splitmirrors: 1
        name: lv_split
        regionsize: 512KB
        background: False
        interval: 10
Note

Thin provisioning needs two create states to run (create, convert, and create).

5. Testing

Linux testing is done with kitchen-salt.

5.1. Requirements

  • Ruby

  • Docker

$ gem install bundler
$ bundle install
$ bin/kitchen test [platform]
bash

Where [platform] is the platform name defined in kitchen.yml, e.g. debian-9-2019-2-py3.

5.2. bin/kitchen converge

Creates the docker instance and runs the lvm main state, ready for testing.

5.3. bin/kitchen verify

Runs the inspec tests on the actual instance.

5.4. bin/kitchen destroy

Removes the docker instance.

5.5. bin/kitchen test

Runs all of the stages above in one go: i.e. destroy + converge
verify + destroy.

5.6. bin/kitchen login

Gives you SSH access to the instance for manual testing.