Confluent API Documentation

Confluent models functionality in a hierarchical structure. It is a RESTful or filesystem-like structure, depending on how you want to think of it. With respect to REST there are a couple of exceptional resources that are not strictly RESTful, which shall be explained.

This document will review the available resources as they are structured. It is suggested to browse the API using confetty (without arguments) or using a web browser pointed at http://[mgt]:4005/ (once remote HTTP usage has been enabled)

Enabling remote usage over HTTP¶

By default, confluent API is only accessible locally over a unix domain socket. To enable a remote user for HTTP access, the quickest method is to use confetty to create a local account:

# useradd apiuser
# passwd apiuser
confetty create /users/apiuser role=Administrator

With the above example, using 'apiuser' and the entered password in the user/password prompt will provide access when accessing the management server by http://servername:4005/.

Using python to access the API¶

All of the confluent command lines are implemented in python. They serve as a good reference to review accessing the API. For example, reviewing the source code of nodepower can be very informative. In general, a python developer will want to start by importing the client library:

import confluent.client as client

Next, you'll want to create a client session:

session = client.Command()

By default, this will reach out to the local instance. If you want to reach out to a remote server, you may pass that as a string to the Command() call, as in Command('172.20.0.1'). Also you would have to enable remote native confluent protocol, as described in remote confluent.

For many common interactions, there is a convenient method on the session object called 'simple_noderange_command()'. To accommodate more complex scenarios and map more directly to the underlying REST structure, the functions create(), read(), update(), and delete() are provided. See the client.py python API documentation for more details.

Top-level collections¶

The root of the API presents the following collections:

The discovery collection: /discovery/¶

The discovery collection gathers functionality related to detecting and scanning for new systems, and promoting detected systems to managed nodes. Generally confluent scans on startup and then passively listens for changes, so detected systems appear here automatically as they are found.

API Structure¶

The Confluent API structure is set up like a pseudo file system. Reading these paths will list the respective data. To update, the same path is given, along with the data to be used in the update, such as {'state' : [newstate]}.

Accessing Nodes: /nodes/ and /noderange/¶

/nodes/¶

The /nodes/ collection lists all defined nodes in confluent. Every operation that can be done against a node is represented in the /nodes/ collection. Functionality is further subdivided into categories under the top level /nodes/ location for a given node. The operations for a specific node are accessed with /nodes/[nodename]/

/noderange/[noderange]/¶

The /noderange/ top level structure appears empty. However, if the client requests a subcollection, [noderange]/, it will try to auto-create a matching collection based on the confluent noderange syntax. Strictly speaking, this is not RESTful, but consider it as an auto-mounting filesystem. For a given collection, the same structure produced by '/nodes/[nodename]/' is reproduced, but the operations are considered to apply to all nodes matching the noderange rather than just one node. Additionally, a noderange has a 'nodes/' subcollection to allow client software to list the nodes that match the noderange, but this does not allow operations on the individual nodes.

In the following examples, /nodes/[nodename]/ can be replaced by /noderange/[noderange]/ to execute the operations on multiple nodes.

Querying or setting power state: /nodes/[nodename]/power/state¶

This resource allows query and setting of the power state. Reading this value provides the current state, and sending {'state': [newstate]} will request a state change.

The recognized states are:

• on - Request system to be powered on. Has no effect if system is already on.
• off - Request system to be powered off, without waiting for OS to shut down.
  This is an immediate power down. Has no effect if system is already off.
• boot - Request system to take appropriate action to immediately start booting. If a system is on, this is effectively 'reset'. If a system is off, it has the same effect as 'on'
• reset - Request a running system to immediately start booting without regard for current OS. This has no effect with the system off.
• shutdown - Send a request to the running OS to gracefully shut down. This returns asynchronously to notify that the request has been relayed, but has no guarantee that the OS will react or that the OS will react as desired (e.g. an OS could present a shutdown dialog on console, or ignore such requests completely)

Reseat node: /nodes/[nodename]/power/reseat¶

Reseating is equivalent to unplugging the node and plugging it back in. Removes standby power and reapplies it.

Setting next boot device: /nodes/[nodename]/boot/nextdevice¶

Check and modify boot device override for next boot. Frequently used for an OS deployment or diagnostic boot to prepare for an exceptional boot case where the default OS boot is not desired, but only for one boot. Parameters are:

• bootmode - Allows requesting the firmware personality. Recognized values are
  • bios - Force a BIOS style boot in the style that x86 systems have historically booted from their initial release
  • uefi - Force the boot to be UEFI style
  • unspecified - Allow platform to choose
• persistent - True/False indication of whether to request the platform leave the override in place. For example, a request to network boot with persistent set to True should reboot from network from that point on, rather than reverting to default boot order after next boot
• nextdevice - The device/pseudo device to use in the next boot attempt. This is a single device and not an order of devices. The recognized devices are:
  • default - Use the usual boot sequence behavior without any overrides
  • setup - Boot the system into a configuration menu provided by firmware. Generally the same menu that results from pressing a special key during boot like 'F1'. If this is active, no keypress during boot should be required.
  • network - Boot the system using a network protocol, generally PXE
  • hd - Attempt to boot straight to a hard disk in a system
  • cd - Boot from a CD/DVD/BD device. In practice, this is frequently a virtual instance of a CD provided by remote media capability of a server.

Identifying a node: /nodes/[nodename]/identify¶

This controls the behavior of the server to provide a means of making its physical location known. Generally, this is an LED that illuminates on request. Sending {'identify': [newstate]} requests activation/deactivation of the LED. It is common for this data not to be readable, so querying the value is not generally promised to produce useful information (the server would return an empty value in such a case).

The recognized states are:

• on - The LED will be illuminated (in some implementations, it will blink)
• off - The LED will be deactivated

Monitoring hardware: /nodes/[nodename]/sensors/hardware/[category]/¶

This presents a collection of 'sensors' relevant to a node. These are current point-in-time indications of both numeric values (e.g. wattage, fanspeed, temperature) and discrete states (missing hard drive, failed DIMM).

Supported categories include:

• all - Returns all sensors present on the node
• temperature - Temperature sensors can include CPU temps, ambient temperatures, DIMM temperatures, etc.
• power - Power sensors can include AC Power and DC Power, and any other measurements of power
• energy - Energy sensors can include AC Energy and DC Energy, and any other measurements of energy
• leds - LED sensors return the state of LEDs on the node, including the identify LED, error LEDs, etc.
• fans - Fan sensors return the speed of fans such as PSU or CPU fans. This may also return discrete sensors such as a fault.

Each sensor may return the following fields:

• health - An assessment of whether the state of the component should be considered normal or a concern.
  The following states are declared:
  • ok - Sensor indicates no problem
  • warning - Sensor indicates an abnormal condition exists, but not one that is currently impacting workload. For example, excess correctable memory errors.
  • critical - Sensor indicates a severe problem exists that is impacting workload or presents an imminent risk of catastrophic data loss. For example, a degraded RAID array.
  • failed - Indicates a severe problem that has caused disruption of resources or data loss. For example, a fatal memory error resulting in a reboot, or loss of non-redundant storage.
• name - A string identifying the sensors
• state_ids - Numeric values representing the observed states. Generally this field can be ignored.
• states - A list of textual descriptions of currently active states. Examples include Present, Failed, Non-Redundant, and are intended to be self-explanatory and can be presented directly to an administrator without processing. Programmatic understanding of the severity is achieved through examining the 'health' field above.
• units - Optional indicator of the units to use when evaluating 'value' field
• value - A numeric value representing the current reading of the sensors. It is null when the sensor is a non-numeric sensor.

Configuring a node: /nodes/[nodename]/configuration/¶

This is where one can view and manipulate various configurations active on the node. This is distinguished from 'attributes' which are values stored about the node by confluent, but are not directly active on the system.

Managing system-defined configuration: /nodes/[nodename]/configuration/system/all¶

This is where one can read or edit system-defined configuration like BIOS or UEFI settings.

Resetting the management controller: /nodes/[nodename]/configuration/management_controller/reset¶

This can be used to request that the management controller for the node be reset. PUT {'state': 'reset'} in order to initiate a restart of the management controller

Viewing user accounts on the management controller: /nodes/[nodename]/configuration/management_controller/users/¶

This is a list of accounts considered local to the management controller. This excludes accounts provided by a central authentication provider, such as LDAP. It is indexed by an arbitrary index value that might not correlate to user names. For IPMI systems, it represents the 'user slot' of the user account. Each account provides the following fields:

• username - The username associated with this account
• privilege_level - The level of access afforded to the account. Levels are:
  • user - Able to read most sensor data
  • operator - Able to manipulate the running system, reboot, and access console
  • administrator - Able to change the configuration of the management controller, including authentication data, ip addresses, alert destinations, and so forth

Configuring NTP: /nodes/[nodename]/configuration/management_controller/ntp/[argument]/¶

Configure and control the NTP functionality of supported management controllers.
For management controllers implementing NTP in a manner supported by confluent, this provides the following mechanisms:

• enabled - Enable or disable NTP
• servers - Collection of servers currently configured. Can create new or update existing

Managing alert destinations: /nodes/[nodename]/configuration/management_controller/alerts/destinations/¶

Manage the list of destinations that the management controller will directly send alerts to. Alert information may be in turn propagated by the respective destination to more destinations and formats. Each item contains the following fields:

• ip - The ip address to transmit to
• retries - If acknowledge is enabled, the number of attempts to perform before giving up
• acknowledge_timeout - When waiting for an acknowledgement from the target, how long to wait before evaluating the need to retry
• acknowledge - Whether to expect an explicit acknowledgement. For example, SNMP traps do not have an SNMP mechanism to acknowledge receipt, so this would be disabled for normal SNMP traps. However, IPMI PET alerts are SNMP traps, but provide a mechanism a receiver can use to confirm receipt. If uncertain, this should be false unless otherwise indicated by the alert destination software.

Viewing host name used by management controller: /nodes/[nodename]/configuration/management_controller/identifier¶

Returns the host name that the management controller uses for DHCP requests.

Manage BMC domain name: /nodes/[nodename]/configuration/management_controller/domain_name/¶

Set/view the domain name of the BMC.

Managing IP configuration: /nodes/[nodename]/configuration/management_controller/net_interfaces/management¶

IP configuration data for the management controller. Note that changing this value without coordinating changes in the associated hardwaremanagement.manager attribute may cause disruption. The fields available:

• ipv4_address - The ipv4 address and netmask length in CIDR notation. This should provide the current value regardless of whether it is DHCP or static, but should not be PUT if the ipv4_configuration is not Static.
• ipv4_configuration - The method to use to assign the IPv4 address, either 'Static' or 'DHCP'
• ipv4_gateway - The gateway to use for non-local traffic. As in ipv4_address, PUT is only supported for this field if 'Static'
• hw_addr - The ethernet mac address of the interface

Running a shell session: /nodes/[nodename]/shell/sessions/¶

This is a non-RESTful resource, used to create a stateful ssh session suitable for use in a web browser. See the source of consolewindow.js for an example of how to interact. RESTful style interaction allows listing currently active shell sessions, but the primary role of translating HTTP to SSH is not something that fits the RESTful models

Running a console session: /nodes/[nodename]/console/session¶

This is a non-RESTful interface. It provides a mechanism for javascript code in a browser to present a terminal-in-a-browser proxying an HTTP based protocol to the appropriate console protocol for the node. The console is the single, authoritative text based console of the node. A node's console is active independent of having any clients connected, and multiple clients connecting always share a single view and input. Upon open, a console session may stream older data from log to client to help recreate the console.

Viewing availability of licensed functionality: /nodes/[nodename]/console/license¶

Describes the availability of potentially licensed functionality pertaining to remote console; for example, remote graphics console is frequently a premium feature provided at additional cost.

Viewing and setting node attributes: /nodes/[nodename]/attributes/[group]/¶

Lists attributes in confluent's datastore pertaining to nodes. This may contain information that confluent needs to function (e.g. address of management controllers), helpful metadata about a node (node location, admin notes), or cached data for performance enhancement or post-mortem (last health state, serial numbers, et al).

Attributes can be accessed via the following groups:

• all - Provides all possible attributes as well as current values
• current - Provides only those attributes that have been given values

When doing UPDATE, 'all' and 'current' will behave identically. The fields are defined in the [attributes] document. Each attribute has:

• value - The current value of the attribute, after any potential expressions and inheritance have been performed.
• inheritedfrom - Present and set if the current value is derived from a group level attribute rather than directly set on the node.
• expression - Present and set if the current value is calculated from an expression

Viewing hardware health: /nodes/[nodename]/health/hardware¶

An overall assessment of the health of the hardware associated with a node. It provides a 'health' field summarizing the most severe detected state, as well as a 'sensors' list of relevant readings to explain the reason for the health assessment. The content of the sensors is identical to the items in '/sensors'

Viewing hardware information: /nodes/[nodename]/inventory/hardware/[category]/¶

A list of hardware devices that are possible, their presence, and associated data.

Categories currently supported are:

• all - This is currently the only supported category, listing all hardware inventories. More categories may be added in the future.

The hardware inventory data is a list of objects with the following fields:

• name - A human friendly name describing the item
• information - A set of free-form key-value structured information about the inventory item. Though free-form, similar devices should resemble each other to the extent feasible.
• present - A true/false value indicated whether the specified device actually is populated in this specific node.

Viewing firmware information: /nodes/[nodename]/inventory/firmware/[category]/¶

Items containing firmware, and the current version information.

Categories currently supported are:

• all - Lists all firmware items and their current version information.
• updates/active - A collection of firmware updates currently in progress. Will hold this information after update completion until removed.

The firmware data may contain:

• date - The date that the firmware was created by the vendor
• version - The version designation as indicated by the vendor
• build - A freeform build identification string vendors may use to more fully describe firmware. For example, 1.2 may mean different things on different products, but a vendor may elect to have unique build ids to embed the product family into a single value, without worrying about making clear what version is newer than another, as is the case with version

Viewing log of hardware events: /nodes/[nodename]/events/hardware/log¶

An enumeration of events and timestamps that have happened to the indicated node. Each event has:

• component - A textual description of a physical or logical entity related to the event. For example, "Progress", "Host Power", "Non Auth DIMMs"
• component_type - A description of what type of entity the component is. Examples are: "System Firmware", "Power Unit" and "Memory"
• event - A text description of the event that occurred
• id - A numerical value representing the id, useful for looking up the id against a database
• record_id - An identifier associated with the event by the providing device
• severity - An assessment of any health state changes that would be caused by this event. The values are the same as the 'health' values.
• timestamp - When available, ISO-8601 timestamp of when the event happened, in local time relative to the confluent server.

Decoding alert data: /nodes/[nodename]/events/hardware/decode¶

This provides a facility for decoding and enriching alert data from a target. For example, an SNMP trap handler can use this to decode a PET (Platform Event Trap) alert originating from an IPMI source into a human-readable event.

Managing physical and virtual media: /nodes/[nodename]/media/[argument]¶

Manage physical and virtual media, such as a USB, CD, or iso image.

Arguments include:

• current - A collection of all uploaded and attached media
• uploads - Manages process of uploading media to management controller for use in OS. Will list current and completed uploads, until told to delete.
• attach - Requests that BMC connect to another server and associate that URL with a media device, instructing BMC to use the file at the URL
• detach - Detaches attached media or deletes an uploaded image or file

Additional node resources¶

The following resources are also available under /nodes/[nodename]/ and /noderange/[noderange]/. They map directly to the corresponding client commands, which are the most convenient way to explore them.

• power/inlets and power/outlets - Power distribution unit (PDU) inlets and outlets associated with the node, for environments where confluent manages PDUs alongside servers.
• console/graphical, console/ikvm, console/ikvm_methods, console/ikvm_screenshot - Remote graphical (KVM) console access and a screenshot of the current graphical console, where licensed and supported.
• deployment/lock, deployment/ident_image, deployment/remote_config/run, deployment/remote_config/active - Per-node OS deployment control, including the deployment lock and remotely launched configuration (e.g. Ansible) runs.
• configuration/storage/ - Hardware storage controller configuration: all, arrays, disks, and volumes for creating and managing RAID arrays and drive usage (see the nodestorage command).
• configuration/management_controller/licenses and .../certificate - Management controller license installation and TLS certificate signing, CSR generation, and installation (see the nodelicense and nodecertutil commands).
• inventory/firmware/[category] - In addition to all, firmware is broken out into core, adapters, disks, and misc categories.
• support/servicedata - Collect vendor service data (support archives) from the node's management controller (see the nodesupport command).