Merge pull request #70711 from shreyasiddhartha/ER-powermon

OBSDOCS-582: Docs for Power Monitoring Tech Preview

Author: mburke5678

_attributes/common-attributes.adoc

@@ -148,6 +148,13 @@ endif::[]
 :loki-op: Loki Operator
 :es-op: OpenShift Elasticsearch Operator
 :log-plug: logging subsystem Console plugin
+//power monitoring
+:PM-title-c: Power monitoring for Red Hat OpenShift
+:PM-title: power monitoring for Red Hat OpenShift
+:PM-shortname: power monitoring
+:PM-shortname-c: Power monitoring
+:PM-operator: Power monitoring Operator
+:PM-kepler: Kepler
 //serverless
 :ServerlessProductName: OpenShift Serverless
 :ServerlessProductShortName: Serverless

_topic_maps/_topic_map.yml

@@ -2699,6 +2699,23 @@ Topics:
   - Name: Configuring the Cluster Observability Operator to monitor a service
     File: configuring-the-cluster-observability-operator-to-monitor-a-service
 ---
+Name: Power monitoring
+Dir: power_monitoring
+Distros: openshift-enterprise,openshift-origin
+Topics:
+- Name: Power monitoring release notes
+  File: power-monitoring-release-notes
+- Name: Power monitoring overview
+  File: power-monitoring-overview
+- Name: Installing power monitoring
+  File: installing-power-monitoring
+- Name: Configuring power monitoring
+  File: configuring-power-monitoring
+- Name: Visualizing power monitoring metrics
+  File: visualizing-power-monitoring-metrics
+- Name: Uninstalling power monitoring
+  File: uninstalling-power-monitoring
+---
 Name: Distributed tracing
 Dir: distr_tracing
 Distros: openshift-enterprise

images/power-monitoring-component-power-source.png

@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// * power_monitoring/power-monitoring-overview.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="power-monitoring-about-power-monitoring_{context}"]
+= About {PM-shortname}
+
+You can use {PM-title} to monitor the power usage and identify power-consuming containers running in an {product-title} cluster. {PM-shortname-c} collects and exports energy-related system statistics from various components, such as CPU and DRAM. It provides granular power consumption data for Kubernetes pods, namespaces, and nodes.

modules/power-monitoring-about-power-monitoring.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+
+// * power_monitoring/visualizing-power-monitoring-metrics.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="power-monitoring-accessing-dashboards_{context}"]
+= Accessing {PM-shortname} dashboards
+
+You can access {PM-shortname} dashboards from the *Administrator* perspective of the {product-title} web console.
+
+.Prerequisites
+
+* You have access to the {product-title} web console.
+* You are logged in as a user with the `cluster-admin` role.
+* You have installed the {PM-operator}.
+* You have deployed {PM-kepler} in your cluster.
+* You have enabled monitoring for user-defined projects.
+
+.Procedure
+
+. In the *Administrator* perspective of the web console, go to *Observe* -> *Dashboards*.
+
+. From the *Dashboard* drop-down list, select the {PM-shortname} dashboard you want to see: 
+** *Power Monitoring / Overview*
+** *Power Monitoring / Namespace*

modules/power-monitoring-accessing-dashboards.adoc

@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+
+// * power_monitoring/visualizing-power-monitoring-metrics.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="power-monitoring-dashboards-overview_{context}"]
+= {PM-shortname-c} dashboards overview
+
+There are two types of {PM-shortname} dashboards. Both provide different levels of details around power consumption metrics for a single cluster:
+
+[discrete]
+== Power Monitoring / Overview dashboard
+
+With this dashboard, you can observe the following information:
+
+* An aggregated view of CPU architecture and its power source (`rapl-sysfs`, `rapl-msr`, or `estimator`) along with total nodes with this configuration
+
+* Total energy consumption by a cluster in the last 24 hours (measured in kilowatt-hour)
+
+* The amount of power consumed by the top 10 namespaces in a cluster in the last 24 hours
+
+* Detailed node information, such as its CPU architecture and component power source
+
+These features allow you to effectively monitor the energy consumption of the cluster without needing to investigate each namespace separately.
+
+[WARNING]
+====
+Ensure that the *Components Source* column does not display `estimator` as the power source.
+
+.The Detailed Node Information table with `rapl-sysfs` as the component power source
+image::power-monitoring-component-power-source.png[]
+
+If {PM-kepler} is unable to obtain hardware power consumption metrics, the *Components Source* column displays `estimator` as the power source, which is not supported in Technology Preview. If that happens, then the values from the nodes are not accurate.
+====
+
+[discrete]
+== Power Monitoring / Namespace dashboard
+
+This dashboard allows you to view metrics by namespace and pod. You can observe the following information:
+
+* The power consumption metrics, such as consumption in DRAM and PKG
+
+* The energy consumption metrics in the last hour, such as consumption in DRAM and PKG for core and uncore components
+
+This feature allows you to investigate key peaks and easily identify the primary root causes of high consumption.

modules/power-monitoring-dashboards-overview.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+
+// * power_monitoring/uninstalling-power-monitoring.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="power-monitoring-deleting-kepler_{context}"]
+= Deleting {PM-kepler}
+
+You can delete {PM-kepler} by removing the {PM-kepler} instance of the `{PM-kepler}` custom resource definition (CRD) from the {product-title} web console.
+
+.Prerequisites
+* You have access to the {product-title} web console.
+* You are logged in as a user with the `cluster-admin` role.
+
+.Procedure
+
+. In the *Administrator* perspective of the web console, go to *Operators* -> *Installed Operators*.
+
+. Click *{PM-title-c}* from the *Installed Operators* list and go to the *{PM-kepler}* tab.
+
+. Locate the {PM-kepler} instance entry in the list.
+
+. Click {kebab} for this entry and select *Delete {PM-kepler}*.
+
+. In the *Delete {PM-kepler}?* dialog, click *Delete* to delete the {PM-kepler} instance.
+

modules/power-monitoring-deleting-kepler.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+
+// * power_monitoring/installing-power-monitoring.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="power-monitoring-deploying-kepler_{context}"]
+= Deploying {PM-kepler}
+
+You can deploy {PM-kepler} by creating an instance of the `{PM-kepler}` custom resource definition (CRD) by using the {PM-operator}. 
+
+.Prerequisites
+* You have access to the {product-title} web console.
+* You are logged in as a user with the `cluster-admin` role.
+* You have installed the {PM-operator}.
+
+.Procedure
+
+. In the *Administrator* perspective of the web console, go to *Operators* -> *Installed Operators*.
+
+. Click *{PM-title-c}* from the *Installed Operators* list and go to the *{PM-kepler}* tab.
+
+. Click *Create {PM-kepler}*.
+
+. On the *Create {PM-kepler}* page, ensure the *Name* is set to `kepler`.
++
+[IMPORTANT]
+====
+The name of your {PM-kepler} instance must be set to `kepler`. All other instances are ignored by the {PM-operator}.
+====
+
+. Click *Create* to deploy {PM-kepler} and {PM-shortname} dashboards.

modules/power-monitoring-deploying-kepler.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * power_monitoring/power-monitoring-overview.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="power-monitoring-hardware-virtualization-support_{context}"]
+= {PM-kepler} hardware and virtualization support
+
+{PM-kepler} is the key component of {PM-shortname} that collects real-time power consumption data from a node through one of the following power estimation methods:
+
+Kernel Power Management Subsystem (preferred)::
+* `rapl-sysfs`: This requires access to the `/sys/class/powercap/intel-rapl` host file.
+* `rapl-msr`: This requires access to the `/dev/cpu/*/msr` host file.
+
+The `estimator` power source::
+Without access to the kernel's power cap subsystem, {PM-kepler} uses a machine learning model to estimate the power usage of the CPU on the node.
++
+[WARNING]
+====
+The `estimator` feature is experimental, not supported, and should not be relied upon.
+====
+
+You can identify the power estimation method for a node by using the *Power Monitoring / Overview* dashboard.
+
+[WARNING]
+====
+{PM-shortname-c} Technology Preview works only in bare-metal deployments. Most public cloud vendors do not expose Kernel Power Management Subsystems to virtual machines.
+====

modules/power-monitoring-hardware-virtualization-support.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+
+// * power_monitoring/installing-power-monitoring.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="power-monitoring-installing-pmo_{context}"]
+= Installing the {PM-operator}
+
+As a cluster administrator, you can install the {PM-operator} from OperatorHub by using the {product-title} web console.
+
+[WARNING]
+====
+You must remove any previously installed versions of the {PM-operator} before installation.
+====
+
+.Prerequisites
+* You have access to the {product-title} web console.
+* You are logged in as a user with the `cluster-admin` role.
+
+.Procedure
+
+. In the *Administrator* perspective of the web console, go to *Operators* -> *OperatorHub*.
+
+. Search for `{PM-shortname}`, click the *{PM-title-c}* tile, and then click *Install*.
+//. On the *Install Operator* page:
+//.. Select an *Update channel*.
+//.. Select a {PM-shortname} *Version* to install.
+// This can be included once the user has options there to choose. Not needed for now.
+
+. Click *Install* again to install the {PM-operator}.
++
+{PM-title-c} is now available in all namespaces of the {product-title} cluster.
+
+.Verification
+
+. Verify that the {PM-operator} is listed in *Operators* -> *Installed Operators*. The *Status* should resolve to *Succeeded*.