Power Control Service (PCS) 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.

The Power Control Service (PCS) performs power-related operations on system components - nodes, blades, and chassis. PCS refers to system components by their xname, or system identifier.

This REST API provides the following functions:

  • Turn xnames on or off.
  • Perform hard and soft reset actions.
  • Set and retrieve power capping parameters and capabilities.
  • Get node rules which are various parameters relating to power operations.

Resources

/transitions

Power xname on or off.

/power-status

Get power status of xnames.

/power-cap

/power-cap-snapshot

Get and set power capping parameters.

Workflows

Set Power Cap for a list of targets

PATCH /power-cap

Send a JSON payload with a list of targets and power capping parameters to be applied to the targets. This is a non-blocking operation. A task ID is returned, used to query the status of the task and get the requested information.

Get Power Cap status and information for a power cap task

GET /power-cap/{taskID}

Retrieve status of specified power cap PATCH operation and current values.

Get Power Cap parameters and capabilities for a list of targets

POST /power-cap/snapshot

Send a JSON payload with a list of target xnames. This will launch a task and return a snapshot ID which can be queried for status.

Get status and current Power Cap settings from recent power cap snapshot

GET /power-cap/{taskID}

Query the status of a power cap snapshot task. If completed, contains the current power cap values as read from the hardware.

Base URLs:

License: MIT

Authentication

  • HTTP Authentication, scheme: bearer

transitions

Endpoints that perform power operations to a set of xnames

post__transitions

Code samples

POST https://api-gw-service-nmn.local/apis/power-control/v1/transitions 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/power-control/v1/transitions \
  -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/power-control/v1/transitions', 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/power-control/v1/transitions", data)
    req.Header = headers

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

POST /transitions

Start a transition

Request to perform power transitions.

Body parameter

{
  "operation": "force-off",
  "taskDeadlineMinutes": 0,
  "location": [
    {
      "xname": "x0c0s0b0n0",
      "deputyKey": "80838f7c-04e3-4cf6-8456-6bd557a0f1be"
    }
  ]
}

Parameters

Name In Type Required Description
body body transition_create true Transition parameters

Example responses

200 Response

{
  "transitionID": "8dd3e1a5-ae40-4761-b8fe-6c489e965fbd",
  "operation": "on"
}

400 Response

Responses

Status Meaning Description Schema
200 OK Accepted transition_start_output
400 Bad Request Bad Request Problem7807
500 Internal Server Error Database error prevented starting the transition Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__transitions

Code samples

GET https://api-gw-service-nmn.local/apis/power-control/v1/transitions 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/power-control/v1/transitions \
  -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/power-control/v1/transitions', 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/power-control/v1/transitions", data)
    req.Header = headers

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

GET /transitions

Retrieve all requested power transitions

Return a complete list of the requested power transitions, with status information. Note that records older than 24 hours are automatically deleted.

Example responses

200 Response

{
  "transitions": [
    {
      "transitionID": "8dd3e1a5-ae40-4761-b8fe-6c489e965fbd",
      "createTime": "2020-12-16T19:00:20",
      "automaticExpirationTime": "2019-08-24T14:15:22Z",
      "transitionStatus": "in-progress",
      "operation": "force-off",
      "taskCounts": {
        "total": 5,
        "new": 2,
        "in-progress": 2,
        "failed": 0,
        "succeeded": 1,
        "un-supported": 0
      }
    }
  ]
}

500 Response

Responses

Status Meaning Description Schema
200 OK OK transitions_getAll
500 Internal Server Error Database error prevented getting the transitions Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__transitions_{transitionID}

Code samples

GET https://api-gw-service-nmn.local/apis/power-control/v1/transitions/{transitionID} 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/power-control/v1/transitions/{transitionID} \
  -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/power-control/v1/transitions/{transitionID}', 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/power-control/v1/transitions/{transitionID}", data)
    req.Header = headers

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

GET /transitions/{transitionID}

Retrieve transition status by ID

Retrieve the transition status information for the specified transitionID.

Parameters

Name In Type Required Description
transitionID path string(uuid) true none

Example responses

200 Response

{
  "transitionID": "8dd3e1a5-ae40-4761-b8fe-6c489e965fbd",
  "createTime": "2020-12-16T19:00:20",
  "automaticExpirationTime": "2019-08-24T14:15:22Z",
  "transitionStatus": "in-progress",
  "operation": "force-off",
  "taskCounts": {
    "total": 5,
    "new": 2,
    "in-progress": 2,
    "failed": 0,
    "succeeded": 1,
    "un-supported": 0
  },
  "tasks": [
    {
      "xname": "x0c0s0b0n0",
      "taskStatus": "failed",
      "taskStatusDescription": "the device did not respond in a timely manner",
      "error": "failed to achieve transition"
    }
  ]
}

400 Response

Responses

Status Meaning Description Schema
200 OK OK transitions_getID
400 Bad Request Bad Request Problem7807
500 Internal Server Error Database error prevented getting the transition Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

delete__transitions_{transitionID}

Code samples

DELETE https://api-gw-service-nmn.local/apis/power-control/v1/transitions/{transitionID} 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/power-control/v1/transitions/{transitionID} \
  -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/power-control/v1/transitions/{transitionID}', 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/power-control/v1/transitions/{transitionID}", data)
    req.Header = headers

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

DELETE /transitions/{transitionID}

Abort an in-progress transition

Attempt to abort an in-progress transition by transitionID

Parameters

Name In Type Required Description
transitionID path string(uuid) true none

Example responses

202 Response

{
  "abortStatus": "Accepted - abort initiated"
}

400 Response

Responses

Status Meaning Description Schema
202 Accepted Accepted - abort initiated transitions_abort
400 Bad Request Specified transition is complete Problem7807
404 Not Found TransitionID not found Problem7807
500 Internal Server Error Database error prevented abort signaling Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

power-status

Endpoints that retrieve power status of xnames

get__power-status

Code samples

GET https://api-gw-service-nmn.local/apis/power-control/v1/power-status 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/power-control/v1/power-status \
  -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/power-control/v1/power-status', 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/power-control/v1/power-status", data)
    req.Header = headers

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

GET /power-status

Retrieve the power state

Retrieve the power state of the components specified by xname.

Parameters

Name In Type Required Description
xname query non_empty_string_list false none
powerStateFilter query power_state false none
managementStateFilter query management_state false none

Enumerated Values

Parameter Value
powerStateFilter on
powerStateFilter off
powerStateFilter undefined
managementStateFilter unavailable
managementStateFilter available

Example responses

200 Response

{
  "status": [
    {
      "xname": "x0c0s0b0n0",
      "powerState": "on",
      "managementState": "available",
      "error": "permission denied - system credentials failed",
      "supportedPowerTransitions": [
        "soft-restart"
      ],
      "lastUpdated": "2022-08-24T16:45:53.953811137Z"
    }
  ]
}

400 Response

Responses

Status Meaning Description Schema
200 OK OK power_status_all
400 Bad Request Bad Request Problem7807
500 Internal Server Error Database error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

post__power-status

Code samples

POST https://api-gw-service-nmn.local/apis/power-control/v1/power-status 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/power-control/v1/power-status \
  -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/power-control/v1/power-status', 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/power-control/v1/power-status", data)
    req.Header = headers

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

POST /power-status

Retrieve the power state

Retrieve the power state of the components specified by xname.

Body parameter

{
  "xname": [
    "string"
  ],
  "powerStateFilter": "on",
  "managementStateFilter": "available"
}

Parameters

Name In Type Required Description
body body power_status_get true Node filtering parameters

Example responses

200 Response

{
  "status": [
    {
      "xname": "x0c0s0b0n0",
      "powerState": "on",
      "managementState": "available",
      "error": "permission denied - system credentials failed",
      "supportedPowerTransitions": [
        "soft-restart"
      ],
      "lastUpdated": "2022-08-24T16:45:53.953811137Z"
    }
  ]
}

400 Response

Responses

Status Meaning Description Schema
200 OK OK power_status_all
400 Bad Request Bad Request Problem7807
500 Internal Server Error Database error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

power-cap

Endpoints that retrieve or set power cap parameters

post__power-cap_snapshot

Code samples

POST https://api-gw-service-nmn.local/apis/power-control/v1/power-cap/snapshot 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/power-control/v1/power-cap/snapshot \
  -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/power-control/v1/power-cap/snapshot', 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/power-control/v1/power-cap/snapshot", data)
    req.Header = headers

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

POST /power-cap/snapshot

Take a power cap snapshot for a set of targets

Get power cap snapshot for a set of targets. This operation returns a taskID to be used for completion status queries, since this can be a long running task. Progress and status for this task can be queried via a GET /power-cap/{taskID}

Body parameter

{
  "xnames": [
    "x0c0s0b0n0"
  ]
}

Parameters

Name In Type Required Description
body body power_cap_snapshot_req false none

Example responses

200 Response

{
  "taskID": "e6d742d9-0922-4edc-baeb-3e1ecb0579d1"
}

400 Response

Responses

Status Meaning Description Schema
200 OK OK. The data was successfully retrieved op_task_start_response
400 Bad Request Bad Request Problem7807
500 Internal Server Error Database error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

patch__power-cap

Code samples

PATCH https://api-gw-service-nmn.local/apis/power-control/v1/power-cap 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/power-control/v1/power-cap \
  -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/power-control/v1/power-cap', 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/power-control/v1/power-cap", data)
    req.Header = headers

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

PATCH /power-cap

Set power capping parameters on a set of targets

Set power cap parameters for a list of targets. The PATCH payload contains the targets and the parameters to set. This operation returns a powercapID to be used for completion status queries, since this can be a long running task. Progress and status for this task can be queried via a GET /power-cap/{taskID}.

Body parameter

{
  "components": [
    {
      "xname": "x0c0s0b0n0",
      "controls": [
        {
          "name": "string",
          "value": 400
        }
      ]
    }
  ]
}

Parameters

Name In Type Required Description
body body power_cap_patch false none

Example responses

200 Response

{
  "taskID": "e6d742d9-0922-4edc-baeb-3e1ecb0579d1"
}

400 Response

Responses

Status Meaning Description Schema
200 OK OK. The data was successfully retrieved op_task_start_response
400 Bad Request Bad Request Problem7807
500 Internal Server Error Database error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__power-cap

Code samples

GET https://api-gw-service-nmn.local/apis/power-control/v1/power-cap 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/power-control/v1/power-cap \
  -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/power-control/v1/power-cap', 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/power-control/v1/power-cap", data)
    req.Header = headers

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

GET /power-cap

Get a list of power-cap tasks (snapshots or sets)

Example responses

200 Response

{
  "tasks": [
    {
      "taskID": "e6d742d9-0922-4edc-baeb-3e1ecb0579d1",
      "type": "snapshot",
      "taskCreateTime": "2021-04-01T19:00:00",
      "automaticExpirationTime": "2019-08-24T14:15:22Z",
      "taskStatus": "Completed",
      "taskCounts": {
        "total": 5,
        "new": 2,
        "in-progress": 2,
        "failed": 0,
        "succeeded": 1,
        "un-supported": 0
      }
    }
  ]
}

500 Response

Responses

Status Meaning Description Schema
200 OK OK. The data was successfully retrieved power_cap_task_list
500 Internal Server Error Database error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__power-cap_{taskID}

Code samples

GET https://api-gw-service-nmn.local/apis/power-control/v1/power-cap/{taskID} 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/power-control/v1/power-cap/{taskID} \
  -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/power-control/v1/power-cap/{taskID}', 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/power-control/v1/power-cap/{taskID}", data)
    req.Header = headers

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

GET /power-cap/{taskID}

Get power cap or snapshot information

Queries the current status for the specified taskID. Use the taskID returned from a PATCH /power-cap or POST /power-cap/snapshot request.

Parameters

Name In Type Required Description
taskID path task_id true none

Example responses

200 Response

{
  "taskID": "e6d742d9-0922-4edc-baeb-3e1ecb0579d1",
  "type": "snapshot",
  "taskCreateTime": "2021-04-01T19:00:00",
  "automaticExpirationTime": "2019-08-24T14:15:22Z",
  "taskStatus": "Completed",
  "taskCounts": {
    "total": 5,
    "new": 2,
    "in-progress": 2,
    "failed": 0,
    "succeeded": 1,
    "un-supported": 0
  },
  "components": [
    {
      "xname": "x0c0s0b0n0",
      "error": "Optional error message",
      "limits": {
        "hostLimitMax": 900,
        "hostLimitMin": 360,
        "powerupPower": 250
      },
      "powerCapLimits": [
        {
          "name": "Node",
          "currentValue": 410,
          "maximumValue": 900,
          "minimumValue": 360
        }
      ]
    }
  ]
}

404 Response

Responses

Status Meaning Description Schema
200 OK OK. The data was successfully retrieved. Task Info is only present for task status operations (PATCH power-cap or POST power-cap/snapshot) power_caps_retdata
404 Not Found TaskID not found Problem7807
500 Internal Server Error Database error Problem7807
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

cli_ignore

Endpoints that should not be parsed by the Cray CLI generator

get__liveness

Code samples

GET https://api-gw-service-nmn.local/apis/power-control/v1/liveness HTTP/1.1
Host: api-gw-service-nmn.local

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/power-control/v1/liveness \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/power-control/v1/liveness', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

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

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

GET /liveness

Get liveness status of the service

Get liveness status of the service

Responses

Status Meaning Description Schema
204 No Content No Content Network API call success None
503 Service Unavailable The service is not taking HTTP requests None
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/power-control/v1/readiness HTTP/1.1
Host: api-gw-service-nmn.local

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/power-control/v1/readiness \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/power-control/v1/readiness', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

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

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

GET /readiness

Get readiness status of the service

Get readiness status of the service

Responses

Status Meaning Description Schema
204 No Content No Content Network API call success None
503 Service Unavailable The service is not taking HTTP requests None
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__health

Code samples

GET https://api-gw-service-nmn.local/apis/power-control/v1/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/power-control/v1/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/power-control/v1/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/power-control/v1/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 PCS service and its dependencies. This actively checks the connection between PCS and the following:

  • KV store
  • Distributed locking subsystem
  • Hardware State Manager
  • Vault
  • Task Runner Service status and mode

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

Example responses

200 Response

{
  "KvStore": "connected, responsive",
  "StateManager": "connected, responsive",
  "BackingStore": "connected, responsive",
  "Vault": "connected, responsive",
  "TaskRunnerMode": "connected, responsive, local mode"
}

Responses

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

Schemas

power_status

{
  "xname": "x0c0s0b0n0",
  "powerState": "on",
  "managementState": "available",
  "error": "permission denied - system credentials failed",
  "supportedPowerTransitions": [
    "soft-restart"
  ],
  "lastUpdated": "2022-08-24T16:45:53.953811137Z"
}

Properties

Name Type Required Restrictions Description
xname xname false none The xname of this piece of hardware
powerState power_state false none The power state of a component.
managementState management_state false none Whether the device is currently available for commands via its management controller
error string¦null false none none
supportedPowerTransitions [string] false none none
lastUpdated string(date-time) false read-only none

power_status_all

{
  "status": [
    {
      "xname": "x0c0s0b0n0",
      "powerState": "on",
      "managementState": "available",
      "error": "permission denied - system credentials failed",
      "supportedPowerTransitions": [
        "soft-restart"
      ],
      "lastUpdated": "2022-08-24T16:45:53.953811137Z"
    }
  ]
}

Properties

Name Type Required Restrictions Description
status [power_status] false none none

power_status_get

{
  "xname": [
    "string"
  ],
  "powerStateFilter": "on",
  "managementStateFilter": "available"
}

Filters to limit which nodes have their power status returned.

Properties

Name Type Required Restrictions Description
xname non_empty_string_list false none none
powerStateFilter power_state false none The power state of a component.
managementStateFilter management_state false none Whether the device is currently available for commands via its management controller

transitions_getID

{
  "transitionID": "8dd3e1a5-ae40-4761-b8fe-6c489e965fbd",
  "createTime": "2020-12-16T19:00:20",
  "automaticExpirationTime": "2019-08-24T14:15:22Z",
  "transitionStatus": "in-progress",
  "operation": "force-off",
  "taskCounts": {
    "total": 5,
    "new": 2,
    "in-progress": 2,
    "failed": 0,
    "succeeded": 1,
    "un-supported": 0
  },
  "tasks": [
    {
      "xname": "x0c0s0b0n0",
      "taskStatus": "failed",
      "taskStatusDescription": "the device did not respond in a timely manner",
      "error": "failed to achieve transition"
    }
  ]
}

Properties

Name Type Required Restrictions Description
transitionID string(uuid) false none none
createTime string false none none
automaticExpirationTime string(date-time) false none When the record will be deleted
transitionStatus string false none none
operation string false none none
taskCounts task_counts false none none
tasks [transition_task_data] false none none

Enumerated Values

Property Value
transitionStatus new
transitionStatus in-progress
transitionStatus completed
transitionStatus aborted
transitionStatus abort-signaled
operation on
operation off
operation soft-restart
operation hard-restart
operation init
operation force-off
operation soft-off

transitions_getAll

{
  "transitions": [
    {
      "transitionID": "8dd3e1a5-ae40-4761-b8fe-6c489e965fbd",
      "createTime": "2020-12-16T19:00:20",
      "automaticExpirationTime": "2019-08-24T14:15:22Z",
      "transitionStatus": "in-progress",
      "operation": "force-off",
      "taskCounts": {
        "total": 5,
        "new": 2,
        "in-progress": 2,
        "failed": 0,
        "succeeded": 1,
        "un-supported": 0
      }
    }
  ]
}

Properties

Name Type Required Restrictions Description
transitions [transitions_get] false none none

transitions_get

{
  "transitionID": "8dd3e1a5-ae40-4761-b8fe-6c489e965fbd",
  "createTime": "2020-12-16T19:00:20",
  "automaticExpirationTime": "2019-08-24T14:15:22Z",
  "transitionStatus": "in-progress",
  "operation": "force-off",
  "taskCounts": {
    "total": 5,
    "new": 2,
    "in-progress": 2,
    "failed": 0,
    "succeeded": 1,
    "un-supported": 0
  }
}

Properties

Name Type Required Restrictions Description
transitionID string(uuid) false none none
createTime string false none none
automaticExpirationTime string(date-time) false none When the record will be deleted
transitionStatus string false none none
operation string false none none
taskCounts task_counts false none none

Enumerated Values

Property Value
transitionStatus in-progress
transitionStatus new
transitionStatus completed
transitionStatus aborted
transitionStatus abort-signaled
operation on
operation off
operation soft-restart
operation hard-restart
operation init
operation force-off
operation soft-off

transition_start_output

{
  "transitionID": "8dd3e1a5-ae40-4761-b8fe-6c489e965fbd",
  "operation": "on"
}

Properties

Name Type Required Restrictions Description
transitionID string(uuid) false none none
operation string false none none

Enumerated Values

Property Value
operation on
operation off
operation soft-restart
operation hard-restart
operation init
operation force-off
operation soft-off

transitions_abort

{
  "abortStatus": "Accepted - abort initiated"
}

Properties

Name Type Required Restrictions Description
abortStatus string false none none

transition_task_data

{
  "xname": "x0c0s0b0n0",
  "taskStatus": "failed",
  "taskStatusDescription": "the device did not respond in a timely manner",
  "error": "failed to achieve transition"
}

Properties

Name Type Required Restrictions Description
xname xname false none The xname of this piece of hardware
taskStatus string false none none
taskStatusDescription string false none none
error string false none none

Enumerated Values

Property Value
taskStatus new
taskStatus in-progress
taskStatus failed
taskStatus succeeded
taskStatus unsupported

reserved_location

{
  "xname": "x0c0s0b0n0",
  "deputyKey": "80838f7c-04e3-4cf6-8456-6bd557a0f1be"
}

Properties

Name Type Required Restrictions Description
xname xname true none The xname of this piece of hardware
deputyKey string(uuid) false none none

transition_create

{
  "operation": "force-off",
  "taskDeadlineMinutes": 0,
  "location": [
    {
      "xname": "x0c0s0b0n0",
      "deputyKey": "80838f7c-04e3-4cf6-8456-6bd557a0f1be"
    }
  ]
}

Properties

Name Type Required Restrictions Description
operation string false none The operation that should be applied to the hardware.
taskDeadlineMinutes integer false none The number of minutes to wait for a single transition task to complete before continuing. Defaults to 5 minutes, if unspecified. 0 disables waiting. -1 waits as long as it takes.
location [reserved_location] false none none

Enumerated Values

Property Value
operation on
operation off
operation soft-off
operation soft-restart
operation hard-restart
operation init
operation force-off

task_counts

{
  "total": 5,
  "new": 2,
  "in-progress": 2,
  "failed": 0,
  "succeeded": 1,
  "un-supported": 0
}

Properties

Name Type Required Restrictions Description
total integer false none none
new integer false none none
in-progress integer false none none
failed integer false none none
succeeded integer false none none
un-supported integer false none none

Problem7807

{
  "type": "about:blank",
  "detail": "Detail about this specific problem occurrence. See RFC7807",
  "instance": "",
  "statusCode": 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
statusCode number(integer) false none none
title string false none none

power_state

"on"

The power state of a component.

Properties

Name Type Required Restrictions Description
anonymous string false none The power state of a component.

Enumerated Values

Property Value
anonymous on
anonymous off
anonymous undefined

management_state

"available"

Whether the device is currently available for commands via its management controller

Properties

Name Type Required Restrictions Description
anonymous string false none Whether the device is currently available for commands via its management controller

Enumerated Values

Property Value
anonymous unavailable
anonymous available

non_empty_string_list

[
  "string"
]

Properties

None

xname

"x0c0s0b0n0"

The xname of this piece of hardware

Properties

Name Type Required Restrictions Description
anonymous string false none The xname of this piece of hardware

task_id

"497f6eca-6276-4993-bfeb-53cbbbba6f08"

Task ID from power-cap, snapshot operation

Properties

Name Type Required Restrictions Description
anonymous string(uuid) false none Task ID from power-cap, snapshot operation

power_cap_patch

{
  "components": [
    {
      "xname": "x0c0s0b0n0",
      "controls": [
        {
          "name": "string",
          "value": 400
        }
      ]
    }
  ]
}

Properties

Name Type Required Restrictions Description
components [power_cap_patch_component] false none none

power_cap_patch_component

{
  "xname": "x0c0s0b0n0",
  "controls": [
    {
      "name": "string",
      "value": 400
    }
  ]
}

Properties

Name Type Required Restrictions Description
xname xname false none The xname of this piece of hardware
controls [power_cap_patch_component_control] false none none

power_cap_patch_component_control

{
  "name": "string",
  "value": 400
}

Properties

Name Type Required Restrictions Description
name string false none none
value integer false none none

op_task_start_response

{
  "taskID": "e6d742d9-0922-4edc-baeb-3e1ecb0579d1"
}

Properties

Name Type Required Restrictions Description
taskID string(uuid) false none none

power_caps_retdata

{
  "taskID": "e6d742d9-0922-4edc-baeb-3e1ecb0579d1",
  "type": "snapshot",
  "taskCreateTime": "2021-04-01T19:00:00",
  "automaticExpirationTime": "2019-08-24T14:15:22Z",
  "taskStatus": "Completed",
  "taskCounts": {
    "total": 5,
    "new": 2,
    "in-progress": 2,
    "failed": 0,
    "succeeded": 1,
    "un-supported": 0
  },
  "components": [
    {
      "xname": "x0c0s0b0n0",
      "error": "Optional error message",
      "limits": {
        "hostLimitMax": 900,
        "hostLimitMin": 360,
        "powerupPower": 250
      },
      "powerCapLimits": [
        {
          "name": "Node",
          "currentValue": 410,
          "maximumValue": 900,
          "minimumValue": 360
        }
      ]
    }
  ]
}

Properties

allOf

Name Type Required Restrictions Description
anonymous power_cap_task_info false none none

and

Name Type Required Restrictions Description
anonymous object false none none
» components [rsp_power_cap_components] false none none

power_cap_task_list

{
  "tasks": [
    {
      "taskID": "e6d742d9-0922-4edc-baeb-3e1ecb0579d1",
      "type": "snapshot",
      "taskCreateTime": "2021-04-01T19:00:00",
      "automaticExpirationTime": "2019-08-24T14:15:22Z",
      "taskStatus": "Completed",
      "taskCounts": {
        "total": 5,
        "new": 2,
        "in-progress": 2,
        "failed": 0,
        "succeeded": 1,
        "un-supported": 0
      }
    }
  ]
}

Properties

Name Type Required Restrictions Description
tasks [power_cap_task_info] false none none

power_cap_task_info

{
  "taskID": "e6d742d9-0922-4edc-baeb-3e1ecb0579d1",
  "type": "snapshot",
  "taskCreateTime": "2021-04-01T19:00:00",
  "automaticExpirationTime": "2019-08-24T14:15:22Z",
  "taskStatus": "Completed",
  "taskCounts": {
    "total": 5,
    "new": 2,
    "in-progress": 2,
    "failed": 0,
    "succeeded": 1,
    "un-supported": 0
  }
}

Properties

Name Type Required Restrictions Description
taskID string(uuid) false none none
type string false none The task can either be the result of a snapshot or a patch
taskCreateTime string false none none
automaticExpirationTime string(date-time) false none When the record will be deleted
taskStatus string false none none
taskCounts task_counts false none none

Enumerated Values

Property Value
type snapshot
type patch

power_cap_snapshot_req

{
  "xnames": [
    "x0c0s0b0n0"
  ]
}

Properties

Name Type Required Restrictions Description
xnames [xname] false none [The xname of this piece of hardware]

rsp_power_cap_components

{
  "xname": "x0c0s0b0n0",
  "error": "Optional error message",
  "limits": {
    "hostLimitMax": 900,
    "hostLimitMin": 360,
    "powerupPower": 250
  },
  "powerCapLimits": [
    {
      "name": "Node",
      "currentValue": 410,
      "maximumValue": 900,
      "minimumValue": 360
    }
  ]
}

Properties

Name Type Required Restrictions Description
xname xname false none The xname of this piece of hardware
error string false none nullable error field
limits capabilities_limits false none none
powerCapLimits [rsp_power_cap_components_control] false none none

rsp_power_cap_components_control

{
  "name": "Node",
  "currentValue": 410,
  "maximumValue": 900,
  "minimumValue": 360
}

Properties

Name Type Required Restrictions Description
name string false none none
currentValue integer false none The current power cap limit as reported by the device
maximumValue integer false none The maximum power cap limit the device may be set to
minimumValue integer false none The minimum power cap limit the device may be set to

Enumerated Values

Property Value
name Node
name Accel

capabilities_limits

{
  "hostLimitMax": 900,
  "hostLimitMin": 360,
  "powerupPower": 250
}

Properties

Name Type Required Restrictions Description
hostLimitMax integer false none Node maximum power draw, measured in watts, as reported by underlying Redfish implementation
hostLimitMin integer false none Node minimum power draw, measured in watts, as reported by underlying Redfish implementation
powerupPower integer false none Typical power consumption of each node during hardware initialization, specified in watts

health_rsp

{
  "KvStore": "connected, responsive",
  "StateManager": "connected, responsive",
  "BackingStore": "connected, responsive",
  "Vault": "connected, responsive",
  "TaskRunnerMode": "connected, responsive, local mode"
}

Properties

Name Type Required Restrictions Description
KvStore string true none Status of the KV Store.
DistLocking string true none Status of the distributed locking mechanism
StateManager string true none Status of the connection to the Hardware State Manager.
Vault string true none Status of the connection to Vault.
TaskRunner any true none TRS status and mode (local or remote/worker).