# Debian 12 VM Deployment Cheatsheet

## Quick Deployment

### Basic Deployment
```bash
# Deploy VM with default settings
ansible-playbook plays/deploy-debian12-vm.yml

# Deploy with custom VM name
ansible-playbook plays/deploy-debian12-vm.yml -e "vm_name=myvm"
```

### Custom Configuration
```bash
# Deploy with custom resources
ansible-playbook plays/deploy-debian12-vm.yml \
  -e "vm_name=custom-vm" \
  -e "vm_vcpus=4" \
  -e "vm_memory_mb=4096" \
  -e "vm_disk_size_gb=50"

# Deploy with custom network
ansible-playbook plays/deploy-debian12-vm.yml \
  -e "vm_name=web-server" \
  -e "vm_network=default" \
  -e "vm_hostname=webserver" \
  -e "vm_domain=example.com"
```

## Tag-Based Execution

### Selective Deployment Steps
```bash
# Pre-flight checks only
ansible-playbook plays/deploy-debian12-vm.yml -t preflight,validate

# Download image only
ansible-playbook plays/deploy-debian12-vm.yml -t download

# Verify image checksum
ansible-playbook plays/deploy-debian12-vm.yml -t verify

# Create storage only
ansible-playbook plays/deploy-debian12-vm.yml -t storage

# Generate cloud-init config only
ansible-playbook plays/deploy-debian12-vm.yml -t cloud-init

# Deploy VM (skip download if image exists)
ansible-playbook plays/deploy-debian12-vm.yml -t deploy

# Validation only
ansible-playbook plays/deploy-debian12-vm.yml -t validate

# Cleanup temporary files
ansible-playbook plays/deploy-debian12-vm.yml -t cleanup
```

### Debug Mode
```bash
# Show console output (use with caution)
ansible-playbook plays/deploy-debian12-vm.yml -t debug
```

## Common Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `vm_name` | debian12-guest | VM name in libvirt |
| `vm_hostname` | debian12 | VM hostname |
| `vm_domain` | localdomain | Domain name |
| `vm_vcpus` | 2 | Number of vCPUs |
| `vm_memory_mb` | 2048 | RAM in MB |
| `vm_disk_size_gb` | 20 | Disk size in GB |
| `vm_network` | default | Libvirt network |
| `vm_bridge` | virbr0 | Bridge interface |
| `ansible_user_ssh_key` | (predefined) | SSH public key for ansible user |

## Post-Deployment

### Access the VM
```bash
# Get VM IP address
virsh domifaddr debian12-guest

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

# Direct SSH (from grokbox)
ssh ansible@<VM_IP>
```

### VM Management
```bash
# Start VM
virsh start debian12-guest

# Stop VM
virsh shutdown debian12-guest

# Force stop VM
virsh destroy debian12-guest

# Remove VM
virsh undefine debian12-guest --remove-all-storage

# VM status
virsh dominfo debian12-guest

# List all VMs
virsh list --all

# VM console access
virsh console debian12-guest
```

### Add to Inventory

Add the deployed VM to your Ansible inventory:

```yaml
# inventories/development/hosts.yml
kvm_guests:
  children:
    development:
      hosts:
        debian12-guest:
          ansible_host: 192.168.122.XX
          ansible_user: ansible
          ansible_ssh_common_args: '-o ProxyJump=grokbox -o StrictHostKeyChecking=accept-new'
          host_description: "Debian 12 Development VM"
          host_role: development
          vm_vcpus: 2
          vm_memory_mb: 2048
```

## Troubleshooting

### Check Cloud-Init Status
```bash
# On the VM
cloud-init status
cloud-init status --wait
cloud-init status --long

# View cloud-init logs
cat /var/log/cloud-init.log
cat /var/log/cloud-init-output.log
```

### Network Issues
```bash
# Check VM network interface
virsh domiflist debian12-guest

# Check VM IP
virsh domifaddr debian12-guest

# Check network connectivity from grokbox
ping <VM_IP>
```

### VM Console Access
```bash
# Connect to serial console
virsh console debian12-guest

# Disconnect: Ctrl + ]
```

### Storage Issues
```bash
# Check VM disk
virsh domblklist debian12-guest

# Check disk usage on hypervisor
qemu-img info /var/lib/libvirt/images/debian12-guest.qcow2

# Resize disk (if needed, after deployment)
qemu-img resize /var/lib/libvirt/images/debian12-guest.qcow2 +10G
```

### VM Won't Start
```bash
# Check libvirt logs
journalctl -u libvirtd -f

# Check VM XML configuration
virsh dumpxml debian12-guest

# Validate VM configuration
virt-xml-validate /etc/libvirt/qemu/debian12-guest.xml
```

### SSH Connection Issues
```bash
# Test SSH connectivity
ssh -vvv -J grokbox ansible@<VM_IP>

# Check SSH service on VM (via console)
virsh console debian12-guest
# Then: systemctl status ssh
```

## Security Features

The deployed VM includes:

- ✅ Ansible user with passwordless sudo
- ✅ SSH key-based authentication only
- ✅ Root login disabled via SSH
- ✅ UFW firewall enabled (SSH allowed)
- ✅ Automatic security updates configured
- ✅ Audit daemon (auditd) enabled
- ✅ Time synchronization (chrony)
- ✅ Essential security packages installed
- ✅ AIDE for file integrity monitoring
- ✅ Secure SSH configuration

## Package List

### Essential Packages
- sudo, vim, htop, tmux
- curl, wget, rsync, git
- python3, python3-pip
- jq, bc

### Security Packages
- aide (file integrity)
- auditd (system auditing)
- ufw (firewall)
- unattended-upgrades

### System Packages
- chrony (time sync)
- lvm2 (storage management)
- cloud-guest-utils
- parted

## Validation Checklist

After deployment, verify:

- [ ] VM is running: `virsh list`
- [ ] VM has IP address: `virsh domifaddr debian12-guest`
- [ ] SSH accessible: `ssh -J grokbox ansible@<VM_IP>`
- [ ] Cloud-init completed: `cloud-init status`
- [ ] Security updates enabled: `systemctl status unattended-upgrades`
- [ ] Firewall enabled: `sudo ufw status`
- [ ] Time sync working: `chronyc tracking`
- [ ] Audit daemon running: `systemctl status auditd`

## Next Steps

1. Add VM to Ansible inventory
2. Run configuration management roles
3. Configure application-specific settings
4. Set up monitoring and logging
5. Configure backups
6. Document VM purpose and services

## Quick Reference

### Deployment Flow
1. **Preflight** → Check if VM exists, validate virtualization
2. **Install** → Install required packages on hypervisor
3. **Download** → Download Debian 12 cloud image
4. **Storage** → Create VM disk from cloud image
5. **Cloud-Init** → Generate cloud-init configuration
6. **Deploy** → Create and start VM
7. **Validate** → Verify SSH connectivity and system status
8. **Cleanup** → Remove temporary files

### Important Paths
- VM Disk: `/var/lib/libvirt/images/debian12-guest.qcow2`
- Cloud-Init ISO: `/var/lib/libvirt/images/debian12-guest-cloud-init.iso`
- Base Image: `/var/lib/libvirt/images/debian-12-generic-amd64.qcow2`
- VM Config: `/etc/libvirt/qemu/debian12-guest.xml`

### Support
For issues or questions:
- Check `/var/log/cloud-init.log` on VM
- Check `journalctl -u libvirtd` on hypervisor
- Review playbook documentation: `plays/deploy-debian12-vm.yml`
- Consult CLAUDE.md for infrastructure guidelines