lpars

Logical partitions of an IBM HMC, by its REST API

Returns, for each logical partition (AIX, Linux, IBM i) and each Virtual I/O Server of the IBM Power servers a Hardware Management Console (HMC) manages, its state and the state of its RMC connection to the HMC, read from the HMC REST API with an account. Every partition is watched by default. Three watches are offered, each one set on the probe.

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, LogicalPartition and VirtualIOServer resources, whose quick properties PartitionName, PartitionState and RMCState are the values read. 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 two feeds, the session in the header X-API-Session:

1. GET https://<host:address>/rest/api/uom/LogicalPartition: the partitions of every managed system;
2. GET https://<host:address>/rest/api/uom/VirtualIOServer: the Virtual I/O Servers, which IBM serves apart.

<entry><id>…UUID…</id><content type="application/vnd.ibm.powervm.uom+xml; type=LogicalPartition">
  <LogicalPartition:LogicalPartition …>
    <PartitionName kb="CUR" kxe="false">lpar1</PartitionName>
    <PartitionState kb="ROO" kxe="false">running</PartitionState>
    <ResourceMonitoringControlState kb="ROR" kxe="false">active</ResourceMonitoringControlState>

• A partition is named by its PartitionName; two partitions of one name (on two managed systems) each keep their own, the second carrying its UUID (lpar1 #…).
• state is the HMC's, as it writes it: running, not activated, starting, shutting down, open firmware, error, not available, migrating running, suspended…
• rmc is the state of the RMC connection between the HMC and the partition, through which the HMC makes dynamic changes (DLPAR): active, inactive, none, busy, unknown.
• The HMC answers 204, without a body, for a feed with no entry: a site without Virtual I/O Server. No partition at all stops the collector misconfigured: the account sees only the partitions its resource role is set on.
• A code 401 or 403 at the logon stops the collector misconfigured, as a second refusal of a feed does; any other code but 200 and 204 stops it unreachable.

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. The logon and the DELETE that closes a refused session are the only requests that are not a GET, and change nothing on the partitions.

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: the HMC's self-signed certificate is trusted by pinning its fingerprint (protocol:http:fingerprint), by adding its authority under protocol:tls:authorities, or by trusting the first fingerprint in the tab "Security".
• An HMC account in protocol:http:user and protocol:http:password, of the task role hmcviewer (Viewer: it views the HMC and the systems, and changes nothing), the narrowest of the predefined roles, with a resource role that covers the partitions to watch.

Outputs

Watches

• not-running raises on every partition that does not run. A partition stopped on purpose (a spare, a test partition, one kept for a restore) is left out by the selection of the probe (*-test), or the selection keeps only the partitions that must run.
• A partition moved by Live Partition Mobility reads migrating running during the move: not-running raises unless for is set, or the state is added to its list.

Limits

• The address is written into the URL as is: an IPv6 address must be given as a name.
• Each feed carries the whole description of every partition (adapters, profiles, I/O): on an HMC with many hundreds of partitions, an answer beyond the poller's limit stops the collector unreachable.
• 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, LogicalPartition, VirtualIOServer, HTTP Status Codes). The layout of the feeds, the element ResourceMonitoringControlState (served as the quick property RMCState), and the lists of states are read in IBM's own client library, pypowervm (its LogicalPartitionStateEnum and ResourceMonitoringControlStateEnum), and in the HMC responses it publishes for its tests.