Merge pull request #51335 from michaelryanmcneill/OSDOCS-4296

lpettyjo · web-flow · commit 551d7ca9d50d · 2022-10-11T11:06:13.000-04:00
OSDOCS-4296: Adding information on user-defined alerting
diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml
@@ -138,6 +138,8 @@ Topics:
       File: osd-accessing-monitoring-for-user-defined-projects
     - Name: Configuring the monitoring stack
       File: osd-configuring-the-monitoring-stack
+    - Name: Enabling alert routing for user-defined projects
+      File: osd-enabling-alert-routing-for-user-defined-projects
     - Name: Managing metrics
       File: osd-managing-metrics
     - Name: Managing alerts
diff --git a/_topic_maps/_topic_map_rosa.yml b/_topic_maps/_topic_map_rosa.yml
@@ -230,6 +230,8 @@ Topics:
     File: rosa-accessing-monitoring-for-user-defined-projects
   - Name: Configuring the monitoring stack
     File: rosa-configuring-the-monitoring-stack
+  - Name: Enabling alert routing for user-defined projects
+    File: rosa-enabling-alert-routing-for-user-defined-projects
   - Name: Managing metrics
     File: rosa-managing-metrics
   - Name: Managing alerts
diff --git a/modules/monitoring-applying-a-custom-configuration-to-alertmanager-for-user-defined-alert-routing.adoc b/modules/monitoring-applying-a-custom-configuration-to-alertmanager-for-user-defined-alert-routing.adoc
@@ -1,6 +1,9 @@
 // Module included in the following assemblies:
 //
 // * monitoring/managing-alerts.adoc
+// * monitoring/osd-managing-alerts.adoc
+// * osd_cluster_admin/osd_monitoring/osd-managing-alerts.adoc
+// * rosa_cluster_admin/rosa_monitoring/rosa-managing-alerts.adoc
 
 :_content-type: PROCEDURE
 [id="applying-a-custom-configuration-to-alertmanager-for-user-defined-alert-routing_{context}"]
@@ -10,7 +13,12 @@ If you have enabled a separate instance of Alertmanager dedicated to user-define
 
 .Prerequisites
 
+ifdef::openshift-rosa,openshift-dedicated[]
+* You have access to the cluster as a user with the `cluster-admin` or `dedicated-admin` role.
+endif::[]
+ifndef::openshift-rosa,openshift-dedicated[]
 * You have access to the cluster as a user with the `cluster-admin` role.
+endif::[]
 
 .Procedure
 
diff --git a/modules/monitoring-enabling-a-separate-alertmanager-instance-for-user-defined-alert-routing.adoc b/modules/monitoring-enabling-a-separate-alertmanager-instance-for-user-defined-alert-routing.adoc
@@ -1,17 +1,30 @@
 // Module included in the following assemblies:
 //
 // * monitoring/enabling-alert-routing-for-user-defined-projects.adoc
+// * monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc
+// * osd_cluster_admin/osd_monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc
+// * rosa_cluster_admin/rosa_monitoring/rosa-enabling-alert-routing-for-user-defined-projects.adoc
 
 :_content-type: PROCEDURE
 [id="enabling-a-separate-alertmanager-instance-for-user-defined-alert-routing_{context}"]
 = Enabling a separate Alertmanager instance for user-defined alert routing
 
+ifndef::openshift-rosa,openshift-dedicated[]
 In some clusters, you might want to deploy a dedicated Alertmanager instance for user-defined projects, which can help reduce the load on the default platform Alertmanager instance and can better separate user-defined alerts from default platform alerts.
-In these cases, you can optionally enable a separate instance of Alertmanager to send alerts only for user-defined projects.
+endif::[]
+ifdef::openshift-rosa,openshift-dedicated[]
+In {product-title}, you may want to deploy a dedicated Alertmanager instance for user-defined projects, which provides user-defined alerts separate from default platform alerts.
+endif::[]
+In these cases, you can optionally enable a separate instance of Alertmanager to send alerts for user-defined projects only.
 
 .Prerequisites
 
+ifdef::openshift-rosa,openshift-dedicated[]
+* You have access to the cluster as a user with the `cluster-admin` or `dedicated-admin` role.
+endif::[]
+ifndef::openshift-rosa,openshift-dedicated[]
 * You have access to the cluster as a user with the `cluster-admin` role.
+endif::[]
 * You have enabled monitoring for user-defined projects in the `cluster-monitoring-config` config map for the `openshift-monitoring` namespace.
 * You have installed the OpenShift CLI (`oc`).
 
diff --git a/modules/monitoring-granting-users-permission-to-configure-alert-routing-for-user-defined-projects.adoc b/modules/monitoring-granting-users-permission-to-configure-alert-routing-for-user-defined-projects.adoc
@@ -1,6 +1,9 @@
 // Module included in the following assemblies:
 //
 // * monitoring/enabling-alert-routing-for-user-defined-projects.adoc
+// * monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc
+// * osd_cluster_admin/osd_monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc
+// * rosa_cluster_admin/rosa_monitoring/rosa-enabling-alert-routing-for-user-defined-projects.adoc
 
 :_content-type: PROCEDURE
 [id="granting-users-permission-to-configure-alert-routing-for-user-defined-projects_{context}"]
@@ -11,7 +14,12 @@ You can grant users permission to configure alert routing for user-defined proje
 
 .Prerequisites
 
+ifdef::openshift-rosa,openshift-dedicated[]
+* You have access to the cluster as a user with the `cluster-admin` or `dedicated-admin` role.
+endif::[]
+ifndef::openshift-rosa,openshift-dedicated[]
 * You have access to the cluster as a user with the `cluster-admin` role.
+endif::[]
 * 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.
diff --git a/modules/monitoring-listing-alerting-rules-for-all-projects-in-a-single-view.adoc b/modules/monitoring-listing-alerting-rules-for-all-projects-in-a-single-view.adoc
@@ -1,6 +1,9 @@
 // Module included in the following assemblies:
 //
 // * monitoring/managing-alerts.adoc
+// * monitoring/osd-managing-alerts.adoc
+// * osd_cluster_admin/osd_monitoring/osd-managing-alerts.adoc
+// * rosa_cluster_admin/rosa_monitoring/rosa-managing-alerts.adoc
 
 :_content-type: PROCEDURE
 [id="listing-alerting-rules-for-all-projects-in-a-single-view_{context}"]
@@ -10,7 +13,12 @@ As a cluster administrator, you can list alerting rules for core {product-title}
 
 .Prerequisites
 
+ifdef::openshift-rosa,openshift-dedicated[]
+* You have access to the cluster as a user with the `cluster-admin` or `dedicated-admin` role.
+endif::[]
+ifndef::openshift-rosa,openshift-dedicated[]
 * You have access to the cluster as a user with the `cluster-admin` role.
+endif::[]
 * You have installed the OpenShift CLI (`oc`).
 
 .Procedure
diff --git a/modules/monitoring-managing-alerting-rules-for-user-defined-projects.adoc b/modules/monitoring-managing-alerting-rules-for-user-defined-projects.adoc
@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
 // * monitoring/managing-alerts.adoc
+//
 
 :_content-type: CONCEPT
 [id="managing-alerting-rules-for-user-defined-projects_{context}"]
@@ -10,6 +11,13 @@
 
 In {product-title} {product-version}, you can create, view, edit, and remove alerting rules in user-defined projects.
 
+ifdef::openshift-rosa,openshift-dedicated[]
+[IMPORTANT]
+====
+Managing alerting rules for user-defined projects is only available in {product-title} version 4.11 and up. 
+====
+endif::[]
+
 .Alerting rule considerations
 
 * The default alerting rules are used specifically for the {product-title} cluster.
diff --git a/modules/monitoring-understanding-alert-routing-for-user-defined-projects.adoc b/modules/monitoring-understanding-alert-routing-for-user-defined-projects.adoc
@@ -19,11 +19,12 @@ After a user has defined alert routing for a user-defined project, user-defined
 
 * To the `alertmanager-user-workload` pods in the `openshift-user-workload-monitoring` namespace if you have enabled a separate instance of Alertmanager for user-defined projects. 
 
-Note the following limitations and features of alert routing for user-defined projects:
+[NOTE]
+====
+The following are limitations 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.
 
-*  If the user-defined Alertmanager instance is enabled, cluster administrators can also define the main configuration of the user-defined Alertmanager instance.
-
 * When a namespace is excluded from user-defined monitoring, `AlertmanagerConfig` resources in the namespace cease to be part of the Alertmanager configuration.
+====
diff --git a/modules/osd-monitoring-understanding-alert-routing-for-user-defined-projects.adoc b/modules/osd-monitoring-understanding-alert-routing-for-user-defined-projects.adoc
@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc
+// * osd_cluster_admin/osd_monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc
+// * rosa_cluster_admin/rosa_monitoring/rosa-enabling-alert-routing-for-user-defined-projects.adoc
+
+:_content-type: CONCEPT
+[id="osd-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. 
+With this feature, you can allow users with the **alert-routing-edit** role to configure alert notification routing and receivers for user-defined projects.
+These notifications are routed by an Alertmanager instance dedicated to user-defined monitoring.
+
+Users can then create and configure user-defined alert routing by creating or editing the `AlertmanagerConfig` objects for their user-defined projects without the help of an administrator.
+
+After a user has defined alert routing for a user-defined project, user-defined alert notifications are routed to the `alertmanager-user-workload` pods in the `openshift-user-workload-monitoring` namespace.
+
+[NOTE]
+====
+The following are limitations 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.
+
+* When a namespace is excluded from user-defined monitoring, `AlertmanagerConfig` resources in the namespace cease to be part of the Alertmanager configuration.
+====
diff --git a/monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc b/monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc
@@ -0,0 +1,30 @@
+:_content-type: ASSEMBLY
+[id="osd-enabling-alert-routing-for-user-defined-projects"]
+= Enabling alert routing for user-defined projects
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: osd-enabling-alert-routing-for-user-defined-projects
+
+toc::[]
+
+[role="_abstract"]
+In {product-title}, a cluster administrator can enable alert routing for user-defined projects. This process consists of two general steps:
+
+* Enable alert routing for user-defined projects to use a separate Alertmanager instance.
+* Grant additional users permission to configure alert routing for user-defined projects.
+
+After you complete these steps, developers and other users can configure custom alerts and alert routing for their user-defined projects.
+
+//Overview of setting up alert routing for user-defined projects
+include::modules/osd-monitoring-understanding-alert-routing-for-user-defined-projects.adoc[leveloffset=+1]
+
+// Enabling a dedicated Alertmanager instance for use in user-defined projects
+include::modules/monitoring-enabling-a-separate-alertmanager-instance-for-user-defined-alert-routing.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]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../monitoring/osd-accessing-monitoring-for-user-defined-projects.adoc[Accessing monitoring for user-defined projects]
+* xref:../monitoring/osd-managing-alerts.adoc#creating-alert-routing-for-user-defined-projects_managing-alerts.adoc#creating-alerting-rules-for-user-defined-projects_osd-managing-alerts[Creating alert routing for user-defined projects]
diff --git a/monitoring/osd-managing-alerts.adoc b/monitoring/osd-managing-alerts.adoc
@@ -6,8 +6,72 @@ include::_attributes/attributes-openshift-dedicated.adoc[]
 
 toc::[]
 
-Alerts for monitoring workloads in user-defined projects are not currently supported in this {product-title}.
+In {product-title}, the Alerting UI enables you to manage alerts, silences, and alerting rules.
+
+* *Alerting rules*. Alerting rules contain a set of conditions that outline a particular state within a cluster. Alerts are triggered when those conditions are true. An alerting rule can be assigned a severity that defines how the alerts are routed.
+* *Alerts*. An alert is fired when the conditions defined in an alerting rule are true. Alerts provide a notification that a set of circumstances are apparent within an {product-title} cluster.
+* *Silences*. A silence can be applied to an alert to prevent notifications from being sent when the conditions for an alert are true. You can mute an alert after the initial notification, while you work on resolving the underlying issue.
+
+[NOTE]
+====
+The alerts, silences, and alerting rules that are available in the Alerting UI relate to the projects that you have access to. For example, if you are logged in with `cluster-admin` or `dedicated-admin` privileges, all alerts, silences, and alerting rules are accessible.
+====
+
+// Accessing the Alerting UI in the Administrator and Developer perspectives
+include::modules/monitoring-accessing-the-alerting-ui.adoc[leveloffset=+1]
+
+// Searching and filtering alerts, silences, and alerting rules
+include::modules/monitoring-searching-alerts-silences-and-alerting-rules.adoc[leveloffset=+1]
+
+// Getting information about alerts, silences and alerting rules
+include::modules/monitoring-getting-information-about-alerts-silences-and-alerting-rules.adoc[leveloffset=+1]
+
+// Managing silences
+include::modules/monitoring-managing-silences.adoc[leveloffset=+1]
+include::modules/monitoring-silencing-alerts.adoc[leveloffset=+2]
+include::modules/monitoring-editing-silences.adoc[leveloffset=+2]
+include::modules/monitoring-expiring-silences.adoc[leveloffset=+2]
+
+// Managing alerting rules for user-defined projects
+include::modules/monitoring-managing-alerting-rules-for-user-defined-projects.adoc[leveloffset=+1]
+include::modules/monitoring-optimizing-alerting-for-user-defined-projects.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* See the link:https://prometheus.io/docs/practices/alerting/[Prometheus alerting documentation] for further guidelines on optimizing alerts
+* See xref:../monitoring/osd-understanding-the-monitoring-stack.adoc#osd-understanding-the-monitoring-stack[Monitoring overview] for details about {product-title} {product-version} monitoring architecture
+
+include::modules/monitoring-creating-alerting-rules-for-user-defined-projects.adoc[leveloffset=+2]
+include::modules/monitoring-reducing-latency-for-alerting-rules-that-do-not-query-platform-metrics.adoc[leveloffset=+2]
+
+* See xref:../monitoring/osd-understanding-the-monitoring-stack.adoc#osd-understanding-the-monitoring-stack[Monitoring overview] for details about {product-title} {product-version} monitoring architecture.
+
+include::modules/monitoring-accessing-alerting-rules-for-your-project.adoc[leveloffset=+2]
+include::modules/monitoring-listing-alerting-rules-for-all-projects-in-a-single-view.adoc[leveloffset=+2]
+include::modules/monitoring-removing-alerting-rules-for-user-defined-projects.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* See the link:https://prometheus.io/docs/alerting/alertmanager/[Alertmanager documentation]
+
+[role="_additional-resources"]
+.Additional resources
+* See xref:../monitoring/osd-understanding-the-monitoring-stack.adoc#osd-understanding-the-monitoring-stack[Monitoring overview] for details about {product-title} monitoring architecture.
+* See the link:https://prometheus.io/docs/alerting/alertmanager/[Alertmanager documentation] for information about alerting rules.
+* See the link:https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config[Prometheus relabeling documentation] for information about how relabeling works.
+* See the link:https://prometheus.io/docs/practices/alerting/[Prometheus alerting documentation] for further guidelines on optimizing alerts.
+
+// Applying a custom configuration to Alertmanager for user-defined alert routing
+include::modules/monitoring-applying-a-custom-configuration-to-alertmanager-for-user-defined-alert-routing.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* See link:https://www.pagerduty.com/[the PagerDuty official site] for more information on PagerDuty.
+* See link:https://www.pagerduty.com/docs/guides/prometheus-integration-guide/[the PagerDuty Prometheus Integration Guide] to learn how to retrieve the `service_key`.
+* See link:https://prometheus.io/docs/alerting/configuration/[Alertmanager configuration] for configuring alerting through different alert receivers.
 
 [id="alerts-next-steps"]
 == Next steps
-* xref:../monitoring/osd-reviewing-monitoring-dashboards.adoc#osd-reviewing-monitoring-dashboards[Reviewing monitoring dashboards]
+* xref:../monitoring/osd-reviewing-monitoring-dashboards.adoc#osd-reviewing-monitoring-dashboards[Reviewing monitoring dashboards]
diff --git a/osd_cluster_admin/osd_monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc b/osd_cluster_admin/osd_monitoring/osd-enabling-alert-routing-for-user-defined-projects.adoc
@@ -0,0 +1,37 @@
+:_content-type: ASSEMBLY
+[id="osd-enabling-alert-routing-for-user-defined-projects"]
+= Enabling alert routing for user-defined projects
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: osd-enabling-alert-routing-for-user-defined-projects
+
+toc::[]
+
+[role="_abstract"]
+In {product-title}, a cluster administrator can enable alert routing for user-defined projects. 
+
+[IMPORTANT]
+====
+Managing alerting rules for user-defined projects is only available in {product-title} version 4.11 and up. 
+====
+
+This process consists of two general steps:
+
+* Enable alert routing for user-defined projects to use a separate Alertmanager instance.
+* Grant additional users permission to configure alert routing for user-defined projects.
+
+After you complete these steps, developers and other users can configure custom alerts and alert routing for their user-defined projects.
+
+//Overview of setting up alert routing for user-defined projects
+include::modules/osd-monitoring-understanding-alert-routing-for-user-defined-projects.adoc[leveloffset=+1]
+
+// Enabling a dedicated Alertmanager instance for use in user-defined projects
+include::modules/monitoring-enabling-a-separate-alertmanager-instance-for-user-defined-alert-routing.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]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../osd_cluster_admin/osd_monitoring/osd-accessing-monitoring-for-user-defined-projects.adoc#osd-accessing-monitoring-for-user-defined-projects[Accessing monitoring for user-defined projects]
+* xref:../../osd_cluster_admin/osd_monitoring/osd-managing-alerts.adoc#creating-alerting-rules-for-user-defined-projects_osd-managing-alerts[Creating alert routing for user-defined projects]
diff --git a/osd_cluster_admin/osd_monitoring/osd-managing-alerts.adoc b/osd_cluster_admin/osd_monitoring/osd-managing-alerts.adoc
diff --git a/rosa_cluster_admin/rosa_monitoring/rosa-enabling-alert-routing-for-user-defined-projects.adoc b/rosa_cluster_admin/rosa_monitoring/rosa-enabling-alert-routing-for-user-defined-projects.adoc
diff --git a/rosa_cluster_admin/rosa_monitoring/rosa-managing-alerts.adoc b/rosa_cluster_admin/rosa_monitoring/rosa-managing-alerts.adoc
