Sankofa/docs/proxmox/reference/IMAGE_INVENTORY.md

# Proxmox Image Inventory and Requirements

**Last Updated**: 2024-12-19

## Summary

All VM manifests and examples reference: **`ubuntu-22.04-cloud`**

## Required Images for Remaining Tasks

### Primary Image Required

**Image Name**: `ubuntu-22.04-cloud`  
**Type**: Cloud Image (qcow2 format)  
**Purpose**: Default OS image for all test VMs and examples  
**Required For**:
- TASK-015: Deploy test VMs via Crossplane
- TASK-016: End-to-end testing
- All example VM manifests

### Image References in Codebase

#### VM Manifests Using `ubuntu-22.04-cloud`:

1. **test-vm-instance-1.yaml** (ML110-01)
   - Image: `ubuntu-22.04-cloud`
   - Storage: `local-lvm`
   - Node: `ML110-01`
   - Site: `us-sfvalley`

2. **test-vm-instance-2.yaml** (R630-01)
   - Image: `ubuntu-22.04-cloud`
   - Storage: `local-lvm`
   - Node: `R630-01`
   - Site: `us-sfvalley-2`

3. **vm-example.yaml** (Example)
   - Image: `ubuntu-22.04-cloud`
   - Storage: `local-lvm`
   - Node: `ML110-01`
   - Site: `us-sfvalley`

4. **README.md** (Documentation)
   - Image: `ubuntu-22.04-cloud`
   - Default example image

5. **gitops/templates/vm/ubuntu-22.04.yaml**
   - Image: `ubuntu-22.04-cloud`
   - Template for VM creation

6. **gitops/templates/vm/ubuntu-20.04.yaml**
   - Image: `ubuntu-20.04-cloud`
   - Alternative template

## Image Availability Check

### Current Status

⚠️ **API-based image listing is limited**:
- Storage content endpoints require additional permissions
- Cannot verify images via API without proper access
- Images may exist but not be visible via current API tokens

### Verification Methods

1. **Proxmox Web UI**:
   - Log in to: https://ml110-01.sankofa.nexus:8006
   - Navigate to: **Datacenter** → **Storage** → Select storage → **Content**
   - Check for: `ubuntu-22.04-cloud` or similar

2. **SSH Command**:
   ```bash
   ssh root@192.168.11.10
   ls -lh /var/lib/vz/template/iso/
   ls -lh /var/lib/vz/template/cache/
   ```

3. **Proxmox Command**:
   ```bash
   pveam list local
   ```

## Image Download Instructions

### Method 1: Download via Proxmox Web UI

1. Log in to Proxmox Web UI
2. Go to: **Datacenter** → **Storage** → Select storage (e.g., `local`)
3. Click **Content** tab
4. Click **Templates** → **Download**
5. Search for: `ubuntu-22.04-standard`
6. Download template

### Method 2: Download via Command Line (SSH)

```bash
# SSH into Proxmox node
ssh root@192.168.11.10

# List available templates
pveam available

# Download Ubuntu 22.04 template
pveam download local ubuntu-22.04-standard_22.04-1_amd64.tar.gz

# Verify download
pveam list local
```

### Method 3: Download Cloud Image Manually

```bash
# Download Ubuntu 22.04 Cloud Image
wget https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img

# Upload to Proxmox storage
# Via Web UI: Storage → Content → Upload
# Or via API (see below)
```

### Method 4: Upload via API

```bash
source .env

# Upload ISO/image file
curl -k -H "Authorization: PVEAPIToken ${PROXMOX_TOKEN_ML110_01}" \
  -F "filename=@ubuntu-22.04-server-cloudimg-amd64.img" \
  "https://192.168.11.10:8006/api2/json/storage/local/upload"
```

## Image Requirements by Task

### TASK-015: Deploy Test VMs via Crossplane

**Required Images**:
- ✅ `ubuntu-22.04-cloud` (or equivalent)
- Storage: `local-lvm` (or configured storage pool)
- Location: Both ML110-01 and R630-01 (if using multi-site)

**Action**: Ensure image exists on both nodes before deployment

### TASK-016: End-to-End Testing

**Required Images**:
- ✅ `ubuntu-22.04-cloud` (primary)
- Optional: Additional OS images for testing diversity
  - `ubuntu-20.04-cloud`
  - `debian-12-standard`
  - `centos-stream-9-standard`

### TASK-019: Backup Procedures

**Required Images**:
- ✅ Test VM images for backup/restore testing
- Same images as TASK-015

## Image Naming Conventions

### Proxmox Template Names

- **Standard Templates**: `ubuntu-22.04-standard_22.04-1_amd64.tar.gz`
- **Cloud Images**: `ubuntu-22.04-cloud` (custom name)
- **ISO Files**: `ubuntu-22.04-server-amd64.iso`

### Storage Locations

- **Templates**: `/var/lib/vz/template/cache/`
- **ISO Files**: `/var/lib/vz/template/iso/`
- **Local Storage**: `local` (default)
- **LVM Storage**: `local-lvm` (for VM disks)

## Image Checklist

### For ML110-01 (us-sfvalley)

- [ ] `ubuntu-22.04-cloud` image available
- [ ] Image accessible from storage pool: `local-lvm`
- [ ] Image verified (can be used for VM creation)
- [ ] (Optional) Additional test images

### For R630-01 (us-sfvalley-2)

- [ ] `ubuntu-22.04-cloud` image available
- [ ] Image accessible from storage pool: `local-lvm`
- [ ] Image verified (can be used for VM creation)
- [ ] (Optional) Additional test images

## Image Verification Script

```bash
# Check if image exists (via SSH)
ssh root@192.168.11.10 "pveam list local | grep ubuntu-22.04"

# Check storage content (via API - may require permissions)
curl -k -H "Authorization: PVEAPIToken ${TOKEN}" \
  "https://192.168.11.10:8006/api2/json/storage/local/content"
```

## Next Steps

1. **Verify Image Availability**:
   - Check via Web UI or SSH
   - Use `pveam list local` command

2. **Download Missing Images**:
   - Use `pveam download` command
   - Or download from official sources and upload

3. **Update Manifests** (if needed):
   - If image name differs, update VM manifests
   - Ensure image name matches actual file name

4. **Test Image**:
   - Create a test VM using the image
   - Verify VM boots correctly
   - Verify cloud-init works (if using cloud images)

## Related Documentation

- [Image Requirements](./IMAGE_REQUIREMENTS.md)
- [Task List](./TASK_LIST.md)
- [VM Provisioning Runbook](../runbooks/PROXMOX_VM_PROVISIONING.md)