processor-allocation

Processor allocation of the servers of an IBM HMC, by its REST API

Returns, for each IBM Power server a Hardware Management Console (HMC) manages, the share of its configurable processor units already assigned to partitions, and the units still free, read from the HMC REST API with an account. It answers "can I start or grow a partition on this server?": it is an allocation, not the load of the processors, which is not read. Two watches are offered, both unchecked by default.

Versions

Written for the HMC REST API (Web Services API, schema V1_1_0 and later) as IBM documents it for the HMC of POWER9 (HMC V9) and Power10 (HMC V10): the Logon and ManagedSystem resources. Hence the common level, under the folder hmc of the product.

How it works

The collector opens a session, or takes back the one its probe keeps (see "The session" in managed-systems, which works the same way), then reads GET https://<host:address>/rest/api/uom/ManagedSystem, the session in the header X-API-Session:

<ManagedSystem:ManagedSystem …>
  <AssociatedSystemProcessorConfiguration kb="CUD" kxe="false" schemaVersion="V1_0">
    <ConfigurableSystemProcessorUnits kb="ROR" kxe="false">8</ConfigurableSystemProcessorUnits>
    <CurrentAvailableSystemProcessorUnits kb="ROR" kxe="false">7.6</CurrentAvailableSystemProcessorUnits>
  …
  <SystemName kb="CUR" kxe="false">p10-a</SystemName>

• A system is named by its SystemName, as in managed-systems.
• assigned is (configurable − available) × 100 / configurable, to a tenth of a percent.
• available is CurrentAvailableSystemProcessorUnits: the processor units free to assign, a processor core counting 1.
• A system that gives no configurable unit (powered off, no connection) returns nothing on that run.
• A code 401 or 403 at the logon stops the collector misconfigured, as a second refusal of the feed does; any other code but 200 stops it unreachable. No system at all stops it misconfigured.

The password comes from protocol:http:password, a secret variable: it only goes, written by xml.escape, in the body of the logon. The session only goes in the header X-API-Session, and in the cache.

Prerequisites

• The HMC's address as the host's address, reachable from the poller in HTTPS (443). Its certificate follows the TLS profile of the probe, as for managed-systems.
• An HMC account in protocol:http:user and protocol:http:password, of the task role hmcviewer (Viewer: it views and changes nothing), the narrowest of the predefined roles, with a resource role that covers the managed systems to watch.

Outputs

Watches

• A server whose capacity is all assigned on purpose leaves assigned-high unchecked.

Limits

• The use of the processors is not read. The HMC serves it through its Performance and Capacity Monitoring API (/rest/api/pcm/…), only once an administrator has enabled the collection of utilization data for the system on the HMC, a change of its settings that a monitoring account should not make; and as JSON files linked from an Atom feed, a second collector's matter.
• The address is written into the URL as is: an IPv6 address must be given as a name.
• Each value is read as the HMC writes it, with its attributes kb and kxe; a value written without attributes would stop the collector misconfigured, never return a wrong value.
• Not checked against an HMC: the routes are those of IBM's documentation of the HMC REST APIs (Logon, ManagedSystem). The elements AssociatedSystemProcessorConfiguration, ConfigurableSystemProcessorUnits and CurrentAvailableSystemProcessorUnits are not described in that documentation: they are read in IBM's own client library, pypowervm, and in the HMC responses it publishes for its tests.