lvm – Keystone Core

lvm

Manages one LVM object per declaration — a Physical Volume (pv), a Volume Group (vg), or a Logical Volume (lv). Idempotent: re-applying an unchanged declaration reports no change, and a size-based LV or a VG’s PV set is reconciled in place.

Category: Storage

States

State	Meaning
`present`	The object exists. An existing size-based LV below its declared size is grown; an existing VG whose live PV set differs from `pvs:` is extended/reduced.
`absent`	The object does not exist; an existing PV, VG, or LV is removed (LVM refuses to remove one that still holds data/children).

Parameters

Parameter	Type	Description
`pv`	string	Device path (e.g. `/dev/sdb1`) for a Physical Volume operation. Mutually exclusive with `vg`/`lv`.
`vg`	string	Volume Group name. On its own it is a VG operation; combined with `lv` it names the parent VG of a Logical Volume.
`pvs`	list	Member device paths for a VG (required when a VG is `present`). Reconciled on an existing VG: devices added/removed to match.
`lv`	string	Logical Volume name for an LV operation. Requires `vg` (the parent volume group).
`size`	string	LV size, e.g. `10G`, `500M`, `1T` (no suffix = MiB). Grow-only “at least” semantics. Mutually exclusive with `extents`.
`extents`	string	LV size as a percentage, e.g. `100%FREE`, `50%VG`. Create-only. Mutually exclusive with `size`.
`resize_fs`	bool	Pass `--resizefs` to `lvextend` so the contained filesystem grows with a size-based LV. Default: `false`.

Examples

Build a stack: PV, then VG, then LV

The require requisites order each object after its dependency.

lvm:
  pv-sdb1:
    state: present
    pv: /dev/sdb1
  vg-data:
    state: present
    vg: data
    pvs:
      - /dev/sdb1
    require:
      - lvm: pv-sdb1
  lv-home:
    state: present
    lv: home
    vg: data
    size: 10G
    require:
      - lvm: vg-data

Grow a logical volume and its filesystem

lvm:
  lv-home-grow:
    state: present
    lv: home
    vg: data
    size: 20G
    resize_fs: true

Consume all free space, and remove an old PV

lvm:
  lv-scratch:
    state: present
    lv: scratch
    vg: data
    extents: 100%FREE
  pv-old:
    state: absent
    pv: /dev/sdc1

Notes

Linux only; other operating systems get a no-op provider that reports the LVM tools as unavailable.
Exactly one of pv / vg / lv must be set per declaration; the operation is implied by which one.
A VG that is present requires pvs: (at least one device); the live PV set is reconciled (add via vgextend, remove via vgreduce).
size and extents are mutually exclusive on an LV. size is grow-only (never shrinks); extents LVs are create-only.
DriftSeverity is HIGH — LVM objects are data-bearing. The module never passes -f/--force, so LVM refuses to clobber existing data, non-empty VGs, or mounted LVs; operators must clear blockers first.
Out of scope (planned, #23): LV shrink, extents-based resize, thin/cache/snapshot, RAID, PV metadata, and allocation policy. Use the disk module to create a filesystem on the resulting device.

link mount