From f6273cac466b0c7f188fd7a758b487a0996185b4 Mon Sep 17 00:00:00 2001 From: Parul Singh Date: Wed, 28 Jun 2023 17:08:52 -0400 Subject: [PATCH] Doc page modifications - Add requirements.txt - Add installation doc - Reorg dir - Add technical deep dive section Signed-off-by: Parul Singh --- README.md | 3 +- docs/installation/community-operator.md | 1 + docs/installation/kepler-helm.md | 57 +++++++++++++++++ docs/installation/kepler-operator.md | 28 +++++++++ docs/installation/kepler-rpm.md | 25 ++++++++ docs/installation/kepler.md | 82 ------------------------- docs/usage/deep_dive.md | 25 ++++++++ mkdocs.yml | 10 +++ requirements.txt | 3 + 9 files changed, 150 insertions(+), 84 deletions(-) create mode 100644 docs/installation/community-operator.md create mode 100644 docs/installation/kepler-helm.md create mode 100644 docs/installation/kepler-operator.md create mode 100644 docs/installation/kepler-rpm.md create mode 100644 docs/usage/deep_dive.md create mode 100644 requirements.txt diff --git a/README.md b/README.md index cdb69f8f..2f39f57b 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,7 @@ Follow https://sustainable-computing.io/ to see documentation - Python 3.8 ```bash -pip install mkdocs -pip install mkdocs-material +pip install -r requirements.txt ``` ## Commands diff --git a/docs/installation/community-operator.md b/docs/installation/community-operator.md new file mode 100644 index 00000000..4f750d26 --- /dev/null +++ b/docs/installation/community-operator.md @@ -0,0 +1 @@ +# Kepler Community Operator on OpenShift \ No newline at end of file diff --git a/docs/installation/kepler-helm.md b/docs/installation/kepler-helm.md new file mode 100644 index 00000000..43f91b12 --- /dev/null +++ b/docs/installation/kepler-helm.md @@ -0,0 +1,57 @@ +# Deploy using Helm Chart + +The Kepler Helm Chart is available on [GitHub](https://github.com/sustainable-computing-io/kepler-helm-chart/tree/main) and [ArtifactHub](https://artifacthub.io/packages/helm/kepler/kepler) + +For Installation [Helm](https://helm.sh) must be installed to use the charts. +Please refer to Helm's [documentation](https://helm.sh/docs/) to get started. + +The chart is accessible using the following commands: + +Add the helm repo + +```bash +helm repo add kepler https://sustainable-computing-io.github.io/kepler-helm-chart +``` + +You can see the latest version by using the folllowing command: + +```bash +helm search repo kepler +``` + +If you would like to test and look at the manifest files before deploying you can run: + +```bash +helm install kepler kepler/kepler --namespace kepler --create-namespace --dry-run --devel +``` + +Then to install run the following: + +```bash +helm install kepler kepler/kepler --namespace kepler --create-namespace +``` + +You may want to override [values.yaml](https://github.com/sustainable-computing-io/kepler-helm-chart/blob/main/chart/kepler/values.yaml) file use the following command. + +```bash +helm install kepler kepler/kepler --values values.yaml --namespace kepler --create-namespace +``` + +The following table lists the configurable parameters for this chart and their default values. + +Parameter|Description| Default +---|---|--- +global.namespace| Kubernete namespace for kepler |kepler +image.repository|Repository for Kepler Image| quay.io/sustainable\_computing\_io/kepler +image.pullPolicy|Pull policy for Kepler|Always +image.tag|Image tag for Kepler Image |latest +serviceAccount.name|Service acccount name for Kepler|kepler-sa +service.type|Kepler service type|ClusterIP +service.port|Kepler service exposed port|9102 + +#### Uninstall Kepler +To uninstall this chart, use the following steps + +```bash +helm delete --purge kepler --tiller-namespace +``` diff --git a/docs/installation/kepler-operator.md b/docs/installation/kepler-operator.md new file mode 100644 index 00000000..a2298a01 --- /dev/null +++ b/docs/installation/kepler-operator.md @@ -0,0 +1,28 @@ +# Kepler Operator on Kind + +## Getting Started + +You’ll need a Kubernetes cluster to run against. You can use KIND to get a local cluster for testing, or run against a remote cluster. Note: Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster kubectl cluster-info shows). + +### To run a kind cluster locally + +``` sh +make cluster-up CLUSTER_PROVIDER='kind' CI_DEPLOY=true GRAFANA_ENABLE=true +``` + +### To run kepler-operator locally on the cluster +You can use the image from quay.io to deploy kepler-operator. + +```sh +make deploy IMG=quay.io/sustainable_computing_io/kepler-operator:latest +kubectl apply -k config/samples/ +``` + +### Uninstall the operator +To delete the CRDs from the cluster: +```sh +make undeploy +``` + + +To run Kepler operator on a kind cluster [follow](https://github.com/sustainable-computing-io/kepler-operator#getting-started) \ No newline at end of file diff --git a/docs/installation/kepler-rpm.md b/docs/installation/kepler-rpm.md new file mode 100644 index 00000000..4dccabbf --- /dev/null +++ b/docs/installation/kepler-rpm.md @@ -0,0 +1,25 @@ +# Install Kepler as RPM +To install the kepler rpm [download](https://github.com/sustainable-computing-io/kepler/releases/) the latest stable version, unpack and install: + +```sh +sudo dnf localinstall kepler-[version.arch].rpm + +systemctl start kepler.service +``` + +Check status with + +```sh +systemctl status kepler.service + +journalctl -f | grep kepler +``` + +In order to do process-level energy accounting type: +```sh +mkdir -p /etc/kepler/kepler.config +echo -n true > /etc/kepler/kepler.config/ENABLE_PROCESS_METRICS +``` +The kepler service runs on default port 8888. + +Use your web browser to navigate to the machine IP on port 8888. \ No newline at end of file diff --git a/docs/installation/kepler.md b/docs/installation/kepler.md index 03065738..e5f08fc8 100644 --- a/docs/installation/kepler.md +++ b/docs/installation/kepler.md @@ -63,63 +63,6 @@ Login with the credentials mentioned above. You can skip the window where Grafan ![](../fig/grafana_dashboard.png) -### Deploy using Helm Chart - -The Kepler Helm Chart is available on [GitHub](https://github.com/sustainable-computing-io/kepler-helm-chart/tree/main) and [ArtifactHub](https://artifacthub.io/packages/helm/kepler/kepler) - -For Installation [Helm](https://helm.sh) must be installed to use the charts. -Please refer to Helm's [documentation](https://helm.sh/docs/) to get started. - -The chart is accessible using the following commands: - -Add the helm repo - -```bash -helm repo add kepler https://sustainable-computing-io.github.io/kepler-helm-chart -``` - -You can see the latest version by using the folllowing command: - -```bash -helm search repo kepler -``` - -If you would like to test and look at the manifest files before deploying you can run: - -```bash -helm install kepler kepler/kepler --namespace kepler --create-namespace --dry-run --devel -``` - -Then to install run the following: - -```bash -helm install kepler kepler/kepler --namespace kepler --create-namespace -``` - -You may want to override [values.yaml](https://github.com/sustainable-computing-io/kepler-helm-chart/blob/main/chart/kepler/values.yaml) file use the following command. - -```bash -helm install kepler kepler/kepler --values values.yaml --namespace kepler --create-namespace -``` - -The following table lists the configurable parameters for this chart and their default values. - -Parameter|Description| Default ----|---|--- -global.namespace| Kubernete namespace for kepler |kepler -image.repository|Repository for Kepler Image| quay.io/sustainable\_computing\_io/kepler -image.pullPolicy|Pull policy for Kepler|Always -image.tag|Image tag for Kepler Image |latest -serviceAccount.name|Service acccount name for Kepler|kepler-sa -service.type|Kepler service type|ClusterIP -service.port|Kepler service exposed port|9102 - -#### Uninstall Kepler -To uninstall this chart, use the following steps - -```bash -helm delete --purge kepler --tiller-namespace -``` ### Deploy from source code Follow the steps below to deploy the Kepler exporter as a Daemonset to run on all Nodes. The following deployment will also create a service listening on port `9102`. @@ -204,28 +147,3 @@ kubectl apply --server-side -f manifests/setup until kubectl get servicemonitors --all-namespaces ; do date; sleep 1; echo ""; done kubectl apply -f manifests/ ``` -## Install Kepler as RPM -To install the kepler rpm [download](https://github.com/sustainable-computing-io/kepler/releases/) the latest stable version, unpack and install: - -```sh -sudo dnf localinstall kepler-[version.arch].rpm - -systemctl start kepler.service -``` - -Check status with - -```sh -systemctl status kepler.service - -journalctl -f | grep kepler -``` - -In order to do process-level energy accounting type: -```sh -mkdir -p /etc/kepler/kepler.config -echo -n true > /etc/kepler/kepler.config/ENABLE_PROCESS_METRICS -``` -The kepler service runs on default port 8888. - -Use your web browser to navigate to the machine IP on port 8888. \ No newline at end of file diff --git a/docs/usage/deep_dive.md b/docs/usage/deep_dive.md new file mode 100644 index 00000000..b2493b86 --- /dev/null +++ b/docs/usage/deep_dive.md @@ -0,0 +1,25 @@ +# Kepler Deep Dive + +- [ ] Components and what they do +- [ ] What metrics are gathered on various systems + * [ ] BM + * [ ] VM + * [ ] Linux standalone +- [ ] Why these metric? +- [ ] How is the power consumption attribution done? +- [ ] Explain the [models](https://github.com/sustainable-computing-io/kepler-model-server/tree/main/tests/test_models). How the models are different and is there a right use case/scenario for when to apply a particular model over another? + * [ ] AbsComponentModelWeight + * [ ] AbsComponentPower + * [ ] AbsModelWeight + * [ ] AbsPower + * [ ] DynComponentModelWeight + * [ ] DynComponentPower + * [ ] XGBoost + +- [ ] Each model has three sub models BPFOnly, CgroupOnly, CounterOnly but we use only one of these models. Why is that? + + + + + + diff --git a/mkdocs.yml b/mkdocs.yml index b645aae6..7a3c3b53 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,6 +5,7 @@ theme: custom_dir: overrides features: - navigation.footer + highlightjs: true hljs_languages: - yaml @@ -18,13 +19,18 @@ nav: - 'design/power_estimation.md' - 'design/power_model.md' - 'design/metrics.md' + - 'design/ebpf_in_kepler.md' - Installation: - 'installation/kepler.md' + - 'installation/kepler-helm.md' + - 'installation/kepler-operator.md' + - 'installation/kepler-rpm.md' - Advanced: - 'usage/general_config.md' - 'usage/kepler_daemon.md' - 'usage/model_server.md' - 'usage/trouble_shooting.md' + - 'usage/deep_dive.md' - Hardware Engagement: - 'hardwareengagement/index.md' - Model Training: @@ -35,6 +41,10 @@ nav: - 'project/contributing.md' - 'project/support.md' +markdown_extensions: + - pymdownx.tasklist: + custom_checkbox: true + extra: version: v0.4 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..b16efe18 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +mkdocs +mkdocs-static-i18n +mkdocs-material \ No newline at end of file