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

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

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)

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

# On Proxmox node
qm disk import <vmid> local:iso/ubuntu-22.04-cloud.img local-lvm vm-100-disk-0

Then use:

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