Kubernetes deployment instructions updates (#50)

* update instructions for deploying prometheus on k8s

* add explorer k8s instruction

* add ruleset upgrade instructions

* update alert manager config

Author: laulauland

src/pages/deploying-alertmanager/_meta.json

@@ -1,3 +1,4 @@
 {
 	"docker": "Docker",
+	"kubernetes": "Kubernetes"
 }

src/pages/deploying-alertmanager/docker.mdx

@@ -4,6 +4,7 @@ short: Docker
 ---
 
 import { Steps } from "nextra/components";
+import CreateSlackApplication from "@/snippets/create-slack-application.mdx"
 
 # Deploying Alertmanager on Docker 
 
@@ -17,7 +18,7 @@ Alertmanager is available as a Docker image from the official Prometheus organiz
 
 Make sure you have Prometheus running in the environment you're hoping to connect the Alertmanager to. See [Deploying Prometheus to Docker](deploying-prometheus/docker).
 
-### Autometrics-instrumented application with defined SLOs
+### Autometrics-instrumented application with SLOs
 
 Autometrics enables you to set up smarter alerts using the Service Level Objectives (SLO) approach. You can read more about SLOs in Autometrics [here](/slo) and follow the guides for SLO-instrumentation under each supported language:
 
@@ -34,11 +35,7 @@ In the following guide we'll deploy a basic Alertmanager instance configured to
 
 ### Create a Slack application
 
-First, we need to create a Slack application that will be used to send notifications to Slack. You can create a new Slack application [here](https://api.slack.com/apps). Make sure to install it to the workspace you want to send notifications to.
-
-Once you've created and installed the application, you'll need to get the bot token that will be used to send notifications. You can find it under the `OAuth & Permissions` tab in the application settings.
-
-It will look something like this: `xoxb-*****`.
+<CreateSlackApplication />
 
 ### Create a configuration file for Alertmanager
 
@@ -98,4 +95,4 @@ alerting:
             - "alertmanager:9093" # or the host address of the Alertmanager instance
 ```
 
-</Steps>
+</Steps>

src/pages/deploying-alertmanager/kubernetes.mdx

@@ -0,0 +1,52 @@
+---
+title: Deploying Alertmanager in Kubernetes
+short: Kubernetes
+---
+
+import { Steps, Tabs, Tab } from "nextra/components"
+import CreateSlackApplication from "@/snippets/create-slack-application.mdx"
+
+# Deploying Alertmanager in Kubernetes
+
+Alertmanager is a utility service deployed alongside Prometheus to help route, group, and prioritize alerts. Alertmanager does not trigger alerts - alerting *rules* are set in Prometheus itself, Alertmanager only takes care of the lifecycle of the alert *after* it has been triggered (you can think of it as Zapier but for Prometheus alerts).
+
+Alertmanager is part of the Prometheus stack, the most popular open-source monitoring solution for Kubernetes, therefore deploying and configuring it is pretty straightforward.
+
+## Requirements
+- Kubernetes cluster running with `kubectl` configured to access it
+- [Helm](https://helm.sh/docs/intro/install) installed
+
+### Autometrics-instrumented application with SLOs
+
+Autometrics enables you to set up smarter alerts using the Service Level Objectives (SLO) approach. You can read more about SLOs in Autometrics [here](/slo) and follow the guides for SLO-instrumentation under each supported language:
+
+- [Rust](/rust/adding-alerts-and-slos)
+- [TypeScript](/typescript/adding-alerts-and-slos)
+- [Go](/go/adding-alerts-and-slos)
+- [Python](/python/adding-alerts-and-slos)
+
+## Instructions
+
+<Steps>
+
+### Create a `monitoring` namespace
+
+It is a good practice to keep all monitoring resources in a separate namespace. To create a namespace run the following command (if you already have a namespace for monitoring tools, you can skip this step):
+
+```bash
+kubectl create namespace monitoring
+```
+
+### Deploy Alertmanager to Kubernetes
+
+Run the following command to install Alertmanager using the Helm chart. If you've already installed Prometheus using Helm, you can skip this step.
+
+```bash
+helm install prometheus prometheus-community/kube-prometheus-stack --namespace monitoring
+```
+
+This will install Alertmanager in your cluster along with Prometheus, Node Exporter, and a few other components. As these components are installed together they are configured to work with each other out of the box.
+
+</Steps>
+
+You can now configure your Alertmanager to group, organize, and send alerts to whichever channel you're using for incident response. See [Alertmanager documentation](https://prometheus.io/docs/alerting/latest/configuration/) for details.

src/pages/deploying-explorer/_meta.json

@@ -1,5 +1,6 @@
 {
 	"docker": "Docker",
+	"kubernetes": "Kubernetes",
 	"northflank": "Northflank",
 	"railway": "Railway"
 }

src/pages/deploying-explorer/kubernetes.mdx

@@ -0,0 +1,89 @@
+---
+title: Deploying Explorer in Kubernetes
+short: Kubernetes
+---
+
+import { Steps, Tabs, Tab } from "nextra/components"
+
+# Deploying Explorer in Kubernetes
+
+Explorer can be deployed in Kubernetes using the Docker image of the `am` CLI tool.
+
+#### Requirements
+- Kubernetes cluster running with `kubectl` configured to access it
+
+<Steps>
+
+### Create a `monitoring` namespace
+
+It is a good practice to keep all monitoring resources in a separate namespace. To create a namespace run the following command:
+
+```bash
+kubectl create namespace monitoring
+```
+
+(If you already have a namespace for monitoring, you can skip this step)
+
+### Create a deployment and service configuration
+
+In order to deploy Explorer, we need it to successfully connect to Prometheus and be made accessible from outside the cluster. To do that we will create a deployment and a service configuration.
+
+As the configuration is quite simple we keep it in a single file, but it is also possible to split it into two files.
+
+Create a file named `explorer.yaml` with the following content:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: explorer
+  namespace: monitoring
+  labels:
+    app: explorer
+spec:
+  selector:
+    matchLabels:
+      app: explorer
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        app: explorer
+    spec:
+      containers:
+      - name: explorer
+        image: autometrics/am-proxy:latest
+        imagePullPolicy: IfNotPresent
+        env:
+        - name: PROMETHEUS_URL
+          value: http://<prometheus_service_name>.<namespace>.svc.cluster.local
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: explorer
+  namespace: monitoring
+spec:
+  selector:
+    app: explorer
+  type: LoadBalancer
+  ports:
+    - port: 6789
+      targetPort: 6789 # Explorer default port
+```
+
+Note: the `LoadBalancer` configuration will vary depending on the Kubernetes provider and will need to be adapted accordingly. The above configuration is for a Kubernetes cluster running locally with [minikube](https://minikube.sigs.k8s.io/docs/).
+
+### Apply the configuration
+
+To apply the configuration run the following command:
+
+```bash
+kubectl apply -f explorer.yaml
+```
+
+### Verify the deployment
+
+To verify that the deployment was successful, navigate to the URL of the service. If the deployment was successful, you should see the Explorer UI.
+
+</Steps>

src/pages/deploying-prometheus/kubernetes.mdx

@@ -2,16 +2,51 @@
 title: Deploying Prometheus in Kubernetes
 short: Kubernetes
 ---
+
+import { Steps, Tabs, Tab } from "nextra/components"
+
 # Deploying Prometheus in Kubernetes
 
+Prometheus is the most popular open-source monitoring solution for Kubernetes, therefore deploying and configuring it is pretty straightforward.
+
 Prometheus supports service discovery, so it can automatically find Kubernetes
 pods to scrape.
 
-If you have Prometheus installed using the [helm
-chart](https://github.com/prometheus-community/helm-charts), service discovery
-should be enabled by default.
+## Requirements
+
+- Kubernetes cluster running with `kubectl` configured to access it
+- Make sure you have [Helm](https://helm.sh/docs/intro/install) installed
+
+
+## Instructions
+
+<Steps>
+
+### Create a `monitoring` namespace
+
+It is a good practice to keep all monitoring resources in a separate namespace.
+
+```bash
+kubectl create namespace monitoring
+```
+
+### Deploy Prometheus to Kubernetes
+
+
+Run the following command to install Prometheus using the Helm chart:
+
+```bash
+helm install prometheus prometheus-community/kube-prometheus-stack --namespace monitoring
+```
+
+This will install Prometheus in your cluster along with Alertmanager, Node Exporter, and a few other components.
+
+
+### Make Autometrics discoverable
 
-Add the following annotations to your app's deployment:
+If you have installed Prometheus using the [helm chart](https://github.com/prometheus-community/helm-charts), service discovery should be enabled by default.
+
+Service discovery uses Kubernetes labels to tell Prometheus which ports to look for. In order to make sure that your application metrics are available add the following annotations to your app's deployment:
 
 ```yaml filename="deployment.yaml"
 apiVersion: apps/v1
@@ -22,5 +57,52 @@ spec:
       annotations:
         prometheus.io/scrape: "true"
         prometheus.io/path: "/metrics"
-        prometheus.io/port: "9091"
+        prometheus.io/port: "9464" # this can be different depending on which library you have used for instrumentation
+```
+
+### (Optional) Add Autometrics ruleset to Prometheus
+
+If you want to make use of the SLO alerting features in Autometrics, you need to add the Autometrics alerting rules to your Prometheus instance.
+
+You can find the ruleset in the [Autometrics repository](https://github.com/autometrics-dev/autometrics-shared/blob/main/autometrics.rules.yml).
+
+#### Save the ruleset to a file
+
+```bash
+curl https://raw.githubusercontent.com/autometrics-dev/autometrics-shared/main/autometrics.rules.yml > autometrics.rules.yml
+```
+
+#### Create a ConfigMap from the ruleset
+
+```bash
+kubectl create configmap autometrics-rules --from-file=autometrics.rules.yml --namespace monitoring
 ```
+
+#### Create a `values.yaml` file for the Prometheus Helm chart
+
+The `values.yaml` file is used to add extra configuration to the Prometheus Helm chart. In this case we will mount the extra configuration as a ConfigMap and modify Prometheus configuration to include the Autometrics ruleset.
+
+```yaml filename="values.yaml"
+server:
+  extraConfigmapMounts:
+    - name: autometrics-rules
+      mountPath: /autometrics-alerts/
+      configMap: autometrics-rules
+      readOnly: true
+serverFiles:
+  prometheus.yml:
+    rule_files:
+      - /etc/config/recording_rules.yml # leave whichever rules you have already
+      - /etc/config/alerting_rules.yml #
+      - /autometrics-alerts/autometrics.rules.yml # <- add the autometrics ruleset here
+```
+
+#### Upgrade Prometheus using Helm
+
+Upgrade the Prometheus installation using the `helm upgrade` command, passing in the `values.yaml` file.
+
+```bash
+helm upgrade prometheus prometheus-community/kube-prometheus-stack --namespace monitoring -f values.yaml
+```
+
+</Steps>

src/snippets/create-slack-application.mdx

@@ -0,0 +1,5 @@
+First, we need to create a Slack application that will be used to send notifications to Slack. You can create a new Slack application [here](https://api.slack.com/apps). Make sure to install it to the workspace you want to send notifications to.
+
+Once you've created and installed the application, you'll need to get the bot token that will be used to send notifications. You can find it under the `OAuth & Permissions` tab in the application settings.
+
+It will look something like this: `xoxb-*****`.