mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-09-23 11:46:28 +00:00
Pulse Monitor
3f8f1f7899
Replaced the two-step setup code process with a simpler token-in-URL approach: - Auth token is now embedded directly in the setup URL - No more prompting users for setup codes - Same security level with better UX - Backwards compatible with old setupCode field The new flow generates a command like: curl -sSL "http://pulse/api/setup-script?...&auth_token=TOKEN" | bash This makes it much easier for users, especially in Proxmox shell where interactive prompts can be problematic.
158 lines
4.3 KiB
Markdown
158 lines
4.3 KiB
Markdown
# VM Disk Usage Monitoring
|
|
|
|
Pulse can show actual disk usage for VMs (just like containers) when the QEMU Guest Agent is installed and configured properly.
|
|
|
|
## What You See
|
|
|
|
**Without QEMU Guest Agent:**
|
|
- VMs show allocated disk size only (e.g., 32GB allocated)
|
|
- No visibility into actual disk usage inside the VM
|
|
|
|
**With QEMU Guest Agent:**
|
|
- VMs show real disk usage like containers do (e.g., 5.2GB used of 32GB)
|
|
- Accurate threshold alerts based on actual usage
|
|
- Better capacity planning with real data
|
|
|
|
## Requirements
|
|
|
|
### 1. Install QEMU Guest Agent in Your VMs
|
|
|
|
**Linux VMs:**
|
|
```bash
|
|
# Debian/Ubuntu
|
|
apt-get install qemu-guest-agent
|
|
systemctl enable --now qemu-guest-agent
|
|
|
|
# RHEL/Rocky/AlmaLinux
|
|
yum install qemu-guest-agent
|
|
systemctl enable --now qemu-guest-agent
|
|
|
|
# Alpine
|
|
apk add qemu-guest-agent
|
|
rc-update add qemu-guest-agent
|
|
rc-service qemu-guest-agent start
|
|
```
|
|
|
|
**Windows VMs:**
|
|
- Download virtio-win guest tools from: https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/
|
|
- Install the guest tools package which includes the QEMU Guest Agent
|
|
- The service starts automatically after installation
|
|
|
|
### 2. Enable Guest Agent in VM Options
|
|
|
|
In Proxmox web UI:
|
|
1. Select your VM
|
|
2. Go to **Options** → **QEMU Guest Agent**
|
|
3. Check **Enabled**
|
|
4. Start/restart the VM
|
|
|
|
Or via CLI:
|
|
```bash
|
|
qm set <vmid> --agent enabled=1
|
|
```
|
|
|
|
### 3. Verify Guest Agent is Working
|
|
|
|
Check if the agent is responding:
|
|
```bash
|
|
qm agent <vmid> ping
|
|
```
|
|
|
|
Get filesystem info (what Pulse uses):
|
|
```bash
|
|
qm agent <vmid> get-fsinfo
|
|
```
|
|
|
|
### 4. Pulse Permissions
|
|
|
|
Pulse needs the right permissions to query the guest agent:
|
|
|
|
**Proxmox 8 and below:** Requires `VM.Monitor` permission
|
|
**Proxmox 9+:** Requires `VM.GuestAgent.Audit` permission
|
|
|
|
When you run the Pulse setup script, it automatically detects your Proxmox version and sets the correct permissions. If setting up manually:
|
|
|
|
```bash
|
|
# Proxmox 9+
|
|
pveum aclmod / -user pulse-monitor@pam -role PVEAuditor
|
|
# PVEAuditor includes VM.GuestAgent.Audit in PVE 9+
|
|
|
|
# Proxmox 8 and below
|
|
pveum role add PulseMonitor -privs VM.Monitor
|
|
pveum aclmod / -user pulse-monitor@pam -role PulseMonitor
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Guest Agent Not Responding
|
|
|
|
**Check if agent is running inside VM:**
|
|
```bash
|
|
# Linux
|
|
systemctl status qemu-guest-agent
|
|
|
|
# Windows
|
|
Get-Service QEMU-GA
|
|
```
|
|
|
|
**Check VM configuration:**
|
|
```bash
|
|
# Should show "agent: 1"
|
|
qm config <vmid> | grep agent
|
|
```
|
|
|
|
**Check agent communication:**
|
|
```bash
|
|
# Should return without error
|
|
qm agent <vmid> ping
|
|
```
|
|
|
|
### Disk Usage Not Showing
|
|
|
|
If the agent is working but Pulse still shows allocated size:
|
|
|
|
1. **Check Pulse permissions** - Ensure the Pulse user has VM.Monitor (PVE 8) or VM.GuestAgent.Audit (PVE 9+)
|
|
2. **Check agent version** - Older agents might not support filesystem info
|
|
3. **Windows VMs** - Ensure virtio-win drivers are up to date
|
|
4. **Check Pulse logs** - Look for "GetVMFSInfo" errors
|
|
|
|
### Network Filesystems
|
|
|
|
The agent reports all mounted filesystems. Pulse automatically filters out:
|
|
- Network mounts (NFS, CIFS, SMB)
|
|
- Special filesystems (proc, sys, tmpfs, etc.)
|
|
- Bind mounts and overlays
|
|
|
|
Only local disk usage is counted toward the VM's total.
|
|
|
|
## Best Practices
|
|
|
|
1. **Install guest agent in VM templates** - New VMs will have it ready
|
|
2. **Monitor agent status** - Set up alerts if critical VMs lose agent connectivity
|
|
3. **Keep agents updated** - Update guest agents when updating VM operating systems
|
|
4. **Test after VM migrations** - Verify agent still works after moving VMs between nodes
|
|
|
|
## Platform-Specific Notes
|
|
|
|
### Cloud-Init Images
|
|
Most cloud images include qemu-guest-agent pre-installed but may need to be enabled:
|
|
```bash
|
|
systemctl enable --now qemu-guest-agent
|
|
```
|
|
|
|
### Docker/Kubernetes VMs
|
|
Container workloads can show high disk usage due to container layers. Consider:
|
|
- Using separate disks for container storage
|
|
- Monitoring container disk usage separately
|
|
- Setting appropriate thresholds for container hosts
|
|
|
|
### Database VMs
|
|
Databases often pre-allocate space. The guest agent shows actual usage, which might be less than what the database reports internally.
|
|
|
|
## Benefits
|
|
|
|
With QEMU Guest Agent disk monitoring:
|
|
- **Accurate alerts** - Alert on real usage, not allocated space
|
|
- **Better planning** - See actual growth trends
|
|
- **Prevent surprises** - Know when VMs are actually running out of space
|
|
- **Optimize storage** - Identify over-provisioned VMs |