DPU Endpoints

ClusterWareAI ™ DPU primitives represent Data Processing Units (DPUs) attached to compute nodes. Compute nodes can optionally have one or more DPUs. The ClusterWareAI software can PXE boot and deploy images to DPUs.

ClusterWareAI DPU support is available for NVIDIA BlueField-3 DPUs with DOCA. Additional support may be added in future releases. Contact Penguin Computing to discuss alternative requirements.

When issuing requests, the UID field in the URL can be the actual UID of the primitive, the generated name of the primitive as given in the "name" field, the MAC address, the assigned IP address, the hostname, or the fully qualified hostname. For example, once a DPU, n4, is created, it can be referenced through /dpu/n4, /dpu/<UID>, /dpu/<MAC>, or /dpu/<IP>.

Data Fields

DPU primitives can have several fields:

name
   Assigned by the software: The name is computed from the naming pool
   pattern and the DPU's index.

description
   Optional: A text string with descriptive information.

type
   Assigned by the software: Always set to ``dpu``. The type is fixed and
   cannot be modified after creation.

mac
   Required: Every DPU must have a MAC address. The MAC address must be
   unique across compute nodes, switches, and DPUs.

host
   Required: The compute node host for this DPU provided by node name, UID,
   or other identifier.

attributes
   Optional: A set of key-value pairs assigned to the DPU. Use these
   attributes when configuring the DPU at boot time.

groups
   Optional: An ordered list of Attribute Groups that this DPU belongs to.
   attributes from each group are applied (overwritten) based on the order
   of the groups.

naming_pool
   Optional: A naming pool may be assigned and used to calculate the DPU's
   name, index, and IP address.

index
   Assigned by the software; the index (integer) is computed based on
   the naming pool

ip
   Assigned by the software; the IP address is computed based on the naming
   pool

power_uri
   Optional: A URI used by power-control helpers. The URI can be a template
   with bracketed fields that are substituted from the DPU's attributes,
   status, or hardware values.

redfish_uri
   Optional

cmdline
   Optional: Kernel command-line override for DPU boot workflows.

Additional Endpoints

Several collection endpoints provide lookup and selection helpers for known DPUs:

GET /dpus/bymac/<part>
   Returns DPU UIDs based on a partial MAC-address match.

GET /dpus/byip/<part>
   Returns DPU UIDs based on a partial assigned-IP match.

GET /dpus/byindex/<index>
   Returns DPU UIDs based on index.

GET /dpus/select/<expr>
   Returns DPU UIDs selected by an expression.

GET /dpus/rescan
   Rescans the database to check DPU indices.

Several endpoints provide finer-grained access to the list of Attribute Groups that the DPU belongs to:

GET /dpu/<UID>/groups
   Returns the ordered list of Attribute Groups applied to the DPU.

POST /dpu/<UID>/groups
   Appends one group key or a list of group keys to the current group list.

DELETE /dpu/<UID>/groups
   Removes one group key or a list of group keys from the current group
   list.

Several endpoints provide finer-grained access to the attributes assigned to a specific DPU. DPUs inherit attributes from all groups that they belong to and overwrite them with any DPU-specific attributes:

GET /dpu/<UID>/attributes
   Returns a JSON object with the effective attributes for this DPU. If
   ``fmt=ini`` is supplied, the response is returned as plaintext INI-style
   content instead of JSON.

PUT /dpu/<UID>/attributes
   Replaces the current set of DPU-specific attributes with the sent data.

PATCH /dpu/<UID>/attributes
   Updates the current set of DPU-specific attributes with the sent data.

DELETE /dpu/<UID>/attributes
   Accepts one key or a list of keys to remove from the DPU-specific
   attributes. If an attribute is set by an Attribute Group, it will still be
   present in the DPU's overall list of attributes.

Several endpoints support boot, power, status, reachability, and command execution workflows. Hard BMC-style actions such as power on, power off, cycle, and reset are not valid directly on DPUs. Include "host": true in PUT /dpu/<UID>/power_state requests to run power actions against the host compute node. Use ?host=true with GET /dpu/<UID>/power_state to query the host compute node's power state.

PUT /dpu/<UID>/bootdev
   Sets the next boot device. The request body must contain ``bootdev`` with
   one of ``none``, ``pxe``, ``disk``, or ``bios``.

GET /dpu/<UID>/power_uri
   Returns a JSON object with ``unparsed`` and ``parsed`` power URI data
   after substitutions have been applied.

GET /dpu/<UID>/power_state
   Returns the power state of the host. For a DPU, requires the ``host=true``
   query parameter to return the host node's power state.

PUT /dpu/<UID>/power_state
   Requests a power-state action. The request body may contain ``state`` or
   ``steps``, plus optional ``force`` and ``host`` boolean fields.

GET /dpu/<UID>/status
   Returns the most recent DPU status information.

GET /dpu/<UID>/ping
   Checks whether the DPU is reachable.

PUT /dpu/<UID>/exec
   Executes a command on the DPU. The request body must contain ``cmd`` and
   may contain ``stdin``. The response is an ``application/octet-stream``
   stream with raw command output, not a JSON object with ``success`` and
   ``data`` keys.

The DPU status and attribute reporting endpoints mirror the machine status reporting system used by compute nodes:

PUT /dpu/putstatus
   Updates status information from the acting DPU. This endpoint is exposed
   as a public endpoint and identifies the caller from the request
   connection. If ``fmt=ini`` is supplied, the response is plaintext.

POST /dpu/putstatus
   Administratively assigns DPU status or hardware data. The request body
   includes the target ``uid`` field plus status and/or hardware data.

PUT /dpu/putattribs
   Updates attributes from the acting DPU. This endpoint is exposed as a
   public endpoint and identifies the caller from the request connection.

DPU state map endpoints are also available for workflows that wait for groups of DPUs to reach selected states:

POST /dpus/waitfor
   Uploads a set of states that can be watched for changes.

GET /dpus/waitfor/<name>
   Returns the named state map.

PUT /dpus/waitfor/<name>
   Keeps the named state map active and returns current matching DPU lists.

DELETE /dpus/waitfor/<name>
   Deletes the named state map.

GET /dpus/waitfor/<name>/dpus
   Returns the current DPU lists for entries in the state map.

Example

Create a new DPU attached to host node n1:

curl -X POST https://head1.cluster.local/api/v1/dpus \
    --data '{"host":"n1", "mac":"22:33:44:55:66:77"}' \
    -H "Authorization: Bearer <access_token>"
{"success": true, "data": "4b1fe139f7d64d14a8b4e7fbe675ce15"}

Verify the DPU data using the returned UID:

curl -X GET https://head1.cluster.local/api/v1/dpu/4b1fe139f7d64d14a8b4e7fbe675ce15 \
    -H "Authorization: Bearer <access_token>"
{"success": true, "data": {"mac": "22:33:44:55:66:77", \
    "host": "341b9947f6e644b78f6d88f5d7f898f4", "attributes": {}, "index": 4, \
    "ip": "192.168.122.104", "type": "dpu", "uid": "4b1fe139f7d64d14a8b4e7fbe675ce15", \
     "groups": [], "hardware": {}, "power_uri": null, "name": "n4", \
     "hostname": "n4", "domain": "cluster.local"}}

Since DPUs can be referenced by name or MAC address, the same information is available using:

curl -X GET https://head1.cluster.local/api/v1/dpus/22:33:44:55:66:77 \
    -H "Authorization: Bearer <access_token>"

Set the DPU to boot from PXE on its next boot:

curl -X PUT https://head1.cluster.local/api/v1/dpu/n4/bootdev \
    --data '{"bootdev":"pxe"}' \
    -H "Authorization: Bearer <access_token>"
{"success": true}

Power cycle the DPU's host compute node:

curl -X PUT https://head1.cluster.local/api/v1/dpu/n4/power_state \
    --data '{"state":"cycle", "host": true}' \
    -H "Authorization: Bearer <access_token>"
{"success": true, "data": "cycle"}