c94a25f66f
All checks were successful
PR Review Automation / review (pull_request) Successful in 3m36s
Test / frontend-typecheck (pull_request) Successful in 1m39s
Test / frontend-tests (pull_request) Successful in 1m44s
Test / rust-fmt-check (pull_request) Successful in 17m2s
Test / rust-clippy (pull_request) Successful in 18m9s
Test / rust-tests (pull_request) Successful in 20m20s
- Bump version to 1.1.0 in Cargo.toml and tauri.conf.json - Update CHANGELOG.md with v1.1.0 release notes - Add Kubernetes management feature documentation
339 lines
9.8 KiB
Markdown
339 lines
9.8 KiB
Markdown
# 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
|