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

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

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

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

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

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

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

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

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

```yaml
---
- 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

```yaml
---
- 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

```yaml
---
- 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

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

```bash
# Test SSH connectivity
ssh ansible@<VM_IP>

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

### Verify LVM Configuration

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

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

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

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

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

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

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

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

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

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

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

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

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

```bash
# 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](../../roles/deploy_linux_vm/README.md)
- [Role Documentation](../../docs/roles/deploy_linux_vm.md)
- [Linux VM Deployment Runbook](../../docs/runbooks/deployment.md)
- [CLAUDE.md Guidelines](../../CLAUDE.md)

---

**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`