# CHANGELOG

## Version 2.0 - Production-Grade Improvements (2025-11-15)

### Major Changes

#### 1. Architecture Refactoring
- **ADDED**: Split `tasks/main.yml` into 6 modular task files
- **ADDED**: `tasks/preflight-checks.yml` - Environment validation
- **ADDED**: `tasks/download-image.yml` - Debian image with caching
- **ADDED**: `tasks/create-vm.yml` - Idempotent VM creation
- **ADDED**: `tasks/configure-vm.yml` - Disk, Cloud-Init, TPM, GPU
- **ADDED**: `tasks/create-template.yml` - Idempotent template conversion
- **ADDED**: `tasks/create-clones.yml` - Clone deployment with per-clone error handling
- **CHANGED**: `tasks/main.yml` now orchestrates subtasks via `include_tasks`
- **BENEFIT**: Each stage is independent, testable, and reusable

#### 2. Error Handling
- **ADDED**: Block/rescue error handling to all major operations
- **ADDED**: Automatic retry logic (3 retries, 5-second delays)
- **ADDED**: Context-aware error messages with next steps
- **ADDED**: Validation checks before operations
- **BENEFIT**: Clear failures with guidance, not silent errors

#### 3. Idempotency
- **ADDED**: Status checks before all state-changing operations
- **FIXED**: Template conversion (was broken on re-run)
  - Before: Used non-existent `.lock` file as idempotency marker
  - After: Checks actual `template: 1` flag in VM config
- **ADDED**: VM existence check before creation
- **ADDED**: Clone existence check before cloning
- **ADDED**: Image existence check before download
- **BENEFIT**: Safe to re-run playbook multiple times

#### 4. Pre-flight Validation
- **ADDED**: Comprehensive pre-flight checks (20+ validations)
  - Proxmox installation and version
  - User permissions for `qm` commands
  - Storage pool existence and accessibility
  - SSH key file existence and readability
  - VM ID uniqueness and format
  - Clone ID uniqueness and format
  - IP address format validation (CIDR)
  - Gateway IP validation
  - DNS server IP validation
  - Snippets directory existence
- **BENEFIT**: Fail fast with clear messages, not 50% through playbook

#### 5. Configuration Improvements
- **IMPROVED**: `defaults/main.yml` with extensive documentation
- **ADDED**: Retry and timeout configuration variables
- **ADDED**: Debug mode option
- **ADDED**: Security warnings and Vault integration example
- **CHANGED**: Better-organized variable sections with headers
- **BENEFIT**: Clear, maintainable configuration

#### 6. Task Enhancements

##### download-image.yml
- **ADDED**: Caching (skips re-download if exists)
- **ADDED**: Directory creation if missing
- **ADDED**: Automatic retry on download failure
- **ADDED**: Image integrity verification (size check)
- **ADDED**: Image info display (size, date)

##### create-vm.yml
- **ADDED**: VM existence check
- **ADDED**: Error handling with meaningful messages
- **ADDED**: Verification after creation
- **ADDED**: Status messages before and after

##### configure-vm.yml
- **ADDED**: Block/rescue for disk configuration
- **ADDED**: SSH key validation before use
- **ADDED**: Retry logic for disk import
- **ADDED**: Cloud-Init snippet validation
- **ADDED**: Separate blocks for TPM, disk, GPU configs
- **IMPROVED**: Better error recovery

##### create-template.yml
- **FIXED**: Idempotent template conversion (major fix!)
- **ADDED**: VM stop verification before conversion
- **ADDED**: Template status check
- **ADDED**: Proper error handling
- **CHANGED**: Skip if already templated

##### create-clones.yml
- **ADDED**: Per-clone error handling (loop with block/rescue)
- **ADDED**: Clone existence check
- **ADDED**: Clone list validation
- **ADDED**: Individual clone result reporting
- **BENEFIT**: One failed clone doesn't stop others

#### 7. Cloud-Init Improvements
- **ADDED**: SSH key readability check
- **ADDED**: Snippet file validation
- **IMPROVED**: Cloud-Init configuration application
- **BENEFIT**: Clear errors if configuration fails

#### 8. Helper Utilities
- **ADDED**: `tasks/helpers.yml` with reusable functions
  - `check_vm_exists` - Check if VM exists
  - `check_template` - Check if VM is template
  - `check_vm_status` - Get VM status
  - `check_storage` - Check storage space
  - `validate_vm_id` - Validate VM ID format
  - `get_vm_info` - Read VM configuration
  - `list_vms` - List all VMs
  - `cleanup_snippets` - Remove old snippets
- **BENEFIT**: Reusable functions for automation

#### 9. Logging & Visibility
- **ADDED**: Task naming convention `[STAGE] Action: description`
- **ADDED**: Progress banner at playbook start
- **ADDED**: Completion summary at playbook end
- **ADDED**: Per-operation status messages
- **ADDED**: Rich debug output throughout
- **BENEFIT**: Clear visibility into what's happening

#### 10. Documentation
- **ADDED**: `IMPROVEMENTS.md` - Detailed guide with before/after
- **ADDED**: `QUICK_REFERENCE.md` - Commands and troubleshooting
- **ADDED**: `IMPLEMENTATION_SUMMARY.md` - Overview and manifest
- **ADDED**: `CHANGELOG.md` - This file
- **ADDED**: Extensive inline comments in all task files
- **IMPROVED**: `defaults/main.yml` comments and structure

### Backward Compatibility

⚠️ **Breaking Changes**: None - role is backward compatible

- Old `create_clones` and `make_template` variables still work
- Old task structure wrapped in new modular approach
- All existing variables are preserved
- Default values unchanged

### Migration

1. Replace task files with new versions
2. Update `defaults/main.yml` (new options are optional)
3. Run `--tags preflight -vvv` to verify environment
4. Test with `--check` flag
5. Run normally

### Known Issues Fixed

| Issue | Before | After |
|-------|--------|-------|
| Template conversion fails on re-run | ❌ Broken | ✅ Idempotent |
| No validation of SSH key | ❌ Silent failure | ✅ Checked before use |
| One failed clone stops all clones | ❌ All-or-nothing | ✅ Per-clone handling |
| Poor error messages | ❌ Generic errors | ✅ Context-aware |
| No pre-flight validation | ❌ Fails mid-playbook | ✅ Early validation |
| Can't re-run playbook safely | ❌ Fails or duplicates | ✅ Idempotent |

### Performance Improvements

- **Image caching**: No re-download if already present
- **Selective execution**: Use tags to skip expensive operations
- **Retry logic**: Automatic recovery without manual intervention

### Testing Recommendations

```bash
# 1. Validate environment
ansible-playbook tasks/main.yml --tags preflight -vvv

# 2. Dry run
ansible-playbook tasks/main.yml --check -vv

# 3. Full test
ansible-playbook tasks/main.yml -vv

# 4. Verify idempotency (re-run)
ansible-playbook tasks/main.yml -vv

# 5. Add clones only
ansible-playbook tasks/main.yml --tags clones -vv
```

### Configuration Examples Added

- Minimal DHCP setup
- Production static IP setup
- TPM + Vault integration
- Multi-clone scenarios

### Security Enhancements

- SSH key validation before use
- Permissions checking for `qm` command
- Ansible Vault integration example
- Clear security warnings in comments

### Files Status

| File | Status | Notes |
|------|--------|-------|
| `tasks/main.yml` | Refactored | Now an orchestrator |
| `tasks/preflight-checks.yml` | New | 20+ checks |
| `tasks/download-image.yml` | Improved | Caching + validation |
| `tasks/create-vm.yml` | Improved | Idempotent + error handling |
| `tasks/configure-vm.yml` | Improved | Block/rescue for each feature |
| `tasks/create-template.yml` | Improved | Fixed idempotency bug |
| `tasks/create-clones.yml` | Improved | Per-clone error handling |
| `tasks/helpers.yml` | New | 8 utility functions |
| `defaults/main.yml` | Improved | Documentation + new options |
| `templates/cloudinit_userdata.yaml.j2` | Unchanged | No changes needed |
| `templates/cloudinit_vendor.yaml.j2` | Unchanged | No changes needed |
| `IMPROVEMENTS.md` | New | Comprehensive guide |
| `QUICK_REFERENCE.md` | New | Quick reference |
| `IMPLEMENTATION_SUMMARY.md` | New | Overview |
| `CHANGELOG.md` | New | This file |

### Deprecated

None - all old functionality is preserved

### Future Roadmap

- [ ] Molecule testing integration
- [ ] Terraform module wrapper
- [ ] Backup/restore functionality
- [ ] Notification callbacks (Slack, email)
- [ ] Performance metrics collection
- [ ] Cleanup/destroy role
- [ ] Galaxy package publishing
- [ ] Prometheus metrics export

### Thanks

To the Proxmox and Ansible communities for best practices and inspiration.

---

**Migration Status**: ✅ Ready for production use

**Testing**: Recommended in dev environment first

**Support**: See IMPROVEMENTS.md or QUICK_REFERENCE.md for issues