infra-automation/cheatsheets/deploy-debian12-vm.md

Debian 12 VM Deployment Cheatsheet

Quick Deployment

Basic Deployment

# 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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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

# Connect to serial console
virsh console debian12-guest

# Disconnect: Ctrl + ]

Storage Issues

# 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

# 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

# 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