vms

Virtual machines of a VMware vCenter, by its REST API

Returns the power state of each virtual machine of a vCenter, read from the vCenter REST API with an account. Three watches are offered, none checked by default: which machines must run and which must stay off, only the administrator knows.

Versions

Written for the REST API that vCenter serves under /api from vSphere 7.0 Update 2 (7.0, 8.0 and 9.0). The older API under /rest, the only one of vSphere 6.5 to 7.0 Update 1, is not served: those versions are out of VMware's general support. Hence the folder vcenter-7.0u2.

How it works

The collector logs in once (POST https://<host:address>/api/session, the account in Basic; the id of the session kept 50 minutes in the cache of the probe, encrypted on the poller, and asked again, once, when vCenter answers 401), then reads GET https://<host:address>/api/vcenter/vm, the id in the header vmware-api-session-id:

[{"vm": "vm-42", "name": "web01", "power_state": "POWERED_ON", "cpu_count": 2, "memory_size_MiB": 4096}]

• A machine is named as vCenter names it; two machines of the same name (in two folders) each keep their own, the second carrying its id (web01 #vm-77).
• The power is powered-on, powered-off or suspended.
• A vCenter with no machine returns no value, and raises nothing.
• A code 401 or 403 at the login stops the collector misconfigured, a code 403 on the list too; any other code but 200 stops it unreachable.

The password comes from protocol:http:password, a secret variable: it only goes in the Basic header of the login. The id of the session is a secret too: it only goes in the header and in the cache.

Use

The probe has one selection for all its watches. To watch both the machines that must run and those that must stay off, put two probes of this collector on the vCenter:

• one whose selection is "Only" the machines that must run (web*, db01), with "Virtual machine not powered on" checked;
• one whose selection is "Only" the machines that must stay off (the cold standbys), with "Virtual machine not powered off" checked.

Prerequisites

• The vCenter's address as the host's address, reachable from the poller in HTTPS (443), its certificate trusted by the TLS profile of the probe: the root certificate of the vCenter's own authority (VMCA, in https://<vcenter>/certs/download.zip) under protocol:tls:authorities, a pinned fingerprint in protocol:http:fingerprint, or the first fingerprint trusted in the tab "Security".
• A vSphere account given the role Read-only on the vCenter root, propagated to its children, in protocol:http:user and protocol:http:password.

Outputs

Watches

Limits

• The snapshots of the machines are not read: the vCenter REST API does not list them (neither under /api in 7.0 and 8.0 nor in 9.0). They are served by the vSphere Web Services API, and over JSON by its VI/JSON form from vSphere 8.0 Update 1, which this collector does not use. The heartbeat of VMware Tools is not read either: it would take one request per machine.
• vCenter refuses to list more than 4,000 machines at once (code 500): the collector then stops unreachable, and says why.
• Whether the templates are listed among the machines is not documented, and not verified.
• The address is written into the URL as is: an IPv6 address must be given as a name.
• Not checked against a vCenter: the routes, fields and states are those of the published OpenAPI specifications of the vSphere Automation API, 7.0.3 and 8.0.2 (as the Ansible collection vmware.vmware_rest carries them); whether every field is served as early as 7.0 U2 is not verified.