From 1f946fcf655023871b552619f0b0b17dca7aa996 Mon Sep 17 00:00:00 2001 From: Scott Trent Date: Tue, 1 Oct 2024 16:36:37 +0900 Subject: [PATCH] improve docs Signed-off-by: Scott Trent --- deployment/README.md | 32 +++++++++++++++++++++++++++++ doc/carbon.md | 12 +++++------ doc/openshift-installation.md | 5 +++-- samples/README.md | 38 +++++++++++++++++++++++++++++++++++ 4 files changed, 79 insertions(+), 8 deletions(-) create mode 100644 deployment/README.md create mode 100644 samples/README.md diff --git a/deployment/README.md b/deployment/README.md new file mode 100644 index 0000000..e664591 --- /dev/null +++ b/deployment/README.md @@ -0,0 +1,32 @@ +# Deployment files + +- `deploy.sh` + Deploy SusQL via a Helm chart. +- `kepler-check.yaml` + Used by `deploy.sh` to verify that Kepler is available. +- `kepler_dashboard.json` + A grafana dashboard. +- `local-cluster-config.yaml` + A yaml file used to deploy a local `kind` cluster. +- `prometheus.yaml` + Used by `deploy.sh` to deploy Prometheus in the cluster. +- `setup-local.sh` + Deploy SusQL on a local `kind` cluster. +- `susql-controller` + Helm Chart files used to deploy SusQL. + +## License + +Copyright 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. diff --git a/doc/carbon.md b/doc/carbon.md index c981f6f..0b86092 100644 --- a/doc/carbon.md +++ b/doc/carbon.md @@ -1,10 +1,10 @@ # Carbon Dioxide Emission Estimation -There are three primary CO2 emission calculation methods. +SusQL supports three primary CO2 emission calculation methods. "Out-of-the-box" SusQL reports an estimated CO2 emission value for all measured workloads using the `static` method: -The behavior of SusQL carbon calculation can be tuned by modyfing the `susql-config` `ConfigMap` in the same namespace that the SusQL operator is running in. +The behavior of SusQL carbon calculation can be tuned by modifying the `susql-config` `ConfigMap` in the same namespace that the SusQL operator is running in. A sample file is provided in `samples/susql-config.yaml`. ## `static` Method @@ -13,7 +13,7 @@ A sample file is provided in `samples/susql-config.yaml`. #### `static` Method `ConfigMap` Configurable Items - `CARBON-METHOD` - The `static` method is enabled when this is set to `static`. - - `CARBON-INTENSITY` - Carbon intensity value. A coefficient used to convert Joules to grams of CO2 per Joule. The unit definition is grams of CO2 per Joule. + - `CARBON-INTENSITY` - Carbon intensity value. A coefficient used to convert Joules to grams of CO2 per Joule. The unit definition is grams of CO2 per Joule. (If you have a custom grams per KWH carbon intensity value, you can multiple it times 0.0000002777777778 to get grams CO2 per Joule.) The default carbon intensity value is based on [US EPA](https://www.epa.gov/energy/greenhouse-gases-equivalencies-calculator-calculations-and-references) data. ## `simpledynamic` Method @@ -46,8 +46,8 @@ vi helm-chart/values.yaml ``` - Preparation: required software and permission - Ensure that `helm`, and `kubectl` (or `oc`) are installed - - Ensure that CLI user is logged in to the cluster with sufficient permissions -- Perform installation: (The example installes into namespace `gsf`. However, other namespaces may be used.) + - Ensure that the CLI user is logged in to the cluster with sufficient permissions +- Perform installation: (The example installs into namespace `gsf`. However, other namespaces may be used.) ``` cd carbon-aware-sdk helm upgrade --install --wait carbon-aware-sdk helm-chart --create-namespace gsf @@ -71,7 +71,7 @@ Apply the updated `susql-config.yaml` file: oc apply -f susql-config.yaml -n ``` You are now ready to install and use the SusQL operator. -If the SusQL Operator is already installed, then restart the control pod. +If the SusQL Operator is already installed, then restart the control pod to enable new `susql-config` values. #### `casdk` Method `ConfigMap` Configurable Items - `CARBON-METHOD` - The `casdk` method is enabled when this is set to `casdk`. diff --git a/doc/openshift-installation.md b/doc/openshift-installation.md index c0f250c..c0e2e75 100644 --- a/doc/openshift-installation.md +++ b/doc/openshift-installation.md @@ -1,6 +1,7 @@ -# SusQL Operator Installation via OpenShift Community Operator Catalog +# SusQL Operator Installation via OpenShift Red Hat Community Operator Catalog -Installation of the SusQL Operator on OpenShift is very easy. +Installation of the SusQL Operator on OpenShift using the OpenShift +Red Hat Community Opertor Catalog is very easy. ## Prerequisites diff --git a/samples/README.md b/samples/README.md new file mode 100644 index 0000000..cfe62b7 --- /dev/null +++ b/samples/README.md @@ -0,0 +1,38 @@ +# samples + +## scripts +- `start.sh` - deploy labels and start workloads +- `clean.sh` - cleanup labels and workloads +- `labelgroups.sh` - view LabelGroup information directly from LabelGroup CR +- `susqltop` - show top energy consuming groups +- `susqltopmon` - run susqltop periodically + +## configuration yaml file +- `susql-config.yaml` + +## labelgroup yaml files +- `labelgroups.yaml` + +## workload yaml files +- `energy-consumer-job.yaml` +- `gpu-consumer-job.yaml` +- `training-job-1.yaml` +- `training-job-2.yaml` +- `rhosaij.yaml` + + +## 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.