Find VMs and nodes in a Proxmox VE cluster

The generated cmdlets need to know where a guest is: -Node pve01 -Vmid 100. In a cluster you usually know the name or the id, not the node, and the VM may have migrated since yesterday. Get-PveGuest looks the VMs and containers up in the whole cluster and returns them with their node.

Get-PveGuest

Without parameters it returns every VM and container of the cluster, sorted by node and id:

Get-PveGuest | Format-Table vmid, name, node, type, status

The objects are the entries of type vm of /cluster/resources: vmid, name, node, type (qemu for VMs, lxc for containers), status, pool, tags, template, and the live usage (cpu, mem, maxmem, disk, maxdisk, uptime).

Selecting guests

-VmIdOrName takes a comma-separated list, the same selection used by the other cv4pve tools. Each item is one of:

Item	Selects
100	The guest with that id.
100:120	Ids from 100 to 120, both included.
web01	By name, without case.
%web%, web%, %web	Names that contain, start with or end with web.
web*, db-0?	PowerShell wildcards on the name.
@node-pve01	Everything on node pve01. @all-pve01 and all-pve01 do the same.
@pool-customer1	Everything in pool customer1 and in its nested pools (customer1/web…).
@tag-production	Everything with tag production, among the other tags of the guest.
@all, all	Everything.

An item starting with - excludes what it selects, wherever it is in the list:

Get-PveGuest -VmIdOrName 100
Get-PveGuest -VmIdOrName '%web%'
Get-PveGuest -VmIdOrName '100:120,200,db01'
Get-PveGuest -VmIdOrName '@tag-production,-@node-pve03'     # production, except what runs on pve03
Get-PveGuest -VmIdOrName '@all,-@tag-template,-9000:9099'   # everything, except templates by tag and a range

Each guest is returned once, even when it matches several items. The exclusions are applied after all the other items: -100:110 excludes a range, it is not the range from -100 to 110.

Into the other cmdlets

The objects have node and vmid properties, which the generated cmdlets bind by name. Filter on type first, because VMs and containers have different endpoints:

# configuration of every VM tagged "production"
Get-PveGuest -VmIdOrName '@tag-production' |
    Where-Object type -eq 'qemu' |
    Get-PveNodesQemuConfig |
    ForEach-Object { $_.Response.data | Select-Object name, memory, cores }

# containers of pool "web" that are stopped
Get-PveGuest -VmIdOrName '@pool-web' |
    Where-Object { $_.type -eq 'lxc' -and $_.status -eq 'stopped' }

The functions written for convenience (power and snapshots) take the same -VmIdOrName and choose the endpoint for each guest themselves.

Templates are included: filter them out with Where-Object template -ne 1 when a script must not touch them.

Note

/cluster/resources is refreshed by Proxmox VE every few seconds. Right after a task (a start, a migration, a new guest), Get-PveGuest may still show the previous status or node, and a guest just created may appear without its name for a moment. To know the state right after a task, ask the guest itself: Get-PveNodesQemuStatusCurrent or Get-PveNodesLxcStatusCurrent.

Get-PveVm is the former name of Get-PveGuest and still works as an alias.

Get-PveNode

Get-PveNode returns the nodes of the cluster, from the same /cluster/resources, with node, status (online or offline) and the usage of CPU, memory and disk. -Node filters by name, with wildcards:

Get-PveNode | Format-Table node, status, cpu, maxcpu, mem, maxmem
Get-PveNode -Node 'pve0*'

Permissions

Both read /cluster/resources, which returns only what the token or user may see: a token limited to pool web gets the guests of that pool and nothing else. An empty result may mean missing privileges, not an empty cluster. @pool- also reads the pools, with Get-PvePools.