PKey GUIDs Rest API

Warning

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:

    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.

  • 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

    Copy
    Copied!
                

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

    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

  • 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

  • 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

    Copy
    Copied!
                

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

    Warning

    To 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.

    Copy
    Copied!
                

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

    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

  • 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

© Copyright 2023, NVIDIA. Last updated on Feb 8, 2024.