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
```bash
ansible-playbook plays/deploy-debian-lvm-netinst.yml
```

### Custom Configuration
```bash
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

```bash
# 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
```bash
# 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
```bash
# Get VM IP
ssh grokbox "virsh domifaddr debian-lvm-guest"

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

### Access VM
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:

```bash
# 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
```bash
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
```bash
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