improve documentation

Signed-off-by: Scott Trent <[email protected]>

README.md

@@ -33,11 +33,14 @@ Kepler is assumed to be installed in the cluster.
 
 ### Installation
 
-Follow these instructions to install the SusQL Operator with Helm.
-- [Installation with Helm](doc/helm-installation.md)
+Follow these instructions for easy SusQL installation from the Red Hat Community Operator catalog on an OpenShift cluster.
+- [Installation on OpenShift](doc/openshift-installation.md)
+
+Follow these instructions to install the SusQL Operator from [OperatorHub.io](https://operatorhub.io) on a Kubernetes cluster including OpenShift.
+- [Installation from OperatorHub.io](doc/operatorhub-installation.md)
 
-Follow these instructions to install the SusQL Operator from [OperatorHub](https://operatorhub.io).
-- [Installation with OperatorHub](doc/operatorhub-installation.md)
+Follow these instructions to install the SusQL Operator with Helm on a Kubernetes cluster including OpenShift.
+- [Installation with Helm](doc/helm-installation.md)
 
 
 ## Using SusQL

config/manifests/bases/susql-operator.clusterserviceversion.yaml

@@ -34,6 +34,8 @@ spec:
     1. Deployment of [Kepler](https://sustainable-computing.io/) on the cluster
     2. Ensure that [User Project Monitoring](https://docs.openshift.com/container-platform/latest/monitoring/enabling-monitoring-for-user-defined-projects.html)
     is enabled to monitor energy consumed in user projects.
+    3. Creation of a SusQL Service Monitor:
+          `oc apply -n <NAMESPACE> -f https://raw.githubusercontent.com/sustainable-computing-io/susql-operator/main/hack/susql-servicemonitor.yaml`
 
     ### API Backward Compatibility
 

doc/openshift-installation.md

@@ -0,0 +1,47 @@
+# SusQL Operator Installation via OpenShift Community Operator Catalog
+
+Installation of the SusQL Operator on OpenShift is very easy.
+
+## Prerequisites
+
+- [Kepler](https://sustainable-computing.io/) is assumed to be installed in the cluster. `oc` is assumed to be installed, and you are assumed to be logged in to the cluster in your CLI environment.
+- Installation of the SusQL Operator has been extensively used with Red Hat OpenShift clusters 4.14 and higher.
+- Consider enabling User Project Monitoring when using on OpenShift.  https://docs.openshift.com/container-platform/latest/monitoring/enabling-monitoring-for-user-defined-projects.html
+- Other versions of OpenShift clusters are also expected to function.
+- Ensure that the following command is run to install the service monitor. Replace`<NAMESPACE>` with the namespace SusQL is installed into. (Usually `openshift-operators`)
+```
+oc apply -n <NAMESPACE> -f oc apply -f https://raw.githubusercontent.com/sustainable-computing-io/susql-operator/main/hack/susql-servicemonitor.yaml
+```
+
+## Installation
+
+Use the OpenShift web console to install the SusQL Operator:
+- Click on "Operator->OperatorHub"
+- Search for "SusQL"
+- Click on it, and follow the GUI prompts to install.
+
+# Customization
+
+Before deploying the SusQL Operator create a `ConfigMap` called `susql-config` in
+the same namespace that the operator will run in.
+[susql-config.yaml](susql-config.yaml) is a good starting point. If you download it first, you
+could create the ConfigMap with `oc apply -n <NAMESPACE> -f susql-config.yaml`.
+If you update (or create) the ConfigMap after the SusQL Operator has been installed, then restarting the SusQL Operator controller pod will
+enable the changes. (e.g., Delete the pod, and allow it to be recreated automatically.)
+
+## License
+
+Copyright 2023, 2024.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

doc/operatorhub-installation.md

@@ -1,13 +1,18 @@
-# SusQL Operator Installation via OperatorHub
+# SusQL Operator Installation via OperatorHub.io
 
-Installation of the SusQL Operator via OperatorHub is fairly easy.
+Installation of the SusQL Operator via OperatorHub.io is fairly easy.
 
 ## Prerequisites
 
-Kepler is assumed to be installed in the cluster. `oc` is assumed to be installed, and you are assumed to be logged in to the cluster in your CLI environment.
-Installation of the SusQL Operator has been extensively used with Red Hat OpenShift clusters 4.14 and higher.
-Consider enabling User Project Monitoring when using on OpenShift.  https://docs.openshift.com/container-platform/latest/monitoring/enabling-monitoring-for-user-defined-projects.html
-Other flavors and versions of Kubernetes clusters are also expected to function.
+- [Kepler](https://sustainable-computing.io/) is assumed to be installed in the cluster. `oc` is assumed to be installed, and you are assumed to be logged in to the cluster in your CLI environment.
+- Installation of the SusQL Operator has been extensively used with Red Hat OpenShift clusters 4.14 and higher.
+- Consider enabling User Project Monitoring when using on OpenShift.  https://docs.openshift.com/container-platform/latest/monitoring/enabling-monitoring-for-user-defined-projects.html
+- Other flavors and versions of Kubernetes clusters are also expected to function.
+- Ensure that the following command is run to install the service monitor. Replace`<NAMESPACE>` with the namespace SusQL is installed into. (Usually `openshift-operators`)
+```
+oc apply -n <NAMESPACE> -f oc apply -f https://raw.githubusercontent.com/sustainable-computing-io/susql-operator/main/hack/susql-servicemonitor.yaml
+```
+
 
 ## Installation
 
@@ -45,16 +50,10 @@ Next, use the OpenShift web console to install the SusQL Operator:
 Before deploying the SusQL Operator create a `ConfigMap` called `susql-config` in
 the same namespace that the operator will run in.
 [susql-config.yaml](susql-config.yaml) is a good starting point. If you download it first, you
-could create the ConfigMap with `oc apply -n YOURNAMESPACE -f susql-config.yaml`.
+could create the ConfigMap with `oc apply -n <NAMESPACE> -f susql-config.yaml`.
 If you update (or create) the ConfigMap after the SusQL Operator has been installed, then restarting the SusQL Operator controller pod will
 enable the changes. (e.g., Delete the pod, and allow it to be recreated automatically.)
 
-# Post Installation Steps
-
-After installing the SusQL Operator be sure to enable the service monitor. This will enable energy and carbon data to be 
-viewed with cluster observability tools such as the "Observe->Metrics" graphs with OpenShift.
-`oc apply -n openshift-operators -f https://raw.githubusercontent.com/sustainable-computing-io/susql-operator/main/hack/susql-operator-susql-controller-manager-metrics-monitor_monitoring.coreos.com_v1_servicemonitor.yaml`
-
 ## License
 
 Copyright 2023, 2024.