# Proxmox Integration - Implementation Summary

## Overview

This document summarizes the implementation plan for adding Proxmox integration to the TRCAA application (v1.2.0).

## What Was Planned

### Core Features

1. **Multi-Cluster Management** - Support for multiple Proxmox clusters (both VE and PBS)
2. **Cross-Datacenter Metrics** - Unified dashboard across all clusters
3. **Full VM Management** - Start/stop/reboot/migrate operations
4. **Backup Management** - PBS job and backup management
5. **Live Migration** - VM migration between clusters
6. **Triage Integration** - Link Proxmox resources to issues and collect logs

## Critical Corrections (Based on User Feedback)

### Port Configuration

**Correction:** Proxmox VE and PBS use **different default ports**:

| 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

### Ceph Storage Management

**Addition:** Full Ceph cluster management required:

| Component | Management Operations |
|-----------|----------------------|
| **Ceph Pools** | Create, delete, list, quota management |
| **Ceph OSDs** | List, status, weight management, out/in |
| **Ceph MDS** | List, status, failover management |
| **Ceph RBD** | Create, delete, clone, snap, resize |
| **Ceph Monitors** | List, status, quorum health |
| **Ceph Health** | Overall cluster health monitoring |

### Proxmox Datacenter Manager Features (v1.2.0)

**Addition:** Include these PDM features in v1.2.0:

1. **SDN (Software-Defined Networking)**
   - List virtual networks
   - View network status
   - Bridge configuration

2. **Firewall Management**
   - List firewall rules
   - Enable/disable firewall
   - Rule management (add, delete, update)

3. **HA (High Availability) Groups**
   - List HA groups
   - Manage HA resources
   - Failover configuration

4. **Update Management**
   - Check for package updates
   - List available updates
   - Update status across clusters

### Backup Management Scope

**Clarification:** Full backup job management including:

| Feature | Description |
|---------|-------------|
| **Backup Scheduling** | Cron-style scheduling for backup jobs |
| **Trigger Backups** | Manual backup job execution |
| **Backup Restoration** | Restore backups to target cluster |
| **Backup Replication** | Cross-cluster backup replication |
| **Deduplication** | Monitor deduplication status |
| **Backup Jobs** | Create, delete, list, edit backup jobs |

### Cluster Selection UI

**Requirement:** Dropdown with three selection modes:

| Mode | Description | Use Case |
|------|-------------|----------|
| **Single Cluster** | Select one specific cluster | Targeted operations on one cluster |
| **Multiple Clusters** | Select 2+ specific clusters | Cross-cluster operations |
| **ALL Clusters** | All configured clusters | Global operations, dashboard |

### Authentication

- Root username/password authentication to Proxmox nodes (port 8006)
- Automatic API token generation and management
- Encrypted credential storage using AES-256-GCM
- SSL fingerprint verification (configurable)
- Support for self-signed certificates

### Technical Approach

**Backend:**
- New module: `src-tauri/src/proxmox/`
- API client with proper authentication flow
- Cluster registry for multi-cluster support
- Metrics aggregation across clusters
- Database migrations for new schema

**Frontend:**
- New sidebar item: "Proxmox"
- Cluster selector and management UI
- VM manager interface
- Backup manager interface
- Cross-cluster dashboard
- State management with Zustand

## Files Created

### Documentation

1. **`docs/TICKET-proxmox-integration.md`** (27 KB)
   - Complete implementation plan
   - Architecture details
   - Implementation phases (6 weeks)
   - Testing strategy
   - Security considerations
   - Risk assessment

2. **`docs/PROXMOX-QUICK-REFERENCE.md`** (8 KB)
   - Quick reference card
   - API endpoints
   - IPC commands
   - Common tasks
   - Troubleshooting guide

## Key Decisions

### 1. Authentication Method

**Decision:** Use root credentials + port 8006 (VE) / 8007 (PBS)

**Rationale:**
- Simpler than Proxmox Datacenter Manager setup
- No additional network configuration required
- Works in all environments
- Aligns with user's feedback
- Default ports set by cluster type, user can override

### 2. Credential Storage

**Decision:** Store root credentials encrypted, generate API tokens

**Rationale:**
- Consistent with existing integration patterns
- Uses `encrypt_token()` from `src-tauri/src/integrations/auth.rs`
- API tokens provide better security than storing passwords
- Token auto-refresh before expiry

### 3. Multi-Cluster Support

**Decision:** Full multi-cluster support (primary feature)

**Rationale:**
- Key selling point of Proxmox Datacenter Manager
- Enables cross-datacenter management
- Supports active/standby architectures
- Allows unified monitoring

### 4. UI Location

**Decision:** New sidebar item (not settings tab)

**Rationale:**
- Proxmox is a core feature, not just configuration
- Similar to Kubernetes integration
- Easy access for daily operations
- Dashboard potential

## Implementation Phases

| Phase | Duration | Focus | Deliverables |
|-------|----------|-------|--------------|
| 1 | Week 1 | Foundation | Auth flow, API client, DB schema |
| 2 | Week 2 | VE Management | VM operations, node status, **Ceph management** |
| 3 | Week 3 | PBS + Advanced | Backup jobs, **SDN, Firewall, HA groups** |
| 4 | Week 4 | Cross-Datacenter | Cluster registry, metrics, **cluster selector UI** |
| 5 | Week 5 | Triage Integration | Resource linking, log collection |
| 6 | Week 6 | Testing & Docs | Tests, documentation, release |

## TDD Compliance

### Rust Tests

- **Target Coverage:** 80%+
- **Test Files:**
  - `src-tauri/src/proxmox/tests/auth_tests.rs`
  - `src-tauri/src/proxmox/tests/client_tests.rs`
  - `src-tauri/src/proxmox/tests/cluster_tests.rs`
  - `src-tauri/src/proxmox/tests/metrics_tests.rs`
- **Approach:** TDD with mockito for HTTP mocking

### Frontend Tests

- **Unit Tests:** Vitest, 80%+ coverage
- **Component Tests:** React Testing Library
- **E2E Tests:** WebdriverIO for critical paths

## Security Considerations

### Encryption

- **Passwords:** AES-256-GCM encrypted
- **API Tokens:** AES-256-GCM encrypted
- **Key Source:** `TRCAA_ENCRYPTION_KEY` env var or auto-generated `.enckey`

### Audit Logging

- Cluster add/remove
- Authentication events
- VM lifecycle operations
- Migration operations
- Backup operations

### SSL/TLS

- Fingerprint verification (configurable)
- Support for self-signed certificates
- Certificate pinning option

## Database Changes

### New Tables

1. **proxmox_clusters** - Store cluster configuration
2. **proxmox_resources** - Cache resource status
3. **proxmox_credentials** - Store API tokens

### Migration

- File: `src-tauri/src/db/migrations.rs`
- Number: 012_proxmox_clusters
- Type: Additive (no breaking changes)

## Integration Points

### Existing Patterns

- **Authentication:** Use `src-tauri/src/integrations/auth.rs`
- **Encryption:** Use `encrypt_token()` / `decrypt_token()`
- **Audit:** Use `src-tauri/src/audit/log.rs`
- **IPC:** Follow `src-tauri/src/commands/integrations.rs` pattern

### New Patterns

- **Cluster Registry:** Manage multiple client connections
- **Metrics Aggregation:** Cross-cluster data collection
- **Live Migration:** Multi-cluster coordination

## Success Criteria

### Functional

**Cluster Management:**
- [ ] Add/remove multiple clusters (VE and PBS)
- [ ] Default ports configured correctly (8006 for VE, 8007 for PBS)
- [ ] User can override port per cluster
- [ ] Cluster selection dropdown (single/multi/all) works

**Authentication:**
- [ ] Authentication with root credentials
- [ ] API token generation and storage
- [ ] SSL fingerprint verification configurable

**Proxmox VE:**
- [ ] VM management operations
- [ ] Ceph management (pools, OSDs, MDS, RBD, health)
- [ ] SDN management (zones, DHCP, firewall)
- [ ] Firewall management (rules, enable/disable)
- [ ] HA group management

**Proxmox Backup Server:**
- [ ] PBS backup operations
- [ ] Backup scheduling (create/edit/delete jobs)
- [ ] Manual backup trigger
- [ ] Backup restoration
- [ ] Backup replication between clusters

**Cross-Datacenter:**
- [ ] Cross-cluster metrics
- [ ] Live migration between clusters
- [ ] Global dashboard

**Triage Integration:**
- [ ] Triage integration (link resources, collect logs)

### Non-Functional

- [ ] ≥80% code coverage
- [ ] <2s cluster status refresh
- [ ] <5s VM list (100 VMs)
- [ ] All credentials encrypted
- [ ] Documentation complete

## Next Steps

1. **Review Plan** - User reviews documentation
2. **Clarify Requirements** - Address any questions
3. **Begin Implementation** - Phase 1 (Week 1)
4. **TDD Approach** - Write tests first, then implementation
5. **Iterate** - Phases 2-6
6. **Release** - v1.2.0

## Questions for User

Before implementation begins, please confirm:

1. **Authentication Flow** - Root credentials → API token ✓ (Confirmed)
2. **Cluster Support** - Both VE and PBS ✓ (Confirmed)
3. **Multi-Cluster** - Full support with cross-datacenter ✓ (Confirmed)
4. **UI Location** - Sidebar item ✓ (Confirmed)
5. **Credential Storage** - Encrypted in database ✓ (Confirmed)
6. **Version** - v1.2.0 ✓ (Confirmed)

## References

- **Proxmox API:** https://pve.proxmox.com/pve-docs/api-viewer/
- **Proxmox Datacenter Manager:** https://github.com/proxmox/proxmox-datacenter-manager
- **TRCAA Integrations:** `docs/wiki/Integrations.md`
- **Architecture Docs:** `docs/architecture/`

---

**Document Version:** 1.0  
**Date:** 2026-06-06  
**Status:** Planning Complete - Ready for Implementation  
**Next Action:** User approval to begin Phase 1