NVIDIA UFM Enterprise REST API Guide v6.18.0
NVIDIA UFM Enterprise REST API Guide v6.18.0

NVIDIA SHARP REST API

Note

SHARPv2 must be running (enable_SHARP = true) and the NVIDIA Scalable Hierarchical Aggregation and Reduction Protocol (SHARP)™ allocation parameter must be enabled (enable_SHARP_alloction = true) for this API to trigger resource (GUID) allocations and deallocations within SHARP.

NVIDIA SHARP reservation REST APIs support the following operations:

Get All Reservations

  • Description – Retrieves all SHARP reservations

  • Request URL – GET /ufmRest/app/sharp/allocate_resources

  • Request Content-Type – Application/json

  • Response

    Copy
    Copied!
                

    { "anas1":{ "pkey":"0x12", "guids":["0x248a0703008a850a", "0x248a0703008a850b"] }, "anas2":{ "pkey":"0x12", "guids": ["0xf452140300383a01", "0xf452140300383a02"] } }

  • Status Codes

    • 200 – OK

    • 400 – BAD_REQUEST

Get Specific SHARP Reservation

  • Description – Gets specific SHARP reservation by app_id

  • Request URL – GET /ufmRest/app/sharp/allocate_resources/<app_id>

  • Request Content Type – Application/json

  • Status Codes

    • 200 – OK

    • 400 – BAD_REQUEST

    • 404 – NOT_FOUND

Copy
Copied!
            

{ "anas1":{ "pkey": "0x12", "guids": ["0x248a0703008a850a", "0x248a0703008a850b"] } }


Create a New SHARP Reservation

Note

The following API is replacing the deprecated SHARP API presented in earlier versions of this UFM Enterprise REST API Guide.

  • Description – Creates a new SHARP reservation. By default, the SHARP blocking API is called, which entails sending the reservation request to SHARP and awaiting the response (success or fail). To revert to the previous behavior of using the non-blocking API, set the "blocking" parameter in the API to false. If the partial allocation parameter is set to false, the SHARP allocation request will not succeed in the event that even a single node is absent in the fabric. By default, this parameter is set to true.

  • Example of a false partial allocation: Request URL – POST /ufmRest/app/sharp/resources?partially_alloc=false

  • Example of calling a non-blocking API: Request URL – POST /ufmRest/app/sharp/resources?blocking=false

  • Request Content-Type – Application/json

  • Status Codes

    • 202 – ACCEPTED (All nodes were added successfully to created allocation)

    • 206 – PARTIAL (Not all nodes were added to created allocation because they are not found in the fabric)

    • 200 - OK (All nodes were added successfully to the created allocation and the SHARP blocking API is called)

    • 400 – BAD_REQUEST

  • Request Data

    Name

    Value

    Default

    Description

    Mandatory/Optional

    App_id

    String

    None

    "0x7fff" (This is the default management pkey) Application id.

    It is also the identifier of this nodes allocation

    Mandatory

    App_resources_limit

    Integer

    -1

    Application resources limitation

    Optional

    Hosts_names

    String

    None

    A string of hosts names separated by a comma, to be added to sharp allocation.

    Example:

    "r-ufm77,r-ufm51"

    Optional

    Port_guids

    list

    None

    List of ports guids Example:

    ["f452140300383a01", "f452140300383a02"]

    Optional

    pkey

    Hexadecimal string between "0x0001"-"0x7ffe" exclusive

    "0x7fff" (This is the default management pkey)

    Created network PKey to be used by Sharp

    Optional

Examples:

  • Create SHARP allocation by sending hosts_names:

    Copy
    Copied!
                

    { "app_id":"99", "hosts_names":"r-ufm51,r-ufm55", "pkey":"0x12", "app_resources_limit": -1 }

  • Create SHARP allocation by sending port_guids:

    Copy
    Copied!
                

    { "app_id":"99", "port_guids": ["f452140300383a01", "f452140300383a02"], "pkey":"0x12", "app_resources_limit": -1 }

Delete SHARP Reservation

Note

The following API is replacing the deprecated SHARP API presented in earlier versions of the UFM Enterprise REST API Guide.

  • Description - Deletes SHARP Allocation. By default, the SHARP blocking API is called to delete SHARP reservation.

  • Example of calling delete allocation using SHARP blocking API: Request URL - DELETE /ufmRest/app/sharp/resources/<app_id>

  • Example of calling delete allocation using SHARP non-blocking API: Request URL - DELETE /ufmRest/app/sharp/resources/<app_id>?blocking=false

  • Request Content-Type – Application/json

  • Status Codes

    • 204 – NO CONTENT

    • 400 – BAD_REQUEST

Update SHARP Reservation

Note

The following API is replacing the deprecated SHARP API presented in earlier versions of this UFM Enterprise REST API Guide.

  • Description – Updates SHARP Allocation. By default, the update SHARP blocking API is called, which entails sending the update reservation request to SHARP and awaiting the response (success or fail). To revert to the previous behavior of using the non-blocking API, set the "blocking" parameter in the API to false. If the partial allocation parameter is set to false, the SHARP allocation request will not succeed in the event that even a single node is absent in the fabric. By default, this parameter is set to true.

  • Example of a false partial allocation: Request URL – PUT /ufmRest/app/sharp/resources/<app_id>?partially_alloc=false

  • Example of calling a non-blocking API: Request URL – PUT /ufmRest/app/sharp/resources<app_id>?blocking=false

  • Request Content-Type – Application/json

  • Status Codes

    • 202 – ACCEPTED (All nodes were updated successfully to SHARP allocation)

    • 206 – PARTIAL (Not all nodes were updated to SHARP allocation because they are not found in the fabric)

    • 200 - OK (All nodes were updated successfully to the SHARP allocation and the SHARP blocking API is called)

    • 400 – BAD_REQUEST

  • Body Examples:

    • Update SHARP allocation by sending hosts_names:

      Copy
      Copied!
                  

      {    "hosts_names":"r-ufm51,r-ufm77" }

    • Update SHARP allocation by sending port_guids:

      Copy
      Copied!
                  

      {    "port_guids":["f452140300383a01", "f452140300383a02"] }

The SHARP jobs REST API provides methods on obtaining information on SHARP jobs and support the following operations:

Get All SHARP Jobs

  • Description – Retrieves all active SHARP jobs.

  • Request URL – GET /ufmRest/app/sharp/resources/jobs

  • Request Content Type – Application/json

  • Status Codes

    • 200 – OK

  • Response

    Copy
    Copied!
                

    {    "99:58":{       "job_id":58,       "num_guids":1,       "num_rails":1,       "trees":{          "0":{             "tree_id":0,             "type":"LLT",             "ANs":{                "0x33333":{                   "description":"sw3",                   "lid":23,                   "rank":1,                   "guid":"0x33333",                   "parent_guid":null,                   "child_guids":null,                   "hca_guids":[                      "0x78395179",                      "0x78395178"                   ]                }             }          }       },       "reservation_key":"99"    },    "99:74":{       "job_id":74,       "num_guids":1,       "num_rails":1,       "trees":{          "0":{             "tree_id":0,             "type":"LLT",             "ANs":{                "0x33333":{                   "description":"sw3",                   "lid":23,                   "rank":1,                   "guid":"0x33333",                   "parent_guid":null,                   "child_guids":null,                   "hca_guids":[                      "0x78395179",                      "0x78395178"                   ]                }             },             "reservation_key":"99"          }       }    } }

Get a Specific SHARP Job

  • Description – Retrieves specific active SHARP jobs with specific a reservation_id

  • Request URL – GET /ufmRest/app/sharp/resources/jobs/<job_id>?reservation_id=<reservation_id>

  • Request Content Type – Application/json

  • Status Codes

    • 200 – OK

    • 404 – NOT_FOUND

  • Response

    Copy
    Copied!
                

    {    "99:58":{       "job_id":58,       "num_guids":1,       "num_rails":1,       "trees":{          "0":{             "tree_id":0,             "type":"LLT",             "ANs":{                "0x33333":{                   "description":"sw3",                   "lid":23,                   "rank":1,                   "guid":"0x33333",                   "parent_guid":null,                   "child_guids":null,                   "hca_guids":[                      "0x78395179",                      "0x78395178"                   ]                }             }          }       },       "reservation_key":"99"    } }

Get All SHARP Non-Blocking Jobs

  • Description – Retrieves all active SHARP jobs using non blocking SHARP API

  • Request URL – GET /ufmRest/app/sharp/resources/jobs_nb

  • Request Content Type – Application/json

  • Status Codes

    • 200 – OK

  • Response – the HTTP response location header contains a URL with job ID created for running the action.

    Example:

    Copy
    Copied!
                

    { "ID":"1", "Status":"Completed", "Progress":100, "Description":"Get sharp jobs", "Created":"2023-05-03 09:48:35", "LastUpdated":"2023-05-03 09:48:35",     "Summary": { "99:58":{       "job_id":58,       "num_guids":1,       "num_rails":1,       "trees":{           "0":{              "tree_id":0,             "type":"LLT",             "ANs":{                "0x33333":{                   "description":"sw3",                   "lid":23,                   "rank":1,                   "guid":"0x33333",                   "parent_guid":null,                   "child_guids":null,                  "hca_guids":["0x78395179", "0x78395178"]                }             }          }       },       "reservation_key":"99"    },    "99:74":{       "job_id":74,       "num_guids":1,       "num_rails":1,       "trees":{          "0":{             "tree_id":0,             "type":"LLT",             "ANs":{                "0x33333":{                   "description":"sw3",                   "lid":23,                   "rank":1,                   "guid":"0x33333",                   "parent_guid":null,                   "child_guids":null,                  "hca_guids":["0x78395179", "0x78395178"]                }             },             "reservation_key":"99"          }       }   } }, "RelatedObjects":[], "CreatedBy":"admin", "Operation":"Get sharp jobs", "Foreground":true, "SiteName":"" }

Get Specific SHARP Non-Blocking Job

  • Description – Retrieves specific active SHARP jobs with specific reservation_id using non blocking SHARP API

  • Request URL – GET /ufmRest/app/sharp/resources/jobs_nb/<job_id>?reservation_id=<reservation_id>

  • Request Content Type – Application/json

  • Status Codes

    • 200 – OK

    • 404 – NOT_FOUND

  • Response – the HTTP Response location header contains a URL with job ID created for running the action. Example:

    Copy
    Copied!
                

    { "ID":"1", "Status":"Completed", "Progress":100, "Description":"Get sharp jobs", "Created":"2023-05-03 09:48:35", "LastUpdated":"2023-05-03 09:48:35",     "Summary": { "99:58":{       "job_id":58,       "num_guids":1,       "num_rails":1,       "trees":{          "0":{             "tree_id":0,             "type":"LLT",             "ANs":{                "0x33333":{                   "description":"sw3",                   "lid":23,                   "rank":1,                   "guid":"0x33333",                   "parent_guid":null,                   "child_guids":null,                   "hca_guids":["0x78395179", "0x78395178"]                     }             }          }       },       "reservation_key":"99"  },  "RelatedObjects":[], "CreatedBy":"admin", "Operation":"Get sharp jobs", "Foreground":true, "SiteName":"" }

    Extract the Performance counters of specific hostnames

    • Description – This API is used to get the Performance counters for a specific list of hostnames.

      You can do filtering based on counter names. you can show the job summary in both JSON and CSV format.

    • Request URL – POST /ufmRest/app/sharp/resources/pm_counters?csv_format=true

    • Request Content Type – Application/json

    • {"hosts_names":"r-ufm51,r-ufm77", "pm_counters_names": ["PortRcvConstraintErrors", "PortXmitConstraintErrors"]}

    • Status Codes

      • 202 – ACCEPTED

      • 400 – BAD_REQUEST

    • Response – the HTTP Response location header contains a URL with job ID created for running the action. Example:

      Copy
      Copied!
                  

      [ { "ID": "1", "Status": "Completed", "Progress": 100, "Description": "Get performance counters for hosts of sharp jobs", "Created": "2024-07-28 07:37:34", "LastUpdated": "2024-07-28 07:37:37", "Summary": "NodeGUID,PortGUID,PortNumber,PortRcvConstraintErrors,PortXmitConstraintErrors,SystemName\n0xb8599f03000a7768,0xb8599f03000a7768,1,0,0,r-ufm77\n0x0c42a1030079a66c,0x0c42a1030079a66c,35,0,0,sw-ufm-qm01\n0x0c42a1030079a66c,0x0c42a1030079a66c,36,0,0,sw-ufm-qm01\n0x0c42a1030079a66c,0x0c42a1030079a66c,37,0,0,sw-ufm-qm01\n0x0c42a1030079a66c,0x0c42a1030079a66c,38,6,0,sw-ufm-qm01\n0xb8599f03000a7769,0xb8599f03000a7769,1,0,0,r-ufm77\n0xf452140300383a00,0xf452140300383a01,1,0,0,r-ufm51\n0xf452140300383a00,0xf452140300383a02,2,0,0,r-ufm51\n", "RelatedObjects": "", "CreatedBy": "admin", "Operation": "", "Foreground": true, "SiteName": "" }, { "ID": "2", "Status": "Completed", "Progress": 100, "Description": "Get performance counters for hosts of sharp jobs", "Created": "2024-07-28 07:38:39", "LastUpdated": "2024-07-28 07:38:41", "Summary": "[{'NodeGUID': '0xb8599f03000a7768', 'PortGUID': '0xb8599f03000a7768', 'PortNumber': '1', 'PortRcvConstraintErrors': '0', 'PortXmitConstraintErrors': '0', 'SystemName': 'r-ufm77'}, {'NodeGUID': '0x0c42a1030079a66c', 'PortGUID': '0x0c42a1030079a66c', 'PortNumber': '35', 'PortRcvConstraintErrors': '0', 'PortXmitConstraintErrors': '0', 'SystemName': 'sw-ufm-qm01'}, {'NodeGUID': '0x0c42a1030079a66c', 'PortGUID': '0x0c42a1030079a66c', 'PortNumber': '36', 'PortRcvConstraintErrors': '0', 'PortXmitConstraintErrors': '0', 'SystemName': 'sw-ufm-qm01'}, {'NodeGUID': '0x0c42a1030079a66c', 'PortGUID': '0x0c42a1030079a66c', 'PortNumber': '37', 'PortRcvConstraintErrors': '0', 'PortXmitConstraintErrors': '0', 'SystemName': 'sw-ufm-qm01'}, {'NodeGUID': '0x0c42a1030079a66c', 'PortGUID': '0x0c42a1030079a66c', 'PortNumber': '38', 'PortRcvConstraintErrors': '6', 'PortXmitConstraintErrors': '0', 'SystemName': 'sw-ufm-qm01'}, {'NodeGUID': '0xb8599f03000a7769', 'PortGUID': '0xb8599f03000a7769', 'PortNumber': '1', 'PortRcvConstraintErrors': '0', 'PortXmitConstraintErrors': '0', 'SystemName': 'r-ufm77'}, {'NodeGUID': '0xf452140300383a00', 'PortGUID': '0xf452140300383a01', 'PortNumber': '1', 'PortRcvConstraintErrors': '0', 'PortXmitConstraintErrors': '0', 'SystemName': 'r-ufm51'}, {'NodeGUID': '0xf452140300383a00', 'PortGUID': '0xf452140300383a02', 'PortNumber': '2', 'PortRcvConstraintErrors': '0', 'PortXmitConstraintErrors': '0', 'SystemName': 'r-ufm51'}]", "RelatedObjects": "", "CreatedBy": "admin", "Operation": "", "Foreground": true, "SiteName": "" } ]

© Copyright 2024, NVIDIA. Last updated on Aug 29, 2024.