# 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