feat(KFLUXUI-592): improve the Readme.md for system alerts and yaml files

Author: testcara

components/konflux-info/README.md

@@ -6,7 +6,6 @@ The `KONFLUX-INFO` directory contains:
 
 ```bash
 .
-├── auto-alert-schema.json  # JSON shema definition for auto-alert-content.yaml
 ├── base/                   # Common resources (e.g., RBAC)
 ├── production/             # Production cluster configurations
 ├── staging/                # Staging cluster configurations
@@ -18,10 +17,10 @@ Each cluster directory contains:
 
 ```bash
 .
-├── auto-alerts # The directory manages auto-generated alerts content shown in the UI
+├── system-alerts # The directory manages auto-generated alerts content shown in the UI
 ├── banner-content.yaml # The banner content shown in the UI
 ├── info.json # Metadata about the cluster
-└── kustomization.yaml # Kustomize configuration for this cluster, including base, auto-alerts, and other configs
+└── kustomization.yaml # Kustomize configuration for this cluster, including base, system-alerts, and other configs
 
 ```
 
@@ -230,41 +229,83 @@ When there are no events to announce:
   Purpose: Release announcement for Konflux 1.2
   ```
 
-## 📢 Auto Alerts(WIP)
+---
+
+## 📢 System Alerts
 
 We enables the infrastructure team to automatically surface specific operational issues or warnings in the Konflux UI.
 
 These alerts would be auto-generated from monitoring systems or automation scripts, written as Kubernetes ConfigMaps, and automatically picked up by the Konflux UI to inform users of system-wide conditions.
 
 ### ✅ Alert YAML Format
 
-Each file under auto-alerts/ must be a valid Kubernetes ConfigMap, including at minimum:
+Each file under `system-alerts/` must be a valid Kubernetes ConfigMap and would be considered as one alert.
+
+We use below simple JSON format inside the ConfigMap to make generation via scripts easier and more reliable:
+
+- Only two fields are supported in the alert content:
+
+  - summary: A short, user-facing message.
+  - type: One of info, warning, or danger.
+
+- JSON is used instead of YAML for ease of script generation.
+
+- The label `konflux.system.alert: "true"` is required — this is how the Konflux UI discovers and filters alert ConfigMaps.
+
+Here is an example:
 
 ```yaml
 apiVersion: v1
 kind: ConfigMap
 metadata:
-  name: konflux-auto-alert-xyz
+  name: konflux-system-alert-xyz
   namespace: konflux-info
   labels:
-    konflux-auto-alert: "true" # Required. UI filter alerts out by this label.
+    konflux.system.alert: "true"
 data:
-  auto-alert-content.yaml: |
-    enable: true
-    summary: "Builds are delayed due to maintenance"
-    type: "warning"
+  system-alert-content.json: |
+    {
+      "summary": "Builds are delayed due to maintenance",
+      "type": "warning"
+    }
 ```
 
-🔐 The data.banner-content.yaml should follow the schema defined in `auto-alert-schema.json`
+Note there is no CI validation for the `system-alert-content.json` payload.
 
 ### Folder Structure
 
+When there are active alerts, the folder structure is:
+
 ```bash
 
-auto-alerts/   # Alert ConfigMaps (one file = one alert)
+system-alerts/   # Alert ConfigMaps (one file = one alert)
 .
-├── alert-1.yaml           # Fully valid ConfigMap YAML
+├── alert-1.yaml        # A example valid ConfigMap containing alert content
 ├── alert-2.yaml
-└── kustomization.yaml     # Auto-generated, includes all alert YAMLs
+└── kustomization.yaml  # Auto-generated, includes all alert YAMLs
 
 ```
+
+When there are no alerts, the `system-alerts/` folder and its reference in the parent `kustomization.yaml` should be both removed automatically to avoid kustomize errors.
+
+### When to Add or Remove an Alert
+
+These ConfigMaps are automatically generated by monitoring or scripting systems based on the current system state.
+
+- Add an alert
+
+  - A new YAML file should be generated under `system-alerts` when a new system condition or issue needs to be surfaced to users.
+  - `kustomization.yaml` under `system-alerts` should be refreshed to ensure the new YAML file is covered.
+  - If the `system-alerts/` directory does not exist (e.g. no previous alerts), you must:
+    - Create the `system-alerts/` directory.
+    - Generate its local `kustomization.yaml`
+    - Ensure the parent kustomization.yaml includes a reference to `system-alerts/`.
+
+- To remove an alert:
+  - Delete the corresponding alert YAML file from `system-alerts/.`
+  - `kustomization.yaml` under `system-alerts` should be refreshed to ensure the deleted YAML has been removed.
+  - If no alerts remain:
+    - Delete the `system-alerts/` directory.
+    - Remove its reference from the parent `kustomization.yaml`.
+
+⚙️ These add/remove actions are expected to be handled by automation. Manual edits are discouraged unless for emergency override or debugging purposes.

components/konflux-info/auto-alert-schema.json

@@ -8,9 +8,6 @@ rules:
       - get
     apiGroups:
       - ''
-    resourceNames:
-      - konflux-public-info
-      - konflux-banner-configmap
     resources:
       - configmaps
 ---

components/konflux-info/base/rbac.yaml

@@ -1 +1 @@
-[] 
+[]

components/konflux-info/production/kflux-ocp-p01/auto-alerts/kustomization.yaml

@@ -2,10 +2,9 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
   - ../../base
-  - auto-alerts
 
 generatorOptions:
- disableNameSuffixHash: true
+  disableNameSuffixHash: true
 
 configMapGenerator:
   - name: konflux-public-info

components/konflux-info/production/kflux-ocp-p01/banner-content.yaml

@@ -2,10 +2,9 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
   - ../../base
-  - auto-alerts
 
 generatorOptions:
- disableNameSuffixHash: true
+  disableNameSuffixHash: true
 
 configMapGenerator:
   - name: konflux-public-info

components/konflux-info/production/kflux-ocp-p01/kustomization.yaml

@@ -2,10 +2,9 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
   - ../../base
-  - auto-alerts
 
 generatorOptions:
- disableNameSuffixHash: true
+  disableNameSuffixHash: true
 
 configMapGenerator:
   - name: konflux-public-info