ansible_proxmox_VM/QUICK_REFERENCE.md

Quick Reference Guide

Key Improvements at a Glance

Error Handling

# All major operations now have try-catch blocks
block:
  - name: "Try operation"
    command: ...
rescue:
  - name: "Handle error with context"
    fail:
      msg: "Clear error message"

Idempotency

# All operations check before acting
- stat: path="/path/to/resource"
  register: resource
- command: "create resource"
  when: not resource.stat.exists

Pre-flight Validation

ansible-playbook tasks/main.yml --tags preflight
# Validates: Proxmox, storage, SSH keys, IP addresses, permissions

---

Run Commands

Command	Purpose
ansible-playbook tasks/main.yml	Full deployment
ansible-playbook tasks/main.yml --tags preflight	Validate only
ansible-playbook tasks/main.yml --tags image,vm	VM creation only
ansible-playbook tasks/main.yml --tags clones	Clone deployment only
ansible-playbook tasks/main.yml --check	Dry run (no changes)
ansible-playbook tasks/main.yml -vvv	Verbose debug output

---

Task Stages

1. STAGE 1: preflight-checks.yml - Validate environment
2. STAGE 2: download-image.yml - Cache Debian image
3. STAGE 3: create-vm.yml - Create base VM
4. STAGE 4: configure-vm.yml - Configure disk, networking, Cloud-Init
5. STAGE 5: create-template.yml - Convert to template (idempotent)
6. STAGE 6: create-clones.yml - Deploy clones

---

File Changes Summary

File	Status	Key Changes
tasks/main.yml	Refactored	Now orchestrates subtasks
tasks/preflight-checks.yml	New	Environment validation
tasks/download-image.yml	Improved	Retry logic, validation
tasks/create-vm.yml	Improved	Error handling, idempotency
tasks/configure-vm.yml	Improved	Disk, Cloud-Init, TPM, GPU
tasks/create-template.yml	Improved	Idempotent template conversion
tasks/create-clones.yml	Improved	Per-clone error handling
tasks/helpers.yml	New	Utility functions
defaults/main.yml	Improved	Better docs, new options
IMPROVEMENTS.md	New	Complete guide

---

Before vs After Examples

Idempotent Template Conversion

Before ❌

- name: Convert VM to template
  command: qm template {{ vm_id }}
  args:
    creates: "/etc/pve/qemu-server/{{ vm_id }}.conf.lock"
  # .lock doesn't exist → always runs → fails on re-run

After ✅

- name: "[TEMPLATE] Check if VM is already a template"
  shell: "qm config {{ vm_id }} | grep -q 'template: 1'"
  register: is_template
  failed_when: false

- name: "[TEMPLATE] Convert VM to template"
  command: "qm template {{ vm_id }}"
  when: is_template.rc != 0
  # Checks actual template status → safe to re-run

Error Handling

Before ❌

- name: Import disk
  command: qm importdisk {{ vm_id }} {{ image_path }} {{ storage }}
  # Fails with generic error, no recovery

After ✅

- name: "[CONFIG] Import qcow2 disk"
  command: qm importdisk ...
  register: disk_import
  retries: 3           # Try 3 times
  delay: 5             # Wait 5 seconds between tries
  until: disk_import is succeeded

- rescue:
  - name: "[CONFIG] Handle disk configuration error"
    fail:
      msg: "Failed to configure disk for VM {{ vm_id }}: ..."
  # Clear context, automatic retries

Validation

Before ❌

# No checks, script fails mysteriously

After ✅

# Pre-flight checks:
[PREFLIGHT] Check if running on Proxmox host
[PREFLIGHT] Verify qm command is available
[PREFLIGHT] Check if user can run qm commands
[PREFLIGHT] Verify storage pool exists
[PREFLIGHT] Check SSH key file exists
[PREFLIGHT] Validate VM ID is unique
[PREFLIGHT] Validate clone IDs are unique
[PREFLIGHT] Validate IP address format
# All failing fast with context

---

Security Notes

1. Passwords: Use Ansible Vault for ci_password

   ansible-vault create group_vars/proxmox/vault.yml
   

2. SSH Keys: Automatically validated before use

3. Permissions: Warns if user can't run qm commands

---

Performance Tips

1. Use linked clones (full: 0) for faster deployments
2. Tag-based execution to skip unnecessary stages
3. Caching of Debian image to avoid re-downloads
4. Parallel cloning (multiple --tags clones invocations)

---

Troubleshooting Commands

# Check Proxmox version
qm version

# List all VMs
qm list

# Check specific VM
qm config 150

# Check storage
pvesm status local-lvm

# Check Cloud-Init status (inside VM)
cloud-init status
cloud-init logs -f

---

Got Issues?

1. Check IMPROVEMENTS.md for detailed explanation
2. Run --tags preflight -vvv to see exact validation errors
3. Check inline comments in each task file
4. Review Proxmox logs: journalctl -u pveproxy -f

---

Version: 2.0 (Improved with error handling & idempotency) Last Updated: 2025-11-15