rework docs and ruler volumes (#317)

nschad · web-flow · commit a9df59bbb852 · 2022-02-07T19:43:43.000+01:00
* rework docs and ruler volume

Signed-off-by: nschad &lt;niclas.schad@gmail.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@
 * [CHANGE] undo querier store optimization #304
   * config.querier.query_ingesters_within: 13h -> 0s (default)
   * config.querier.query_store_after: 12h -> 0s (default)
+* [CHANGE] Change sidecar default values to match values in documentation #317
+* [CHANGE] Remove ruler.persistentVolume.subPath since it was never persistent to begin with #317
 * [ENHANCEMENT] Fix the indentation of memcached guide #309
 * [ENHANCEMENT] Added api endpoints for Grafana 8 unified alerting #291
 * [ENHANCEMENT] Add guide on how to configure alertmanager/ruler with configmap #313
diff --git a/README.md b/README.md
@@ -634,7 +634,6 @@ Kubernetes: `^1.19.0-0`
 | ruler.&ZeroWidthSpace;livenessProbe.&ZeroWidthSpace;httpGet.&ZeroWidthSpace;path | string | `"/ready"` |  |
 | ruler.&ZeroWidthSpace;livenessProbe.&ZeroWidthSpace;httpGet.&ZeroWidthSpace;port | string | `"http-metrics"` |  |
 | ruler.&ZeroWidthSpace;nodeSelector | object | `{}` |  |
-| ruler.&ZeroWidthSpace;persistentVolume.&ZeroWidthSpace;subPath | string | `nil` |  |
 | ruler.&ZeroWidthSpace;podAnnotations | object | `{"prometheus.io/port":"8080","prometheus.io/scrape":"true"}` | Pod Annotations |
 | ruler.&ZeroWidthSpace;podDisruptionBudget.&ZeroWidthSpace;maxUnavailable | int | `1` |  |
 | ruler.&ZeroWidthSpace;podLabels | object | `{}` | Pod Labels |
@@ -656,7 +655,7 @@ Kubernetes: `^1.19.0-0`
 | ruler.&ZeroWidthSpace;sidecar.&ZeroWidthSpace;defaultFolderName | string | `""` | The default folder name, it will create a subfolder under the `folder` and put rules in there instead |
 | ruler.&ZeroWidthSpace;sidecar.&ZeroWidthSpace;enableUniqueFilenames | bool | `false` | A value of true will produce unique filenames to avoid issues when duplicate data keys exist between ConfigMaps and/or Secrets within the same or multiple Namespaces. |
 | ruler.&ZeroWidthSpace;sidecar.&ZeroWidthSpace;enabled | bool | `false` | Enable sidecar that collect the configmaps with specified label and stores the included files them into the respective folders |
-| ruler.&ZeroWidthSpace;sidecar.&ZeroWidthSpace;folder | string | `"/tmp/rules"` | Folder where the files should be placed. |
+| ruler.&ZeroWidthSpace;sidecar.&ZeroWidthSpace;folder | string | `"/data/rules"` | Folder where the files should be placed. |
 | ruler.&ZeroWidthSpace;sidecar.&ZeroWidthSpace;folderAnnotation | string | `"k8s-sidecar-target-directory"` | The annotation the sidecar will look for in ConfigMaps and/or Secrets to override the destination folder for files. If the value is a relative path, it will be relative to FOLDER |
 | ruler.&ZeroWidthSpace;sidecar.&ZeroWidthSpace;image.&ZeroWidthSpace;repository | string | `"omegavveapon/kopf-k8s-sidecar"` |  |
 | ruler.&ZeroWidthSpace;sidecar.&ZeroWidthSpace;image.&ZeroWidthSpace;sha | string | `""` |  |
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -4,8 +4,10 @@ description: >-
   Cortex is a horizontally scalable, highly available, multi-tenant, long term Prometheus.
   The cortex-helm-chart helps the operator with deploying cortex on a Kubernetes cluster.
 twitter_username: CortexMetrics
-github_username:  cortexproject
+github_username: cortexproject
 
 # Build settings
 remote_theme: pmarsceill/just-the-docs
 # color_scheme: "dark"
+
+footer_content: "Copyright &copy; 2022 cortexproject. Distributed by an <a href=\"https://github.com/cortexproject/cortex-helm-chart/blob/master/LICENSE\">Apache License 2.0.</a>"
diff --git a/docs/development.md b/docs/development.md
@@ -0,0 +1,12 @@
+---
+layout: page
+title: Development
+nav_order: 3
+has_children: true
+permalink: /docs/development
+---
+# Development
+{: .no_toc }
+
+Tutorials on how to develop the chart locally
+{: .fs-6 .fw-300 }
diff --git a/docs/development/developing_the_docs.md b/docs/development/developing_the_docs.md
@@ -0,0 +1,30 @@
+---
+layout: page
+title: Working with the cortex-helm-chart docs
+parent: Development
+has_children: false
+has_toc: false
+---
+# Working with the cortex-helm-chart docs
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+# Setup
+
+The cortex-helm-chart docs uses [jekyll](https://jekyllrb.com/) with the [just-the-docs](https://github.com/pmarsceill/just-the-docs) theme. Unfortunately due to security concerns GitHub doesn't let us preview from pull requests or different branches. However GitHub created [this](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll) guide on how to test your changes locally.
+
+# Preview
+
+After installing ruby and bundle. Simply change into the `/docs` folder of the cortex-helm-chart and run:
+
+```
+bundle exec jekyll serve --incremental --livereload
+```
+
+For further options you can consult `bundle exec jekyll serve --help`
diff --git a/docs/guides.md b/docs/guides.md
@@ -1,7 +1,13 @@
 ---
 layout: page
 title: Guides
-nav_order: 3
+nav_order: 2
 has_children: true
+has_toc: true
 permalink: /docs/guides
----
+---
+# Guides
+{: .no_toc }
+
+Guides & Best-Practices on how to configure the cortex-helm-chart.
+{: .fs-6 .fw-300 }
diff --git a/docs/guides/configure_configmap.markdown b/docs/guides/configure_configmap.markdown
@@ -1,18 +1,28 @@
 ---
 layout: page
-title: Configure with configmap
+title: Configuring Cortex with configmap
 parent: Guides
-has_children: true
+has_children: false
 has_toc: false
 ---
-# Configuring using configmap
+# Configuring Cortex with configmap
+{: .no_toc }
 
-By default, cortex configuration is managed using a *Secret*. To use a *ConfigMap* instead, set **useConfigMap**:
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+# Configuring Cortex with configmap
+
+By default, cortex configuration is managed using a `Secret`. To use a `ConfigMap` instead, set **useConfigMap**:
 
 {% raw %}
 ```yaml
 useConfigMap: true
 ```
 {% endraw %}
 
-Note: if **useConfigMap** is enabled, sensitive values should be stored in separate secrets, then referenced in the config [using environment variables](https://cortexmetrics.io/docs/configuration/configuration-file/#use-environment-variables-in-the-configuration). Use *extraVolumes*, *extraVolumeMounts*, *extraEnvs*, and *extraArgs* to add environment variables from secrets.
+Note: if **useConfigMap** is enabled, sensitive values should be stored in separate secrets, then referenced in the config [using environment variables](https://cortexmetrics.io/docs/configuration/configuration-file/#use-environment-variables-in-the-configuration). Use `extraVolumes`, `extraVolumeMounts`, `extraEnvs`, and `extraArgs` to add environment variables from secrets.
diff --git a/docs/guides/configure_memberlist.markdown b/docs/guides/configure_memberlist.markdown
@@ -1,9 +1,19 @@
 ---
 layout: page
-title: Memberlist
+title: Configure memberlist
 parent: Guides
-has_children: true
+has_children: false
 has_toc: false
+---
+# Configure memberlist
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
 ---
 # Setup
 
diff --git a/docs/guides/configure_memcached.markdown b/docs/guides/configure_memcached.markdown
@@ -2,8 +2,18 @@
 layout: page
 title: Configure memcached
 parent: Guides
-has_children: true
+has_children: false
 has_toc: false
+---
+# Configuring memcached as the caching store
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
 ---
 # Configuring memcached as the caching store
 
diff --git a/docs/guides/configure_ruler_and_alertmanager_with_configmap.markdown b/docs/guides/configure_ruler_and_alertmanager_with_configmap.markdown
@@ -1,11 +1,11 @@
 ---
 layout: page
-title: Configure Ruler and Alertmanager with Configmap
+title: Configure Ruler and Alertmanager with configmap
 parent: Guides
 has_children: false
 has_toc: false
 ---
-# Configure Ruler and Alertmanager with Configmap
+# Configure Ruler and Alertmanager with configmap
 {: .no_toc }
 
 ## Table of contents
@@ -35,8 +35,9 @@ To provide the Ruler with the *rules* to alert on, we must create a ConfigMap wi
 
 **IMPORTANT** things to note:
 
-- This ruleset is ONLY for tenantfoo (We will explicitly map it to tenantfoo later)
-- The section under `tenantfoo.yaml` is validated and interpreted exactly as a [Prometheus rules configuration](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) would be. How you configure this is completely up to you.
+- This ruleset is ONLY for tenantfoo (We will explicitly map it to tenantfoo later).
+- The section under `tenantfoo.yaml` is validated and interpreted exactly as a [Prometheus alerting rules configuration](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) would be. How you configure this is completely up to you.
+- [Prometheus recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) are also configured here in the same way as alerting rules.
 
 ```yaml
 kind: ConfigMap
@@ -66,7 +67,7 @@ To provide the Alertmanager with the information needed to *route* notifications
 **IMPORTANT** things to note:
 
 - These routing rules are ONLY for tenantfoo. The Alertmanager takes the key under `data` (excluding `.yaml`) and uses it as the tenant name for that specific config.
-- The section under `tenantfoo.yaml` is validated and interpreted exactly as a [Prometheus alerting rules configuration](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) would be. How you configure this is completely up to you.
+- The section under `tenantfoo.yaml` is validated and interpreted exactly as a [Alertmanager configuration](hhttps://prometheus.io/docs/alerting/latest/configuration/#configuration-file) would be. How you configure this is completely up to you.
 
 ```yaml
 kind: ConfigMap
@@ -112,7 +113,7 @@ config:
   ruler_storage:
     backend: "local"
     local:
-      # where your mounted configmap data will be persistently stored
+      # where your mounted configmap data will be temporary stored
       directory: /data/rules
 
   alertmanager:
diff --git a/docs/guides/configure_rules_via_configmap.markdown b/docs/guides/configure_rules_via_configmap.markdown
@@ -2,8 +2,18 @@
 layout: page
 title: Configure rules via configmap
 parent: Guides
-has_children: true
+has_children: false
 has_toc: false
+---
+# Configure rules via configmap
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
 ---
 # Configure rules via configmap
 
diff --git a/docs/guides/configure_rules_via_sidecar.markdown b/docs/guides/configure_rules_via_sidecar.markdown
@@ -2,22 +2,31 @@
 layout: page
 title: Configure rules via sidecar
 parent: Guides
-has_children: true
+has_children: false
 has_toc: false
+---
+# Configure rules via sidecar
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
 ---
 # Rules and AlertManager configuration
 Cortex can be configured to use a sidecar container in the Ruler and AlertManager to dynamically discover rules and AlertManager config/templates that are declared as ConfigMaps to allow easy and extensible configuration that avoids having to store state in the Cortex system itself (via config service, etc).
 Put ConfigMaps into the specified namespace, and they are automatically detected and added as files to the Ruler and/or AlertManager containers, both of which are polling for changes on the filesystem and will make the new configurations go live dynamically.
 This feature is disabled by default. Here is a simple example:
 
-Please note that this is only supported with the **local** backend. Otherwise cortex will overwrite what the operator puts in the folder with what is in s3/gcs/azure/swift. Cortex does not 2-way sync the files. Also please be aware of the following:
+Please note that this is only supported with the **local** backend. Otherwise cortex will overwrite what the operator[^1] puts in the folder with what is in s3/gcs/azure/swift. Cortex does not 2-way sync the files. Also please be aware of the following:
 - local alertmanager config storage is read-only (cortex API is severely limited to read-only requests)
 - local alertmanager storage does not support state persistency (however your configurations are saved in etcd via kubernetes)
 - local ruler storage does not support RuleGroups
 - local ruler storage does not support namespaces
-```yaml
-backend: "local"
-```
+
+[^1]: Also referenced here as the sidecar. Effectively the sidecar is an image which is an kubernetes operator.
 
 ## Helm values config
 
@@ -35,43 +44,55 @@ alertmanager:
 And here are the related configuration values in AlertManager and Ruler:
 ```yaml
 config:
-  alertmanager:
-    data_dir: /data/
+  ruler:
+    enable_api: true
+    # already set-up temporary emptyDir volume. Cortex will parse rules from /data/rules
+    # and copy them here for prometheus rule evaluation
+    rule_path: /rules
 
-  alertmanager_storage:
+  ruler_storage:
     backend: "local"
     local:
-      path: "/data"
-  
-  ruler:
-    rule_path: /data/rules
+      # temporary volume of type emptyDir
+      directory: /data/rules
 
-  ruler_storage:
+  alertmanager:
+    enable_api: true
+    # temporary volume if not using stateful alertmanagers
+    data_dir: /data
+
+  alertmanager_storage:
     backend: "local"
     local:
-      directory: "/tmp/rules"
+      # temporary volume if not using stateful alertmanagers
+      path: /data
 ```
-In AlertManager, the data_dir and local storage directory should be the same.
-In the Ruler, there needs to be two separate volumes. One is read-only and serves as the location shared with the sidecar that contains all of the rules that were derived from configmaps (/tmp/rules). The other is read-write and used by the Ruler itself for its own management of rules, etc (/data).
-Example ConfigMap containing a rule:
+
+## Creating alerting/recording rules and alertmanager configs
+
+In AlertManager, the `data_dir` and local storage directory should be the same.
+In the Ruler, there need to be two separate volumes. One is used by Cortex for evaluating alerting and recording rules (/rules) and should be temporary. The other is used by the user (YOU) to temporarily store your alerting and recording rules (/data/rules).
+Example ConfigMap containing an alerting rule:
+
 {% raw %}
 ```yaml
 kind: ConfigMap
 metadata:
   annotations:
-    k8s-sidecar-target-directory: /tmp/rules/fake
+    # Override destination folder so we can save the config under /data/rules/<TENANT>/tenantfoo.yaml
+    k8s-sidecar-target-directory: /data/rules/tenantfoo
   labels:
     # Label cortex_rules must exist unless overridden by ruler.sidecar.label
     cortex_rules: "1"
   name: rules-cortex-9f99md47tc
   namespace: cortex-rules
 apiVersion: v1
 data:
-  fake.yaml: |-
+  tenantfoo.yaml: |-
     groups:
-      - name: fake-system-metrics
+      - name: tenantfoo-system-metrics
         rules:
-          - alert: HighCPUusage
+          - alert: HighCPUUsage
             expr: avg(100 - rate(node_cpu_seconds_total{instance=~"qag1ge1l.+",mode="idle"}[5m]) * 100) by (instance) > 100
             for: 3m
             labels:
@@ -82,18 +103,20 @@ data:
 
 ```
 {% endraw %}
+
 Example ConfigMap containing an alertmanager-config:
+
 ```yaml
 apiVersion: v1
 kind: ConfigMap
 metadata:
   annotations:
-    k8s-sidecar-target-directory: /data/fake
+    k8s-sidecar-target-directory: /data/tenantfoo
   labels:
     cortex_alertmanager: "1"
   name: alertmanager-example-config
 data:
-  fake.yaml: |-
+  tenantfoo.yaml: |-
     global:
       resolve_timeout: 5m
       http_config: {}
diff --git a/docs/guides/getting_started_with_block_storage.markdown b/docs/guides/getting_started_with_block_storage.markdown
@@ -2,8 +2,19 @@
 layout: page
 title: Getting started with block storage
 parent: Guides
-has_children: true
+has_children: false
 has_toc: false
+nav_order: 1
+---
+# Getting started with block storage
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
 ---
 # Getting Started
 
diff --git a/docs/guides/upgrade-v1.markdown b/docs/guides/upgrade-v1.markdown
diff --git a/templates/ruler/ruler-dep.yaml b/templates/ruler/ruler-dep.yaml
diff --git a/values.yaml b/values.yaml
