memory-allocation

Memory 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 memory already taken, and the memory still free to assign to a partition, 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 use of the memory inside the partitions, 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 …>
  <AssociatedSystemMemoryConfiguration kb="CUD" kxe="false" schemaVersion="V1_0">
    <ConfigurableSystemMemory kb="ROR" kxe="false">98304</ConfigurableSystemMemory>
    <CurrentAvailableSystemMemory kb="ROR" kxe="false">88832</CurrentAvailableSystemMemory>
  …
  <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: the configurable memory that is not available is taken.
• available is CurrentAvailableSystemMemory, as the HMC writes it, returned as MiB (see Limits).
• A system that gives no configurable memory (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 memory is all assigned on purpose leaves assigned-high unchecked.

Limits

• The use of the memory inside the partitions is not read: the HMC serves it through its Performance and Capacity Monitoring API, under the conditions processor-allocation gives.
• The unit of the memory, the HMC's MB, is not written in IBM's public documentation: it is read in the HMC responses pypowervm publishes, where the memory is a whole number of the system's memory regions (256 MB). Those powers of two point to binary megabytes: available is returned as MiB, which is not confirmed by IBM. assigned, a ratio, does not depend on it.
• 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 AssociatedSystemMemoryConfiguration, ConfigurableSystemMemory and CurrentAvailableSystemMemory 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.