chore: apply all changes

ansible/roles/expand_root_lv/README.md

@@ -1,7 +1,8 @@
 # expand-root-lv role
 
-Idempotent role that extends the root LVM logical volume to fill its
-volume group and grows the underlying filesystem (ext4 or xfs).
+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
 
@@ -24,6 +25,22 @@ 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
+
+1. **growpart** — resizes the underlying partition to claim the newly
+   provisioned disk space. Idempotent: no-op when the partition already
+   fills the disk.
+2. **pvresize** — tells the kernel/LVM about the new partition size so
+   the VG sees the additional free PEs.
+3. **lvextend** — extends the LV to claim all free PE in the VG
+   (`+100%FREE`). No-op when there's nothing to grow.
+4. **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
@@ -49,22 +66,30 @@ 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:
+
+```yaml
+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 names in `host_vars/<host>.yml` for hosts that use a
-different LVM layout.
+Override the VG/LV/PV names in `host_vars/<host>.yml` for hosts that use a
+different layout.
 
 ## Limitations
 
-- Does not extend the underlying partition. If the operator grows the
-  Proxmox disk and the partition itself needs to grow before lvextend
-  can claim the new space, run `growpart /dev/sda 3` (or equivalent)
-  first. A future enhancement could automate this via `cloud-utils`'
-  `growpart` package, but it's out of scope for the initial template
-  fix-up case where the partition already covers the whole disk.
+- 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.