From 1c9217d8e2222d7dcbef6ac7f27abc6e46e26016 Mon Sep 17 00:00:00 2001 From: Aidan Reilly <74046732+aireilly@users.noreply.github.com> Date: Wed, 6 Apr 2022 10:51:15 +0100 Subject: [PATCH] applied sagidlow Redfish comments --- ...nf-rfhe-notifications-api-refererence.adoc | 2 +- ...alling-amq-interconnect-messaging-bus.adoc | 4 +- modules/nw-rfhe-creating-hardware-event.adoc | 10 ++--- modules/nw-rfhe-creating_bmc_event_sub.adoc | 6 +-- modules/nw-rfhe-installing-operator-cli.adoc | 6 ++- ...-rfhe-installing-operator-web-console.adoc | 3 +- modules/nw-rfhe-introduction.adoc | 41 +++++++++++-------- monitoring/using-rfhe.adoc | 10 ++--- 8 files changed, 45 insertions(+), 37 deletions(-) diff --git a/modules/cnf-rfhe-notifications-api-refererence.adoc b/modules/cnf-rfhe-notifications-api-refererence.adoc index ea3ad7c47e38..42681695bbc3 100644 --- a/modules/cnf-rfhe-notifications-api-refererence.adoc +++ b/modules/cnf-rfhe-notifications-api-refererence.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * networking/using-rfhe.adoc +// * monitoring/using-rfhe.adoc :_content-type: REFERENCE [id="cnf-rfhe-notifications-api-refererence_{context}"] diff --git a/modules/hw-installing-amq-interconnect-messaging-bus.adoc b/modules/hw-installing-amq-interconnect-messaging-bus.adoc index 768b756f9285..65bce420dd5f 100644 --- a/modules/hw-installing-amq-interconnect-messaging-bus.adoc +++ b/modules/hw-installing-amq-interconnect-messaging-bus.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * networking/using-rfhe.adoc +// * monitoring/using-rfhe.adoc :_content-type: PROCEDURE [id="hw-installing-amq-interconnect-messaging-bus_{context}"] @@ -34,7 +34,7 @@ amq-interconnect-645db76c76-k8ghs 1/1 Running 0 23h interconnect-operator-5cb5fc7cc-4v7qm 1/1 Running 0 23h ---- -. Check that the required `hw-event-proxy` hardware event producer pod is running in the `openshift-hw-events` namespace. +. Verify that the required `hw-event-proxy` hardware event producer pod is running in the `openshift-hw-events` namespace. + [source,terminal] ---- diff --git a/modules/nw-rfhe-creating-hardware-event.adoc b/modules/nw-rfhe-creating-hardware-event.adoc index 9a7d104d2c7a..b78845d28cdf 100644 --- a/modules/nw-rfhe-creating-hardware-event.adoc +++ b/modules/nw-rfhe-creating-hardware-event.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * networking/using-rfhe.adoc +// * monitoring/using-rfhe.adoc :_content-type: PROCEDURE [id="nw-rfhe-creating-hardware-event_{context}"] @@ -17,7 +17,7 @@ To start using baremetal hardware events, create the a `HardwareEvent` custom re [NOTE] ==== -Create a single instance of the `HardwareEvent` resource. Multiple `HardwareEvent` resources are not permitted. +Multiple `HardwareEvent` resources are not permitted. ==== .Procedure @@ -39,8 +39,8 @@ spec: logLevel: "debug" <3> msgParserTimeout: "10" <4> ---- -<1> Mandatory. Use the `nodeSelector` field to target nodes with the specified label, for example, `node-role.kubernetes.io/hw-event: ""`. -<2> Mandatory. AMQP host that delivers the events at the transport layer using the AMQP protocol. +<1> Required. Use the `nodeSelector` field to target nodes with the specified label, for example, `node-role.kubernetes.io/hw-event: ""`. +<2> Required. AMQP host that delivers the events at the transport layer using the AMQP protocol. <3> Optional. The default value is `debug`. Sets the log level in hw-event-proxy logs. The following log levels are available: `fatal`, `error`, `warning`, `info`, `debug`, `trace`. <4> Optional. Sets the timeout value in milliseconds for the Message Parser. If a message parsing request is not responded to within the timeout duration, the original hardware event message is passed to the cloud native event framework. The default value is 10. @@ -51,7 +51,7 @@ spec: $ oc create -f hardware-event.yaml ---- -. Create a BMC username and password `Secret` CR that allows the hardware events proxy to access the Redfish message registry for the bare-metal host. +. Create a BMC username and password `Secret` CR that enables the hardware events proxy to access the Redfish message registry for the bare-metal host. + .. Save the following YAML in the `hw-event-bmc-secret.yaml` file: + diff --git a/modules/nw-rfhe-creating_bmc_event_sub.adoc b/modules/nw-rfhe-creating_bmc_event_sub.adoc index 956e743bfdbe..092ca5a72633 100644 --- a/modules/nw-rfhe-creating_bmc_event_sub.adoc +++ b/modules/nw-rfhe-creating_bmc_event_sub.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * networking/using-rfhe.adoc +// * monitoring/using-rfhe.adoc :_content-type: PROCEDURE [id="nw-rfhe-creating_bmc_event_sub_{context}"] @@ -15,10 +15,10 @@ You can only create a `BMCEventSubscription` CR for physical hardware that suppo [NOTE] ==== -Use the `BMCEventSubscription` CR to subscribe to pre-defined Redfish events. The Redfish standard does not provide an option to create specific alerts and thresholds. For example, to receive an alert event when an enclosure's temperature exceeds 40° Celsius, you need to manually configure the event according to the vendor's recommendations. +Use the `BMCEventSubscription` CR to subscribe to predefined Redfish events. The Redfish standard does not provide an option to create specific alerts and thresholds. For example, to receive an alert event when an enclosure's temperature exceeds 40° Celsius, you must manually configure the event according to the vendor's recommendations. ==== -To subscribe to Redfish hardware events for the node using a `BMCEventSubscription` custom resource (CR), perform the following procedure: +Perform the following procedure to subscribe to Redfish hardware events for the node using a `BMCEventSubscription` custom resource (CR). .Prerequisites * Install the OpenShift CLI (`oc`). diff --git a/modules/nw-rfhe-installing-operator-cli.adoc b/modules/nw-rfhe-installing-operator-cli.adoc index dbcec638ad0f..49f5afc46a26 100644 --- a/modules/nw-rfhe-installing-operator-cli.adoc +++ b/modules/nw-rfhe-installing-operator-cli.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * networking/using-rfhe.adoc +// * monitoring/using-rfhe.adoc :_content-type: PROCEDURE [id="nw-rfhe-installing-operator-cli_{context}"] @@ -88,7 +88,9 @@ spec: $ oc create -f hw-events-sub.yaml ---- -. To verify that the Operator is installed, enter the following command: +.Verification + +To verify that the Operator is installed, run the following command: + [source,terminal] ---- diff --git a/modules/nw-rfhe-installing-operator-web-console.adoc b/modules/nw-rfhe-installing-operator-web-console.adoc index 059d1e35c0b3..2767a29a79b7 100644 --- a/modules/nw-rfhe-installing-operator-web-console.adoc +++ b/modules/nw-rfhe-installing-operator-web-console.adoc @@ -1,6 +1,7 @@ // Module included in the following assemblies: // -// * networking/using-rfhe.adoc +// * monitoring/using-rfhe.adoc + :_content-type: PROCEDURE [id="nw-rfhe-installing-operator-web-console_{context}"] = Installing the Baremetal Hardware Event Proxy Operator using the web console diff --git a/modules/nw-rfhe-introduction.adoc b/modules/nw-rfhe-introduction.adoc index 030dc7315106..52b4593e5c8e 100644 --- a/modules/nw-rfhe-introduction.adoc +++ b/modules/nw-rfhe-introduction.adoc @@ -1,45 +1,50 @@ // Module included in the following assemblies: // -// * networking/multiple_networks/configuring-ptp.adoc +// * monitoring/using-rfhe.adoc + :_content-type: CONCEPT [id="nw-rfhe-introduction_{context}"] = How Redfish hardware events work -The Baremetal Hardware Event Proxy enables applications running on baremetal clusters to respond quickly to Redfish hardware changes and failures such as breaches of temperature thresholds, fan failure, disk loss, power outages, and memory failure. These hardware events are delivered over a reliable low-latency transport channel based on Advanced Message Queuing Protocol (AMQP). The latency of the messaging service is in the 10~20 millisecond range. -The hardware event proxy provides a publish-subscribe service for the hardware events, where multiple applications can use REST APIs to subscribe and consume the events. -The hardware event proxy supports hardware that complies with Redfish OpenAPI v1.8 or higher. +The Baremetal Hardware Event Proxy enables applications running on baremetal clusters to respond quickly to Redfish hardware changes and failures such as breaches of temperature thresholds, fan failure, disk loss, power outages, and memory failure. These hardware events are delivered over a reliable low-latency transport channel based on Advanced Message Queuing Protocol (AMQP). The latency of the messaging service is between 10 to 20 milliseconds. + +The hardware event proxy provides a publish-subscribe service for the hardware events, where multiple applications can use REST APIs to subscribe and consume the events. The hardware event proxy supports hardware that complies with Redfish OpenAPI v1.8 or higher. [id="rfhe-elements_{context}"] == Redfish hardware events data flow -The following figure illustrates an example Redfish hardware events data flow. vDU is used here as an example of an application interacting with Redfish events: + +The following figure illustrates an example Redfish hardware events data flow. vDU is used as an example of an application interacting with Redfish events: .Redfish hardware events data flow image::211_OpenShift_Redfish_dataflow_0222.png[Redfish hardware events data flow] === Operator-managed pod -The Operator makes use of custom resources to manage the pod containing the hardware event proxy and its components using the HardwareEvent CR. + +The Operator uses custom resources to manage the pod containing the hardware event proxy and its components using the `HardwareEvent` CR. === Hardware event proxy -A container created to handle Redfish events. At startup, the hardware event proxy queries the Redfish API and downloads all the Message Registries, including custom registries. The hardware event proxy then begins to receive subscribed events from the Redfish hardware. -The proxy enables applications running on bare-metal clusters to respond quickly to Redfish hardware changes and failures such as breaches of temperature thresholds, fan failure, disk loss, power outages, and memory failure, reported using the `HardwareEvent` CR. +At startup, the hardware event proxy queries the Redfish API and downloads all the message registries, including custom registries. The hardware event proxy then begins to receive subscribed events from the Redfish hardware. + +The proxy enables applications running on bare-metal clusters to respond quickly to Redfish hardware changes and failures such as breaches of temperature thresholds, fan failure, disk loss, power outages, and memory failure. The events are reported using the `HardwareEvent` CR. === Cloud Native Event -Cloud Native Events (CNE) is a Rest-API specification for defining the format of event data: https://github.com/redhat-cne/spec/blob/main/event_spec.md. + +Cloud Native Events (CNE) is a REST API specification for defining the format of event data. === CNCF CloudEvents -CloudEvents is a vendor-neutral specification for defining the format of event data. -A specification developed by the Cloud Native Computing Foundation (CNCF) for describing event data in a common way: -https://cloudevents.io/. -=== Dispatch router (AMQP 1.0 qpid) -The dispatch router is responsible for the message delivery service between publisher and subscriber. AMQP 1.0 qpid is an open standard designed to support reliable, high-performance, fully-symmetrical messaging over the internet. AMQP connects systems, supports management processes with the information they need and reliably transmits onward the instructions that run a distributed network via a connection-oriented messaging API. +link:https://cloudevents.io/[CloudEvents] is a vendor-neutral specification developed by the Cloud Native Computing Foundation (CNCF) for defining the format of event data. + +=== AMQP dispatch router + +The dispatch router is responsible for the message delivery service between publisher and subscriber. AMQP 1.0 qpid is an open standard that supports reliable, high-performance, fully-symmetrical messaging over the internet. + +=== Cloud event proxy sidecar -=== Sidecar: Cloud event proxys -A cloud events framework (based on ORAN API specifications) container image that provides an event publish-subscribe framework for hardware events. +The cloud event proxy sidecar container image is based on the ORAN API specification and provides a publish-subscribe event framework for hardware events. [id="rfhe-data-flow_{context}"] == Redfish message parsing service -In addition to relating Redfish events, the Redfish Hardware Event Proxy provides message parsing service for events without a `Message` property. The proxy downloads all the Redfish Message Registries including vendor specific registries from the hardware when it starts. If a event it received does not contain a Message property, the proxy will use the information from registries to construct the `Message` and `Resolution` properties and add them to the event before passing the event to the cloud events framework. -This service allows Redfish events to be generated with smaller message size and achieve lower latency. +In addition to handling Redfish events, the Redfish hardware event proxy provides message parsing for events without a `Message` property. The proxy downloads all the Redfish message registries including vendor specific registries from the hardware when it starts. If an event does not contain a `Message` property, the proxy uses the Redfish message registries to construct the `Message` and `Resolution` properties and add them to the event before passing the event to the cloud events framework. This service allows Redfish events to have smaller message size and lower transmission latency. diff --git a/monitoring/using-rfhe.adoc b/monitoring/using-rfhe.adoc index c1a59593740a..06f24ae88de5 100644 --- a/monitoring/using-rfhe.adoc +++ b/monitoring/using-rfhe.adoc @@ -14,7 +14,7 @@ include::snippets/technology-preview.adoc[leveloffset=+1] {product-title} enables your monitoring services to consume cloud-native events from Redfish hardware event-capable equipment. The Redfish service publishes events on a node and transmits them on an advanced message queue to your subscribing applications. -Redfish hardware events provide the basis for a standard network monitoring services that is cloud friendly and secure. The standard is developed under the guidance of the DMTF (formerly referred to as the Distributed Management Task Force). Redfish provides an industry-standard protocol with a RESTful interface. The protocol is used for the management of distributed, converged or software-defined resources and infrastructure. +Redfish hardware events provide the basis for a standard network monitoring services that is cloud friendly and secure. The standard is developed under the guidance of the Distributed Management Task Force. Redfish provides an industry-standard protocol with a RESTful interface. The protocol is used for the management of distributed, converged or software-defined resources and infrastructure. [NOTE] ==== @@ -23,13 +23,13 @@ Redfish hardware events work only with Redfish-capable devices on OpenShift sing The hardware-related events published through Redfish to monitoring applications may include: -* breaches of temperature limits -* server status -* fan status +* Breaches of temperature limits +* Server status +* Fan status Application developers can use the Redfish hardware events API to get log updates on errors that have or could occur in a distributed system. -You can use the OpenShift Container Platform console to install the Redfish hardware event service by deploying the Operator and subscribing to the service. The Operator manages the lifecycle of the event service. +You can use the {product-title} console to install the Redfish hardware event service by deploying the Operator and subscribing to the service. The Operator manages the lifecycle of the event service. include::modules/nw-rfhe-introduction.adoc[leveloffset=+1] [id="installing-hw-events"]