Sankofa/docs/VM_TEMPLATE_REVIEW_SUMMARY.md

# VM Template Review Summary

**Date**: 2025-12-11  
**Action**: Reviewed all VM templates for image configuration issues

---

## Template Image Format Analysis

### Current State

**Total Templates**: 29 production templates

### Image Format Distribution

1. **Volid Format** (1 template):
   - `vm-100.yaml`: `local:iso/ubuntu-22.04-cloud.img`
   - ⚠️ **Issue**: Triggers `importdisk` API, causes lock timeouts

2. **Search Format** (28 templates):
   - All others: `ubuntu-22.04-cloud`
   - ⚠️ **Issue**: Provider searches storage, can timeout if image not found

---

## Root Cause

### Problem 1: Volid Format with .img Extension
```yaml
image: "local:iso/ubuntu-22.04-cloud.img"
```

**Provider Behavior**:
1. Detects volid format (contains `:`)
2. Detects `.img` extension → triggers `importdisk`
3. Creates VM with blank disk
4. Calls `importdisk` API → **holds lock**
5. Tries to update config → **fails (locked)**
6. Lock never releases → **VM stuck**

### Problem 2: Search Format
```yaml
image: "ubuntu-22.04-cloud"
```

**Provider Behavior**:
1. Searches all storage pools for image
2. Storage operations can timeout
3. If not found → VM created without disk
4. If found → may still trigger import if `.img` extension

---

## Available Images in Storage

From Proxmox node:
- ✅ `local:iso/ubuntu-22.04-cloud.img` (660M) - Cloud image
- ✅ `local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst` (124M) - Template

---

## Recommended Solutions

### Option 1: Use Existing Template (Recommended)
```yaml
image: "local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst"
```

**Advantages**:
- ✅ Direct template usage (no import)
- ✅ Faster VM creation
- ✅ No lock issues
- ✅ Already in storage

**Disadvantages**:
- ❌ Standard Ubuntu (not cloud-init optimized)
- ❌ May need manual cloud-init setup

### Option 2: Pre-import Cloud Image to local-lvm
```bash
# On Proxmox node
qm disk import <vmid> local:iso/ubuntu-22.04-cloud.img local-lvm vm-100-disk-0
```

Then use:
```yaml
image: "local-lvm:vm-100-disk-0"
```

**Advantages**:
- ✅ Cloud-init ready
- ✅ Faster than importdisk during creation

**Disadvantages**:
- ❌ Requires manual pre-import
- ❌ Image tied to specific storage

### Option 3: Fix Provider Code (Long-term)
- Add task monitoring for `importdisk`
- Wait for import completion before config updates
- Better lock management and timeout handling

---

## Templates Requiring Update

### High Priority (Currently Broken)
1. `vm-100.yaml` - Uses volid format, triggers importdisk

### Medium Priority (May Have Issues)
All 28 templates using `ubuntu-22.04-cloud`:
- May fail if image not found in storage
- May timeout during storage search

---

## Action Plan

### Immediate
1. ✅ **VMs 100 and 101 removed**
2. ⏳ **Update `vm-100.yaml`** to use template format
3. ⏳ **Test VM creation** with new format
4. ⏳ **Decide on image strategy** for all templates

### Short-term
1. Review all templates
2. Standardize image format
3. Document image requirements
4. Test VM creation workflow

### Long-term
1. Enhance provider code for importdisk handling
2. Add image pre-import automation
3. Create image management documentation

---

## Verification Checklist

After template updates:

- [ ] VM creates successfully
- [ ] Disk is attached (`scsi0` configured)
- [ ] Boot order is set (`boot: order=scsi0`)
- [ ] Guest agent enabled (`agent: 1`)
- [ ] Cloud-init configured (`ide2` present)
- [ ] Network configured (`net0` present)
- [ ] VM can start and boot
- [ ] No lock issues

---

## Related Documentation

- `docs/VM_TEMPLATE_IMAGE_ISSUE_ANALYSIS.md` - Detailed technical analysis
- `crossplane-provider-proxmox/pkg/proxmox/client.go` - Provider code
- `examples/production/vm-100.yaml` - Problematic template
- `examples/production/basic-vm.yaml` - Base template

---

**Status**: ✅ **VMs REMOVED** | ⚠️ **TEMPLATES NEED UPDATE**