API endpoints to get node history

Adds API for retrieving node history events
via a node. Includes pagination and limitation
of the response set.

Story: 2002980
Tas: 42961

Change-Id: I22a92fa6c30d721f6a5dd0670b2e0a9cf76ad7b1

4 files changed, 135 insertions, 0 deletions

diff --git a/api-ref/source/baremetal-api-v1-nodes-history.inc b/api-ref/source/baremetal-api-v1-nodes-history.inc
new file mode 100644
index 000000000..46cfa2ec4
--- /dev/null
+++ b/api-ref/source/baremetal-api-v1-nodes-history.inc
@@ -0,0 +1,76 @@
+.. -*- rst -*-
+
+================
+History of nodes
+================
+
+.. versionadded:: 1.78
+
+Identifying history of events from nodes is available via API version 1.78 via
+the ``v1/nodes/{node_ident}/history`` endpoint. In default policy
+configuration, only "System" scoped users as well as owners who are listed
+owners of associated nodes can list and retrieve nodes.
+
+List history entries for a node
+===============================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/history
+
+Normal response code: 200
+
+Error codes: 400,401,403,404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_ident: node_ident
+   - detail: detail
+   - marker: marker
+   - limit: limit
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - history: n_history
+
+**Example list of history events from a node:**
+
+.. literalinclude:: samples/node-history-list-response.json
+   :language: javascript
+
+Retrieve a specific history entry
+=================================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/history/{history_event_uuid}
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_ident: node_ident
+   - history_event_uuid: history_event_ident
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - created_at: created_at
+   - user: history_user_ident
+   - severity: history_severity
+   - event: history_event
+   - event_type: history_event_type
+   - conductor: hostname
+
+Deleting history entries for a node
+===================================
+
+Due to the nature of an immutable history record, records cannot be deleted
+via the REST API. Records and ultimately expired history records are managed
+by the conductor.
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index b8f19267a..50c6a6d14 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -27,6 +27,7 @@
 .. include:: baremetal-api-v1-allocation.inc
 .. include:: baremetal-api-v1-node-allocation.inc
 .. include:: baremetal-api-v1-deploy-templates.inc
+.. include:: baremetal-api-v1-nodes-history.inc
 .. NOTE(dtantsur): keep chassis close to the end since it's semi-deprecated
 .. include:: baremetal-api-v1-chassis.inc
 .. NOTE(dtantsur): keep misc last, since it covers internal API
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 266986c1b..b3eb28f82 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -74,6 +74,12 @@ driver_ident:
   in: path
   required: true
   type: string
+history_event_ident:
+  description: |
+    The UUID of a history event.
+  in: path
+  required: true
+  type: string
 hostname_ident:
   description: |
     The hostname of the conductor.
@@ -971,6 +977,36 @@ fault:
   in: body
   required: false
   type: string
+history_event:
+  description: |
+    The event message body which has been logged related to the node for
+    this error.
+  in: body
+  required: true
+  type: string
+history_event_type:
+  description: |
+    Short descriptive string to indicate where the error occurred at to
+    enable API users/System Operators to be able to identify repeated
+    issues in a particular area of operation, such as 'deployment',
+    'console', 'cleaning', 'monitoring'.
+  in: body
+  required: true
+  type: string
+history_severity:
+  description: |
+    Severity indicator for the event being returned. Typically this will
+    indicate if this was an Error or Informational entry.
+  in: body
+  required: true
+  type: string
+history_user_ident:
+  description: |
+    The UUID value representing the user whom appears to have caused
+    the recorded event.
+  in: body
+  required: true
+  type: string
 hostname:
   description: |
     The hostname of this conductor.
@@ -1122,6 +1158,12 @@ n_description:
   in: body
   required: true
   type: string
+n_history:
+  description: |
+    History events attached to this node.
+  in: body
+  required: true
+  type: array
 n_ind_state:
   description: |
     The state of an indicator of the component of the node. Possible values
diff --git a/api-ref/source/samples/node-history-list-response.json b/api-ref/source/samples/node-history-list-response.json
new file mode 100644
index 000000000..632e6572b
--- /dev/null
+++ b/api-ref/source/samples/node-history-list-response.json
@@ -0,0 +1,16 @@
+{
+  "history": [
+    {
+      "uuid": "e5840e39-b4ba-4a93-8071-cff9aa2c9633",
+      "created_at": "2021-09-15T17:45:04.686541+00:00",
+      "severity": "ERROR",
+      "event": "Something is wrong",
+      "links": [
+        {
+          "href": "http://localhost/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/history/e5840e39-b4ba-4a93-8071-cff9aa2c9633",
+          "rel": "self"
+        }
+      ]
+    }
+  ]
+}