From d01bea732bd3303415a736bb1109ad0051c53690 Mon Sep 17 00:00:00 2001
From: Sofiane Gerhardt <sofiane.gerhardt@phoenix-technologies.ch>
Date: Wed, 15 Oct 2025 17:13:16 +0200
Subject: [PATCH] Enhance AlertManagerConfig documentation with detailed
 comments on receivers, inhibit rules, and routing configurations

---
 Guide-Alerting.md | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/Guide-Alerting.md b/Guide-Alerting.md
index 9944cc8..99a083c 100644
--- a/Guide-Alerting.md
+++ b/Guide-Alerting.md
@@ -34,6 +34,7 @@ kind: AlertmanagerConfig
 metadata:
   name: alerts
 spec:
+  # Receivers define destinations for alerts (email, pagerduty, webhook, etc.)
   receivers:
     - name: email-receiver
       emailConfigs:
@@ -47,8 +48,10 @@ spec:
           sendResolved: true
           headers:
             - key: Subject
+              # Template used to format email subject. Includes namespace, status and group labels.
               value: '[{{ .CommonLabels.namespace }}][{{ .Status | toUpper }}{{ if eq .Status "firing" }}:{{ .Alerts.Firing | len }}{{ end }}] {{ .GroupLabels.SortedPairs.Values | join " " }} {{ if gt (len .CommonLabels) (len .GroupLabels) }}({{ with .CommonLabels.Remove .GroupLabels.Names }}{{ .Values | join " " }}{{ end }}){{ end }}'
 
+  # InhibitRules suppress notifications for lower-severity alerts when a matching higher-severity alert is firing
   inhibitRules:
     - sourceMatch:
         - name: severity
@@ -56,16 +59,19 @@ spec:
       targetMatch:
         - name: severity
           value: warning
-      equal: ["alertname"]
+      equal: ["alertname"]  # Fields that must match between source and target alerts to apply inhibition
 
+  # Route defines how alerts are grouped and which receiver is used by default
   route:
     groupBy:
-      - alertname
+      - alertname   # Alerts with the same values for these labels are grouped together
       - severity
-    groupWait: 30s
-    groupInterval: 5m
-    repeatInterval: 12h
-    receiver: email-receiver
+    groupWait: 30s   # Wait time to collect alerts before sending first notification for a group
+    groupInterval: 5m # Minimum interval between notifications for an alert group
+    repeatInterval: 12h # How often to resend notifications for ongoing alerts
+    receiver: email-receiver # Default receiver for alerts that don't match child routes
+
+    # Child routes allow overriding routing for specific alert matchers (e.g., severity)
     routes:
       - matchers:
           - name: severity