Update documentation structure and enhance .gitignore
- 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
178
docs/guest-agent/GUEST_AGENT_CHECKLIST.md
Normal file
178
docs/guest-agent/GUEST_AGENT_CHECKLIST.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# Guest Agent Implementation - Completion Checklist
|
||||
|
||||
## ✅ Code Implementation (COMPLETED)
|
||||
|
||||
### 1. VM Creation Code
|
||||
- [x] **New VM creation** - `agent=1` added to VM config (line 318)
|
||||
- [x] **VM cloning** - `agent=1` added to cloned VM config (line 242)
|
||||
- [x] **VM updates** - `agent=1` enforced in UpdateVM function (line 560)
|
||||
|
||||
**Status:** ✅ All code changes are in place and verified
|
||||
|
||||
### 2. Automation Scripts
|
||||
- [x] **Enable script** - `scripts/enable-guest-agent-existing-vms.sh` created and executable
|
||||
- [x] Dynamic node discovery
|
||||
- [x] Dynamic VM discovery
|
||||
- [x] Status checking before enabling
|
||||
- [x] Comprehensive summaries
|
||||
- [x] **Verification script** - `scripts/verify-guest-agent.sh` created and executable
|
||||
- [x] Lists all VMs with status
|
||||
- [x] Per-node summaries
|
||||
- [x] Color-coded output
|
||||
|
||||
**Status:** ✅ All scripts created and ready to use
|
||||
|
||||
### 3. Documentation
|
||||
- [x] Updated `docs/enable-guest-agent-manual.md`
|
||||
- [x] Updated `scripts/README.md`
|
||||
- [x] Created `docs/GUEST_AGENT_ENABLED.md`
|
||||
- [x] Created this checklist
|
||||
|
||||
**Status:** ✅ All documentation updated
|
||||
|
||||
---
|
||||
|
||||
## ⏳ Operational Tasks (TO BE COMPLETED)
|
||||
|
||||
### 1. Enable Guest Agent on Existing VMs
|
||||
**Status:** ⏳ **NOT YET EXECUTED**
|
||||
|
||||
**Action Required:**
|
||||
```bash
|
||||
./scripts/enable-guest-agent-existing-vms.sh
|
||||
```
|
||||
|
||||
**What this does:**
|
||||
- Discovers all nodes on both Proxmox sites
|
||||
- Discovers all VMs on each node
|
||||
- Enables guest agent (`agent=1`) in Proxmox config for VMs that need it
|
||||
- Provides summary of actions taken
|
||||
|
||||
**Expected Output:**
|
||||
- List of all nodes discovered
|
||||
- List of all VMs processed
|
||||
- Count of VMs enabled
|
||||
- Count of VMs already enabled
|
||||
- Count of failures (if any)
|
||||
|
||||
---
|
||||
|
||||
### 2. Verify Guest Agent Status
|
||||
**Status:** ⏳ **NOT YET EXECUTED**
|
||||
|
||||
**Action Required:**
|
||||
```bash
|
||||
./scripts/verify-guest-agent.sh
|
||||
```
|
||||
|
||||
**What this does:**
|
||||
- Lists all VMs with their current guest agent status
|
||||
- Shows which VMs have guest agent enabled/disabled
|
||||
- Provides per-node and per-site summaries
|
||||
|
||||
**Expected Output:**
|
||||
- Table showing VMID, Name, and Status (ENABLED/DISABLED)
|
||||
- Summary statistics per node
|
||||
- Overall summary across all sites
|
||||
|
||||
---
|
||||
|
||||
### 3. Install Guest Agent Package in OS (for existing VMs)
|
||||
**Status:** ⏳ **TO BE VERIFIED**
|
||||
|
||||
**Action Required (if not already installed):**
|
||||
|
||||
For each existing VM, SSH in and verify/install:
|
||||
|
||||
```bash
|
||||
# SSH into VM
|
||||
ssh admin@<vm-ip>
|
||||
|
||||
# Check if package is installed
|
||||
dpkg -l | grep qemu-guest-agent
|
||||
|
||||
# If not installed, install it:
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y qemu-guest-agent
|
||||
sudo systemctl enable qemu-guest-agent
|
||||
sudo systemctl start qemu-guest-agent
|
||||
|
||||
# Verify it's running
|
||||
sudo systemctl status qemu-guest-agent
|
||||
```
|
||||
|
||||
**Note:** VMs created with updated manifests already include guest agent installation in cloud-init userData, so they should have the package automatically.
|
||||
|
||||
**Check if userData includes guest agent:**
|
||||
```bash
|
||||
grep -r "qemu-guest-agent" examples/ gitops/ all-vm-userdata.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Current Status Summary
|
||||
|
||||
| Task | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Code Implementation | ✅ Complete | All code changes verified in place |
|
||||
| Enable Script | ✅ Ready | Script exists and is executable |
|
||||
| Verification Script | ✅ Ready | Script exists and is executable |
|
||||
| Documentation | ✅ Complete | All docs updated |
|
||||
| **Run Enable Script** | ⏳ **Pending** | Needs to be executed |
|
||||
| **Run Verify Script** | ⏳ **Pending** | Needs to be executed |
|
||||
| **OS Package Installation** | ⏳ **Unknown** | Needs verification per VM |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Actions
|
||||
|
||||
1. **Run the enablement script:**
|
||||
```bash
|
||||
cd /home/intlc/projects/Sankofa
|
||||
./scripts/enable-guest-agent-existing-vms.sh
|
||||
```
|
||||
|
||||
2. **Run the verification script:**
|
||||
```bash
|
||||
./scripts/verify-guest-agent.sh
|
||||
```
|
||||
|
||||
3. **Review the output** to see:
|
||||
- How many VMs had guest agent enabled
|
||||
- Which VMs already had it enabled
|
||||
- Any failures that need attention
|
||||
|
||||
4. **For VMs that need OS package installation:**
|
||||
- Check if cloud-init userData already includes it
|
||||
- If not, SSH into each VM and install manually
|
||||
- Or update the VM manifests to include it in userData
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Verification Commands
|
||||
|
||||
### Check if code changes are in place:
|
||||
```bash
|
||||
grep -n "agent.*1" crossplane-provider-proxmox/pkg/proxmox/client.go
|
||||
```
|
||||
|
||||
### Check if scripts exist:
|
||||
```bash
|
||||
ls -lh scripts/*guest*agent*.sh
|
||||
```
|
||||
|
||||
### Check if scripts are executable:
|
||||
```bash
|
||||
test -x scripts/enable-guest-agent-existing-vms.sh && echo "Executable" || echo "Not executable"
|
||||
test -x scripts/verify-guest-agent.sh && echo "Executable" || echo "Not executable"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
- **New VMs:** Will automatically have guest agent enabled (code is in place)
|
||||
- **Existing VMs:** Need to run the enablement script
|
||||
- **OS Package:** May need manual installation for existing VMs, but check userData first
|
||||
- **Future VMs:** Will have both Proxmox config and OS package automatically configured
|
||||
|
||||
182
docs/guest-agent/GUEST_AGENT_CONFIGURATION_ANALYSIS.md
Normal file
182
docs/guest-agent/GUEST_AGENT_CONFIGURATION_ANALYSIS.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# Guest Agent Configuration Analysis
|
||||
|
||||
**Date**: 2025-12-09
|
||||
**Question**: Is the Guest Agent fully configured in all templates before lock file issues occur?
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
✅ **YES** - The Proxmox-level guest agent (`agent: 1`) is configured **BEFORE** VM creation and **BEFORE** any lock file issues can occur.
|
||||
|
||||
⚠️ **Note**: The OS-level guest agent package installation happens later via cloud-init after the VM boots.
|
||||
|
||||
---
|
||||
|
||||
## Configuration Timeline
|
||||
|
||||
### 1. Proxmox-Level Guest Agent (`agent: 1`)
|
||||
|
||||
**Location**: `crossplane-provider-proxmox/pkg/proxmox/client.go`
|
||||
|
||||
**When Configured**: **BEFORE VM Creation**
|
||||
|
||||
```go
|
||||
// Line 308-318: Initial VM configuration
|
||||
vmConfig := map[string]interface{}{
|
||||
"vmid": vmID,
|
||||
"name": spec.Name,
|
||||
"cores": spec.CPU,
|
||||
"memory": parseMemory(spec.Memory),
|
||||
"net0": fmt.Sprintf("virtio,bridge=%s", spec.Network),
|
||||
"scsi0": diskConfig,
|
||||
"ostype": "l26",
|
||||
"agent": "1", // ✅ Set HERE - BEFORE VM creation
|
||||
}
|
||||
|
||||
// Line 345: VM is created with agent already configured
|
||||
if err := c.httpClient.Post(ctx, fmt.Sprintf("/nodes/%s/qemu", spec.Node), vmConfig, &resultStr); err != nil {
|
||||
return nil, errors.Wrap(err, "failed to create VM")
|
||||
}
|
||||
```
|
||||
|
||||
**Order of Operations**:
|
||||
1. ✅ `agent: 1` is set in `vmConfig` (line 317)
|
||||
2. ✅ VM is created with this configuration (line 345)
|
||||
3. ⚠️ Lock file issues occur during subsequent updates (if any)
|
||||
|
||||
**Conclusion**: The Proxmox guest agent is configured **BEFORE** any lock file issues can occur during VM creation.
|
||||
|
||||
---
|
||||
|
||||
### 2. Cloning Path
|
||||
|
||||
**Location**: `crossplane-provider-proxmox/pkg/proxmox/client.go` (line 242)
|
||||
|
||||
```go
|
||||
cloneConfig := map[string]interface{}{
|
||||
"newid": vmID,
|
||||
"name": spec.Name,
|
||||
"target": spec.Node,
|
||||
}
|
||||
// ... clone operation ...
|
||||
|
||||
// After cloning, update config
|
||||
vmConfig := map[string]interface{}{
|
||||
"agent": "1", // ✅ Set during clone update
|
||||
}
|
||||
```
|
||||
|
||||
**Conclusion**: Guest agent is also set during cloning operations.
|
||||
|
||||
---
|
||||
|
||||
### 3. Update Path
|
||||
|
||||
**Location**: `crossplane-provider-proxmox/pkg/proxmox/client.go` (line 671)
|
||||
|
||||
```go
|
||||
// Always ensure guest agent is enabled
|
||||
vmConfig["agent"] = "1"
|
||||
```
|
||||
|
||||
**Conclusion**: Guest agent is enforced during updates (this is where lock issues occurred, but agent was already set).
|
||||
|
||||
---
|
||||
|
||||
## OS-Level Guest Agent (Package Installation)
|
||||
|
||||
### Configuration in Templates
|
||||
|
||||
**All 29 VM templates** include:
|
||||
|
||||
1. **Package in cloud-init**:
|
||||
```yaml
|
||||
packages:
|
||||
- qemu-guest-agent
|
||||
```
|
||||
|
||||
2. **Service enablement in runcmd**:
|
||||
```yaml
|
||||
runcmd:
|
||||
- systemctl enable qemu-guest-agent
|
||||
- systemctl start qemu-guest-agent
|
||||
```
|
||||
|
||||
3. **Verification steps**:
|
||||
```yaml
|
||||
- |
|
||||
echo "Verifying QEMU Guest Agent is running..."
|
||||
for i in {1..30}; do
|
||||
if systemctl is-active --quiet qemu-guest-agent; then
|
||||
echo "QEMU Guest Agent is running"
|
||||
exit 0
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
```
|
||||
|
||||
**When This Runs**: After VM boots, during cloud-init execution (2-5 minutes after VM start).
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
### Templates Checked
|
||||
|
||||
✅ All 29 VM templates include `qemu-guest-agent`:
|
||||
- `basic-vm.yaml`
|
||||
- `medium-vm.yaml`
|
||||
- `large-vm.yaml`
|
||||
- `nginx-proxy-vm.yaml`
|
||||
- `cloudflare-tunnel-vm.yaml`
|
||||
- All 16 `smom-dbis-138/*.yaml` files
|
||||
- All 8 `phoenix/*.yaml` files
|
||||
|
||||
### Code Verification
|
||||
|
||||
✅ Guest agent is set in three places:
|
||||
1. **Initial VM creation** (line 317) - ✅ BEFORE lock issues
|
||||
2. **Cloning** (line 242) - ✅ During clone
|
||||
3. **Updates** (line 671) - ⚠️ May encounter locks, but agent already set
|
||||
|
||||
---
|
||||
|
||||
## Answer to Question
|
||||
|
||||
**Q**: Is the Guest Agent being fully configured implemented before lock file?
|
||||
|
||||
**A**: **YES** - The Proxmox-level guest agent configuration (`agent: 1`) is set in the initial `vmConfig` map **BEFORE** the VM is created via the API call. This means:
|
||||
|
||||
1. ✅ Guest agent is configured **BEFORE** VM creation
|
||||
2. ✅ Guest agent is configured **BEFORE** any lock file issues can occur
|
||||
3. ✅ Guest agent is configured **BEFORE** image import operations
|
||||
4. ✅ Guest agent is configured **BEFORE** cloud-init setup
|
||||
|
||||
The OS-level package installation happens later via cloud-init, but the Proxmox-level configuration (which is what Proxmox needs to communicate with the guest agent) is set from the very beginning.
|
||||
|
||||
---
|
||||
|
||||
## Potential Issues
|
||||
|
||||
### If Lock Occurs During Update
|
||||
|
||||
If a lock occurs during an update operation (line 671), the guest agent configuration is already set from the initial VM creation. The update would just ensure it remains set, but it's not critical if the update fails because the agent was already configured.
|
||||
|
||||
### OS-Level Package Installation
|
||||
|
||||
The OS-level `qemu-guest-agent` package installation happens via cloud-init after the VM boots. If cloud-init fails or the VM doesn't boot, the package won't be installed, but the Proxmox-level configuration (`agent: 1`) is still set, so Proxmox will be ready to communicate once the package is installed.
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. ✅ **Current Implementation is Correct**: Guest agent is configured before VM creation
|
||||
2. ✅ **No Changes Needed**: The configuration order is optimal
|
||||
3. ✅ **Templates are Complete**: All templates include OS-level package installation
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-09
|
||||
**Status**: ✅ **GUEST AGENT CONFIGURED BEFORE LOCK ISSUES**
|
||||
|
||||
17
docs/guest-agent/README.md
Normal file
17
docs/guest-agent/README.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# Guest Agent Documentation
|
||||
|
||||
This directory contains documentation related to Proxmox guest agent implementation and configuration.
|
||||
|
||||
## Contents
|
||||
|
||||
- **[Guest Agent Checklist](GUEST_AGENT_CHECKLIST.md)** - Checklist for guest agent setup
|
||||
- **[Guest Agent Configuration Analysis](GUEST_AGENT_CONFIGURATION_ANALYSIS.md)** - Analysis of guest agent configuration
|
||||
|
||||
**Related Guides**:
|
||||
- [Quick Install Guest Agent](../guides/QUICK_INSTALL_GUEST_AGENT.md) - Quick installation guide
|
||||
- [Enable Guest Agent Manual](../guides/enable-guest-agent-manual.md) - Manual steps
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-09
|
||||
|
||||
Reference in New Issue
Block a user