feat: notification grouping & Inhibition (#381)

* docs: notification inhibition

* docs: notification grouping

* chore: typo fixes

* chore: vale error fixes

Author: adityathebe

mission-control-chart

@@ -0,0 +1,24 @@
+---
+title: Grouping
+sidebar_custom_props:
+  icon: group
+---
+
+Mission Control may generate multiple related notifications within a short time window. Instead of sending each alert,
+you can use notification grouping to merge multiple events into a single message.
+
+_Example_: When multiple Helm releases fail to upgrade because of a common unavailable dependency,
+you can use notification grouping to merge the notifications for all the affected helm releases into a single message.
+
+The `groupBy` parameter lets you define how to group notifications.
+You can group by:
+
+- `type` (type of the config)
+- `description`
+- `status_reason`
+- `label` in the format `label:app`
+- `tag` in the format `tag:namespace`
+
+```yaml title="" file=<rootDir>/modules/mission-control/fixtures/notifications/config-health.yaml {11-12}
+
+```

mission-control/docs/guide/notifications/concepts/grouping.md

@@ -0,0 +1,20 @@
+---
+title: Inhibition
+sidebar_custom_props:
+  icon: block
+---
+
+import Inhibition from '../../../reference/notifications/_inhibition.mdx';
+
+Multiple related notifications may be generated within a short time window. Instead of sending each alert separately,
+you can use notification inhibition to inhibit notifications based on the resource hierarchy.
+
+_Example_: When a Kubernetes pod becomes unhealthy, its replicaset and the deployment will also become unhealthy.
+If you have a notification set up to alert on `config.unhealthy`, you'll receive 3 different notifications for the same cause.
+
+```yaml title="deployment-with-inhibition.yaml" file=<rootDir>/modules/mission-control/fixtures/notifications/deployment-with-inhibition.yaml
+```
+
+<Inhibition />
+
+

mission-control/docs/guide/notifications/concepts/inhibition.mdx

@@ -4,7 +4,7 @@ sidebar_custom_props:
   icon: dedupe
 ---
 
-The repeat interval determines the duration between subsequent notifications after an initial successful delivery.
+The repeat interval determines the duration between subsequent related notifications after an initial successful delivery. 
 
 ```yaml title="deployment-failed.yaml"
 apiVersion: mission-control.flanksource.com/v1
@@ -14,24 +14,33 @@ metadata:
   namespace: default
 spec:
   events:
-    - config.healthy
     - config.unhealthy
-    - config.warning
-    - config.unknown
   filter: config.type == "Kubernetes::Deployment"
   to:
     email: [email protected]
   repeatInterval: 2h
+  groupBy:
+    - type
+  groupByInterval: 12h
 ```
 
-## Grouping Per Resource per Source Event
+With the above notification in place, if a Kubernetes Deployment's health fluctuates between `healthy` and `unhealthy` multiple times within a 2-hour window, the system only sends one notification in that period.
 
-The `repeatInterval` applies per unique resource per unique event source. This prevents duplicate notifications when the same resource triggers the same event type multiple times within the interval window. It still allows notifications for different event types on the same resource within the window.
+### Repeat groups
 
-### Example:
+Repeat interval works in tandem with [notification grouping](./grouping.md).
+If multiple notifications fall in the same group, only one notification will be sent for the group within the repeat interval.
 
-With the above notification in place, if a Kubernetes Helm release's health fluctuates between `healthy` and `unhealthy` multiple times within a 2-hour window, the system limits notifications to just two: one for the `config.healthy` event and one for the `config.unhealthy` event.
+#### Example:
 
-However, if the Helm release health shifts to `warning` during this same period, it triggers an additional notification. This occurs because the warning status is considered a separate event source.
+Deployment A becomes unhealthy due to a missing storage class, triggering a notification.
+Soon after, Deployment B also turns unhealthy for the same reason. Since it’s grouped with A, no additional notification is sent during the repeat interval.
+After the 2-hour interval passes, if Deployment C also becomes unhealthy for the same issue, a new notification is sent for C but A & B will also be included in the notification.
 
-The notification throttling mechanism operates independently for each distinct resource. As a result, other Helm releases are not affected by this limitation.
+
+
+| Time   | Deployment | Status     | Action Taken                                       |
+|--------|------------|------------|----------------------------------------------------|
+| 10:00  | A          | Unhealthy  | Notification sent _(first in group)_                 |
+| 10:15  | B          | Unhealthy  | Supressed due to repeat interval _(grouped with A for 12h)_ |
+| 12:10  | C          | Unhealthy  | Notification sent _(repeat interval expired)_ Includes A, B, and C in the message _(group is still active since groupByInterval is 12h)_ |

mission-control/docs/guide/notifications/concepts/repeat-interval.mdx

@@ -51,30 +51,4 @@ spec:
   waitFor: 5m
   //highlight-next-line
   waitForEvalPeriod: 30s
-```
-:::
-
-### Grouping Notifications
-
-Multiple related notifications may be generated within a short time window. Instead of sending each alert separately, 
-you can use notification grouping to consolidate multiple events into a single message.
-
-_Example_: When a Kubernetes deployment becomes unhealthy, its replicaset and associated pods will also become unhealthy. 
-If you have a notification set up to alert on `config.unhealthy`, you'll receive 3 different notifications at the very least for the same cause.
-
-The `groupBy` parameter allows you to define how notifications should be grouped. 
-Grouping can be done via 
-- `type` (type of the config)
-- `description`
-- `status_reason`
-- `labels` in the format `labels:app`
-- `tags` in the format `tag:namespace`
-
-:::info
-Grouping only works with waitFor. 
-Hence, a waitFor duration is required 
-:::
-
-
-```yaml title="" file=<rootDir>/modules/mission-control/fixtures/notifications/config-health.yaml {11-12}
 ```

mission-control/docs/guide/notifications/concepts/wait-for.mdx

@@ -0,0 +1,33 @@
+<Fields 
+  rows={[
+    {
+      field: 'depth',
+      scheme: 'int',
+      description: 'Defines how many levels of child or parent resources to traverse.'
+    },
+    {
+      field: 'direction',
+      scheme: '`inoming`|`outgoing`|`both`',
+      required: true,
+      description: 'Specifies the traversal direction in relation to the "From" resource. Can be "outgoing" (looks for child resources), "incoming" (looks for parent resources), or "all" (considers both).'
+    },
+    {
+      field: 'from',
+      scheme: '`string`',
+      required: true,
+      description: 'Specifies the starting resource type (for example, "Kubernetes::Deployment").'
+    },
+    {
+      field: 'soft',
+      scheme: 'bool',
+      description: 'When true, relates using soft relationships. Example: Deployment to Pod is hard relationship, but Node to Pod is soft relationship.'
+    },
+    {
+      field: 'to',
+      scheme: '`[]string`',
+      required: true,
+      description: 'Specifies the traversal direction in relation to the `from` resource. `outgoing` looks for child resources and `incoming` looks for parent resources.'
+    }
+  ]}
+/>
+

mission-control/docs/reference/notifications/_inhibition.mdx

@@ -1,3 +1,5 @@
+import Inhibition from '../../reference/notifications/_inhibition.mdx';
+
 <Fields withTemplates="true" rows={[
   {
     field: "events",
@@ -60,6 +62,11 @@
     description: "Group notifications that are in waiting stage based on labels, tags and attributes. Only applicable when `waitFor` is provided. See [Grouping attributes](../../guide/notifications/concepts/wait-for#grouping-notifications)",
     scheme: "[]string"
   },
+  {
+    field: "groupByInterval",
+    description: "The maximum duration for which notifications will be grouped together before creating a new group. _(Default: 24h)_",
+    scheme: "duration"
+  },
   {
     field: "title",
     description: "Channel dependent e.g. subject for email",
@@ -95,8 +102,17 @@
     description: "specify the `<namespace>/<name>` of the playbook that should be triggered when this notification fires.",
     scheme: "string",
   },
+  {
+    field: "inhibitions",
+    description: "Inhibitions are used to inhibit notifications based on the resource hierarchy.",
+    scheme: "[`[]Inhibition`](#inhibition)",
+  }
 ]}/>
 
 :::info Single Recipient
 Only one recipient can be specified
 :::
+
+### Inhibition
+
+<Inhibition />