# Proxmox Integration - Quick Reference **Version:** v1.2.0 **Status:** Planning ✓ | Implementation: Pending --- ## Core Concepts ### Port Configuration | Service | Default Port | API Endpoint | |---------|--------------|--------------| | Proxmox VE | **8006** | `https://hostname:8006/api2/json` | | Proxmox Backup Server | **8007** | `https://hostname:8007/api2/json` | **Implementation:** - Default port set by cluster type (8006 for VE, 8007 for PBS) - User can override port if needed - Port displayed in cluster configuration UI ### Authentication Flow ``` User Input → Root Credentials → Proxmox API → API Token → Encrypted Storage ↓ SSL Fingerprint Verification (Optional) ``` ### Data Flow ``` Proxmox Cluster (port 8006 for VE, 8007 for PBS) ↓ HTTPS API ProxmoxClient (cached in memory) ↓ Encrypted Token Database (SQLite + AES-256-GCM) ``` --- ## Key Files ### Backend | File | Purpose | |------|---------| | `src-tauri/src/proxmox/mod.rs` | Module exports | | `src-tauri/src/proxmox/client.rs` | Proxmox API client | | `src-tauri/src/proxmox/auth.rs` | Authentication logic | | `src-tauri/src/proxmox/cluster.rs` | Cluster registry | | `src-tauri/src/proxmox/models.rs` | Data models | | `src-tauri/src/commands/proxmox.rs` | IPC commands | | `src-tauri/src/db/migrations.rs` | DB schema (migration 012) | ### Frontend | File | Purpose | |------|---------| | `src/pages/Proxmox/index.tsx` | Main page | | `src/pages/Proxmox/ClusterList.tsx` | Cluster management | | `src/pages/Proxmox/ClusterDashboard.tsx` | Metrics dashboard | | `src/pages/Proxmox/VMManager.tsx` | VM operations | | `src/pages/Proxmox/AddClusterModal.tsx` | Add cluster UI | | `src/lib/tauriCommands.ts` | IPC wrappers | | `src/stores/proxmoxStore.ts` | State management | --- ## Database Schema ### New Tables **proxmox_clusters** ```sql id TEXT PRIMARY KEY name TEXT NOT NULL node_address TEXT NOT NULL -- hostname:8006 node_fingerprint TEXT -- SSL cert hash username TEXT NOT NULL -- root encrypted_password TEXT NOT NULL cluster_type TEXT CHECK('ve' OR 'pbs') status TEXT DEFAULT 'unknown' last_connected_at TEXT created_at TEXT updated_at TEXT ``` **proxmox_resources** ```sql id TEXT PRIMARY KEY cluster_id TEXT NOT NULL resource_type TEXT -- 'node', 'vm', 'ct', 'storage', 'backup' resource_id TEXT -- VM ID, storage ID name TEXT status TEXT cpu_usage REAL memory_usage REAL storage_usage REAL details TEXT -- JSON blob last_updated_at TEXT ``` **proxmox_credentials** ```sql id TEXT PRIMARY KEY cluster_id TEXT NOT NULL api_token TEXT NOT NULL -- Encrypted API token token_hash TEXT NOT NULL -- SHA-256 for audit expires_at TEXT created_at TEXT ``` --- ## API Endpoints ### Authentication ``` POST /api2/json/access/ticket Request: { username: "root", password: "..." } Response: { ticket: "PVE@pam!root!...", CSRFPreventionToken: "..." } ``` ### Proxmox VE ``` GET /api2/json/nodes - List nodes GET /api2/json/nodes/{node}/qemu - List VMs GET /api2/json/nodes/{node}/qemu/{vmid}/status/current - Get VM status POST /api2/json/nodes/{node}/qemu/{vmid}/status/start - Start VM POST /api2/json/nodes/{node}/qemu/{vmid}/status/stop - Stop VM POST /api2/json/nodes/{node}/qemu/{vmid}/status/reboot - Reboot VM POST /api2/json/nodes/{node}/qemu/{vmid}/migrate - Migrate VM GET /api2/json/nodes/{node}/storage - List storage GET /api2/json/cluster/resources - Cluster resources ### Ceph Management ``` GET /api2/json/nodes/{node}/ceph/pool - List pools POST /api2/json/nodes/{node}/ceph/pool - Create pool DELETE /api2/json/nodes/{node}/ceph/pool/{pool} - Delete pool GET /api2/json/nodes/{node}/ceph/osd - List OSDs POST /api2/json/nodes/{node}/ceph/osd/{id}/set - Set OSD weight POST /api2/json/nodes/{node}/ceph/osd/{id}/out - Set OSD out POST /api2/json/nodes/{node}/ceph/osd/{id}/in - Set OSD in GET /api2/json/nodes/{node}/ceph/mds - List MDS POST /api2/json/nodes/{node}/ceph/mds/{id}/failover - MDS failover GET /api2/json/nodes/{node}/ceph/rbd - List RBDs POST /api2/json/nodes/{node}/ceph/rbd - Create RBD DELETE /api2/json/nodes/{node}/ceph/rbd/{pool}/{name} - Delete RBD PUT /api2/json/nodes/{node}/ceph/rbd/{pool}/{name} - Resize RBD GET /api2/json/cluster/ceph/status - Ceph status GET /api2/json/cluster/ceph/health - Ceph health ``` ### SDN Management ``` GET /api2/json/nodes/{node}/sdn/zones - List SDN zones GET /api2/json/nodes/{node}/sdn/dhcp - List SDN DHCP GET /api2/json/nodes/{node}/sdn/firewall - List SDN firewall ``` ### Firewall Management ``` GET /api2/json/nodes/{node}/firewall/rules - List firewall rules POST /api2/json/nodes/{node}/firewall/rules - Add firewall rule DELETE /api2/json/nodes/{node}/firewall/rules/{ruleid} - Delete firewall rule POST /api2/json/nodes/{node}/firewall/status - Enable firewall DELETE /api2/json/nodes/{node}/firewall/status - Disable firewall ``` ### HA Group Management ``` GET /api2/json/cluster/ha/resources - List HA resources GET /api2/json/cluster/ha/groups - List HA groups POST /api2/json/cluster/ha/groups - Create HA group DELETE /api2/json/cluster/ha/groups/{group} - Delete HA group POST /api2/json/cluster/ha/resources/{rid} - Manage HA resource ``` ### Proxmox Backup Server ``` GET /api2/json/nodes/{node}/backup - List backups POST /api2/json/nodes/{node}/backup/{jobid}/run - Run backup job GET /api2/json/nodes/{node}/storage - List datastores GET /api2/json/nodes/{node}/backup/status - Backup status ### Backup Scheduling & Replication ``` POST /api2/json/nodes/{node}/backup/{jobid} - Create/edit backup job DELETE /api2/json/nodes/{node}/backup/{jobid} - Delete backup job POST /api2/json/nodes/{node}/backup/restore - Restore backup GET /api2/json/nodes/{node}/backup/replication - List replication status POST /api2/json/nodes/{node}/backup/replication - Trigger replication ``` --- ## IPC Commands ### Cluster Management ```typescript addProxmoxClusterCmd(config) removeProxmoxClusterCmd(clusterId) listProxmoxClustersCmd() getProxmoxClusterCmd(clusterId) testProxmoxConnectionCmd(config) ``` ### VM Operations ```typescript listProxmoxVMsCmd(clusterId) startProxmoxVMCmd(clusterId, vmId) stopProxmoxVMCmd(clusterId, vmId) rebootProxmoxVMCmd(clusterId, vmId) shutdownProxmoxVMCmd(clusterId, vmId) suspendProxmoxVMCmd(clusterId, vmId) cloneProxmoxVMCmd(clusterId, vmId, newId, name) migrateProxmoxVMCmd(clusterId, vmId, targetClusterId, online) ``` ### PBS Operations ```typescript listProxmoxBackupsCmd(clusterId) runProxmoxBackupJobCmd(clusterId, jobId) listProxmoxDatastoresCmd(clusterId) restoreProxmoxBackupCmd(clusterId, backupId, datastore) ``` ### Metrics ```typescript getProxmoxMetricsCmd(clusterId) getCrossClusterMetricsCmd() ``` ### Triage Integration ```typescript linkProxmoxResourceCmd(issueId, clusterId, resourceType, resourceId) collectProxmoxLogsCmd(issueId, clusterId, resourceType, resourceId, timeRange) ``` --- ## Configuration ### Environment Variables ```bash # Encryption key (auto-generated if not set) TRCAA_ENCRYPTION_KEY=<32-byte-hex-key> # Optional: Proxmox-specific config PROXMOX_DEFAULT_PORT=8006 PROXMOX_DEFAULT_TIMEOUT=30 PROXMOX_ENABLE_SSL_VERIFY=true ``` ### Cluster Configuration (JSON) ```json { "name": "pve-cluster-1", "node_address": "pve1.example.com:8006", "node_fingerprint": "SHA256:ABC123...", "username": "root", "encrypted_password": "base64(gcm-encrypted-password)", "cluster_type": "ve" } ``` --- ## Security Checklist - [ ] All passwords encrypted with AES-256-GCM - [ ] API tokens stored encrypted - [ ] SSL fingerprint verification configurable - [ ] Audit logging for all operations - [ ] No credentials in logs - [ ] CSRF tokens handled properly - [ ] Rate limiting implemented - [ ] Error messages don't leak sensitive info --- ## Testing Strategy ### Rust Tests ```bash # Run all Proxmox tests cargo test --manifest-path src-tauri/Cargo.toml --lib proxmox # Run specific test module cargo test --manifest-path src-tauri/Cargo.toml -- lib proxmox::client # Test coverage cargo test --manifest-path src-tauri/Cargo.toml --lib proxmox -- --test-threads=1 --nocapture ``` ### Frontend Tests ```bash # Unit tests npm run test -- proxmox # Coverage npm run test:coverage -- proxmox ``` ### E2E Tests ```bash # Full integration npm run test:e2e ``` --- ## Common Tasks ### Add New Cluster 1. Call `addProxmoxClusterCmd(config)` 2. Backend validates credentials 3. Generates API token 4. Stores encrypted credentials 5. Returns success/error ### List VMs 1. Call `listProxmoxVMsCmd(clusterId)` 2. Client authenticates (if needed) 3. Calls Proxmox API 4. Returns VM list ### Start VM 1. Call `startProxmoxVMCmd(clusterId, vmId)` 2. Client validates authentication 3. Calls Proxmox API 4. Returns task status ### Live Migration 1. Call `migrateProxmoxVMCmd(sourceClusterId, vmId, targetClusterId, online)` 2. Validates both clusters 3. Creates migration task 4. Returns task ID for polling --- ## Troubleshooting ### Common Issues **"SSL fingerprint mismatch"** - Verify cluster SSL certificate - Disable fingerprint verification for self-signed certs **"Authentication failed"** - Verify root credentials - Check Proxmox API is accessible on port 8006 - Ensure user has proper permissions **"Rate limit exceeded"** - Implement exponential backoff - Reduce request frequency - Use caching **"Cluster unreachable"** - Verify network connectivity - Check firewall rules - Ensure Proxmox service is running --- ## Performance Targets | Operation | Target Latency | Max Data | |-----------|---------------|----------| | Cluster list | < 1s | 50 clusters | | VM list | < 2s | 100 VMs | | VM status | < 500ms | N/A | | Metrics refresh | < 5s | 10 nodes | | Migration | < 10s | N/A | --- ## Next Steps 1. ✅ **Planning complete** - This document 2. ⏳ **Phase 1** - Foundation (Week 1) 3. ⏳ **Phase 2** - VE Management (Week 2) 4. ⏳ **Phase 3** - PBS Support (Week 3) 5. ⏳ **Phase 4** - Cross-Datacenter (Week 4) 6. ⏳ **Phase 5** - Triage Integration (Week 5) 7. ⏳ **Phase 6** - Testing & Docs (Week 6) --- ## Resources - **Proxmox API Docs:** https://pve.proxmox.com/pve-docs/api-viewer/ - **Proxmox Datacenter Manager:** https://github.com/proxmox/proxmox-datacenter-manager - **TRCAA Architecture:** `docs/architecture/` - **Integration Patterns:** `docs/wiki/Integrations.md` --- **Document Version:** 1.0 **Last Updated:** 2026-06-06 **Author:** AI Assistant **Review Status:** Pending