feat: Implement Debian VM template creation and cloning on Proxmox

- Added default configuration for VM creation in defaults/main.yml.
- Created tasks for configuring the VM with UEFI, TPM, disks, GPU, and Cloud-Init in tasks/configure-vm.yml.
- Implemented clone creation and configuration logic in tasks/create-clones.yml.
- Added template conversion functionality in tasks/create-template.yml.
- Developed base VM creation logic in tasks/create-vm.yml.
- Included image download and caching tasks in tasks/download-image.yml.
- Introduced utility tasks for common operations in tasks/helpers.yml.
- Organized main orchestration logic in tasks/main.yml, with clear stages for each operation.
- Added pre-flight checks to validate the environment before execution in tasks/preflight-checks.yml.

QUICK_REFERENCE.md

@@ -0,0 +1,203 @@
+# Quick Reference Guide
+
+## Key Improvements at a Glance
+
+### Error Handling
+```yaml
+# 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
+```yaml
+# All operations check before acting
+- stat: path="/path/to/resource"
+  register: resource
+- command: "create resource"
+  when: not resource.stat.exists
+```
+
+### Pre-flight Validation
+```bash
+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** ❌
+```yaml
+- 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** ✅
+```yaml
+- 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** ❌
+```yaml
+- name: Import disk
+  command: qm importdisk {{ vm_id }} {{ image_path }} {{ storage }}
+  # Fails with generic error, no recovery
+```
+
+**After** ✅
+```yaml
+- 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** ❌
+```yaml
+# No checks, script fails mysteriously
+```
+
+**After** ✅
+```yaml
+# 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`
+   ```bash
+   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
+
+```bash
+# 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