PKey GUIDs Rest API
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
Description: Allows creating a PKey without GUIDs.
Request URL: POST /ufmRest/resources/pkeys/add
Request Content Type: Application/json
Request Data Example:
{
"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.
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
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
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
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
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
NoteTo use this API to trigger Mellanox Scalable Hierarchical Aggregation and Reduction Protocol (SHARP)™ allocations and deallocations, please refer to "NVIDIA SHARP REST API".
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"
}
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
Description – deletes a PKey and all of its configured GUIDs
Request URL – DELETE /ufmRest/resources/pkeys/<pkey>
Status Codes
200 – OK
404 – not found
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
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