Create plugin to list Virtual Machines in order to test include/exclude options

[atc0005]

Overview

Provide a plugin to list Virtual Machines n order to test include/exclude options.

This plugin would provide a way to test the include/exclude options supported by other plugins:

• include/exclude based on Virtual Machine name
• include/exclude based on Resource Pool name
• include/exclude based on power state
• and so on

The idea is that this could be useful for sysadmins, but also to anyone developing a plugin or extending features for existing plugins (e.g., #588, #595).

A later version of the plugin might provide a flag to accept a list of Virtual Machine names as an assertion check: error if the results from applying include/exclude filters do not exactly match the given list.

References

• check-vmware/cmd/check_vmware_vm_power_uptime/main.go

  Lines 335 to 336 in be2a29d

  	vms,
  	filteredVMs,

• check-vmware/internal/vsphere/vms.go

  Lines 1488 to 1489 in be2a29d

  	allVMs []mo.VirtualMachine,
  	evaluatedVMs []mo.VirtualMachine,

[atc0005]

Also related:

What does "filtered by" mean?

If we look solely at this line:

check-vmware/cmd/check_vmware_vm_power_uptime/main.go

Line 214 in be2a29d

Str("vms_filtered_by_power_state", strings.Join(vsphere.VMNames(filteredVMs), ", ")).

it isn't so clear to me, but if we add in the other lines for that function call it becomes clearer:

check-vmware/cmd/check_vmware_vm_power_uptime/main.go

Lines 213 to 216 in be2a29d

	log.Debug().
	Str("vms_filtered_by_power_state", strings.Join(vsphere.VMNames(filteredVMs), ", ")).
	Int("vms_excluded_by_power_state", numVMsExcludedByPowerState).
	Msg("VMs after power state filtering")

VMs filtered by X is the VMs remaining after X filtering is applied to drop those which don't meet the criteria.

This becomes even clearer when you take in the surrounding logic:

check-vmware/cmd/check_vmware_vm_power_uptime/main.go

Lines 198 to 216 in be2a29d

	log.Debug().
	Str("vms_evaluated", strings.Join(vsphere.VMNames(vms), ", ")).
	Msg("Evaluated Virtual Machines")
	log.Debug().Msg("Drop any VMs we've been asked to exclude from checks")
	filteredVMs, numVMsExcludedByName := vsphere.ExcludeVMsByName(vms, cfg.IgnoredVMs)
	log.Debug().
	Str("vms_filtered_by_name", strings.Join(vsphere.VMNames(filteredVMs), ", ")).
	Int("vms_excluded_by_name", numVMsExcludedByName).
	Msg("VMs after name filtering")
	log.Debug().Msg("Filter VMs to specified power state")
	filteredVMs, numVMsExcludedByPowerState := vsphere.FilterVMsByPowerState(filteredVMs, cfg.PoweredOff)
	log.Debug().
	Str("vms_filtered_by_power_state", strings.Join(vsphere.VMNames(filteredVMs), ", ")).
	Int("vms_excluded_by_power_state", numVMsExcludedByPowerState).
	Msg("VMs after power state filtering")

The vms_evaluated line is clearly meant (at least from reading my own writing) to indicate what we have to work with "at the beginning". The value for this line is the vms collection.

That said, the vsphere.VMPowerCycleUptimeReport function has these parameters:

check-vmware/internal/vsphere/vms.go

Lines 1488 to 1489 in be2a29d

	allVMs []mo.VirtualMachine,
	evaluatedVMs []mo.VirtualMachine,

but we give it these arguments:

check-vmware/cmd/check_vmware_vm_power_uptime/main.go

Lines 335 to 336 in be2a29d

	vms,
	filteredVMs,

• vms in main.go map to allVMs in vms.go
• filteredVMs in main.go map to evaluatedVMs in vms.go

I find other examples like this sprinkled about.

I expect that within a single plugin I was probably consistent (variable scope helps with this), but since shared logic spans multiple files and functions the meaning behind the terms was mixed up.

At some point I'll need to carve out the time to build a brief terms list and enforce the consistent use of those terms across the project.

In particular, the mixing of "all" VMs and "filtered" VMs (see /cmd/check_vmware_vm_power_uptime/main.go and /internal/vsphere/vms.go) are problematic.