Docs: document editing cortex/loki recording rules, namespaces and groups (#38547)

* document recording rule creation

* namespace/group editing docs

* explain namespaces & groups

* Jita's suggestions

docs/sources/alerting/unified-alerting/alerting-rules/_index.md

@@ -9,6 +9,8 @@ weight = 130
 One or more queries and/or expressions, a condition, the frequency of evaluation, and the (optional) duration that a condition must be met before creating an alert. Alerting rules are how you express the criteria for creating an alert. Queries and expressions select and can operate on the data you wish to alert on. A condition sets the threshold that an alert must meet or exceed to create an alert. The interval specifies how frequently the rule should be evaluated. The duration, when configured, sets a period that a condition must be met or exceeded before an alert is created. Alerting rules also can contain settings for what to do when your query does not return any data, or there is an error attempting to execute the query.
 
 - [Create Cortex or Loki managed alert rule]({{< relref "./create-cortex-loki-managed-rule.md" >}})
+- [Create Cortex or Loki managed recording rule]({{< relref "./create-cortex-loki-managed-recording-rule.md" >}})
+- [Edit Cortex or Loki rule groups and namespaces]({{< relref "./edit-cortex-loki-group-namespace.md" >}})
 - [Create Grafana managed alert rule]({{< relref "./create-grafana-managed-rule.md" >}})
 - [State and Health of alerting rules]({{< relref "./state-and-health.md" >}})
 - [View existing alert rules and their current state]({{< relref "./rule-list.md" >}})

docs/sources/alerting/unified-alerting/alerting-rules/create-cortex-loki-managed-recording-rule.md

@@ -0,0 +1,56 @@
++++
+title = "Create Cortex or Loki managed recording rule"
+description = "Create Cortex or Loki managed recording rule"
+keywords = ["grafana", "alerting", "guide", "rules", "recording rules", "create"]
+weight = 400
++++
+
+# Create a Cortex or Loki managed recording rule
+
+You can create and manage recording rules for an external Cortex or Loki instance. Recording rules calculate frequently needed expressions or computationally expensive expressions in advance and save the result as a new set of time series. Querying this new time series is faster, especially for dashboards since they query the same expression every time the dashboards refresh. 
+
+For both Cortex and Loki data sources to work with Grafana 8.0 alerting, enable the ruler API by configuring their respective services. The `local` rule storage type (default for Loki data source), only supports viewing of rules. If you want to edit rules, then configure one of the other rule storage types.
+
+When configuring a Grafana Prometheus data source to point to Cortex, use the legacy /api/prom prefix, not /prometheus. Only single-binary mode is currently supported, provide a separate URL for the ruler API.
+
+## Add a Cortex or Loki managed recording rule
+
+1. Hover your cursor over the Alerting (bell) icon.
+1. Click **New alert rule**.
+1. Click on the **Alert type** drop down and select **Cortex / Loki managed recording rule**.
+1. Enter the recording rule details using instructions in the [Recording rule fields](#recording-rule-fields) section.
+1. Click **Save** in the upper right corner to save the rule.
+
+## Edit a Cortex or Loki managed recording rule
+
+1. Hover your cursor over the Alerting (bell) icon in the side menu.
+1. Expand an existing recording rule in the **Cortex / Loki** section and click **Edit**.
+1. Update the recording rule details using instructions in the [Recording rule fields](#recording-rule-fields) section.
+1. Click **Save and exit** to save and exit rule editing.
+
+## Recording rule fields
+
+This section describes the fields you fill out to create a recording rule.
+
+### Rule type
+
+- **Rule name -** Enter a descriptive name. The name will get displayed in the alert rule list. It will also get added as an `alertname` label to every alert instance that is created from this rule. Recording rules names must be valid [metric names](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels). 
+- **Rule type -** Select **Cortex / Loki managed recording rule**.
+- **Data source -** Select a Prometheus or Loki data source. Only data sources that support Cortex ruler API are available.
+- **Namespace -** Select an existing rule namespace or click **Add new** and enter a name to create a new one. Namespaces can contain one or more rule groups and have only organizational purpose.
+- **Group -** Select an existing group within the selected namespace or click **Add new** to create a new group. Newly created rules are added to the end of this group. Rules within a group are run sequentially at a regular interval, with the same evaluation time.
+
+![Rule type section screenshot](/static/img/docs/alerting/unified/rule-edit-cortex-recording-rule-8-2.png 'Rule type section screenshot')
+
+### Query
+
+Enter a PromQL or LogQL expression. The result of this expression will get recorded as the value for the new metric.
+
+![Query section](/static/img/docs/alerting/unified/rule-edit-cortex-recording-rule-query-8-2.png 'Query section screenshot')
+
+
+### Details
+
+You can optionally define labels in the details section.
+
+![Details section](/static/img/docs/alerting/unified/rule-recording-rule-labels-8-2.png 'Details section screenshot')

docs/sources/alerting/unified-alerting/alerting-rules/create-cortex-loki-managed-rule.md

@@ -15,21 +15,21 @@ In order for both Cortex and Loki data sources to work with Grafana 8.0 alerting
 
 1. In the Grafana menu hover your cursor over the Alerting (bell) icon.
 1. To create a new alert rule, click **New alert rule**. To edit an existing rule, expand one of the rules in the **Cortex / Loki** section and click **Edit**.
-1. Click on the **Alert type** drop down and select **Cortex / Loki managed alert**.
+1. Click on the **Rule type** drop down and select **Cortex / Loki managed alert**.
 1. Fill out the rest of the fields. Descriptions are listed below in [Alert rule fields](#alert-rule-fields).
-1. When you have finished writing your rule, click **Save** in the upper right corner to save the rule,, or **Save and exit** to save and exit rule editing.
+1. When you have finished writing your rule, click **Save** in the upper right corner to save the rule, or **Save and exit** to save and exit rule editing.
 
 ## Alert rule fields
 
 This section describes the fields you fill out to create an alert.
 
-### Alert type
+### Rule type
 
-- **Alert name -** Enter a descriptive name. The name will be displayed in the alert rule list, as well as added as `alertname` label to every alert instance that is created from this rule.
+- **Rule name -** Enter a descriptive name. The name will be displayed in the alert rule list, as well as added as `alertname` label to every alert instance that is created from this rule.
-- **Alert type -** Select **Cortex / Loki managed alert**.
+- **Rule type -** Select **Cortex / Loki managed alert**.
 - **Data source -** Select a Prometheus or Loki data source. Only Prometheus data sources that support Cortex ruler API will be available.
-- **Namespace -** Select an existing rule namespace or click **Add new** to create a new one.
+- **Namespace -** Select an existing rule namespace or click **Add new** and enter a name to create a new one. Namespaces can contain one or more rule groups and have only organizational purpose.
-- **Group -** Select an existing group within the selected namespace or click **Add new** to create a new one. Newly created rules will be added to the end of the rule group.
+- **Group -** Select an existing group within the selected namespace or click **Add new** and enter a name to create a new one. Newly created rules will be added to the end of the rule group. Rules within a group are run sequentially at a regular interval, with the same evaluation time.
 
 ![Alert type section screenshot](/static/img/docs/alerting/unified/rule-edit-cortex-alert-type-8-0.png 'Alert type section screenshot')
 

docs/sources/alerting/unified-alerting/alerting-rules/edit-cortex-loki-namespace-group.md

@@ -0,0 +1,34 @@
++++
+title = "Edit Cortex or Loki rule groups and namespaces"
+description = "Edit Cortex or Loki rule groups and namespaces"
+keywords = ["grafana", "alerting", "guide", "group", "namespace", "cortex", "loki"]
+weight = 400
++++
+
+# Edit Cortex or Loki rule groups and namespaces
+
+You can rename Cortex or Loki rule namespaces and groups and edit group evaluation intervals.
+
+## Rename a namespace
+
+A namespace contains one or more groups. To rename a namespace, find a group that belongs to the namespace, then update the namespace.
+
+1. Hover your cursor over the Alerting (bell) icon in the side menu.
+1. Locate a group that belongs to the namespace you want to edit and click the edit (pen) icon.
+1. Enter a new name in the  **Namespace** field, then click **Save changes**.
+
+A new namespace is created and all groups are copied into this namespace from the old one. The old namespace is deleted.
+
+## Rename rule group or change rule group evaluation interval
+
+The rules within a group are run sequentially at a regular interval, the default interval is one (1) minute. You can modify this interval using the following instructions.
+
+1. Hover your cursor over the Alerting (bell) icon in the side menu.
+1. Find the group you want to edit and click the edit (pen) icon.
+1. Modify the **Rule group** and **Rule group evaluation interval** information as necessary.
+1. Click **Save changes**.
+
+If you remaned the group, a new group is created that has all the rules from the old group, and the old group deleted.
+
+![Group list](/static/img/docs/alerting/unified/rule-list-edit-cortex-loki-icon-8-2.png 'Rule group list screenshot')
+![Group edit modal](/static/img/docs/alerting/unified/rule-list-cortex-loki-edit-ns-group-8-2.png 'Rule group edit modal screenshot')