HMS Notification Fanout Daemon v1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Nodes like compute nodes or user access nodes may want to be notified when other nodes or components in the system change state. For example, in a booted system, a node may be in tight communication with other nodes in the system and need to be notified when any of those nodes go away. The HMS Notification Fanout Daemon (HMNFD) provides the Hardware State Manager with the capability of fanning out state change notifications to subscribing compute nodes. HMNFD provides the ability to notify subscribers of component hardware state changes and other changes made to and by the Hardware State Manager. To receive notifications, a compute node must have an http or https based HMNFD API endpoint service running. This is where the State Change Notifications will be sent when they occur. HMNFD works with the Hardware State Manager and distributes state changes and manages subscriptions.

The REST API provides the following functions:

  • Subscription for component state changes:

    • Hardware state (On, Off, Ready, Standby, Halt, etc.)
    • Logical state (arbitrary like AdminDown, Other, etc.)
    • Role (Compute, Management, Application, etc.)
    • SubRole (Master, Worker, Storage, etc.)
    • Enabled state

  • View current subscriptions

  • Delete subscriptions

  • Retrieve and modify current service operating parameters

  • Create state change notifications for distribution to subscribers

Deprecation Notice: V1 of the HMS service has been deprecated as of CSM version 1.2.0. The V1 HMNFD API’s will be removed in the CSM version 1.5 release. All consumers of the V1 HMNFD API interface will need to move to the V2 interface prior to the CSM 1.5 release.

Resources

/subscriptions

Manage and view subscriptions to notifications. This resource is generally used by compute nodes.

/scn

State change notification messages sent from Hardware State Manager to HMNFD; the same format is used for notifications sent by HMNFD to subscribers. This resource applies only to the HSM.

/params

Retrieve or update configurable parameters.

/health

Retrieve health information for the service and its dependencies.

Workflows

Manage SCN Subscriptions

GET /subscriptions

Retrieve and view current subscriptions.

POST /subscriptions/{xname}/agents/{agent}

A node will subscribe to whatever state change notifications (SCNs) it wants to receive. Thus, the node needs to have a service running to which HMNFD can send, via REST, the subscribed-to SCNs. A URL that tells where to send the SCNs is provided as part of the request body schema. Once a subscribed-to SCN occurs, NFD sends it to the node’s service via a REST call to the URL supplied during the subscribe operation. The {xname} and {agent} segments of the URL state which node and which agent on that node are doing the subscribing. The subscription request info is in the body of the POST payload.

PATCH /subscriptions/{xname}/agents/{agent}

Modify an existing SCN subscription. Component list, component states, etc. can be modified with this request, which will remain associated with the component and software agent specified in the URL.

DELETE /subscriptions/{xname}/agents

Delete all subscriptions that are not needed on a given node.

DELETE /subscriptions/{xname}/agents/{agent}

Delete a specific subscription on a given node.

Update Service Configurable Parameters

GET /params

Fetch a JSON-formatted list of current configurable parameters.

PATCH /params

Change the value of one or more configurable parameters.

Base URLs:

Authentication

  • HTTP Authentication, scheme: bearer

subscriptions

Used for managing State Change Notification subscriptions

doGetSubscriptionInfo

Code samples

GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /subscriptions

Retrieve currently-held state change notification subscriptions

Retrieve all information on currently held State Change Notification subscriptions.

Example responses

200 Response

{
  "SubscriptionList": [
    {
      "Components": [
        "x0c1s2b0n3"
      ],
      "Subscriber": "scnHandler@x1000c1s2b0n3",
      "SubscriberComponent": "x1000c1s2b0n3",
      "SubscriberAgent": "scnHandler",
      "Enabled": "true",
      "Roles": [
        "Compute"
      ],
      "SoftwareStatus": [
        "AdminDown"
      ],
      "States": [
        "Ready"
      ],
      "Url": "https://x0c1s2b0n3.cray.com:8080/scns"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success. Currently held subscriptions are returned. SubscriptionListArray
401 Unauthorized Unauthorized. RBAC prevented operation from executing, or authentication token has expired. Problem7807
404 Not Found Does Not Exist. Endpoint not available. Problem7807
405 Method Not Allowed Operation Not Permitted. For /subscriptions, only GET operations are allowed. Problem7807
500 Internal Server Error Internal Server Error. Unexpected condition encountered when processing the request. Problem7807
default Default Unexpected error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

doGetSubscriptionInfoXName

Code samples

GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname} HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /subscriptions/{xname}

Retrieve currently-held state change notification subscriptions for a given component

Retrieve currently held State Change Notification subscriptions for a component.

Parameters

Name In Type Required Description
xname path XName.1.0.0 true none

Example responses

200 Response

{
  "SubscriptionList": [
    {
      "Components": [
        "x0c1s2b0n3"
      ],
      "Subscriber": "scnHandler@x1000c1s2b0n3",
      "SubscriberComponent": "x1000c1s2b0n3",
      "SubscriberAgent": "scnHandler",
      "Enabled": "true",
      "Roles": [
        "Compute"
      ],
      "SoftwareStatus": [
        "AdminDown"
      ],
      "States": [
        "Ready"
      ],
      "Url": "https://x0c1s2b0n3.cray.com:8080/scns"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success. Currently held subscriptions are returned. SubscriptionListArray
400 Bad Request Bad Request. Invalid XName in URL path. Problem7807
401 Unauthorized Unauthorized. RBAC prevented operation from executing, or authentication token has expired. Problem7807
404 Not Found Does Not Exist. Endpoint not available. Problem7807
405 Method Not Allowed Operation Not Permitted. For /subscriptions, only GET operations are allowed. Problem7807
500 Internal Server Error Internal Server Error. Unexpected condition encountered when processing the request. Problem7807
default Default Unexpected error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

doSubscriptionDeleteXName

Code samples

DELETE https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X DELETE https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /subscriptions/{xname}/agents

Delete all state change notification subscriptions for a component

Delete all state change notification subscriptions for a component.

Parameters

Name In Type Required Description
xname path XName.1.0.0 true none

Example responses

400 Response

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "status": 400,
  "title": "Description of HTTP Status code, e.g. 400"
}

Responses

Status Meaning Description Schema
204 No Content Success. None
400 Bad Request Bad Request. Invalid XName in URL path. Problem7807
401 Unauthorized Unauthorized. RBAC prevented operation from executing, or authentication token has expired. Problem7807
404 Not Found Does Not Exist. Endpoint not available. Problem7807
405 Method Not Allowed Operation Not Permitted. Only DELETE operations are allowed. Problem7807
500 Internal Server Error Internal Server Error. Unexpected condition encountered when processing the request. Problem7807
default Default Unexpected error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

doSubscriptionPOSTV2

Code samples

POST https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent} HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /subscriptions/{xname}/agents/{agent}

Subscribe to a state change notification

Subscribe to state change notifications for a set of components. Once this is done, the subscribing components will receive these notifications as they occur, using the URL specified at subscription time. The xname of the subscribing component as well as the software agent doing the subscribing are specified in the URL path.

Body parameter

{
  "Components": [
    "x0c1s2b0n3"
  ],
  "Enabled": "true",
  "Roles": [
    "Compute"
  ],
  "SoftwareStatus": [
    "AdminDown"
  ],
  "States": [
    "Ready"
  ],
  "Url": "https://x0c1s2b0n3.cray.com:8080/scns"
}

Parameters

Name In Type Required Description
body body SubscribePostV2 true none
xname path string true The xname of the subscribing component (typically a node)
agent path string true The software agent running on the subscribing component

Example responses

400 Response

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "status": 400,
  "title": "Description of HTTP Status code, e.g. 400"
}

Responses

Status Meaning Description Schema
200 OK Success. None
400 Bad Request Bad Request. Malformed JSON. Verify all JSON formatting in payload, and that all xnames are properly formatted. Problem7807
401 Unauthorized Unauthorized. RBAC prevented operation from executing, or authentication token has expired. Problem7807
404 Not Found Does Not Exist. Endpoint not available. Problem7807
405 Method Not Allowed Operation Not Permitted. Only PATCH and DELETE operations are allowed. Problem7807
500 Internal Server Error Internal Server Error. Unexpected condition encountered when processing the request. Problem7807
default Default Unexpected error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

doSubscriptionPATCHV2

Code samples

PATCH https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent} HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X PATCH https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.patch('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PATCH", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PATCH /subscriptions/{xname}/agents/{agent}

Modify a subscription to state change notifications

Modify an existing subscription to state change notifications for a component and software agent. The xname of the subscribing component as well as the software agent doing the subscribing are specified in the URL path.

Body parameter

{
  "Components": [
    "x0c1s2b0n3"
  ],
  "Enabled": "true",
  "Roles": [
    "Compute"
  ],
  "SoftwareStatus": [
    "AdminDown"
  ],
  "States": [
    "Ready"
  ],
  "Url": "https://x0c1s2b0n3.cray.com:8080/scns"
}

Parameters

Name In Type Required Description
body body SubscribePostV2 true none
xname path string true The xname of the subscribing component (typically a node)
agent path string true The software agent running on the subscribing component

Example responses

400 Response

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "status": 400,
  "title": "Description of HTTP Status code, e.g. 400"
}

Responses

Status Meaning Description Schema
204 No Content Success. None
400 Bad Request Bad Request. Malformed JSON. Verify all JSON formatting in payload, and that all xnames are properly formatted. Problem7807
401 Unauthorized Unauthorized. RBAC prevented operation from executing, or authentication token has expired. Problem7807
404 Not Found Does Not Exist. Endpoint not available. Problem7807
405 Method Not Allowed Operation Not Permitted. Only POST, PATCH and DELETE operations are allowed. Problem7807
500 Internal Server Error Internal Server Error. Unexpected condition encountered when processing the request. Problem7807
default Default Unexpected error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

doSubscriptionDeleteXNameAgentV2

Code samples

DELETE https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent} HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X DELETE https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/subscriptions/{xname}/agents/{agent}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /subscriptions/{xname}/agents/{agent}

Delete a specific state change notification subscription

Delete a specific state change notification subscription associated with a target component and a target software agent. The xname of the subscribing component as well as the software agent on the subscribing component are specified in the URL path.

Parameters

Name In Type Required Description
xname path string true The xname of the subscribing component (typically a node)
agent path string true The software agent running on the subscribing component

Example responses

400 Response

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "status": 400,
  "title": "Description of HTTP Status code, e.g. 400"
}

Responses

Status Meaning Description Schema
204 No Content Success. None
400 Bad Request Bad Request. Invalid XName in URL path or No matching subscription for DELETE. Problem7807
401 Unauthorized Unauthorized. RBAC prevented operation from executing, or authentication token has expired. Problem7807
404 Not Found Does Not Exist. Endpoint not available. Problem7807
405 Method Not Allowed Operation Not Permitted. Only DELETE operations are allowed. Problem7807
500 Internal Server Error Internal Server Error. Unexpected condition encountered when processing the request. Problem7807
default Default Unexpected error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

scn

State change notification messages sent from Hardware State Manager to HMNFD; the same format is used for notifications sent by HMNFD to subscribers.

doSCN

Code samples

POST https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/scn HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/scn \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/scn', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/scn", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /scn

Send a state change notification

Send a state change notification for fanout to subscribers. This is the API endpoint for Hardware State Manager through which to send state change notifications.

Body parameter

{
  "Components": [
    "x0c1s2b0n3"
  ],
  "Enabled": "true",
  "Role": "Compute",
  "SoftwareStatus": "AdminDown",
  "State": "Ready"
}

Parameters

Name In Type Required Description
body body StateChanges true none

Example responses

400 Response

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "status": 400,
  "title": "Description of HTTP Status code, e.g. 400"
}

Responses

Status Meaning Description Schema
200 OK Success. None
400 Bad Request Bad Request. Malformed JSON. Verify all JSON formatting in payload. Problem7807
401 Unauthorized Unauthorized. RBAC prevented operation from executing, or authentication token has expired. Problem7807
404 Not Found Does Not Exist. Endpoint not available. Problem7807
405 Method Not Allowed Operation Not Permitted. For /scn, only POST operations are allowed. Problem7807
500 Internal Server Error Internal Server Error. Unexpected condition encountered when processing the request. Problem7807
default Default Unexpected error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

params

doParamsGet

Code samples

GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/params HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/params \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/params', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/params", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /params

Retrieve service configurable parameters

Retrieve a JSON-formatted list of current configurable parameters.

Example responses

200 Response

{
  "Debug": 0,
  "KV_url": "http://localhost:2379",
  "Nosm": 1,
  "Port": 27000,
  "Scn_cache_delay": 5,
  "Scn_max_cache": 100,
  "SM_retries": 3,
  "SM_timeout": 5,
  "SM_url": "https://localhost:27999/hsms/v1",
  "Telemetry_host": "kafka.sma.svc.cluster.local:9092:state_change_notifications",
  "Use_telemetry": 1
}

Responses

Status Meaning Description Schema
200 OK Success. Current configurable parameter values are returned. parameters
401 Unauthorized Unauthorized. RBAC prevented operation from executing, or authentication token has expired. Problem7807
404 Not Found Does Not Exist. Endpoint not available. Problem7807
405 Method Not Allowed Operation Not Permitted. For /params, only GET and PATCH operations are allowed. Problem7807
500 Internal Server Error Internal Server Error. Unexpected condition encountered when processing the request. Problem7807
default Default Unexpected error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

doParamsPatch

Code samples

PATCH https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/params HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X PATCH https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/params \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.patch('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/params', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PATCH", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/params", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PATCH /params

Update service configurable parameters

Change the value of one or more configurable parameters.

Body parameter

{
  "Debug": 0,
  "KV_url": "http://localhost:2379",
  "Nosm": 1,
  "Port": 27000,
  "Scn_cache_delay": 5,
  "Scn_max_cache": 100,
  "SM_retries": 3,
  "SM_timeout": 5,
  "SM_url": "https://localhost:27999/hsms/v1",
  "Telemetry_host": "kafka.sma.svc.cluster.local:9092:state_change_notifications",
  "Use_telemetry": 1
}

Parameters

Name In Type Required Description
body body parameters true none

Example responses

400 Response

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "status": 400,
  "title": "Description of HTTP Status code, e.g. 400"
}

Responses

Status Meaning Description Schema
200 OK Success. None
400 Bad Request Bad Request. Malformed JSON. Verify all JSON formatting in payload. Problem7807
401 Unauthorized Unauthorized. RBAC prevented operation from executing, or authentication token has expired. Problem7807
404 Not Found Does Not Exist. Endpoint not available. Problem7807
405 Method Not Allowed Operation Not Permitted. For /params, only GET and PATCH operations are allowed. Problem7807
500 Internal Server Error Internal Server Error. Unexpected condition encountered when processing the request. Problem7807
default Default Unexpected error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

health

get__health

Code samples

GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/health HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/health \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/health', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/health", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /health

Query the health of the service

The health resource returns health information about the HMNFD service and its dependencies. This actively checks the connection between HMNFD and the following:

  • KV Store
  • Message Bus
  • Worker Pool

This is primarily intended as a diagnostic tool to investigate the functioning of the HMNFD service.

Example responses

200 Response

{
  "KvStore": "KV Store not initialized",
  "MsgBus": "Connected and OPEN",
  "HsmSubscriptions": "HSM Subscription key not present",
  "PruneMap": "Number of items:10",
  "WorkerPool": "Workers:5, Jobs:15"
}

Responses

Status Meaning Description Schema
200 OK OK Network API call success Inline
405 Method Not Allowed Operation Not Permitted. For /health, only GET operations are allowed. Problem7807

Response Schema

Status Code 200

Name Type Required Restrictions Description
» KvStore string true none Status of the KV Store.
» MsgBus string true none Status of the connection with the message bus.
» HsmSubscriptions string true none Status of the subscriptions to the Hardware State Manager (HSM). Any error reported by an attempt to access the HSM subscriptions will be included here.
» PruneMap string true none Status of the list of subscriptions to be pruned.
» WorkerPool string true none Status of the worker pool servicing the notifications.
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__liveness

Code samples

GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/liveness HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/liveness \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/liveness', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/liveness", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /liveness

Kubernetes liveness endpoint to monitor service health

The liveness resource works in conjunction with the Kubernetes liveness probe to determine when the service is no longer responding to requests. Too many failures of the liveness probe will result in the service being shut down and restarted.

This is primarily an endpoint for the automated Kubernetes system.

Example responses

405 Response

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "status": 400,
  "title": "Description of HTTP Status code, e.g. 400"
}

Responses

Status Meaning Description Schema
204 No Content No Content Network API call success None
405 Method Not Allowed Operation Not Permitted. For /liveness, only GET operations are allowed. Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__readiness

Code samples

GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/readiness HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/readiness \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/readiness', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/hmnfd/hmi/v2/readiness", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /readiness

Kubernetes readiness endpoint to monitor service health

The readiness resource works in conjunction with the Kubernetes readiness probe to determine when the service is no longer healthy and able to respond correctly to requests. Too many failures of the readiness probe will result in the traffic being routed away from this service and eventually the service will be shut down and restarted if in an unready state for too long.

This is primarily an endpoint for the automated Kubernetes system.

Example responses

405 Response

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "status": 400,
  "title": "Description of HTTP Status code, e.g. 400"
}

Responses

Status Meaning Description Schema
204 No Content No Content Network API call success None
405 Method Not Allowed Operation Not Permitted. For /readiness, only GET operations are allowed. Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

Schemas

SubscribePost

{
  "Components": [
    "x0c1s2b0n3"
  ],
  "Subscriber": "scnHandler@x1000c1s2b0n3",
  "SubscriberComponent": "x1000c1s2b0n3",
  "SubscriberAgent": "scnHandler",
  "Enabled": "true",
  "Roles": [
    "Compute"
  ],
  "SoftwareStatus": [
    "AdminDown"
  ],
  "States": [
    "Ready"
  ],
  "Url": "https://x0c1s2b0n3.cray.com:8080/scns"
}

State Change Notification Subscription Message Payload

Properties

Name Type Required Restrictions Description
Components [XName.1.0.0] false none This is a list of components to associate with a State Change Notification.
Subscriber string false none This is the xname of the subscriber. It can have an optional service name. Note that this is only used for backward compatibility with the V1 API, and is not actually used.
SubscriberComponent string false none This is the xname of the subscriber.
SubscriberAgent string false none This is the name of the subscribing software agent.
Enabled boolean false none If true, subscribe to changes to the Enabled status of a component.
Roles [Roles.1.0.0] false none Node role change to subscribe for
SoftwareStatus [SoftwareStatus.1.0.0] false none Logical status associated with a component
States [HMSState.1.0.0] false none List of states to subscribe for
Url string false none URL to send State Change Notifications to

SubscribePostV2

{
  "Components": [
    "x0c1s2b0n3"
  ],
  "Enabled": "true",
  "Roles": [
    "Compute"
  ],
  "SoftwareStatus": [
    "AdminDown"
  ],
  "States": [
    "Ready"
  ],
  "Url": "https://x0c1s2b0n3.cray.com:8080/scns"
}

State Change Notification Subscription Message Payload

Properties

Name Type Required Restrictions Description
Components [XName.1.0.0] false none This is a list of components to associate with a State Change Notification.
Enabled boolean false none If true, subscribe to changes to the Enabled status of a component.
Roles [Roles.1.0.0] false none Node role change to subscribe for
SoftwareStatus [SoftwareStatus.1.0.0] false none Logical status associated with a component
States [HMSState.1.0.0] false none List of states to subscribe for
Url string false none URL to send State Change Notifications to

parameters

{
  "Debug": 0,
  "KV_url": "http://localhost:2379",
  "Nosm": 1,
  "Port": 27000,
  "Scn_cache_delay": 5,
  "Scn_max_cache": 100,
  "SM_retries": 3,
  "SM_timeout": 5,
  "SM_url": "https://localhost:27999/hsms/v1",
  "Telemetry_host": "kafka.sma.svc.cluster.local:9092:state_change_notifications",
  "Use_telemetry": 1
}

Configurable Parameters Message Payload

Properties

Name Type Required Restrictions Description
Debug integer false none This is the debug level of the heartbeat service. It increases the verbosity of the logging.
KV_url string false none ETCD Key-Value store URL
Nosm integer false none Do not contact Hardware State Manager (for testing/debug)
Port integer false none Port number to respond to
Scn_cache_delay integer false none Max number seconds before sending cached and coalesced SCNs to subscribers.
Scn_max_cache integer false none Max number of similar SCNs to cache and coalesce before sending to subscribers.
SM_retries integer false none Number of times to retry operations with Hardware State Manager on failure
SM_timeout integer false none Number of seconds to wait before giving up when communicating with Hardware State Manager
SM_url string false none URL used when contacting the Hardware State Manager
Telemetry_host string false none URL used when contacting the telemetry bus. Contains service URL, port, and bus topic.
Use_telemetry integer false none Specifies whether or not to dump State Change Notifications onto the telemetry bus

XName.1.0.0

"x0c1s2b0n3"

Identifies sender by xname. This is the physical, location-based name of a component.

Properties

Name Type Required Restrictions Description
anonymous string false none Identifies sender by xname. This is the physical, location-based name of a component.

HMSState.1.0.0

"Ready"

This property indicates the state of the underlying component.

Properties

Name Type Required Restrictions Description
anonymous string false none This property indicates the state of the underlying component.

Enumerated Values

Property Value
anonymous Unknown
anonymous Empty
anonymous Populated
anonymous Off
anonymous On
anonymous Active
anonymous Standby
anonymous Halt
anonymous Ready
anonymous Paused

SoftwareStatus.1.0.0

"AdminDown"

This property indicates a logical state of the underlying component.

Properties

None

Roles.1.0.0

"Compute"

This property indicates a node’s role – compute, service, uan, ssn, and others

Properties

None

StateChanges

{
  "Components": [
    "x0c1s2b0n3"
  ],
  "Enabled": "true",
  "Role": "Compute",
  "SoftwareStatus": "AdminDown",
  "State": "Ready"
}

This is the JSON payload that contains State Change Notification information, sent by the Hardware State Manager

Properties

Name Type Required Restrictions Description
Components [XName.1.0.0] false none This is a list of components to associate with a State Change Notification
Enabled boolean false none If true, component has changed to the Enabled state; if false, it has changed to the Disabled state.
Role Roles.1.0.0 false none This property indicates a node’s role – compute, service, uan, ssn, and others
SoftwareStatus SoftwareStatus.1.0.0 false none This property indicates a logical state of the underlying component.
State HMSState.1.0.0 false none This property indicates the state of the underlying component.

SubscriptionUrl

"https://x0c1s2b0n3.cray.com:7999/scn"

URL to send State Change Notifications to

Properties

Name Type Required Restrictions Description
anonymous string false none URL to send State Change Notifications to

SubscriptionListArray

{
  "SubscriptionList": [
    {
      "Components": [
        "x0c1s2b0n3"
      ],
      "Subscriber": "scnHandler@x1000c1s2b0n3",
      "SubscriberComponent": "x1000c1s2b0n3",
      "SubscriberAgent": "scnHandler",
      "Enabled": "true",
      "Roles": [
        "Compute"
      ],
      "SoftwareStatus": [
        "AdminDown"
      ],
      "States": [
        "Ready"
      ],
      "Url": "https://x0c1s2b0n3.cray.com:8080/scns"
    }
  ]
}

List of all currently held State Change Notification subscriptions.

Properties

Name Type Required Restrictions Description
SubscriptionList [SubscribePost] false none [This is the JSON payload that contains State Change Notification subscription information.]

Problem7807

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "status": 400,
  "title": "Description of HTTP Status code, e.g. 400"
}

RFC 7807 compliant error payload. All fields are optional except the ’type’ field.

Properties

Name Type Required Restrictions Description
type string true none none
detail string false none none
instance string false none none
status number(int32) false none none
title string false none none