PKey GUIDs Rest API - NVIDIA Docs

Note

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

Create an Empty PKey

Description: Allows creating a PKey without GUIDs.
Request URL: POST /ufmRest/resources/pkeys/add
Request Content Type: Application/json

Request Data Example:

Copy
Copied!

            
            {
 "pkey":"0x12",     
 "index0":false,       
 "ip_over_ib":true, 
 "mtu_limit":2,      
 "service_level":0,  
 "rate_limit":2.5     
}

The required parameters are PKey only, all the others are optional and take the default in case they were not sent.

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
ip_over_ib	Boolean: true/false	True	PKey is a member in a multicast group that uses IP over InfiniBand	Optional
index0	Boolean: true/false	False	If true, the API will store the PKey at index 0 of the PKey table of the GUID.	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.
pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory

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

Request Data Example

Copy
Copied!

            
            {
"guids": ["0002c903000e0b72", "0002c903000e0b73"],
"ip_over_ib": false,
"index0": true,        
"membership": "full",
"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

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

Copy
Copied!

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

Response Data Example – with GUID data

Copy
Copied!

            
            {
    "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

Copy
Copied!

            
            ["0x1", "0x2", "0x3"]

Response Data Example – with GUID data

Copy
Copied!

            
            {
"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/updates a list of configured GUIDs for PKey (or overwrites the current list, if found), including Quality-of-Service (QoS) parameters.
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
ip_over_ib	Boolean: true/false	True	PKey is a member in a multicast group that uses IP over InfiniBand	Optional
index0	Boolean: true/false	False	If true, the API will store the PKey at index 0 of the PKey table of the GUID.	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
pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory

Request Data Example

Copy
Copied!

            
            { 
  "guids": ["0002c903000e0b72", "0002c903000e0b73"], 
  "ip_over_ib" : false, "index0": true, 
  "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
Note

To use this API to trigger Mellanox Scalable Hierarchical Aggregation and Reduction Protocol (SHARP)™ allocations and deallocations, please refer to "NVIDIA SHARP 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 - POST /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.

Copy
Copied!

            
            {   
  "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

Copy
Copied!

            
            {
  "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

Copy
Copied!

            
            {
    "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

On This Page