Add Kepler installation guide

CONTRIBUTING.md

@@ -0,0 +1,2 @@
+## Contributing
+If you would like to contribute to this repository, please fork the repository and submit a pull request with your changes. You can also open an issue to report bugs or suggest new experimental conditions.

README.md

@@ -1,2 +1,38 @@
-# gitops-envsus-benchmark-tests
-A project to do energy benchmark tests on different GitOps tools and patterns with Kepler.
+# Energy Benchmarking Experimental Setup for GitOps
+This GitHub repository contains energy-related experimental benchmark tests for different GitOps tools and patterns with Kepler. 
+
+## Motivation
+GitOps has rapidly gained attraction as a promising software delivery approach that can bring numerous benefits, including faster deployment times, increased reliability, and improved scalability. However, there is currently limited research on the energy consumption of GitOps architectures and tools.
+
+This repository aims to fill this gap by collecting energy-related metrics such as energy consumption that can help to evaluate the energy efficiency of GitOps solutions under various experimental conditions and to identify ways to reduce their environmental impact.
+
+## Contents
+The repository includes the following contents:
+
+- docs: This directory contains documentation and instructions on how to run the experiments.
+- experiments: This directory contains experimental scripts that can be used to run the benchmark tests.
+- images: This directory contains screenshots and other images that are used in this repository.
+
+## Requirements
+To run the experimental benchmark tests in this repository, you will need the following:
+
+- [Kubernetes cluster](https://github.com/kubernetes/minikube)
+- [Docker](https://docs.docker.com/engine/install/ubuntu)
+- [Kepler](https://github.com/sustainable-computing-io/kepler)
+- GitOps tools such [Argo CD](https://github.com/argoproj/argo-cd) or [Flux CD](https://github.com/fluxcd/flux2)
+
+Detailed installation and configuration instructions for these tools are provided in the docs directory.
+
+## Running the Experiments
+To run the benchmark tests, follow these steps:
+
+- Install the required tools and configure the environment as described in the docs directory.
+- Clone this repository to your local machine.
+- Navigate to the experiments directory.
+- Run the experimental scripts using the commands provided in the docs directory.
+
+## License
+This repository is licensed under the Apache-2.0 License. See the [LICENSE](LICENSE) file for more details.
+
+## Acknowledgments
+This repository was inspired by the work of the GitOps & Environmental Sustainability Subgroup. We would like to thank the members of the community for their contributions and support.

docs/01-utilities.md

@@ -0,0 +1,49 @@
+# Utilities
+The following utilities need to be installed in order to follow Kepler installation guide:
+
+- Go
+- Make
+- Docker
+- kubectl
+- Helm
+
+# Installation Steps
+
+## Installing Go
+
+```bash
+sudo apt install golang-go
+```
+
+## Installing Make
+
+```bash
+sudo apt install make
+```
+
+## Installing Docker 
+
+```bash
+sudo apt-get update
+sudo apt-get install ca-certificates curl gnupg lsb-release 
+sudo mkdir -p /etc/apt/keyrings
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+sudo apt-get update
+sudo apt-get install docker-ce docker-ce-cli containerd.io
+```
+
+## Installing kubectl
+
+```bash
+curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+curl -LO "https://dl.k8s.io/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256"
+echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check
+sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
+```
+
+## Installing Helm
+
+```bash
+tar -zxvf helm-v3.11.0-linux-amd64.tar.gz 
+sudo mv linux-amd64/helm /usr/local/bin/helm
+```

docs/02-kepler-installation-guide.md

@@ -0,0 +1,100 @@
+# Kepler Installation Guide
+
+This guide will show you how to install Kepler, a lightweight pod-level power consumption metrics exporter, on a Minikube cluster running on an Ubuntu 22.04 host.
+
+## Prerequisites
+
+Before you begin, you'll need to have the following:
+
+- Kernel 4.18+
+- Docker installed
+- Make and go packages installed
+- kubectl command-line tool installed
+- Helm command-line tool installed
+
+## Installation steps
+
+Start by installing Minikube on your machine. You can follow the instructions in the [Minikube documentation](https://minikube.sigs.k8s.io/docs/start/).
+I ran the following commands:
+
+```bash
+curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
+sudo install minikube-linux-amd64 /usr/local/bin/minikube
+sudo usermod -aG docker $USER && newgrp docker
+```
+
+Once you have Minikube installed, start a new cluster using the following command (CPUs and Memory values can be customized):
+
+```bash
+# check CPU cores
+lscpu | grep "CPU(s)"
+# start the cluster
+minikube start --cpus 4 --memory 4096
+```
+
+Next, install the Prometheus Operator on your cluster by running the following commands:
+
+```bash
+git clone https://github.com/prometheus-operator/kube-prometheus.git
+cd kube-prometheus/
+kubectl apply --server-side -f manifests/setup
+kubectl wait --for condition=Established --all CustomResourceDefinition	--namespace=monitoring
+kubectl apply -f manifests/
+cd ../
+```
+
+Clone Kepler repository and generate manifest files by running the following commands:
+
+```bash
+git clone https://github.com/sustainable-computing-io/kepler.git -b v0.4
+cd kepler/
+# to configure Prometheus to scrape Kepler-exporter endpoints, Kepler exporter servicemonitor object is required
+make build-manifest OPTS="PROMETHEUS_DEPLOY"
+# update the NODE_NAME to localhost in the deployment manifest when using Minikube
+```
+
+Deploy Kepler v0.4 to your cluster by running the following command:
+
+```bash
+kubectl apply -f _output/generated-manifest/deployment.yaml
+cd ../
+```
+
+Once Kepler is deployed, verify that Kepler is working by running the following commands:
+
+```bash
+# get Kepler's pod name
+kubectl get pods -n kepler
+# check Kepler's logs
+kubectl logs kepler-exporter-<xxxxx> -n kepler -f
+# get kepler related metrics
+kubectl exec -ti -n kepler daemonset/kepler-exporter -- bash -c "curl localhost:9102/metrics"
+# or
+kubectl port-forward kepler-exporter-<xxxxx> 9102:9102 -n kepler
+# run the following command in another window while keeping port-forward running
+curl http://localhost:9102/metrics
+```
+
+View Kepler metrics that have been exported to Prometheus and visualized with Grafana [Kepler's dashboard](https://github.com/sustainable-computing-io/kepler/blob/main/grafana-dashboards/Kepler-Exporter.json) by running the following commands:
+
+```bash
+# to view grafana dashboard, port-forward grafana svc and import Kepler's dashboard
+kubectl port-forward svc/grafana 3000:3000 -n monitoring 
+# to view metrics in prometheus UI
+kubectl port-forward svc/prometheus-k8s 9090:9090 -n monitoring
+```
+
+## Conclusion
+
+That's it! You should now have Kepler up and running on your Minikube cluster with power consumption metrics being exported.
+
+![Grafana dashboard screenshot](../images/grafana-dashboard.png)
+
+## Clean up
+
+To remove kepler related objects, run the following commands:
+```bash
+kubectl delete ns kepler
+kubectl delete clusterrole kepler-clusterrole
+kubectl delete clusterrolebinding kepler-clusterrole-binding
+```