Note that the previous PKey GUIDs APIs based on /ufmRest/actions/ are deprecated and being replaced by the new set of APIs below (based on /ufmRest/resources/).

Description – allows users to manage PKey GUIDs by getting, adding, and removing GUIDs from PKeys.
Request URL – /ufmRest/resources/
Main Operations
- Add GUIDs to PKey
- Remove GUIDs from PKey
- Get a Specific PKey
- Get all PKeys
- Set GUIDs for PKey
- Delete PKey
- Update QoS for PKey

Add GUIDs to PKey

Description – adds a list of configured GUIDs to PKey.
Request URL – POST /ufmRest/resources/pkeys/
Request Content Type – Application/json

Request Data Parameters

Name	Value	Default	Description	Mandatory/ Optional
guids	["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters	None	List of port GUIDs	Mandatory
pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory
index0	Boolean: true/false	False	If true, the API will store the PKey at index 0 of the PKey table of the GUID.	Optional
ip_over_ib	Boolean: true/false	True	PKey is a member in a multicast group that uses IP over InfiniBand	Optional
membership	“full”, “limited”	"full"	“full”- members with full membership can communicate with all hosts (members) within the network/partition “limited” - members with limited membership cannot communicate with other members with limited membership. However, communication is allowed between every other combination of membership types.	Optional
memberships	[“full”, “limited”, ...] List of “full” or “limited” comma-separated strings. It must be the same length as the GUIDs list. Each value by an index represents a GUID membership.	[]	List of memberships to allow users to create or modify different membership per GUID in same PKey. GUID index 0 in the “guids” list will take index 0 from the memberships list and so on (by order)	This parameter is optional. This parameter conflicts with the “membership” parameter. Users must select either a list of memberships or just one membership for all GUIDs.
mtu_limit	value can be 2k or 4k	2	MTU limit	Optional
service_level	value can be range from 0-15	0	Service level	Optional
rate_limit	value can be one of the following: 2.5, 10, 30, 5, 20, 40, 60, 80, 120, 14, 56, 112, 168, 25, 100, 200, or 300	2.5	Rate Limit	Optional

Response – N/A
Status Codes
- 200 – OK
- 400 – bad request

Request Data Example

{
"guids": ["0002c903000e0b72", "0002c903000e0b73"],
"ip_over_ib": false,
"index0": true,        
"membership": "full",
"mtu_limit":2, 
"service_level":0, 
"rate_limit":2.5,   "pkey": "0x0a12"

}

Response – N/A
Status Codes
- 200 – OK
- 400 – bad request

Remove GUIDs from PKey

Description – remove a list of configured GUIDs from PKey
Request URL – DELETE /ufmRest/resources/pkeys/<pkey>/guids/<guid1>,<guid2>,…
Request Content Type – Application/json

Request Data Parameters

Name	Value	Default	Description	Mandatory/ Optional
guids	["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters	None	List of port GUIDs	Mandatory
pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory

Status Codes
- 200 – OK
- 400 Bad request

Get Specific PKey

Description – returns information about the specified PKey. The "guids_data" parameter enables retrieving information on the GUIDs of the specified PKey as well.
Request URL – GET /ufmRest/resources/pkeys/<pkey>?guids_data=<boolean>
- <pkey> – hexadecimal pkey in the range of 0x0-0x7fff
Request Content Type – Application/json

Response Data Example – without GUID data

{
    "partition": "api_pkey_0x1", 
    "ip_over_ib": true
}

Response Data Example – with GUID data

{
    "guids": [
        {
            "membership": "full", 
            "guid": "0002c903000e0b78", 
            "index0": false
        }
    ], 
    "ip_over_ib": true, 
    "partition": "api_pkey_0x1"
}

Status Codes
- 200 – OK

Get All PKeys

Description – returns a list of all PKeys (with or without their associated GUIDs data).
Request URL – GET /ufmRest/resources/pkeys?guids_data=<boolean>&qos_conf=<boolean>
- guids_data flag
  - False – returns a list of all PKeys
  - True – returns a list of all PKeys including their associated GUIDs
- qos_conf flag
  - False – returns a list of all PKeys without QoS configuration
  - True – returns a list of all PKeys including their associated QoS configuration
- port_info flag
  - False – returns a list of all PKeys without port information details
  - True – returns a list of all PKeys including their associated port information
- max_ports flag
  - <positive-int-value> – returns a list of all PKeys with port information details for ports with number less than or equal to the provided value
Request Content Type
Application/json
Response Data Example – without GUID data
```
["0x1", "0x2", "0x3"]
```

Response Data Example – with GUID data

{
"0x3": {
"guids": [
{
"membership": null, "guid": "0002c903000e0b74",
"index0": false
},
{
"membership": null, "guid": "0002c903000e0b75",
"index0": false
}
],
"ip_over_ib": true, "partition": "api_pkey_0x3",
"qos_conf":{"mtu_limit":4,
             "Rate_limit":300,
              "Service_level":3}
}, "0x2": {
"guids": [
{
"membership": null, "guid": "0002c903000e0b76",
"index0": false
},
{
"membership": null, "guid": "0002c903000e0b77",
"index0": false
}
],
"ip_over_ib": true, "partition": "api_pkey_0x2",
"qos_conf":{"mtu_limit":4,
             "Rate_limit":300,
              "Service_level":3
}, "0x1": {
"guids": [
{
"membership": "full", "guid": "0002c903000e0b78",
"index0": false
}
],
"ip_over_ib": true, "partition": "api_pkey_0x1",
"qos_conf":{"mtu_limit":4,
             "Rate_limit":300,
              "Service_level":3
}
}

Status Codes
- 200 – OK

Set/Update PKey GUIDs

Description – sets a list of configured GUIDs for PKey (or overwrites the current list, if found)
Request URL – PUT /ufmRest/resources/pkeys/
Request Content Type – Application/json

Request Data Parameters

Name	Value	Default	Description	Mandatory/ Optional
guids	["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters	None	List of port GUIDs	Mandatory
pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory
index0	Boolean: true/false	False	If true, the API will store the PKey at index 0 of the PKey table of the GUID.	Optional
ip_over_ib	Boolean: true/false	True	PKey is a member in a multicast group that uses IP over InfiniBand	Optional
membership	“full”, “limited”	"full"	“full”- members with full membership can communicate with all hosts (members) within the network/partition “limited” - members with limited membership cannot communicate with other members with limited membership. However, communication is allowed between every other combination of membership types.	Optional
memberships	[“full”, “limited”, ...] List of “full” or “limited” comma-separated strings. It must be the same length as the GUIDs list. Each value by an index represents a GUID membership.	[]	List of memberships to allow users to create or modify different membership per GUID in same PKey. GUID index 0 in the “guids” list will take index 0 from the memberships list and so on (by order)	This parameter is optional. This parameter conflicts with the “membership” parameter. Users must select either a list of memberships or just one membership for all GUIDs.

Request Data Example

{ 
  "guids": ["0002c903000e0b72", "0002c903000e0b73"], 
  "ip_over_ib" : false, "index0": true, 
  "index0": true,
  "membership": "full", 
  "pkey": "0x0a12"
}

Response – N/A
Status Codes
- 200 – OK
- 400 – bad request
To use this API to trigger Mellanox Scalable Hierarchical Aggregation and Reduction Protocol (SHARP)™ allocations and deallocations, please refer to "NVIDIA SHARP Resource Allocation REST API".

Add Hosts to PKey

Description - Allows the user to create new Partition key (Pkey) assignments, including all the ports allocated to sent host names. UFM-SLURM plugin reads the following API attributes (ip_over_ib, index0, membership) from ufm_slurm.conf file, and sends them in request body.
Request URL - /ufmRest/resources/pkeys/hosts
Status Codes
- 200 – OK
- 400 – not found

Request Data Example:
The response is a job and its status depends on the action output.

{   
  "hosts_names":"r-ufm51,r-ufm77", 
  "ip_over_ib": true, 
  "index0": false, 
  "membership": "full", 
  "pkey": "0xa12" 
}

Remove Hosts from PKey

Description - Using this API allowed the user to remove a list of configured Hosts GUIDs from PKey.
Request URL - DELETE /ufmRest/resources/pkeys/<pkey>/hosts/<host_name1>,<host_name2>,…
Status Codes
- 200 – OK
- 400 – not found

Delete PKey

Description – deletes a PKey and all of its configured GUIDs
Request URL – DELETE /ufmRest/resources/pkeys/<pkey>
Status Codes
- 200 – OK
- 404 – not found

Update PKey QoS

Description – updates the QoS configuration for a specific PKey
Request URL – PUT /ufmRest/resources/pkeys/qos_conf

Request Data Example

{
  "mtu_limit": 4,
  "service_level": 5,
  "rate_limit": 2,
  "pkey": "0x9"
}

Notes
- mtu_limit value can be 2k or 4k
- service_lever value can be range from 0-15
- rate_limit value can be one of the following: 2.5, 10, 30, 5, 20, 40, 60, 80, 120, 14, 56, 112, 168, 25, 100, 200, or 300
- Restarting UFM is required for the PKey QoS configuration to take effect
Status Codes
- 200 – OK
  400 – bad request

PKey Version (Last Updated)

Description – returns the time when PKey data was last modified
Request URL – GET /ufmRest/resources/pkeys/last_updated

Request Data Example

{
    "last_updated": "Thu Sep  3 11:42:39 UTC 2020"
}

Notes
- Last updated data is not persistent and will be reset when UFM is restarted
- By default, when no updates are done on PKey data, last_updated value will be null
- The value of last_updated returned by this REST API will be updated when one of the following REST APIs are called:
  - Add GUIDs to PKey
  - Remove GUIDs from PKey
  - Set GUIDs for PKey
  - Delete PKey
  - Update QoS for PKey

Content

Space Tools

On This Page

Add GUIDs to PKey

Remove GUIDs from PKey

Get Specific PKey

Get All PKeys

Set/Update PKey GUIDs

Add Hosts to PKey

Remove Hosts from PKey

Delete PKey

Update PKey QoS

PKey Version (Last Updated)

Content

Space Tools

PKey GUIDs Rest API

On This Page

Add GUIDs to PKey

Remove GUIDs from PKey

Get Specific PKey

Get All PKeys

Set/Update PKey GUIDs

Add Hosts to PKey

Remove Hosts from PKey

Delete PKey

Update PKey QoS

PKey Version (Last Updated)