hosts

Hosts of a VMware vCenter, by its REST API

Returns, for each ESXi host a vCenter manages, its connection state and its power state, read from the vCenter REST API with an account. Four watches are offered, each one set on the probe.

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, then reads the list of the hosts:

1. POST https://<host:address>/api/session, the account in Basic. vCenter answers 201 and the id of a session, a JSON text. The id is kept in the cache of the probe, encrypted on the poller, for 50 minutes; a session vCenter no longer knows (expired, vCenter restarted) answers 401, and the collector logs in again, once.
2. GET https://<host:address>/api/vcenter/host, the id in the header vmware-api-session-id:

[{"host": "host-10", "name": "esx01.example", "connection_state": "CONNECTED", "power_state": "POWERED_ON"}]

• A host is named as vCenter names it; two hosts of the same name (in two datacenters) each keep their own, the second carrying its id (esx01.example #host-31).
• The connection is vCenter's, in lower case, _ written -: connected, disconnected (an administrator disconnected it), not-responding (vCenter lost it).
• The power is powered-on, powered-off or standby; vCenter gives it for a connected host only, and a host that is not connected returns its connection alone.
• 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. No host at all stops it misconfigured: the account sees only the hosts its role is set on.

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.

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 (monitoring@vsphere.local, or an account of the directory vCenter is joined to) 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 maintenance mode and the health alarms of a host are not read: the vCenter REST API does not serve 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.
• Each probe of a vCenter keeps its own session: five probes, five sessions, each one closed by vCenter when it is idle.
• vCenter answers 500 for more than 2,500 hosts: the collector then stops unreachable.
• 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.