d-bis/Sankofa
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation structure and enhance .gitignore

Browse Source 
- Added generated index files and report directories to .gitignore to prevent unnecessary tracking of transient files.
- Updated README links to reflect new documentation paths for better navigation.
- Improved documentation organization by ensuring all links point to the correct locations, enhancing user experience and accessibility.
This commit is contained in:
defiQUG
2025-12-12 21:18:55 -08:00
parent 664707d912
commit fe0365757a
106 changed files with 4666 additions and 2294 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
docs/reference/CODE_INCONSISTENCIES.md Normal file
View File

@@ -0,0 +1,136 @@
# Code Inconsistencies Found
## Critical Inconsistencies
### 1. Missing Variable Assignment in Controller
**File**: `crossplane-provider-proxmox/pkg/controller/virtualmachine/controller.go:64`
**Issue**: Code search shows line 64 has `proxmox.NewClient(` but the actual file shows it's correctly assigned. However, there's a potential issue with error handling.
**Current Code**:
```go
// Line 63-72
// Create Proxmox client
proxmoxClient, err := proxmox.NewClient(
site.Endpoint,
creds.Username,
creds.Password,
site.InsecureSkipTLSVerify,
)
if err != nil {
return ctrl.Result{}, errors.Wrap(err, "cannot create Proxmox client")
}
```
**Status**: ✅ Actually correct - variable is assigned. No fix needed.
### 2. Inconsistent Client Creation in VMScaleSet Controller
**File**: `crossplane-provider-proxmox/pkg/controller/vmscaleset/controller.go:47`
**Issue**: Creates client with empty parameters, likely a bug.
**Current Code**:
```go
proxmoxClient := proxmox.NewClient("", "", "")
```
**Problem**: This will always fail or use invalid credentials.
**Fix Required**: Should use proper credentials from ProviderConfig, similar to virtualmachine controller.
### 3. Inconsistent Error Handling Patterns
**Location**: Multiple files
**Pattern 1** (virtualmachine/controller.go):
- Credentials error → requeue after 30s
- Site error → requeue after 30s
- VM creation error → no requeue (immediate return)
**Pattern 2** (Other controllers):
- Various requeue strategies
**Recommendation**: Standardize error handling with:
- Retryable errors → requeue with exponential backoff
- Non-retryable errors → no requeue, update status with error condition
- Partial creation errors → cleanup + requeue with longer delay
### 4. importdisk API Usage Without Version Check
**File**: `crossplane-provider-proxmox/pkg/proxmox/client.go:397`
**Issue**: Uses importdisk API without checking if it's available.
**Current Code**:
```go
importPath := fmt.Sprintf("/nodes/%s/qemu/%d/importdisk", spec.Node, vmID)
if err := c.httpClient.Post(ctx, importPath, importConfig, &importResult); err != nil {
return nil, errors.Wrapf(err, "failed to import image...")
}
```
**Problem**: No check if Proxmox version supports this API.
**Fix Required**: Add version check or API availability check before use.
### 5. Inconsistent Status Field Names
**File**: `crossplane-provider-proxmox/apis/v1alpha1/virtualmachine_types.go:56`
**Issue**: Status field is `VMID` but JSON tag is `vmId` (camelCase).
**Current Code**:
```go
VMID int `json:"vmId,omitempty"`
```
**Problem**: Inconsistent naming (Go uses VMID, JSON uses vmId).
**Impact**: Minor - works but inconsistent.
### 6. No Cleanup on Partial VM Creation
**File**: `crossplane-provider-proxmox/pkg/controller/virtualmachine/controller.go:142-145`
**Issue**: When CreateVM fails, no cleanup of partially created VM.
**Current Code**:
```go
createdVM, err := proxmoxClient.CreateVM(ctx, vmSpec)
if err != nil {
return ctrl.Result{}, errors.Wrap(err, "cannot create VM")
}
```
**Problem**: If VM is created but import fails, VM remains orphaned.
**Fix Required**: Add cleanup logic in error path.
### 7. Lock File Handling Not Used in Error Recovery
**File**: `crossplane-provider-proxmox/pkg/proxmox/client.go:803-821`
**Issue**: UnlockVM function exists but not called during error recovery.
**Current Code**: UnlockVM is defined but never used in CreateVM error paths.
**Fix Required**: Call UnlockVM before DeleteVM in cleanup operations.
---
## Summary of Required Fixes
1. ✅ **virtualmachine/controller.go:64** - Actually correct, no fix needed
2. ❌ **vmscaleset/controller.go:47** - Fix client creation
3. ⚠️ **Error handling** - Standardize across all controllers
4. ❌ **importdisk API** - Add version/availability check
5. ⚠️ **Status field naming** - Consider consistency (low priority)
6. ❌ **Partial VM cleanup** - Add cleanup in error paths
7. ❌ **Lock file handling** - Use UnlockVM in cleanup
---
*Last Updated: 2025-12-12*

167
docs/reference/COPY_SCRIPT_TO_PROXMOX_NODES.md Normal file
View File

@@ -0,0 +1,167 @@
# Copy Script to Proxmox Nodes - Instructions
**Script**: `complete-vm-100-guest-agent-check.sh`
**Target**: Both Proxmox nodes (ml110-01 and r630-01)
---
## Issue
The automated copy script cannot connect to the Proxmox nodes. This may be due to:
- Network connectivity issues
- Incorrect password in `.env` file
- SSH access restrictions
- Firewall rules
---
## Solution: Manual Copy
### Option 1: Using SCP (Recommended)
**For ml110-01 (Site 1 - 192.168.11.10):**
```bash
# Load password from .env (adjust if needed)
source .env
PROXMOX_PASS="${PROXMOX_ROOT_PASS:-L@kers2010}"
# Copy script
sshpass -p "$PROXMOX_PASS" scp -o StrictHostKeyChecking=no \
scripts/complete-vm-100-guest-agent-check.sh \
root@192.168.11.10:/usr/local/bin/complete-vm-100-guest-agent-check.sh
# Make executable
sshpass -p "$PROXMOX_PASS" ssh -o StrictHostKeyChecking=no root@192.168.11.10 \
'chmod +x /usr/local/bin/complete-vm-100-guest-agent-check.sh'
# Verify
sshpass -p "$PROXMOX_PASS" ssh -o StrictHostKeyChecking=no root@192.168.11.10 \
'ls -lh /usr/local/bin/complete-vm-100-guest-agent-check.sh'
```
**For r630-01 (Site 2 - 192.168.11.11):**
```bash
# Copy script
sshpass -p "$PROXMOX_PASS" scp -o StrictHostKeyChecking=no \
scripts/complete-vm-100-guest-agent-check.sh \
root@192.168.11.11:/usr/local/bin/complete-vm-100-guest-agent-check.sh
# Make executable
sshpass -p "$PROXMOX_PASS" ssh -o StrictHostKeyChecking=no root@192.168.11.11 \
'chmod +x /usr/local/bin/complete-vm-100-guest-agent-check.sh'
# Verify
sshpass -p "$PROXMOX_PASS" ssh -o StrictHostKeyChecking=no root@192.168.11.11 \
'ls -lh /usr/local/bin/complete-vm-100-guest-agent-check.sh'
```
---
### Option 2: Copy Script Content Directly
If SCP doesn't work, you can copy the script content directly:
1. **Display the script content:**
```bash
cat scripts/complete-vm-100-guest-agent-check.sh
```
2. **SSH to the Proxmox node:**
```bash
sshpass -p "$PROXMOX_PASS" ssh -o StrictHostKeyChecking=no root@192.168.11.10
```
3. **On the Proxmox node, create the file:**
```bash
cat > /usr/local/bin/complete-vm-100-guest-agent-check.sh << 'SCRIPT_EOF'
[paste the entire script content here]
SCRIPT_EOF
chmod +x /usr/local/bin/complete-vm-100-guest-agent-check.sh
```
4. **Verify:**
```bash
/usr/local/bin/complete-vm-100-guest-agent-check.sh
```
---
### Option 3: Use Proxmox Web UI
1. **Access Proxmox Web UI** for each node
2. **Go to Shell** (or use the console)
3. **Create the file** using the web editor or paste the script content
4. **Make it executable:**
```bash
chmod +x /usr/local/bin/complete-vm-100-guest-agent-check.sh
```
---
## Verify Script is Installed
After copying, verify on each node:
```bash
# On ml110-01
sshpass -p "$PROXMOX_PASS" ssh -o StrictHostKeyChecking=no root@192.168.11.10 \
'/usr/local/bin/complete-vm-100-guest-agent-check.sh'
# On r630-01
sshpass -p "$PROXMOX_PASS" ssh -o StrictHostKeyChecking=no root@192.168.11.11 \
'/usr/local/bin/complete-vm-100-guest-agent-check.sh'
```
---
## Troubleshooting
### If "Permission denied" error:
1. **Check password in `.env` file:**
```bash
grep PROXMOX_ROOT_PASS .env
```
2. **Try connecting manually to verify:**
```bash
ssh root@192.168.11.10
```
3. **Check if password authentication is enabled** (may need key-based auth)
### If "Connection refused" or "Host unreachable":
1. **Verify network connectivity:**
```bash
ping 192.168.11.10
ping 192.168.11.11
```
2. **Check if SSH is running on Proxmox nodes:**
```bash
nmap -p 22 192.168.11.10
nmap -p 22 192.168.11.11
```
3. **Verify firewall rules** allow SSH access
---
## Quick Reference
**Script Location**: `scripts/complete-vm-100-guest-agent-check.sh`
**Target Location**: `/usr/local/bin/complete-vm-100-guest-agent-check.sh`
**Nodes**:
- ml110-01: `192.168.11.10`
- r630-01: `192.168.11.11`
**Password**: Check `.env` file for `PROXMOX_ROOT_PASS`
---
**Last Updated**: 2025-12-11

14
docs/reference/README.md Normal file
View File

@@ -0,0 +1,14 @@
# Reference Documentation
This directory contains reference materials, specifications, and technical details.
## Contents
- **[Code Inconsistencies](CODE_INCONSISTENCIES.md)** - Documented code inconsistencies
- **[Copy Script to Proxmox Nodes](COPY_SCRIPT_TO_PROXMOX_NODES.md)** - Instructions for copying scripts
- **[Script Copied to Proxmox Nodes](SCRIPT_COPIED_TO_PROXMOX_NODES.md)** - Details on script deployment
---
**Last Updated**: 2025-01-09

61
docs/reference/SCRIPT_COPIED_TO_PROXMOX_NODES.md Normal file
View File

@@ -0,0 +1,61 @@
# Script Copied to Proxmox Nodes
**Date**: 2025-12-11
**Script**: `complete-vm-100-guest-agent-check.sh`
**Status**: ✅ Successfully copied to both nodes
---
## Summary
The script `complete-vm-100-guest-agent-check.sh` has been successfully copied to both Proxmox nodes:
- ✅ **ml110-01** (192.168.11.10)
- ✅ **r630-01** (192.168.11.11)
**Location**: `/usr/local/bin/complete-vm-100-guest-agent-check.sh`
**Permissions**: Executable (`chmod +x`)
---
## Usage
### On ml110-01:
```bash
sshpass -p 'L@kers2010' ssh root@192.168.11.10
/usr/local/bin/complete-vm-100-guest-agent-check.sh
```
### On r630-01:
```bash
sshpass -p 'L@kers2010' ssh root@192.168.11.11
/usr/local/bin/complete-vm-100-guest-agent-check.sh
```
---
## What the Script Does
The script checks VM 100's guest agent configuration:
1. ✅ Verifies `qm` command is available (must run on Proxmox node)
2. ✅ Checks if VM 100 exists
3. ✅ Verifies guest agent is enabled in VM config (`agent: 1`)
4. ✅ Checks if `qemu-guest-agent` package is installed inside the VM
5. ✅ Verifies the guest agent service is running inside the VM
6. ✅ Provides clear status messages and error handling
---
## Notes
- The script **must be run on the Proxmox node** (not from your local machine)
- It uses `qm guest exec` commands which require the guest agent to be working
- If the guest agent is not working, some checks may fail, but the script will provide clear error messages
---
**Last Updated**: 2025-12-11