# 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

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
  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`:

```yaml
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/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.