diff --git a/api-ref/source/baremetal-api-v1-indicators.inc b/api-ref/source/baremetal-api-v1-indicators.inc new file mode 100644 index 0000000000..0c4b118855 --- /dev/null +++ b/api-ref/source/baremetal-api-v1-indicators.inc @@ -0,0 +1,154 @@ +.. -*- rst -*- + +===================== +Indicators Management +===================== + +The Indicators management is an extension of the node ReST API endpoint that +allows reading and toggling the indicators (e.g. LEDs) on the hardware +units. + +List Indicators +=============== + +.. rest_method:: GET /v1/nodes/{node_ident}/management/indicators + +.. versionadded:: 1.63 + +List all available indicator names for each of the hardware components. +The components that the ``redfish`` driver may have are: ``system``, +``chassis`` and ``drive``. The actual list depends on the support by the +underlying hardware. + +Normal response code: 200 + +Error response codes: 404 (if node not found) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - components: n_components + - name: component_name + - links: links + +**Example list of indicators for the node:** + +.. literalinclude:: samples/node-indicators-list-response.json + :language: javascript + + +List Indicators for hardware component +====================================== + +.. rest_method:: GET /v1/nodes/{node_ident}/management/indicators/{component} + +.. versionadded:: 1.63 + +Retrieves indicators for a given hardware component along with their attributes. +The components that the ``redfish`` driver may have are: ``system``, +``chassis`` and ``drive``. The actual list depends on the support by the +underlying hardware. + +Normal response code: 200 + +Error response codes: 404 (if node or component is not found) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - component: component + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - indicators: n_indicators + - name: indicator_name + - readonly: indicator_readonly + - states: indicator_states + - links: links + +**Example list of indicators for a given component of the node:** + +.. literalinclude:: samples/node-indicators-component-list-response.json + :language: javascript + + +Get Indicator State +=================== + +.. rest_method:: GET /v1/nodes/{node_ident}/management/indicators/{component}/{ind_ident} + +.. versionadded:: 1.63 + +Retrieves the state of a chosen indicator for a given component of the node. +The value of the field in the response object represents its state. The values +can be one of ``OFF``, ``ON``, ``BLINKING`` or ``UNKNOWN``. + +Normal response code: 200 + +Error response codes: 404 (if node, component or indicator is not found) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - component: component + - ind_ident: ind_ident + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - state: n_ind_state + +**Example list of indicators for a given component of the node:** + +.. literalinclude:: samples/node-indicators-get-state-response.json + :language: javascript + + +Set Indicator State +=================== + +.. rest_method:: PUT /v1/nodes/{node_ident}/management/indicators/{component}/{ind_ident} + +.. versionadded:: 1.63 + +Set the state of the desired indicators of the component. + +Normal response code: 204 (No content) + +Error codes: + - 400 (if state is not an accepted value) + - 404 (if node, component or indicator is not found) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - component: component + - ind_ident: ind_ident + - state: n_ind_state + +**Set the State of an Indicator** + +.. literalinclude:: samples/node-indicators-set-state.json diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 60c3faff03..b8f19267ac 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -12,6 +12,7 @@ .. include:: baremetal-api-v1-node-passthru.inc .. include:: baremetal-api-v1-nodes-traits.inc .. include:: baremetal-api-v1-nodes-vifs.inc +.. include:: baremetal-api-v1-indicators.inc .. include:: baremetal-api-v1-portgroups.inc .. include:: baremetal-api-v1-nodes-portgroups.inc .. include:: baremetal-api-v1-ports.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 979417abdd..86a380ff04 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -56,6 +56,12 @@ chassis_ident: in: path required: true type: string +component: + description: | + The Bare Metal node component. + in: path + required: true + type: string deploy_template_ident: description: | The UUID or name of the deploy template. @@ -74,6 +80,12 @@ hostname_ident: in: path required: true type: string +ind_ident: + description: | + The indicator of a Bare Metal component. + in: path + required: true + type: string node_id: description: | The UUID of the node. @@ -538,6 +550,12 @@ clean_steps: in: body required: false type: array +component_name: + description: | + The name of the component available for the node. + in: body + required: true + type: string conductor: description: | The conductor currently servicing a node. This field is read-only. @@ -855,6 +873,25 @@ id: in: body required: true type: string +indicator_name: + description: | + The name of the indicator. + in: body + required: true + type: boolean +indicator_readonly: + description: | + Indicates whether the indicator is readonly. + in: body + required: true + type: boolean +indicator_states: + description: | + The possible states for a given indicator, the only values that can be + returned are: ``ON``, ``OFF``, ``BLINKING`` and ``UNKNOWN`` + in: body + required: true + type: string inspect_interface: description: | The interface used for node inspection, e.g. "no-inspect". @@ -956,12 +993,33 @@ management_interface: in: body required: true type: string +n_components: + description: | + List all available indicators names for each of the hardware components + for this node. + in: body + required: true + type: array n_description: description: | Informational text about this node. in: body required: true type: string +n_ind_state: + description: | + The state of an indicator of the component of the node. Possible values + are: ``OFF``, ``ON``, ``BLINKING`` or ``UNKNOWN``. + in: body + required: true + type: string +n_indicators: + description: | + Retrieves all indicators for a given hardware component along with their + attributes for this node. + in: body + required: true + type: array n_portgroups: description: | Links to the collection of portgroups on this node. diff --git a/api-ref/source/samples/node-indicators-component-list-response.json b/api-ref/source/samples/node-indicators-component-list-response.json new file mode 100644 index 0000000000..51a3b4b163 --- /dev/null +++ b/api-ref/source/samples/node-indicators-component-list-response.json @@ -0,0 +1,45 @@ +{ + "indicators": [ + { + "name": "power", + "readonly": true, + "states": [ + "OFF", + "ON" + ], + "links": [ + { + "href": "http://127.0.0.1:6385/v1/nodes/Compute0/ + management/indicators/system/power", + "rel": "self" + }, + { + "href": "http://127.0.0.1:6385/nodes/Compute0/ + management/indicators/system/power", + "rel": "bookmark" + } + ] + }, + { + "name": "alert", + "readonly": false, + "states": [ + "OFF", + "BLINKING", + "UNKNOWN" + ], + "links": [ + { + "href": "http://127.0.0.1:6385/v1/nodes/Compute0/ + management/indicators/system/alert", + "rel": "self" + }, + { + "href": "http://127.0.0.1:6385/nodes/Compute0/ + management/indicators/system/alert", + "rel": "bookmark" + } + ] + }, + ] +} diff --git a/api-ref/source/samples/node-indicators-get-state-response.json b/api-ref/source/samples/node-indicators-get-state-response.json new file mode 100644 index 0000000000..f4741def6d --- /dev/null +++ b/api-ref/source/samples/node-indicators-get-state-response.json @@ -0,0 +1,3 @@ +{ + "state": "ON" +} diff --git a/api-ref/source/samples/node-indicators-list-response.json b/api-ref/source/samples/node-indicators-list-response.json new file mode 100644 index 0000000000..a813c26ab7 --- /dev/null +++ b/api-ref/source/samples/node-indicators-list-response.json @@ -0,0 +1,34 @@ +{ + "components": [ + { + "name": "system", + "links": [ + { + "href": "http://127.0.0.1:6385/v1/nodes/Compute0/ + management/indicators/system", + "rel": "self" + }, + { + "href": "http://127.0.0.1:6385/nodes/Compute0/ + management/indicators/system", + "rel": "bookmark" + } + ] + }, + { + "name": "chassis", + "links": [ + { + "href": "http://127.0.0.1:6385/v1/nodes/Compute0/ + management/indicators/chassis", + "rel": "self" + }, + { + "href": "http://127.0.0.1:6385/nodes/Compute0/ + management/indicators/chassis", + "rel": "bookmark" + } + ] + } + ] +} diff --git a/api-ref/source/samples/node-indicators-set-state.json b/api-ref/source/samples/node-indicators-set-state.json new file mode 100644 index 0000000000..26063ffe22 --- /dev/null +++ b/api-ref/source/samples/node-indicators-set-state.json @@ -0,0 +1,3 @@ +{ + "state": "BLINKING" +}