infra-automation/cheatsheets/roles/deploy_linux_vm.md

Deploy Linux VM Role Cheatsheet

Quick reference guide for the deploy_linux_vm role - automated Linux VM deployment on KVM hypervisors with LVM and security hardening.

Quick Start

# Deploy a VM with defaults (Debian 12)
ansible-playbook site.yml -t deploy_linux_vm

# Deploy specific distribution
ansible-playbook site.yml -t deploy_linux_vm \
  -e "deploy_linux_vm_os_distribution=ubuntu-22.04"

# Deploy with custom resources
ansible-playbook site.yml -t deploy_linux_vm \
  -e "deploy_linux_vm_name=webserver01" \
  -e "deploy_linux_vm_vcpus=4" \
  -e "deploy_linux_vm_memory_mb=8192"

Common Execution Patterns

Basic Deployment

# Single VM deployment
ansible-playbook -i inventories/production site.yml -t deploy_linux_vm

# Deploy to specific hypervisor
ansible-playbook site.yml -l grokbox -t deploy_linux_vm

# Check mode (dry-run validation)
ansible-playbook site.yml -t deploy_linux_vm --check

Distribution-Specific Deployment

# Debian family
ansible-playbook site.yml -t deploy_linux_vm \
  -e "deploy_linux_vm_os_distribution=debian-12"

ansible-playbook site.yml -t deploy_linux_vm \
  -e "deploy_linux_vm_os_distribution=ubuntu-24.04"

# RHEL family
ansible-playbook site.yml -t deploy_linux_vm \
  -e "deploy_linux_vm_os_distribution=almalinux-9"

ansible-playbook site.yml -t deploy_linux_vm \
  -e "deploy_linux_vm_os_distribution=rocky-9"

# SUSE family
ansible-playbook site.yml -t deploy_linux_vm \
  -e "deploy_linux_vm_os_distribution=opensuse-leap-15.6"

Selective Execution with Tags

# Pre-flight validation only
ansible-playbook site.yml -t deploy_linux_vm,validate,preflight

# Download cloud images only
ansible-playbook site.yml -t deploy_linux_vm,download,verify

# Deploy VM without LVM configuration
ansible-playbook site.yml -t deploy_linux_vm --skip-tags lvm

# Configure LVM only (post-deployment)
ansible-playbook site.yml -t deploy_linux_vm,lvm,post-deploy

# Cleanup temporary files only
ansible-playbook site.yml -t deploy_linux_vm,cleanup

Available Tags

Tag	Description
deploy_linux_vm	Main role tag (required)
validate, preflight	Pre-flight validation checks
install	Install required packages on hypervisor
download, verify	Download and verify cloud images
storage	Create VM disk storage
cloud-init	Generate cloud-init configuration
deploy	Deploy and start VM
lvm, post-deploy	Configure LVM on deployed VM
cleanup	Remove temporary files

Common Variables

VM Configuration

# Basic VM settings
deploy_linux_vm_name: "webserver01"
deploy_linux_vm_hostname: "web01"
deploy_linux_vm_domain: "production.local"
deploy_linux_vm_os_distribution: "ubuntu-22.04"

# Resource allocation
deploy_linux_vm_vcpus: 4
deploy_linux_vm_memory_mb: 8192
deploy_linux_vm_disk_size_gb: 50

LVM Configuration

# Enable/disable LVM
deploy_linux_vm_use_lvm: true

# LVM volume group settings
deploy_linux_vm_lvm_vg_name: "vg_system"
deploy_linux_vm_lvm_pv_device: "/dev/vdb"

# Custom logical volumes (override defaults)
deploy_linux_vm_lvm_volumes:
  - { name: lv_opt, size: 5G, mount: /opt, fstype: ext4 }
  - { name: lv_var, size: 10G, mount: /var, fstype: ext4 }
  - { name: lv_tmp, size: 2G, mount: /tmp, fstype: ext4, mount_options: noexec,nosuid,nodev }

Security Configuration

# Security hardening toggles
deploy_linux_vm_enable_firewall: true
deploy_linux_vm_enable_selinux: true          # RHEL family
deploy_linux_vm_enable_apparmor: true         # Debian family
deploy_linux_vm_enable_auditd: true
deploy_linux_vm_enable_automatic_updates: true
deploy_linux_vm_automatic_reboot: false       # Don't auto-reboot

# SSH hardening
deploy_linux_vm_ssh_permit_root_login: "no"
deploy_linux_vm_ssh_password_authentication: "no"
deploy_linux_vm_ssh_gssapi_authentication: "no"  # GSSAPI disabled per requirements

User Configuration

# Ansible service account
deploy_linux_vm_ansible_user: "ansible"
deploy_linux_vm_ansible_user_ssh_key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"

# Root password (console access only, SSH disabled)
deploy_linux_vm_root_password: "ChangeMe123!"

Supported Distributions

Distribution	Version	OS Family	Identifier
Debian	11, 12	debian	debian-11, debian-12
Ubuntu LTS	20.04, 22.04, 24.04	debian	ubuntu-20.04, ubuntu-22.04, ubuntu-24.04
RHEL	8, 9	rhel	rhel-8, rhel-9
AlmaLinux	8, 9	rhel	almalinux-8, almalinux-9
Rocky Linux	8, 9	rhel	rocky-8, rocky-9
openSUSE Leap	15.5, 15.6	suse	opensuse-leap-15.5, opensuse-leap-15.6

Example Playbooks

Single VM Deployment

---
- name: Deploy Linux VM
  hosts: grokbox
  become: yes
  roles:
    - role: deploy_linux_vm
      vars:
        deploy_linux_vm_name: "web-server"
        deploy_linux_vm_os_distribution: "ubuntu-22.04"

Multi-VM Deployment

---
- name: Deploy Multiple VMs
  hosts: grokbox
  become: yes
  tasks:
    - name: Deploy web servers
      include_role:
        name: deploy_linux_vm
      vars:
        deploy_linux_vm_name: "{{ item.name }}"
        deploy_linux_vm_hostname: "{{ item.hostname }}"
        deploy_linux_vm_os_distribution: "{{ item.distro }}"
      loop:
        - { name: "web01", hostname: "web01", distro: "ubuntu-22.04" }
        - { name: "web02", hostname: "web02", distro: "ubuntu-22.04" }
        - { name: "db01", hostname: "db01", distro: "almalinux-9" }

Database Server with Custom Resources

---
- name: Deploy Database Server
  hosts: grokbox
  become: yes
  roles:
    - role: deploy_linux_vm
      vars:
        deploy_linux_vm_name: "postgres01"
        deploy_linux_vm_hostname: "postgres01"
        deploy_linux_vm_domain: "production.local"
        deploy_linux_vm_os_distribution: "almalinux-9"
        deploy_linux_vm_vcpus: 8
        deploy_linux_vm_memory_mb: 16384
        deploy_linux_vm_disk_size_gb: 100
        deploy_linux_vm_use_lvm: true

Post-Deployment Verification

Check VM Status

# List all VMs on hypervisor
ansible grokbox -m shell -a "virsh list --all"

# Get VM information
ansible grokbox -m shell -a "virsh dominfo <vm_name>"

# Get VM IP address
ansible grokbox -m shell -a "virsh domifaddr <vm_name>"

Verify SSH Access

# Test SSH connectivity
ssh ansible@<VM_IP>

# Test with ProxyJump through hypervisor
ssh -J grokbox ansible@<VM_IP>

Verify LVM Configuration

# SSH to VM and check LVM
ssh ansible@<VM_IP> "sudo vgs && sudo lvs && sudo pvs"

# Check fstab entries
ssh ansible@<VM_IP> "cat /etc/fstab"

# Check disk layout
ssh ansible@<VM_IP> "lsblk"

# Check mounted filesystems
ssh ansible@<VM_IP> "df -h"

Verify Security Hardening

# Check SSH configuration
ssh ansible@<VM_IP> "sudo sshd -T | grep -i gssapi"

# Check firewall (Debian/Ubuntu)
ssh ansible@<VM_IP> "sudo ufw status verbose"

# Check firewall (RHEL/AlmaLinux)
ssh ansible@<VM_IP> "sudo firewall-cmd --list-all"

# Check SELinux status (RHEL family)
ssh ansible@<VM_IP> "sudo getenforce"

# Check AppArmor status (Debian family)
ssh ansible@<VM_IP> "sudo aa-status"

# Check auditd
ssh ansible@<VM_IP> "sudo systemctl status auditd"

# Check automatic updates (Debian/Ubuntu)
ssh ansible@<VM_IP> "sudo systemctl status unattended-upgrades"

# Check automatic updates (RHEL/AlmaLinux)
ssh ansible@<VM_IP> "sudo systemctl status dnf-automatic.timer"

Troubleshooting

Check Cloud-Init Status

# Wait for cloud-init to complete
ssh ansible@<VM_IP> "cloud-init status --wait"

# View cloud-init logs
ssh ansible@<VM_IP> "tail -100 /var/log/cloud-init-output.log"

# Check cloud-init errors
ssh ansible@<VM_IP> "cloud-init analyze show"

VM Won't Start

# Check VM status
ansible grokbox -m shell -a "virsh list --all"

# View VM console logs
ansible grokbox -m shell -a "virsh console <vm_name>"

# Check libvirt logs
ansible grokbox -m shell -a "tail -50 /var/log/libvirt/qemu/<vm_name>.log"

LVM Issues

# Check LVM status
ssh ansible@<VM_IP> "sudo pvs && sudo vgs && sudo lvs"

# Check if second disk exists
ssh ansible@<VM_IP> "lsblk"

# Manually trigger LVM setup (if post-deploy failed)
ansible-playbook site.yml -l grokbox -t deploy_linux_vm,lvm,post-deploy \
  -e "deploy_linux_vm_name=<vm_name>"

Network Connectivity Issues

# Check VM network interfaces
ssh ansible@<VM_IP> "ip addr show"

# Check VM can reach internet
ssh ansible@<VM_IP> "ping -c 3 8.8.8.8"

# Check DNS resolution
ssh ansible@<VM_IP> "nslookup google.com"

# Check libvirt network
ansible grokbox -m shell -a "virsh net-list --all"
ansible grokbox -m shell -a "virsh net-dhcp-leases default"

SSH Connection Refused

# Check if sshd is running
ssh ansible@<VM_IP> "sudo systemctl status sshd"

# Check firewall rules
ssh ansible@<VM_IP> "sudo ufw status" # Debian/Ubuntu
ssh ansible@<VM_IP> "sudo firewall-cmd --list-services" # RHEL

# Check SSH port listening
ssh ansible@<VM_IP> "sudo ss -tlnp | grep :22"

Disk Space Issues

# Check hypervisor disk space
ansible grokbox -m shell -a "df -h /var/lib/libvirt/images"

# Check VM disk space
ssh ansible@<VM_IP> "df -h"

# List large files
ssh ansible@<VM_IP> "sudo du -sh /* | sort -h"

VM Management

Start/Stop/Reboot VM

# Start VM
ansible grokbox -m shell -a "virsh start <vm_name>"

# Shutdown VM gracefully
ansible grokbox -m shell -a "virsh shutdown <vm_name>"

# Force stop VM
ansible grokbox -m shell -a "virsh destroy <vm_name>"

# Reboot VM
ansible grokbox -m shell -a "virsh reboot <vm_name>"

# Enable autostart
ansible grokbox -m shell -a "virsh autostart <vm_name>"

Delete VM

# Stop and delete VM (DESTRUCTIVE)
ansible grokbox -m shell -a "virsh destroy <vm_name>"
ansible grokbox -m shell -a "virsh undefine <vm_name> --remove-all-storage"

VM Snapshots

# Create snapshot
ansible grokbox -m shell -a "virsh snapshot-create-as <vm_name> snapshot1 'Before updates'"

# List snapshots
ansible grokbox -m shell -a "virsh snapshot-list <vm_name>"

# Restore snapshot
ansible grokbox -m shell -a "virsh snapshot-revert <vm_name> snapshot1"

# Delete snapshot
ansible grokbox -m shell -a "virsh snapshot-delete <vm_name> snapshot1"

Performance Optimization

Parallel Deployment

# Deploy multiple VMs in parallel (default: 5 at a time)
ansible-playbook site.yml -t deploy_linux_vm -f 5

# Serial deployment (one at a time)
ansible-playbook site.yml -t deploy_linux_vm -f 1

Skip Slow Operations

# Skip package installation (if already installed)
ansible-playbook site.yml -t deploy_linux_vm --skip-tags install

# Skip image download (if already cached)
ansible-playbook site.yml -t deploy_linux_vm --skip-tags download

Security Checkpoints

• ✓ SSH root login disabled via SSH (console access available)
• ✓ SSH password authentication disabled (key-based only)
• ✓ GSSAPI authentication disabled per requirements
• ✓ Firewall enabled (UFW/firewalld) with SSH allowed
• ✓ SELinux enforcing (RHEL family) or AppArmor enabled (Debian family)
• ✓ Automatic security updates enabled (no auto-reboot by default)
• ✓ Audit daemon (auditd) enabled
• ✓ LVM with secure mount options (/tmp with noexec,nosuid,nodev)
• ✓ Essential security packages installed (aide, auditd, chrony)
• ✓ Ansible service account with passwordless sudo (logged)

Quick Reference Commands

# Standard deployment
ansible-playbook site.yml -t deploy_linux_vm

# Custom VM
ansible-playbook site.yml -t deploy_linux_vm \
  -e "deploy_linux_vm_name=myvm" \
  -e "deploy_linux_vm_os_distribution=ubuntu-22.04"

# Pre-flight check only
ansible-playbook site.yml -t deploy_linux_vm,validate --check

# Deploy without LVM
ansible-playbook site.yml -t deploy_linux_vm --skip-tags lvm

# Configure LVM post-deployment
ansible-playbook site.yml -t deploy_linux_vm,lvm

# Get VM IP
ansible grokbox -m shell -a "virsh domifaddr <vm_name>"

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

# Check VM status
ansible grokbox -m shell -a "virsh list --all"

File Locations

On Hypervisor:

• Cloud images: /var/lib/libvirt/images/*.qcow2
• VM disk: /var/lib/libvirt/images/<vm_name>.qcow2
• LVM disk: /var/lib/libvirt/images/<vm_name>-lvm.qcow2
• Cloud-init ISO: /var/lib/libvirt/images/<vm_name>-cloud-init.iso

On Deployed VM:

• SSH config: /etc/ssh/sshd_config.d/99-security.conf
• Sudoers: /etc/sudoers.d/ansible
• Cloud-init log: /var/log/cloud-init-output.log
• Fstab: /etc/fstab (LVM mounts)

See Also

• Role README
• Role Documentation
• Linux VM Deployment Runbook
• CLAUDE.md Guidelines

---

Role: deploy_linux_vm v1.0.0 Updated: 2025-11-11 Documentation: See roles/deploy_linux_vm/README.md and docs/roles/deploy_linux_vm.md