gsadmin/PSProxmox
1
0
Fork 0
mirror of https://github.com/Grace-Solutions/PSProxmox.git synced 2026-08-13 16:46:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add -IncludeGuestAgent parameter for performance optimization

Browse Source 
- Added optional -IncludeGuestAgent parameter to Get-ProxmoxVM cmdlet
- Guest agent data retrieval is now optional for improved query performance
- Default behavior: Fast queries without guest agent data
- Use -IncludeGuestAgent switch when detailed network information is needed
- Significant performance improvement for normal VM queries
- Updated all documentation and examples to use new parameter
- Fixed binary module structure by removing unnecessary PSD1 from bin folder
- Version bump to 2025.05.30.2323

BREAKING CHANGE: Get-ProxmoxVM no longer fetches guest agent data by default.
Existing scripts that rely on guest agent data must add -IncludeGuestAgent parameter.
This commit is contained in:
AX-AMote
2025-05-30 23:25:19 -04:00
parent 33898b7b80
commit d9bd620168
10 changed files with 174 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/cmdlets/Get-ProxmoxVM.md
+36 -5
View File
@@ -12,12 +12,13 @@ Get-ProxmoxVM
[-Name <String>]
[-UseRegex]
[-RawJson]
[-IncludeGuestAgent]
[<CommonParameters>]
```
## Description
The `Get-ProxmoxVM` cmdlet retrieves virtual machines from Proxmox VE with comprehensive information including guest agent data when available. You can retrieve all VMs, VMs on a specific node, or a specific VM by ID. The cmdlet automatically attempts to gather guest agent information for each VM, providing detailed network interface information from within the guest operating system.
The `Get-ProxmoxVM` cmdlet retrieves virtual machines from Proxmox VE. You can retrieve all VMs, VMs on a specific node, or a specific VM by ID. Use the `-IncludeGuestAgent` parameter to fetch guest agent information, which provides detailed network interface information from within the guest operating system. Note that including guest agent data may slow down queries as it requires additional API calls.
## Parameters
@@ -117,6 +118,22 @@ Accept pipeline input: False
Accept wildcard characters: False
```
### -IncludeGuestAgent
Whether to include guest agent information. This may slow down the query as it requires additional API calls.
```yaml
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```
### CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
@@ -200,7 +217,7 @@ This example gets the raw JSON response for all VMs.
```powershell
Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$vm = Get-ProxmoxVM -VMID 100
$vm = Get-ProxmoxVM -VMID 100 -IncludeGuestAgent
# Check if guest agent is available and running
if ($vm.GuestAgent -and $vm.GuestAgent.Status -eq "running") {
@@ -218,13 +235,13 @@ if ($vm.GuestAgent -and $vm.GuestAgent.Status -eq "running") {
}
```
This example gets a VM and displays guest agent network information if available.
This example gets a VM with guest agent information and displays network interface details.
### Example 8: Filter VMs with active guest agents
```powershell
Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$vmsWithGuestAgent = Get-ProxmoxVM | Where-Object {
$vmsWithGuestAgent = Get-ProxmoxVM -IncludeGuestAgent | Where-Object {
$_.GuestAgent -and $_.GuestAgent.Status -eq "running"
}
@@ -233,7 +250,21 @@ foreach ($vm in $vmsWithGuestAgent) {
}
```
This example gets all VMs and filters those with active guest agents.
This example gets all VMs with guest agent information and filters those with active guest agents.
### Example 9: Performance comparison - with and without guest agent
```powershell
Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
# Fast query without guest agent information
Measure-Command { $vms = Get-ProxmoxVM }
# Slower query with guest agent information
Measure-Command { $vmsWithGA = Get-ProxmoxVM -IncludeGuestAgent }
```
This example demonstrates the performance difference between queries with and without guest agent information.
## Related Links
Documentation/examples/VM-GuestAgent-Examples.ps1
+35 -20
View File
@@ -13,25 +13,25 @@ Write-Host "=== PSProxmox VM Guest Agent Examples ===" -ForegroundColor Green
# Example 1: Get a specific VM with guest agent information
Write-Host "`n1. Getting VM with Guest Agent Information" -ForegroundColor Yellow
$vmid = 100 # Change this to your VM ID
$vm = Get-ProxmoxVM -VMID $vmid
$vm = Get-ProxmoxVM -VMID $vmid -IncludeGuestAgent
if ($vm) {
Write-Host "VM: $($vm.Name) (ID: $($vm.VMID))" -ForegroundColor Cyan
if ($vm.GuestAgent) {
Write-Host "Guest Agent Status: $($vm.GuestAgent.Status)" -ForegroundColor Green
if ($vm.GuestAgent.Status -eq "running" -and $vm.GuestAgent.NetIf) {
Write-Host "Network Interfaces from Guest Agent:" -ForegroundColor Green
foreach ($interface in $vm.GuestAgent.NetIf) {
Write-Host " Interface: $($interface.Name)" -ForegroundColor White
Write-Host " MAC Address: $($interface.MacAddress)" -ForegroundColor Gray
if ($interface.IPv4Addresses -and $interface.IPv4Addresses.Count -gt 0) {
Write-Host " IPv4 Addresses: $($interface.IPv4Addresses -join ', ')" -ForegroundColor Gray
}
if ($interface.IPv6Addresses -and $interface.IPv6Addresses.Count -gt 0) {
Write-Host " IPv6 Addresses: $($interface.IPv6Addresses -join ', ')" -ForegroundColor Gray
}
@@ -49,7 +49,7 @@ if ($vm) {
# Example 2: Get all VMs and show guest agent status
Write-Host "`n2. Guest Agent Status for All VMs" -ForegroundColor Yellow
$allVMs = Get-ProxmoxVM
$allVMs = Get-ProxmoxVM -IncludeGuestAgent
Write-Host "VM Guest Agent Status Summary:" -ForegroundColor Cyan
$guestAgentStats = @{
@@ -61,7 +61,7 @@ $guestAgentStats = @{
foreach ($vm in $allVMs) {
$status = "Not Available"
$color = "Red"
if ($vm.GuestAgent) {
if ($vm.GuestAgent.Status -eq "running") {
$status = "Running"
@@ -75,7 +75,7 @@ foreach ($vm in $allVMs) {
} else {
$guestAgentStats.NotAvailable++
}
Write-Host " $($vm.Name) (ID: $($vm.VMID)): $status" -ForegroundColor $color
}
@@ -86,21 +86,21 @@ Write-Host " Not Available: $($guestAgentStats.NotAvailable)" -ForegroundColor
# Example 3: Filter VMs with active guest agents
Write-Host "`n3. VMs with Active Guest Agents" -ForegroundColor Yellow
$vmsWithActiveGA = $allVMs | Where-Object {
$_.GuestAgent -and $_.GuestAgent.Status -eq "running"
$vmsWithActiveGA = $allVMs | Where-Object {
$_.GuestAgent -and $_.GuestAgent.Status -eq "running"
}
if ($vmsWithActiveGA.Count -gt 0) {
Write-Host "VMs with active Guest Agents:" -ForegroundColor Green
foreach ($vm in $vmsWithActiveGA) {
Write-Host " $($vm.Name) (ID: $($vm.VMID))" -ForegroundColor White
if ($vm.GuestAgent.NetIf) {
$totalIPs = ($vm.GuestAgent.NetIf | ForEach-Object {
$_.IPv4Addresses.Count + $_.IPv6Addresses.Count
$totalIPs = ($vm.GuestAgent.NetIf | ForEach-Object {
$_.IPv4Addresses.Count + $_.IPv6Addresses.Count
} | Measure-Object -Sum).Sum
Write-Host " Network Interfaces: $($vm.GuestAgent.NetIf.Count)" -ForegroundColor Gray
Write-Host " Total IP Addresses: $totalIPs" -ForegroundColor Gray
}
@@ -126,7 +126,7 @@ foreach ($vm in $vmsWithActiveGA) {
IPVersion = "IPv4"
}
}
foreach ($ipv6 in $interface.IPv6Addresses) {
$networkData += [PSCustomObject]@{
VMName = $vm.Name
@@ -158,17 +158,17 @@ Write-Host "Searching for VMs with IP address: $searchIP" -ForegroundColor Cyan
$foundVMs = $vmsWithActiveGA | Where-Object {
$vm = $_
$found = $false
if ($vm.GuestAgent.NetIf) {
foreach ($interface in $vm.GuestAgent.NetIf) {
if ($interface.IPv4Addresses -contains $searchIP -or
if ($interface.IPv4Addresses -contains $searchIP -or
$interface.IPv6Addresses -contains $searchIP) {
$found = $true
break
}
}
}
return $found
}
@@ -181,6 +181,21 @@ if ($foundVMs.Count -gt 0) {
Write-Host "No VMs found with IP address $searchIP" -ForegroundColor Yellow
}
# Example 6: Performance comparison
Write-Host "`n6. Performance Comparison" -ForegroundColor Yellow
Write-Host "Comparing query performance with and without guest agent data:" -ForegroundColor Cyan
# Fast query without guest agent information
$fastTime = Measure-Command { $fastVMs = Get-ProxmoxVM }
Write-Host "Fast query (without guest agent): $($fastTime.TotalSeconds) seconds" -ForegroundColor Green
# Slower query with guest agent information
$slowTime = Measure-Command { $slowVMs = Get-ProxmoxVM -IncludeGuestAgent }
Write-Host "Detailed query (with guest agent): $($slowTime.TotalSeconds) seconds" -ForegroundColor Yellow
$speedDifference = [math]::Round(($slowTime.TotalSeconds / $fastTime.TotalSeconds), 2)
Write-Host "Guest agent queries are ${speedDifference}x slower but provide detailed network information" -ForegroundColor Cyan
Write-Host "`n=== Examples Complete ===" -ForegroundColor Green
# Disconnect from the server when done