expand-root-lv role

Idempotent role that grows the root partition (via growpart), extends the root LVM logical volume to fill its volume group, and grows the underlying filesystem (ext4 or xfs).

Where this runs in the lifecycle

Part of the day0 host-provisioning lifecycle. The canonical entry points are:

playbooks/day0_expand_root_lv.yml   # standalone
playbooks/day0_provision.yml        # umbrella (baseline + expand_root_lv)

Day1 application-deploy playbooks should NOT include this role — day0 is assumed complete before day1 begins.

Why this role exists

The Ubuntu Server autoinstall template (used by the mk-labs wed-baked VM templates) provisions the root LV at roughly half the available disk size — a longstanding installer default that surprises every operator who hasn't been bitten by it before. ~90% of mk-labs VMs need this fix-up before they're fully useful.

After a Proxmox disk grow (increasing the VM disk size), the partition table, physical volume, logical volume, and filesystem all need to be extended in sequence. This role automates the full chain.

Workflow

growpart — resizes the underlying partition to claim the newly provisioned disk space. Idempotent: no-op when the partition already fills the disk.
pvresize — tells the kernel/LVM about the new partition size so the VG sees the additional free PEs.
lvextend — extends the LV to claim all free PE in the VG (+100%FREE). No-op when there's nothing to grow.
fs grow — resize2fs (ext4) or xfs_growfs (xfs), dispatched by detected filesystem type.

Idempotency

If vg_free_count == 0, the lvextend step is skipped and the filesystem-grow step is also skipped (nothing to resize against).
If the target volume group doesn't exist on the host (e.g. a non-LVM layout), the role exits cleanly via meta: end_play.
Safe to leave in a recurring playbook so future disk expansions (Proxmox-side disk grow → reboot → run role) are picked up automatically.

Opt-out for multi-LV hosts

If a host will have a second logical volume in the same VG (e.g. a dedicated /var/lib/postgresql LV for a database server), this role's "grow root to fill VG" behavior is wrong — it will consume the free PE that was being reserved for the second LV.

Set in host_vars/<host>.yml:

expand_root_lv_skip: true

The day0 playbook checks this flag and skips the role cleanly.

To skip only the partition growstep while keeping LV/FS expansion (e.g. when the partition already covers the whole disk but the LV was provisioned small by the template), set:

expand_root_lv_pv_partition: undefined

Defaults

Variable	Default	Purpose
`expand_root_lv_vg_name`	`ubuntu-vg`	LVM volume group name (Ubuntu installer default).
`expand_root_lv_lv_name`	`ubuntu-lv`	LVM logical volume name (Ubuntu installer default).
`expand_root_lv_pv_partition`	`/dev/sda3`	Partition backing the PV; grown via growpart.
`expand_root_lv_mountpoint`	`/`	Mountpoint of the filesystem to grow.

Override the VG/LV/PV names in host_vars/<host>.yml for hosts that use a different layout.

Limitations

The growpart step requires the cloud-guest-utils package. The role installs it automatically on Debian/Ubuntu hosts when expand_root_lv_pv_partition is defined.
Only supports ext4 and xfs filesystems. Other filesystem types (btrfs, etc.) are left as a future enhancement.

3.7 KiB Raw Blame History