From 1da30b9b7ed7cbb39ecf8160efd7599a4a7c93a3 Mon Sep 17 00:00:00 2001 From: Billy McFall <22157057+Billy99@users.noreply.github.com> Date: Wed, 1 May 2024 15:33:36 -0400 Subject: [PATCH] docs: cleanup code blocks in bullets New to Kepler and was trying to follow the documentation to install Kepler for the first time. The https://sustainable-computing.io/installation/kepler/#deploy-the-prometheus-operator section has several issues. Primarily, some of the code blocks lead with `console` in the text, new lines are not honored, and the bulleted numbers don't increment. Fixes in this PR: * Added `pymdownx.superfences` to the `markdown_extensions:` section in `mkdocs.yml`. This fixed the newlines not honored in the indented code blocks and allowed the build to recognize the code block language identifier (`console`). * Added additional spaces to the code blocks in bulleted sections. This indents the code block to the same level as the text and allows the bulleted numbers to increment properly. * For code blocks, replaced `#` with a `$`. To me, `#` implies root access is required and and none of the documented commands require root access. I will change this globally in the docs if this change is acceptable. * Added `admonition` to the `markdown_extensions:` section in mkdocs.yml. When adding things like `Note:`, with `admonition`, is `!!! note` is used, it draws a box around the note. See https://squidfunk.github.io/mkdocs-material/reference/admonitions/. I can remove this, or update the docs globally depending on feedback. * Changed the default language to English. When building and running locally, it defaulted to Chinese. The problem is that only 3 of the pages are translated into Chinese so it looked like it was in English except for those 3 pages on the table of content. So took a while to figure out that the language for the whole website was set to Chinese and that there wasn't some other issue. Signed-off-by: Billy McFall <22157057+Billy99@users.noreply.github.com> --- docs/installation/kepler.md | 133 +++++++++++++++-------------- docs/installation/local-cluster.md | 2 +- mkdocs.yml | 7 +- 3 files changed, 76 insertions(+), 66 deletions(-) diff --git a/docs/installation/kepler.md b/docs/installation/kepler.md index a234e798..49851086 100644 --- a/docs/installation/kepler.md +++ b/docs/installation/kepler.md @@ -8,16 +8,18 @@ The following instructions work for both `Kind` and `Kubeadm` clusters. 1. You have a Kubernetes cluster running. - > **NOTE**: If you want to setup a kind cluster [follow this](./local-cluster.md#install-kind) + !!! note + If you want to setup a kind cluster [follow this](./local-cluster.md#install-kind) 2. The Monitoring stack, i.e. Prometheus with Grafana is set up. [Steps here](#deploy-the-prometheus-operator) - > **Note**: The default Grafana deployment can be accessed with the credentials `admin:admin`. You - can expose the web-based UI locally using: + !!! note + The default Grafana deployment can be accessed with the credentials `admin:admin`. You + can expose the web-based UI locally using: - ```console - # kubectl -n monitoring port-forward svc/grafana 3000 - ``` + ```console + $ kubectl -n monitoring port-forward svc/grafana 3000 + ``` If the perquisites are met, then please proceed to the following sections. @@ -25,13 +27,13 @@ If the perquisites are met, then please proceed to the following sections. To deploy Kepler on `kind`, we need to build it locally with specific flags. The full details of local builds are covered in the [section below](#build-manifests). To deploy on a local `kind` cluster, -you need to use the `PROMETHEUS_DEPLOY` flags. +you need to build using the `PROMETHEUS_DEPLOY` flag. ```console -# git clone --depth 1 git@github.com:sustainable-computing-io/kepler.git -# cd ./kepler -# make build-manifest OPTS="PROMETHEUS_DEPLOY" -# kubectl apply -f _output/generated-manifest/deployment.yaml +$ git clone --depth 1 git@github.com:sustainable-computing-io/kepler.git +$ cd ./kepler +$ make build-manifest OPTS="PROMETHEUS_DEPLOY" +$ kubectl apply -f _output/generated-manifest/deployment.yaml ``` ### Deploying Kepler on a baremetal Kubeadm cluster @@ -41,10 +43,10 @@ builds are covered in the [section below](#build-manifests). To deploy on a loca you need to use the `BM_DEPLOY` and `PROMETHEUS_DEPLOY` flags. ```console -# git clone --depth 1 git@github.com:sustainable-computing-io/kepler.git -# cd ./kepler -# make build-manifest OPTS="BM_DEPLOY PROMETHEUS_DEPLOY" -# kubectl apply -f _output/generated-manifest/deployment.yaml +$ git clone --depth 1 git@github.com:sustainable-computing-io/kepler.git +$ cd ./kepler +$ make build-manifest OPTS="BM_DEPLOY PROMETHEUS_DEPLOY" +$ kubectl apply -f _output/generated-manifest/deployment.yaml ``` ### Dashboard access @@ -57,13 +59,14 @@ using `admin:admin`. Skip the window where Grafana asks to input a new password. ![Grafana dashboard](../fig/grafana_dashboard.png) -> **Note**: To forward ports simply run: +!!! note + To forward ports simply run: - ```console - # kubectl port-forward --address localhost -n kepler service/kepler-exporter 9102:9102 & - # kubectl port-forward --address localhost -n monitoring service/prometheus-k8s 9090:9090 & - # kubectl port-forward --address localhost -n monitoring service/grafana 3000:3000 & - ``` + ```console + $ kubectl port-forward --address localhost -n kepler service/kepler-exporter 9102:9102 & + $ kubectl port-forward --address localhost -n monitoring service/prometheus-k8s 9090:9090 & + $ kubectl port-forward --address localhost -n monitoring service/grafana 3000:3000 & + ``` ### Build manifests @@ -74,15 +77,15 @@ kubelet node to the `redfish.csv` under the `kepler/manifests/k8s/config/exporte the file is as follows: ```csv -kubelet_node_name_1,redfish_username_1,redfish_password_2,https://redfish_ip_or_hostname_1 -kubelet_node_name_2,redfish_username_2,redfish_password_2,https://redfish_ip_or_hostname_2 +$ kubelet_node_name_1,redfish_username_1,redfish_password_2,https://redfish_ip_or_hostname_1 +$ kubelet_node_name_2,redfish_username_2,redfish_password_2,https://redfish_ip_or_hostname_2 ``` where, `kubelet_node_name` in the first column is the name of the node where the kubelet is running. You can get the name of the node by running the following command: ```console -# kubectl get nodes +$ kubectl get nodes ``` `redfish_username` and `redfish_password` in the second and third columns are the credentials to access the Redfish API from each node. @@ -91,19 +94,19 @@ While `https://redfish_ip_or_hostname` in the fourth column is the Redfish endpo Then, build the manifests file that suit your environment and deploy it with the following steps: ```console -# make build-manifest OPTS="" +$ make build-manifest OPTS="" ``` Minimum deployment: ```console -# make build-manifest +$ make build-manifest ``` Deployment with sidecar on openshift: ```console -# make build-manifest OPTS="ESTIMATOR_SIDECAR_DEPLOY OPENSHIFT_DEPLOY" +$ make build-manifest OPTS="ESTIMATOR_SIDECAR_DEPLOY OPENSHIFT_DEPLOY" ``` Manifests will be generated in `_output/generated-manifest/` by default. @@ -144,41 +147,42 @@ to install it. 1. Clone the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project to your local folder, and enter the `kube-prometheus` directory. - ```console - # git clone --depth 1 https://github.com/prometheus-operator/kube-prometheus; cd kube-prometheus; - ``` + ```console + $ git clone --depth 1 https://github.com/prometheus-operator/kube-prometheus; cd kube-prometheus; + ``` 2. This step is optional. You can later manually add the [Kepler Grafana dashboard][1] through the Grafana UI. To automatically do that, fetch the `kepler-exporter` Grafana dashboard and inject in the Prometheus Grafana deployment. - ```console - # KEPLER_EXPORTER_GRAFANA_DASHBOARD_JSON=`curl -fsSL https://raw.githubusercontent.com/sustainable-computing-io/kepler/main/grafana-dashboards/Kepler-Exporter.json | sed '1 ! s/^/ /'` - # mkdir -p grafana-dashboards - # cat - > ./grafana-dashboards/kepler-exporter-configmap.yaml << EOF - apiVersion: v1 - data: - kepler-exporter.json: |- - $KEPLER_EXPORTER_GRAFANA_DASHBOARD_JSON - kind: ConfigMap - metadata: - labels: - app.kubernetes.io/component: grafana - app.kubernetes.io/name: grafana - app.kubernetes.io/part-of: kube-prometheus - app.kubernetes.io/version: 9.5.3 - name: grafana-dashboard-kepler-exporter - namespace: monitoring - EOF - ``` - - > **Note:** The next step uses [yq](https://github.com/mikefarah/yq), a YAML processor. - - ```console - # yq -i e '.items += [load("./grafana-dashboards/kepler-exporter-configmap.yaml")]' ./manifests/grafana-dashboardDefinitions.yaml - # yq -i e '.spec.template.spec.containers.0.volumeMounts += [ {"mountPath": "/grafana-dashboard-definitions/0/kepler-exporter", "name": "grafana-dashboard-kepler-exporter", "readOnly": false} ]' ./manifests/grafana-deployment.yaml - # yq -i e '.spec.template.spec.volumes += [ {"configMap": {"name": "grafana-dashboard-kepler-exporter"}, "name": "grafana-dashboard-kepler-exporter"} ]' ./manifests/grafana-deployment.yaml - ``` + ```console + $ KEPLER_EXPORTER_GRAFANA_DASHBOARD_JSON=`curl -fsSL https://raw.githubusercontent.com/sustainable-computing-io/kepler/main/grafana-dashboards/Kepler-Exporter.json | sed '1 ! s/^/ /'` + $ mkdir -p grafana-dashboards + $ cat - > ./grafana-dashboards/kepler-exporter-configmap.yaml << EOF + apiVersion: v1 + data: + kepler-exporter.json: |- + $KEPLER_EXPORTER_GRAFANA_DASHBOARD_JSON + kind: ConfigMap + metadata: + labels: + app.kubernetes.io/component: grafana + app.kubernetes.io/name: grafana + app.kubernetes.io/part-of: kube-prometheus + app.kubernetes.io/version: 9.5.3 + name: grafana-dashboard-kepler-exporter + namespace: monitoring + EOF + ``` + + !!! note + The next step uses [yq](https://github.com/mikefarah/yq), a YAML processor. + + ```console + $ yq -i e '.items += [load("./grafana-dashboards/kepler-exporter-configmap.yaml")]' ./manifests/grafana-dashboardDefinitions.yaml + $ yq -i e '.spec.template.spec.containers.0.volumeMounts += [ {"mountPath": "/grafana-dashboard-definitions/0/kepler-exporter", "name": "grafana-dashboard-kepler-exporter", "readOnly": false} ]' ./manifests/grafana-deployment.yaml + $ yq -i e '.spec.template.spec.volumes += [ {"configMap": {"name": "grafana-dashboard-kepler-exporter"}, "name": "grafana-dashboard-kepler-exporter"} ]' ./manifests/grafana-deployment.yaml + ``` 3. Finally, apply the objects in the `manifests` directory. This will create the `monitoring` namespace and CRDs, and then wait for them to be available before creating the remaining @@ -186,14 +190,15 @@ resources. During the `until` loop, a response of `No resources found` is to be This statement checks whether the resource API is created but doesn't expect the resources to be there. - ```console - # kubectl apply --server-side -f manifests/setup - # until kubectl get servicemonitors --all-namespaces ; do date; sleep 1; echo ""; done - # kubectl apply -f manifests/ - ``` + ```console + $ kubectl apply --server-side -f manifests/setup + $ until kubectl get servicemonitors --all-namespaces ; do date; sleep 1; echo ""; done + $ kubectl apply -f manifests/ + ``` - > **Note:** It takes a short time (in a Kind cluster), for all the pods and services to - reach a `running` state. + !!! note + It takes a short time (in a Kind cluster), for all the pods and services to + reach a `running` state. [1]:https://raw.githubusercontent.com/sustainable-computing-io/kepler/main/grafana-dashboards/Kepler-Exporter.json [2]:https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/ diff --git a/docs/installation/local-cluster.md b/docs/installation/local-cluster.md index 02790e94..c66fc21a 100644 --- a/docs/installation/local-cluster.md +++ b/docs/installation/local-cluster.md @@ -31,7 +31,7 @@ nodes: We can then spin up a cluster with either: ```console -# export $CLUSTER_NAME="my-cluster" # we can use the --name flag to override the name in our config +# export CLUSTER_NAME="my-cluster" # we can use the --name flag to override the name in our config # kind create cluster --name=$CLUSTER_NAME --config=./local-cluster-config.yaml ``` diff --git a/mkdocs.yml b/mkdocs.yml index 0594b106..dfef1276 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,7 @@ theme: primary: teal name: material logo: logo.png + language: en custom_dir: overrides features: - navigation.footer @@ -13,7 +14,7 @@ theme: hljs_languages: - yaml - rust - + docs_dir: './docs' nav: @@ -53,8 +54,12 @@ nav: - 'project/support.md' markdown_extensions: + - admonition - pymdownx.tasklist: custom_checkbox: true + - pymdownx.details + - pymdownx.superfences + - pymdownx.inlinehilite extra: version: