infra-automation/cheatsheets/deploy-debian-lvm-netinst.md

Deploy Debian with LVM Network Installer - Quick Reference

Playbook

plays/deploy-debian-lvm-netinst.yml

Description

Advanced Debian deployment using network installer (netinst) with full LVM configuration. This playbook creates a VM with proper LVM partitioning per CLAUDE.md requirements using preseed for unattended installation.

Quick Deployment

Basic Usage

ansible-playbook plays/deploy-debian-lvm-netinst.yml

Custom Configuration

ansible-playbook plays/deploy-debian-lvm-netinst.yml \
  -e "vm_name=debian-lvm-server" \
  -e "vm_hostname=db-server" \
  -e "vm_vcpus=4" \
  -e "vm_memory_mb=8192" \
  -e "vm_disk_size_gb=100"

Variables

Variable	Default	Description
vm_name	debian-lvm-guest	VM name in libvirt
vm_hostname	debian-lvm	VM hostname
vm_domain	localdomain	Domain name
vm_vcpus	2	Number of vCPUs
vm_memory_mb	4096	RAM in MB (needs 4GB for installer)
vm_disk_size_gb	50	Disk size in GB
vm_network	default	Libvirt network
debian_version	12	Debian version (11 or 12)
debian_mirror	deb.debian.org	Debian mirror URL

LVM Configuration (CLAUDE.md Compliant)

This playbook creates the following LVM layout:

Physical Volume: /dev/vda2
Volume Group: vg_system

Logical Volumes:
├── lv_root       8G    /
├── lv_opt        3G    /opt
├── lv_tmp        1G    /tmp (noexec,nosuid,nodev)
├── lv_home       2G    /home
├── lv_var        5G    /var
├── lv_var_log    2G    /var/log
├── lv_var_tmp    5G    /var/tmp (noexec,nosuid,nodev)
├── lv_var_audit  1G    /var/log/audit
└── lv_swap       2G    swap

Separate partition:
└── /dev/vda1     2G    /boot (ext4)

Tag-Based Execution

# Pre-flight checks only
ansible-playbook plays/deploy-debian-lvm-netinst.yml --tags preflight

# Download netinst ISO only
ansible-playbook plays/deploy-debian-lvm-netinst.yml --tags download

# Generate preseed configuration only
ansible-playbook plays/deploy-debian-lvm-netinst.yml --tags preseed

# Deploy VM (assumes ISO downloaded)
ansible-playbook plays/deploy-debian-lvm-netinst.yml --tags deploy

# Validation only
ansible-playbook plays/deploy-debian-lvm-netinst.yml --tags validate

Available Tags

• preflight - Pre-flight validation
• install - Install required packages
• download - Download Debian netinst ISO
• preseed - Generate preseed configuration
• storage - Create VM disk
• deploy - Deploy and start VM
• validate - Post-installation validation
• cleanup - Remove temporary files

Installation Process

Timeline

1. Download ISO: ~5 minutes (depending on connection)
2. VM Creation: ~1 minute
3. OS Installation: ~15-20 minutes (unattended)
4. Total Time: ~20-25 minutes

Monitoring Installation

# Watch VM console during installation
ssh grokbox "virsh console debian-lvm-guest"

# Check VM status
ssh grokbox "virsh list --all"

# Monitor from VNC (if available)
ssh grokbox "virsh vncdisplay debian-lvm-guest"

Post-Installation

Wait for Completion

The installation is fully unattended. Wait for:

• Playbook to complete (deployment task will wait 20 minutes)
• VM to reboot automatically
• SSH service to become available

Get VM Information

# Get VM IP
ssh grokbox "virsh domifaddr debian-lvm-guest"

# VM details
ssh grokbox "virsh dominfo debian-lvm-guest"

Access VM

# SSH via ProxyJump
ssh -J grokbox ansible@<VM_IP>

# Add to ~/.ssh/config
Host debian-lvm
    HostName <VM_IP>
    User ansible
    ProxyJump grokbox
    StrictHostKeyChecking accept-new

Verify LVM Configuration

# SSH to VM
ssh -J grokbox ansible@<VM_IP>

# Check physical volumes
sudo pvs

# Check volume groups
sudo vgs

# Check logical volumes
sudo lvs

# Check mounts
df -h
lsblk

# Verify fstab
cat /etc/fstab

Expected output:

NAME                  MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
vda                   252:0    0   50G  0 disk
├─vda1                252:1    0    2G  0 part /boot
└─vda2                252:2    0   48G  0 part
  ├─vg_system-lv_root 254:0    0    8G  0 lvm  /
  ├─vg_system-lv_opt  254:1    0    3G  0 lvm  /opt
  ├─vg_system-lv_tmp  254:2    0    1G  0 lvm  /tmp
  ├─vg_system-lv_home 254:3    0    2G  0 lvm  /home
  ├─vg_system-lv_var  254:4    0    5G  0 lvm  /var
  ├─vg_system-lv_var_log 254:5 0    2G  0 lvm  /var/log
  ├─vg_system-lv_var_tmp 254:6 0    5G  0 lvm  /var/tmp
  ├─vg_system-lv_var_audit 254:7 0  1G  0 lvm  /var/log/audit
  └─vg_system-lv_swap 254:8    0    2G  0 lvm  [SWAP]

Security Features

Preseed Configuration Includes

• Minimal installation (no desktop environment)
• Automatic partitioning with LVM
• Security hardening:
  • SSH server installed
  • Root password set (change after deployment!)
  • ansible user with sudo access
  • SSH key authentication configured
  • UFW firewall enabled
  • Automatic security updates

Post-Installation Security Tasks

# Change root password
ssh -J grokbox ansible@<VM_IP>
sudo passwd root

# Verify SSH configuration
sudo cat /etc/ssh/sshd_config | grep -E 'PermitRoot|PasswordAuth'

# Check firewall
sudo ufw status verbose

# Verify automatic updates
sudo dpkg -l | grep unattended-upgrades

LVM Management

Extend Logical Volumes

# Extend lv_var by 5GB
sudo lvextend -L +5G /dev/vg_system/lv_var
sudo resize2fs /dev/vg_system/lv_var

# Extend lv_var to use all free space
sudo lvextend -l +100%FREE /dev/vg_system/lv_var
sudo resize2fs /dev/vg_system/lv_var

Create New Logical Volumes

# Create new LV for application data
sudo lvcreate -L 10G -n lv_app_data vg_system
sudo mkfs.ext4 /dev/vg_system/lv_app_data
sudo mkdir -p /opt/appdata
sudo mount /dev/vg_system/lv_app_data /opt/appdata

# Add to fstab
echo "/dev/vg_system/lv_app_data /opt/appdata ext4 defaults 0 2" | sudo tee -a /etc/fstab

LVM Snapshots

# Create snapshot of lv_root
sudo lvcreate -L 2G -s -n lv_root_snapshot /dev/vg_system/lv_root

# Mount snapshot
sudo mkdir -p /mnt/snapshot
sudo mount /dev/vg_system/lv_root_snapshot /mnt/snapshot

# Remove snapshot
sudo umount /mnt/snapshot
sudo lvremove /dev/vg_system/lv_root_snapshot

Troubleshooting

Installation Hangs

# Connect to console
ssh grokbox "virsh console debian-lvm-guest"

# Check VM is running
ssh grokbox "virsh list"

# Restart VM if needed
ssh grokbox "virsh reboot debian-lvm-guest"

No IP After Installation

# Check DHCP
ssh grokbox "virsh net-dhcp-leases default"

# Restart network on VM (via console)
ssh grokbox "virsh console debian-lvm-guest"
# Login and run:
sudo systemctl restart networking

Preseed Issues

# Check preseed file syntax
ssh grokbox "debconf-set-selections -c /tmp/preseed.cfg"

# Re-generate preseed
ansible-playbook plays/deploy-debian-lvm-netinst.yml --tags preseed

# View generated preseed
ssh grokbox "cat /tmp/preseed-debian-lvm-guest.cfg"

LVM Not Configured

If LVM is not properly configured after installation:

# Check if LVM packages are installed
ssh ansible@<VM_IP> "dpkg -l | grep lvm2"

# Check if VG exists
ssh ansible@<VM_IP> "sudo vgs"

# Manual LVM setup (if needed)
ssh ansible@<VM_IP> "sudo pvcreate /dev/vda2"
ssh ansible@<VM_IP> "sudo vgcreate vg_system /dev/vda2"

Advantages Over Cloud Images

Why Use Network Installer?

1. Full LVM Support: Proper LVM partitioning from installation
2. CLAUDE.md Compliance: Meets all partitioning requirements
3. Flexibility: Complete control over partitioning
4. Production Ready: Standard Debian installation process
5. Latest Packages: Always installs latest packages during install

Disadvantages

1. Longer Deployment: 15-20 minutes vs 2-3 minutes for cloud images
2. More Complex: Requires preseed configuration
3. Network Dependent: Requires network access during installation

VM Management

Start/Stop/Restart

ssh grokbox "virsh start debian-lvm-guest"
ssh grokbox "virsh shutdown debian-lvm-guest"
ssh grokbox "virsh reboot debian-lvm-guest"
ssh grokbox "virsh destroy debian-lvm-guest"  # Force stop

Delete VM

ssh grokbox "virsh destroy debian-lvm-guest"
ssh grokbox "virsh undefine debian-lvm-guest --remove-all-storage"

Validation Checklist

After deployment:

• VM running: virsh list | grep debian-lvm
• IP assigned: virsh domifaddr debian-lvm-guest
• SSH accessible: ssh -J grokbox ansible@<VM_IP>
• LVM configured: sudo vgs && sudo lvs
• All partitions mounted: df -h
• Firewall enabled: sudo ufw status
• Security updates configured: sudo unattended-upgrades --dry-run
• Swap active: free -h | grep Swap

Important Files

On Hypervisor (grokbox)

• Netinst ISO: /var/lib/libvirt/images/debian-12.0.0-amd64-netinst.iso
• VM disk: /var/lib/libvirt/images/debian-lvm-guest.qcow2
• Preseed config: /tmp/preseed-debian-lvm-guest.cfg
• VM config: /etc/libvirt/qemu/debian-lvm-guest.xml

On Guest VM

• LVM config: /etc/lvm/lvm.conf
• Fstab: /etc/fstab
• Installed packages: /var/log/installer/

Comparison with Other Playbooks

Feature	deploy-debian12-vm.yml	deploy-debian-lvm-netinst.yml	deploy-linux-vm-role
LVM Support	❌ No	✅ Yes (native)	✅ Yes (post-config)
Deployment Time	2-3 min	15-20 min	2-3 min + LVM setup
Multi-distro	❌ No	❌ No	✅ Yes
CLAUDE.md LVM	❌ No	✅ Yes	✅ Yes
Complexity	Low	Medium	High

Related Documentation

• Playbook: plays/deploy-debian-lvm-netinst.yml
• CLAUDE.md: LVM requirements and specifications
• Debian Preseed: https://wiki.debian.org/DebianInstaller/Preseed
• LVM Guide: https://wiki.debian.org/LVM

Support

For issues:

• Check installation logs: /var/log/installer/ on VM
• Review preseed: /tmp/preseed-debian-lvm-guest.cfg on hypervisor
• Monitor console: virsh console debian-lvm-guest
• Consult CLAUDE.md for LVM specifications