96 lines
3.7 KiB
Markdown
96 lines
3.7 KiB
Markdown
# 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.
|