RHDEVDOCS-3419 - Document support for alertmanager routing CRD

Author: bburt-rh

_topic_maps/_topic_map.yml

@@ -2001,6 +2001,8 @@ Topics:
   File: configuring-the-monitoring-stack
 - Name: Enabling monitoring for user-defined projects
   File: enabling-monitoring-for-user-defined-projects
+- Name: Enabling alert routing for user-defined projects
+  File: enabling-alert-routing-for-user-defined-projects
 - Name: Managing metrics
   File: managing-metrics
 - Name: Managing metrics targets

modules/monitoring-creating-alert-routing-for-user-defined-projects.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * monitoring/managing-alerts.adoc
+
+:_content-type: PROCEDURE
+[id="creating-alert-routing-for-user-defined-projects_{context}"]
+= Creating alert routing for user-defined projects
+ 
+[IMPORTANT]
+====
+[subs="attributes+"]
+Alert routing for user-defined projects is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
+
+For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview[https://access.redhat.com/support/offerings/techpreview].
+====
+
+[role="_abstract"]
+If you are a non-administrator user who has been given the `alert-routing-edit` role, you can create or edit alert routing for user-defined projects. 
+
+.Prerequisites
+
+* A cluster administrator has enabled monitoring for user-defined projects.
+* A cluster administrator has enabled alert routing for user-defined projects.
+* You are logged in as a user that has the `alert-routing-edit` role for the project for which you want to create alert routing.
+* You have installed the OpenShift CLI (`oc`).
+
+.Procedure
+
+. Create a YAML file for alert routing. The example in this procedure uses a file called `example-app-alert-routing.yaml`.
+
+. Add an `AlertmanagerConfig` YAML definition to the file. For example:
++
+[source,yaml]
+----
+apiVersion: monitoring.coreos.com/v1alpha1
+kind: AlertmanagerConfig
+metadata:
+  name: example-routing
+  namespace: ns1
+spec:
+  route:
+    receiver: default
+    groupBy: [job]
+  receivers:
+  - name: default
+    webhookConfigs:
+    - url: https://example.org/post
+----
++
+[NOTE]
+====
+For user-defined alerting rules, user-defined routing is scoped to the namespace in which the resource is defined.
+For example, a routing configuration defined in the `AlertmanagerConfig` object for namespace `ns1` only applies to `PrometheusRules` resources in the same namespace.
+====
++
+. Save the file.
+
+. Apply the resource to the cluster:
++
+[source,terminal]
+----
+$ oc apply -f example-app-alert-routing.yaml
+----
++
+The configuration is automatically applied to the Alertmanager pods.

modules/monitoring-disabling-alert-routing-for-user-defined-projects.adoc

@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * monitoring/enabling-alert-routing-for-user-defined-projects.adoc
+
+:_content-type: PROCEDURE
+[id="disabling-alert-routing-for-user-defined-projects_{context}"]
+= Disabling alert routing for user-defined projects
+
+[role="_abstract"]
+If you have enabled alert routing for user-defined projects, you can disable it. By doing so, you prevent users with the **alert-routing-edit** role from configuring alert routing for user-defined projects in Alertmanager.
+
+[NOTE]
+====
+Alert routing for user-defined projects is disabled by default. You do not need to disable it if the feature is not already enabled.
+====
+
+.Prerequisites
+
+* You have enabled monitoring for user-defined projects.
+* You have enabled alert routing for user-defined projects.
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have installed the OpenShift CLI (`oc`).
+
+.Procedure
+
+. Edit the `cluster-monitoring-config` `ConfigMap` object:
++
+[source,terminal]
+----
+$ oc -n openshift-monitoring edit configmap cluster-monitoring-config
+----
++
+. Change the value to `false` for `enableUserAlertmanagerConfig` under the `alertmanagerMain` key in `data/config.yaml`:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-monitoring-config
+  namespace: openshift-monitoring
+data:
+  config.yaml: |
+    enableUserWorkload: true
+    alertmanagerMain:
+      enableUserAlertmanagerConfig: false <1>
+----
+<1> When set to `false`, the `enableUserAlertmanagerConfig` parameter disables alert routing for user-defined projects in a cluster.
++
+. Save the file to apply the changes. Alert routing for user-defined projects is disabled automatically.

modules/monitoring-enabling-alert-routing-for-user-defined-projects.adoc

@@ -0,0 +1,44 @@
+// Module included in the following assemblies:
+//
+// * monitoring/enabling-alert-routing-for-user-defined-projects.adoc
+
+:_content-type: PROCEDURE
+[id="enabling-alert-routing-for-user-defined-projects_{context}"]
+= Enabling alert routing for user-defined projects
+
+[role="_abstract"]
+You can enable alert routing for user-defined projects. By doing so, you enable users with the **alert-routing-edit** role to configure alert routing and receivers for user-defined projects in Alertmanager.
+
+.Prerequisites
+
+* You have enabled monitoring for user-defined projects.
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have installed the OpenShift CLI (`oc`).
+
+.Procedure
+
+. Edit the `cluster-monitoring-config` `ConfigMap` object:
++
+[source,terminal]
+----
+$ oc -n openshift-monitoring edit configmap cluster-monitoring-config
+----
++
+. Add `enableUserAlertmanagerConfig: true` under the `alertmanagerMain` key in `data/config.yaml`:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-monitoring-config
+  namespace: openshift-monitoring
+data:
+  config.yaml: |
+    enableUserWorkload: true
+    alertmanagerMain:
+      enableUserAlertmanagerConfig: true <1>
+----
+<1> When set to `true`, the `enableUserAlertmanagerConfig` parameter enables alert routing for user-defined projects in a cluster.
++
+. Save the file to apply the changes. Alert routing for user-defined projects is enabled automatically.

modules/monitoring-granting-users-permission-to-configure-alert-routing-for-user-defined-projects.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * monitoring/enabling-alert-routing-for-user-defined-projects.adoc
+
+:_content-type: PROCEDURE
+[id="granting-users-permission-to-configure-alert-routing-for-user-defined-projects_{context}"]
+= Granting users permission to configure alert routing for user-defined projects
+
+[role="_abstract"]
+You can grant users permission to configure alert routing for user-defined projects.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* The user account that you are assigning the role to already exists.
+* You have installed the OpenShift CLI (`oc`).
+* You have enabled monitoring for user-defined projects.
+
+.Procedure
+
+* Assign the `alert-routing-edit` role to a user in the user-defined project:
++
+[source,terminal]
+----
+$ oc -n <namespace> adm policy add-role-to-user alert-routing-edit <user> <1>
+----
+<1> For `<namespace>`, substitute the namespace for the user-defined project, such as `ns1`. For `<user>`, substitute the username for the account to which you want to assign the role.

modules/monitoring-granting-users-permission-to-monitor-user-defined-projects.adoc

@@ -17,6 +17,10 @@ Cluster administrators can grant developers and other users permission to monito
 
 You can also grant users permission to configure the components that are responsible for monitoring user-defined projects:
 
-* The *user-workload-monitoring-config-edit* role in the `openshift-user-workload-monitoring` project enables you to edit the `user-workload-monitoring-config` `ConfigMap` object. With this role, you can edit the `ConfigMap` object to configure Prometheus, Prometheus Operator and Thanos Ruler for user-defined workload monitoring.
+* The *user-workload-monitoring-config-edit* role in the `openshift-user-workload-monitoring` project enables you to edit the `user-workload-monitoring-config` `ConfigMap` object. With this role, you can edit the `ConfigMap` object to configure Prometheus, Prometheus Operator, and Thanos Ruler for user-defined workload monitoring.
+
+You can also grant users permission to configure alert routing for user-defined projects:
+
+* The **alert-routing-edit** role grants a user permission to create, update, and delete `AlertmanagerConfig` custom resources for a project.
 
 This section provides details on how to assign these roles by using the {product-title} web console or the CLI.

modules/monitoring-understanding-alert-routing-for-user-defined-projects.adoc

@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//
+// * monitoring/enabling-alert-routing-for-user-defined-projects.adoc
+
+:_content-type: CONCEPT
+[id="understanding-alert-routing-for-user-defined-projects_{context}"]
+= Understanding alert routing for user-defined projects
+
+[role="_abstract"]
+As a cluster administrator, you can enable alert routing for user-defined projects. After doing so, you can allow users to configure alert routing for their user-defined projects. Users can then create and configure user-defined alert routing by creating or editing the `AlertmanagerConfig` objects.
+
+After a user has defined alert routing for a user-defined project, user-defined alerts are routed to the `alertmanager-main` pods in the `openshift-monitoring` namespace. 
+
+Note the following limitations and features of alert routing for user-defined projects:
+
+* For user-defined alerting rules, user-defined routing is scoped to the namespace in which the resource is defined.
+For example, a routing configuration in namespace `ns1` only applies to `PrometheusRules` resources in the same namespace.
+
+* The Cluster Monitoring Operator (CMO) does not deploy a second Alertmanager service dedicated to user-defined alerts.
+Cluster administrators continue to define the main Alertmanager configuration by using a custom secret or the {product-title} web console. 
+
+* When a namespace is excluded from user-defined monitoring, `AlertmanagerConfig` resources in the namespace cease to be part of the Alertmanager configuration.

monitoring/enabling-alert-routing-for-user-defined-projects.adoc

@@ -0,0 +1,36 @@
+:_content-type: ASSEMBLY
+[id="enabling-alert-routing-for-user-defined-projects"]
+= Enabling alert routing for user-defined projects
+include::modules/common-attributes.adoc[]
+:context: enabling-alert-routing-for-user-defined-projects
+
+toc::[]
+
+:FeatureName: Alert routing for user-defined projects 
+include::modules/technology-preview.adoc[leveloffset=+1]
+
+[role="_abstract"]
+In {product-title} {product-version}, a cluster administrator can enable alert routing for user-defined projects.
+
+//Overview of alert routing for user-defined projects
+include::modules/monitoring-understanding-alert-routing-for-user-defined-projects.adoc[leveloffset=+1]
+
+// Enabling alert routing for user-defined projects
+include::modules/monitoring-enabling-alert-routing-for-user-defined-projects.adoc[leveloffset=+1]
+
+// Granting users permission to configure alert routing for user-defined projects
+include::modules/monitoring-granting-users-permission-to-configure-alert-routing-for-user-defined-projects.adoc[leveloffset=+1]
+
+// Disabling alert routing for user-defined projects 
+include::modules/monitoring-disabling-alert-routing-for-user-defined-projects.adoc[leveloffset=+1]
+
+.Additional resources
+
+* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user defined projects]
+* xref:../monitoring/managing-alerts.adoc#managing-alerts[Managing alerts]
+
+== Next steps
+
+* xref:../monitoring/managing-alerts.adoc#creating-alert-routing-for-user-defined-projects_managing-alerts[Creating alert routing for user defined projects]
+
+

monitoring/enabling-monitoring-for-user-defined-projects.adoc

@@ -6,7 +6,7 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-In {product-title} {product-version}, you can enable monitoring for user-defined projects in addition to the default platform monitoring. You can now monitor your own projects in {product-title} without the need for an additional monitoring solution. Using this new feature centralizes monitoring for core platform components and user-defined projects.
+In {product-title} {product-version}, you can enable monitoring for user-defined projects in addition to the default platform monitoring. You can monitor your own projects in {product-title} without the need for an additional monitoring solution. Using this feature centralizes monitoring for core platform components and user-defined projects.
 
 [NOTE]
 ====
@@ -41,4 +41,4 @@ include::modules/monitoring-disabling-monitoring-for-user-defined-projects.adoc[
 
 == Next steps
 
-* xref:../monitoring/managing-metrics.adoc#managing-metrics[Managing metrics]
+* xref:../monitoring/enabling-alert-routing-for-user-defined-projects.adoc#enabling-alert-routing-for-user-defined-projects[Enabling alert routing for user defined projects]

monitoring/managing-alerts.adoc

@@ -57,6 +57,8 @@ include::modules/monitoring-expiring-silences.adoc[leveloffset=+2]
 // Sending notifications to external systems
 include::modules/monitoring-sending-notifications-to-external-systems.adoc[leveloffset=+1]
 include::modules/monitoring-configuring-alert-receivers.adoc[leveloffset=+2]
+// Creating alert routing for user-defined projects
+include::modules/monitoring-creating-alert-routing-for-user-defined-projects.adoc[leveloffset=+2]
 
 // Applying a custom Alertmanager configuration
 include::modules/monitoring-applying-custom-alertmanager-configuration.adoc[leveloffset=+1]