datastores

Datastores of a VMware vCenter, by its REST API

Returns, for each datastore of a vCenter, whether it is accessible, its used space, its free space and its size, 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 (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, with the id in the header vmware-api-session-id:

1. GET https://<host:address>/api/vcenter/datastore, the list:

[{"datastore": "datastore-12", "name": "ds-ssd-01", "type": "VMFS", "free_space": 536870912000, "capacity": 1099511627776}]

2. GET https://<host:address>/api/vcenter/datastore/<id> for each one, the only place where the API says whether it is accessible:

{"name": "ds-ssd-01", "type": "VMFS", "accessible": true, "free_space": 536870912000, "multiple_host_access": true, "thin_provisioning_supported": true}

• A datastore is named as vCenter names it; two datastores of the same name (in two datacenters) each keep their own, the second carrying its id (ds-ssd-01 #datastore-40).
• The state is accessible or inaccessible.
• The used space is the capacity less the free space, over the capacity; sizes are in bytes, returned in GiB. vCenter leaves the space out while it does not know it: such a datastore returns its state only.
• A code 401 or 403 at the login stops the collector misconfigured, a code 403 on a reading too; any other code but 200 stops it unreachable. No datastore at all stops it misconfigured: the account sees only the datastores 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 given the role Read-only on the vCenter root, propagated to its children, in protocol:http:user and protocol:http:password.

Outputs

Watches

Limits

• One reading per datastore: a vCenter with many datastores makes as many requests at each run.
• The space of a thin-provisioned datastore is the space written, not the space promised to its virtual disks: an overcommitted datastore is not seen before it fills.
• The API gives one accessible per datastore: how it judges a datastore that some hosts reach and others do not is not documented, and is not verified.
• vCenter answers 500 for more than 2,500 datastores: 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 and fields 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.