Skip to content

Commit

Permalink
docs: cleanup code blocks in bullets
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
@Billy99
Billy99 committed May 1, 2024
1 parent 1c7e305 commit 1da30b9
Show file tree
Hide file tree
Showing 3 changed files with 76 additions and 66 deletions.
133 changes: 69 additions & 64 deletions docs/installation/kepler.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,30 +8,32 @@ 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.

### Deploying Kepler on a local kind cluster

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
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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.
Expand All @@ -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="<deployment options>"
$ make build-manifest OPTS="<deployment options>"
```

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.
Expand Down Expand Up @@ -144,56 +147,58 @@ 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
resources. During the `until` loop, a response of `No resources found` is to be expected.
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/
2 changes: 1 addition & 1 deletion docs/installation/local-cluster.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down
7 changes: 6 additions & 1 deletion mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ theme:
primary: teal
name: material
logo: logo.png
language: en
custom_dir: overrides
features:
- navigation.footer
Expand All @@ -13,7 +14,7 @@ theme:
hljs_languages:
- yaml
- rust


docs_dir: './docs'
nav:
Expand Down Expand Up @@ -53,8 +54,12 @@ nav:
- 'project/support.md'

markdown_extensions:
- admonition
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.details
- pymdownx.superfences
- pymdownx.inlinehilite

extra:
version:
Expand Down

0 comments on commit 1da30b9

Please sign in to comment.