Merge pull request #139 from sustainable-computing-io/gsf-impact

Documentation for using GSF Impact Plugins with SusQL

.gitignore

@@ -31,3 +31,6 @@ temp-prometheus.yaml
 .susql-deploy-info.txt
 .susql-deploy-info-last.txt
 c3-susql-config.yaml
+nohup.out
+.env
+node_modules

samples/README.md

@@ -20,6 +20,9 @@
 - `training-job-2.yaml`
 - `rhosaij.yaml`
 
+## directories
+- `impact-framework` - sample files for using SusQL with the [Green Software Impact Framework](https://if.greensoftware.foundation).
+
 
 ## License
 

samples/impact-framework/README.md

@@ -0,0 +1,10 @@
+# Using SusQL with the Green Software Foundation's Impact Framework
+
+A large design point in using SusQL data with the Green Software Foundation's
+Impact Framework is whether to run in a container ON the cluster with SusQL, or run
+on a machine external to the cluster.
+
+This directory contains two directories with experiments into both approaches:
+
+- [onClusterApproach](onClusterApproach)
+- [offClusterApproach](offClusterApproach)

samples/impact-framework/offClusterApproach/.trent/README.md

@@ -0,0 +1 @@
+experimentation...

samples/impact-framework/offClusterApproach/.trent/htest.yaml

@@ -0,0 +1,24 @@
+name: hello plugin test
+description: simple verification of plugin tech
+tags: null
+initialize:
+  plugins:
+    'hello-plugin':
+      method: HelloPlugin
+      path: 'https://github.com/trent-s/hello-plugin'
+      config:
+        allow-padding: true
+  outputs: 
+    - yaml
+tree:
+  children:
+    child:
+      pipeline:
+        - hello-plugin
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          carbon: 30
+        - timestamp: 2023-09-06T00:00
+          duration: 3600
+          carbon: 30

samples/impact-framework/offClusterApproach/.trent/pi1/pi1test.yaml

@@ -0,0 +1,28 @@
+name: prometheus importer test
+description: simple susql demo invoking prometheus-importer plugin
+tags: null
+initialize:
+  plugins:
+    prometheus-importer:
+      method: PrometheusImporter
+      path: 'https://github.com/Shivani-G/prometheus-importer'
+      global-config:
+        step: '1h'
+        start: '2024-09-16T23:50:30.000Z'
+        end: '2024-10-16T00:00:30.000Z'
+        query: 'rate(susql_container_joules_total)[1m])'
+        metricLabels:
+          - name
+        metricName: 'energy'
+        defaultLabels:
+          duration: 3600
+          cloud/vendor: 'ibm'
+          cloud/instance-type: 'medium'
+  outputs: 
+    - yaml
+tree:
+  children:
+    child:
+      pipeline:
+        - prometheus-importer
+      inputs:

samples/impact-framework/offClusterApproach/.trent/pi1/steps.txt

@@ -0,0 +1,20 @@
+# in this directory
+npm init -y
+npm install -g husky
+npm install -g @grnsft/if
+# npm remove -g "https://github.com/trent-s/prometheus-importer"
+npm remove -g prometheus-importer
+npm remove prometheus-importer
+npm install -g "https://github.com/Shivani-G/prometheus-importer"
+npm update
+echo "BEARER_TOKEN="$(oc whoami -t) >.env
+echo HOST=https://$(oc get routes -n openshift-monitoring thanos-querier -o jsonpath='{.status.ingress[0].host}') >>.env
+if-run --manifest  pi1test.yaml --debug
+
+
+
+
+## troubleshootign
+# npm cache verify
+# npm install npm@latest -g
+

samples/impact-framework/offClusterApproach/README.md

@@ -0,0 +1,36 @@
+# Using SusQL with the Green Software Foundation's Impact Framework
+
+This particular experiment was performed using a recent RHEL 9 x86 machine,
+however, any OS that supports a sufficiently recent version of `nodejs` should
+work in principle.
+
+The key to importing data from SusQL is a Prometheus Importer Plugin for the GSF Impact Framework.
+Currently there are two such plugins described in the (IF Explorer)[https://explorer.if.greensoftware.foundation]:
+- (`Prometheus Importer`)[https://github.com/andreic94/if-prometheus-importer/blob/main/README.md] by `andreic94`, et al.
+- (`prometheus-importer`)[https://github.com/Shivani-G/prometheus-importer/blob/main/README.md] by `Shibani-G`.
+
+The following is an approach using the later plugin:
+
+### steps
+- Ensure that you are logged into your cluster and can use the `oc` (or `kubectl` command).
+- Make sure that a recent version of `node` is installed.  (This test used v22.9.0)
+- Install Impact Framework
+  - `npm install -g @grnsft/if`
+- Install Prometheus Importer
+  - `npm install -g "https://github.com/Shivani-G/prometheus-importer"`
+- Update, just to be sure: (Starting from the directory that contains this README...)
+  - `cd test; npm update; cd -`
+
+- Create required credential file, and attempt to use prometheus-importer: (Starting from the directory that contains this README...)
+```
+cd test
+echo "BEARER_TOKEN="$(oc whoami -t) >.env
+echo HOST=https://$(oc get routes -n openshift-monitoring thanos-querier -o jsonpath='{.status.ingress[0].host}') >>.env
+
+if-run --manifest  ../ptest.yaml --debug
+cd -
+```
+
+
+Note:
+- `oc` and `kubectl` are (should be) interchangable in this context.

samples/impact-framework/offClusterApproach/ptest.yaml

@@ -0,0 +1,27 @@
+name: prometheus importer test
+description: simple susql demo invoking prometheus-importer plugin
+tags: null
+initialize:
+  plugins:
+    prometheus-importer:
+      method: PrometheusImporter
+      path: 'https://github.com/Shivani-G/prometheus-importer'
+      config:
+        step: '1h'
+        start: '2024-09-16T23:50:30.000Z'
+        end: '2024-10-16T00:00:30.000Z'
+        query: 'rate(susql_container_joules_total)[1m])'
+        metricLabels:
+          - name
+        metricName: 'energy'
+        defaultLabels:
+          duration: 3600
+          cloud/vendor: 'ibm'
+  outputs: 
+    - yaml
+tree:
+  children:
+    child:
+      pipeline:
+        - prometheus-importer
+      inputs:

samples/impact-framework/offClusterApproach/test/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "test",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "prometheus-importer": "github:Shivani-G/prometheus-importer"
+  }
+}

samples/impact-framework/onClusterApproach/.trent/htest.yaml

@@ -0,0 +1,24 @@
+name: hello plugin test
+description: simple verification of plugin tech
+tags: null
+initialize:
+  plugins:
+    'hello-plugin':
+      method: HelloPlugin
+      path: 'https://github.com/trent-s/hello-plugin'
+      config:
+        allow-padding: true
+  outputs: 
+    - yaml
+tree:
+  children:
+    child:
+      pipeline:
+        - hello-plugin
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          carbon: 30
+        - timestamp: 2023-09-06T00:00
+          duration: 3600
+          carbon: 30

samples/impact-framework/onClusterApproach/Dockerfile

@@ -0,0 +1,24 @@
+FROM ubuntu:latest
+
+ENV NPM_CONFIG_PREFIX=/usr/local
+ARG NPM_CONFIG_PREFIX=/usr/local
+
+WORKDIR /work
+COPY ?test.yaml .
+
+RUN apt-get update -y && \
+apt-get upgrade -y && \
+apt-get install git curl vim lsb-release -y && \
+echo "    --- Finished apt-get install" && \
+# npm install -g npm@latest  && \
+# echo "    --- Finished npm update" && \
+curl -fsSL https://deb.nodesource.com/setup_lts.x | bash && \
+apt-get upgrade -y && \
+apt-get install nodejs -y && \
+npm install -g [email protected] && \
+echo "    --- Finished node update" && \
+npm install -g typescript rimraf husky @grnsft/if && \
+echo "    --- Finished if install" && \
+npm install -g "https://github.com/Shivani-G/prometheus-importer" && \
+echo "    --- Finished PI install" && \
+chown -R 1000:1000 /work /usr/local/