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:

https://api-gw-service-nmn.local/apis/power-control/v1

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": "Soft-Restart"
}

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": "Soft-Restart",
      "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": "Soft-Restart",
  "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	[power_operation]	false	none	[An operation to be applied to the hardware.]
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": "Soft-Restart",
  "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	transition_status	false	none	The status of the power transition.
operation	power_operation	false	none	An operation to be applied to the hardware.
taskCounts	task_counts	false	none	none
tasks	[transition_task_data]	false	none	none

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": "Soft-Restart",
      "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": "Soft-Restart",
  "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	transition_status	false	none	The status of the power transition.
operation	power_operation	false	none	An operation to be applied to the hardware.
taskCounts	task_counts	false	none	none

transition_start_output

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

Properties

Name	Type	Required	Restrictions	Description
transitionID	string(uuid)	false	none	none
operation	power_operation	false	none	An operation to be applied to the hardware.

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. The operation parameter is not case sensitive.
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

power_operation

"Soft-Restart"

An operation to be applied to the hardware.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	read-only	An operation to be applied to the hardware.

Enumerated Values

Property	Value
anonymous	On
anonymous	Off
anonymous	Soft-Restart
anonymous	Hard-Restart
anonymous	Init
anonymous	Force-Off
anonymous	Soft-Off

transition_status

"in-progress"

The status of the power transition.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The status of the power transition.

Enumerated Values

Property	Value
anonymous	new
anonymous	in-progress
anonymous	completed
anonymous	aborted
anonymous	abort-signaled

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

Files

power-control.md

Latest commit

History

power-control.md

File metadata and controls

Power Control Service (PCS) v1

Resources

/transitions

/power-status

/power-cap

/power-cap-snapshot

Workflows

Set Power Cap for a list of targets

PATCH /power-cap

Get Power Cap status and information for a power cap task

GET /power-cap/{taskID}

Get Power Cap parameters and capabilities for a list of targets

POST /power-cap/snapshot

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

GET /power-cap/{taskID}

Authentication

transitions

post__transitions

Parameters

Responses

get__transitions

Responses

get__transitions_{transitionID}

Parameters

Responses

delete__transitions_{transitionID}

Parameters

Responses

power-status

get__power-status

Parameters

Enumerated Values

Responses

post__power-status

Parameters

Responses

power-cap

post__power-cap_snapshot

Parameters

Responses

patch__power-cap

Parameters

Responses

get__power-cap

Responses

get__power-cap_{taskID}

Parameters

Responses

cli_ignore

get__liveness

Responses

get__readiness

Responses

get__health

Responses

Schemas

power_status

Properties

power_status_all

Properties

power_status_get

Properties

transitions_getID

Properties

transitions_getAll

Properties

transitions_get

Properties

transition_start_output

Properties

transitions_abort

Properties

transition_task_data

Properties