docs: Getting Started Improvements (#6046)

* docs: Getting Started Improvements

- Enable auth for multi-tenancy.
- Load the Cortex dashboards from the cortex-jsonnet repo for the getting-started tutorial. This should allow newcomers to get a better feel for what Cortex is doing.
- Configure recording rules, alerting rules, and alertmanager with cortextool.
- Add Grafana datasources to showcase multi-tenancy.

Signed-off-by: Charlie Le <[email protected]>

* Update tenant names to be generic

Signed-off-by: Charlie Le <[email protected]>

* Add Makefile to update dashboards

Signed-off-by: Charlie Le <[email protected]>

* Update datasource names in Grafana

Signed-off-by: Charlie Le <[email protected]>

* Use mixin.libsonnet instead of config.libsonnet

Signed-off-by: Friedrich Gonzalez <[email protected]>

---------

Signed-off-by: Charlie Le <[email protected]>
Signed-off-by: Friedrich Gonzalez <[email protected]>
Co-authored-by: Friedrich Gonzalez <[email protected]>

Author: CharlieTLe

docs/getting-started/.gitignore

@@ -0,0 +1 @@
+cortex-jsonnet

docs/getting-started/Makefile

@@ -0,0 +1,20 @@
+# Description: This Makefile is used to generate the dashboards, alerts, and rules files from the cortex-jsonnet repo.
+# It uses a customized mixin.libsonnet file to generate the files.
+
+all:
+	# Clone the cortex-jsonnet repository
+	git clone https://github.com/cortexproject/cortex-jsonnet --depth 1
+	# Show the diff between the mixin.libsonnet file and the cortex-jsonnet/cortex-mixin/mixin.libsonnet file
+	git --no-pager diff --no-index cortex-jsonnet/cortex-mixin/mixin.libsonnet mixin.libsonnet || true
+	# Copy the mixin.libsonnet file to the cortex-jsonnet directory
+	cp mixin.libsonnet cortex-jsonnet/cortex-mixin
+	# Run the build-mixin target
+	docker run -v $(shell pwd)/cortex-jsonnet:/workspace -w /workspace -it quay.io/cortexproject/cortex-jsonnet-build-image:fbe4726 make build-mixin
+	# Remove the dashboards, alerts.yaml, and rules.yaml files
+	rm -rf dashboards alerts.yaml rules.yaml
+	# Copy the files from the cortex-jsonnet/cortex-mixin/out directory to the current directory
+	mv cortex-jsonnet/cortex-mixin/out/* .
+
+clean:
+	# Remove the cortex-jsonnet directory
+	rm -rf cortex-jsonnet

docs/getting-started/_index.md

@@ -54,21 +54,50 @@ how this is configured.
 #### Configure SeaweedFS (S3)
 
 ```sh
-# Create a bucket in SeaweedFS
-curl --aws-sigv4 "aws:amz:local:seaweedfs" --user "any:any" -X PUT http://localhost:8333/cortex-bucket
+# Create buckets in SeaweedFS
+$ curl --aws-sigv4 "aws:amz:local:seaweedfs" --user "any:any" -X PUT http://localhost:8333/cortex-blocks
+$ curl --aws-sigv4 "aws:amz:local:seaweedfs" --user "any:any" -X PUT http://localhost:8333/cortex-ruler
+$ curl --aws-sigv4 "aws:amz:local:seaweedfs" --user "any:any" -X PUT http://localhost:8333/cortex-alertmanager
 ```
 
+#### Configure Cortex Recording Rules and Alerting Rules
+
+We can configure Cortex with [cortextool](https://github.com/cortexproject/cortex-tools/) to load [recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) and [alerting rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/). This is optional, but it is helpful to see how Cortex can be configured to manage rules and alerts.
+
+```sh
+# Configure recording rules for the cortex tenant (optional)
+$ docker run --network host -v $(pwd):/workspace -w /workspace quay.io/cortexproject/cortex-tools:v0.17.0 rules sync rules.yaml alerts.yaml --id cortex --address http://localhost:9009
+```
+
+#### Configure Cortex Alertmanager
+
+Cortex also comes with a multi-tenant Alertmanager. Let's load configuration for it to be able to view them in Grafana.
+
+```sh
+# Configure alertmanager for the cortex tenant
+$ docker run --network host -v $(pwd):/workspace -w /workspace quay.io/cortexproject/cortex-tools:v0.17.0 alertmanager load alertmanager-config.yaml --id cortex --address http://localhost:9009
+```
+
+You can configure Alertmanager in [Grafana as well](http://localhost:3000/alerting/notifications?search=&alertmanager=Cortex%20Alertmanager).
+
+There's a list of recording rules and alerts that should be visible in Grafana [here](http://localhost:3000/alerting/list?view=list&search=datasource:Cortex).
+
 #### Explore
 
-Grafana is configured to use Cortex as a data source. You can explore the data source in Grafana and query metrics. For example, this [explore](http://localhost:3000/explore?schemaVersion=1&panes=%7B%22au0%22:%7B%22datasource%22:%22P6693426190CB2316%22,%22queries%22:%5B%7B%22refId%22:%22A%22,%22expr%22:%22rate%28prometheus_remote_storage_samples_total%5B$__rate_interval%5D%29%22,%22range%22:true,%22instant%22:true,%22datasource%22:%7B%22type%22:%22prometheus%22,%22uid%22:%22P6693426190CB2316%22%7D,%22editorMode%22:%22builder%22,%22legendFormat%22:%22__auto%22,%22useBackend%22:false,%22disableTextWrap%22:false,%22fullMetaSearch%22:false,%22includeNullMetadata%22:false%7D%5D,%22range%22:%7B%22from%22:%22now-1h%22,%22to%22:%22now%22%7D%7D%7D&orgId=1) page is showing the rate of samples being sent to Cortex.
+Grafana is configured to use Cortex as a data source. Grafana is also configured with [Cortex Dashboards](http://localhost:3000/dashboards?tag=cortex) to understand the state of the Cortex instance. The dashboards are generated from the cortex-jsonnet repository. There is a Makefile in the repository that can be used to update the dashboards.
+
+```sh
+# Update the dashboards (optional)
+$ make
+```
 
 If everything is working correctly, then the metrics seen in Grafana were successfully sent from Prometheus to Cortex
 via `remote_write`!
 
 Other things to explore:
 
 - [Cortex](http://localhost:9009) - Administrative interface for Cortex
-   - Try shutting down the [ingester](http://localhost:9009/ingester/shutdown) and see how it affects metric ingestion.
+   - Try shutting down the ingester, and see how it affects metric ingestion.
    - Restart Cortex to bring the ingester back online, and see how Prometheus catches up.
    - Does it affect the querying of metrics in Grafana?
 - [Prometheus](http://localhost:9090) - Prometheus instance that is sending metrics to Cortex

docs/getting-started/alertmanager-config.yaml

@@ -0,0 +1,4 @@
+receivers:
+  - name: default-receiver
+route:
+  receiver: default-receiver