Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 55 additions & 68 deletions components/konflux-info/README.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,51 @@
_Follow links by Ctrl + click (or Cmd + click on Mac)_

- [📂 Directory Structure](#DirectoryStructure)
- [📢 Konflux Banner](#KonfluxBanner)
- [✅ Banner Content Validation](#BannerContentValidation)
- [✅ Banner Content Specification](#BannerContentSpecification)
- [**Schema**](#Schema)
- [**Required and Optional Fields for Each Banner**](#RequiredandOptionalFieldsforEachBanner)
- [Usage Scenarios & Examples](#UsageScenariosExamples)
- [**1. Multiple Banners**](#1.MultipleBanners)
- [**2. One-Time Banner**](#2.One-TimeBanner)
- [**3. Weekly Recurring Banner**](#3.WeeklyRecurringBanner)
- [**4. Monthly Recurring Banner**](#4.MonthlyRecurringBanner)
- [**5. Always-On Banner**](#5.Always-OnBanner)
- [**6. Empty Banner**](#6.EmptyBanner)
- [📝 How to submit a PR for Banner](#HowtosubmitaPRforBanner)
- [✅ UI Behavior](#UIBehavior)
- [❓ Frequently Asked Questions](#FrequentlyAskedQuestions)

# 🚀 konflux-info Repository Guide

## 📂 Directory Structure
## <a name='DirectoryStructure'></a>📂 Directory Structure

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
├── banner-schema.json # JSON schema definition for validating banner-content.yaml files

```

Each cluster directory contains:

```bash
.
├── auto-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

```

---

## ✅ Banner Content Validation
## <a name='KonfluxBanner'></a>📢 Konflux Banner

### <a name='BannerContentValidation'></a>✅ Banner Content Validation

To maintain consistency, a GitHub workflow named **`banner-validate`** automatically validates all `banner-content.yaml` files against the schema defined in [`banner-schema.json`](./banner-schema.json).

Expand All @@ -47,26 +65,19 @@ To maintain consistency, a GitHub workflow named **`banner-validate`** automatic
- Review the error message in the PR checks.
- Compare your changes with the [schema](./banner-schema.json) and [examples in README](#usage-scenarios--examples).

## ✅ Banner Content Specification
### <a name='BannerContentSpecification'></a>✅ Banner Content Specification

The `banner-content.yaml` file defines one or more banners displayed in the Konflux UI. Each cluster has its own `banner-content.yaml` under its directory (e.g., `staging/stone-stage-p01/banner-content.yaml`).

### **Schema**
#### <a name='Schema'></a>**Schema**

The schema for banner content is defined in [`banner-schema.json`](./banner-schema.json) and validated automatically by the `banner-validate` GitHub workflow on every PR.

The file must contain a **YAML list** where each item represents a banner configuration.

---

### **Important Behavior**

- The <strong style="color: red;">UI displays only the first valid active banner</strong> from the list, based on current date, time, and optional recurrence settings.
- If multiple banners are configured, <strong style="color: red;">order matters</strong>.

---

### **Required and Optional Fields for Each Banner**
#### <a name='RequiredandOptionalFieldsforEachBanner'></a>**Required and Optional Fields for Each Banner**

📎 For the full schema used in CI validation, see banner-schema.json. This table is a human-friendly reference for banner authors.

Expand All @@ -86,9 +97,9 @@ The file must contain a **YAML list** where each item represents a banner config

---

### **Usage Scenarios & Examples**
### <a name='UsageScenariosExamples'></a>Usage Scenarios & Examples

#### **1. Multiple Banners**
#### <a name='1.MultipleBanners'></a>**1. Multiple Banners**

Example of a `banner-content.yaml` with multiple banners (first active one is shown in UI):

Expand All @@ -110,7 +121,7 @@ Example of a `banner-content.yaml` with multiple banners (first active one is sh
# No timezone is needed when you expect it's UTC.
```

#### **2. One-Time Banner**
#### <a name='2.One-TimeBanner'></a>**2. One-Time Banner**

For a single event on a specific date:

Expand All @@ -133,7 +144,7 @@ For a single event in today
endTime: "14:00"
```
#### ✅ **2. Weekly Recurring Banner**
#### <a name='3.WeeklyRecurringBanner'></a>✅ **3. Weekly Recurring Banner**
For an event that repeats every week:
Expand All @@ -145,7 +156,7 @@ For an event that repeats every week:
endTime: "04:00"
```
#### ✅ **3. Monthly Recurring Banner**
#### <a name='4.MonthlyRecurringBanner'></a>✅ **4. Monthly Recurring Banner**
For an event that happens on the same day each month:
Expand All @@ -158,7 +169,7 @@ For an event that happens on the same day each month:
timeZone: "Asia/Shanghai"
```
#### ✅ **4. Always-On Banner**
#### <a name='5.Always-OnBanner'></a>✅ **5. Always-On Banner**
For an event that requires immediate notification:
Expand All @@ -167,7 +178,7 @@ For an event that requires immediate notification:
type: "info"
```
#### ✅ **5. Empty Banner**
#### <a name='6.EmptyBanner'></a>✅ **6. Empty Banner**
When there are no events to announce:
Expand All @@ -177,7 +188,7 @@ When there are no events to announce:

---

## 📝 How to submit a PR for Banner
### <a name='HowtosubmitaPRforBanner'></a>📝 How to submit a PR for Banner

1. Locate the target cluster directory:

Expand All @@ -186,7 +197,7 @@ When there are no events to announce:

2. Edit banner-content.yaml:

- <strong style="color: red;">Insert the new banner at the top of the list</strong>.
- **Insert the new banner at the top of the list**.
- Remove obsolete banners to keep the list clean.

Example:
Expand Down Expand Up @@ -225,61 +236,37 @@ When there are no events to announce:
Purpose: Release announcement for Konflux 1.2
```
## ❓ Frequently Asked Questions
- Why is only one banner shown even when multiple are configured?
<strong style="color: red;">We follow the [PatternFly design guidelines](https://www.patternfly.org/components/banner/design-guidelines) for banners</strong>, which emphasize simplicity and clarity. Showing just one banner line at a time helps avoid overwhelming users and ensures that important messages aren't lost in clutter.
- What does “first active” actually mean?
---
<strong style="color: red;">The term 'first' doesn’t imply priority or severity</strong> — it simply refers to the first banner that is currently active based on time and repeat configuration.
### <a name='UIBehavior'></a>✅ UI Behavior
If a banner was scheduled in the past, it should already have been displayed.
- The **UI displays only the first valid active banner** from the list, based on current date, time, and optional recurrence settings.
- If multiple banners are configured, **order matters**.
- **Time-related fields like `startTime` and `endTime` are not displayed in the UI**; they only control when the banner is active.

If it's scheduled in the future, it will show when its time comes.
**To convey duration or timing details, please include them within the `summary`.**

At any given moment, the system checks which banner is active right now, and picks the first one that matches the criteria.
- **The `type` and `summary` fields are displayed directly in the UI**.
- We enjoyed leveraging the [PatternFly Banner component (v5)](https://v5-archive.patternfly.org/components/banner/) to implement the UI, following its design principles for clarity and consistency.

🕒 Banners use fields like `startTime`, `endTime`, `dayOfWeek`, etc., to precisely define when they should appear.

<strong style="color: red;">📝 If multiple messages need to be shared at the same time, consider combining them into a well-written summary inside a single banner.</strong>

## 📢 Auto Alerts(WIP)
---

We enables the infrastructure team to automatically surface specific operational issues or warnings in the Konflux UI.
### <a name='FrequentlyAskedQuestions'></a>❓ Frequently Asked Questions

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.
- Why is only one banner shown even when multiple are configured?

### ✅ Alert YAML Format
**We follow the [PatternFly design guidelines](https://www.patternfly.org/components/banner/design-guidelines) for banners**, which emphasize simplicity and clarity. Showing just one banner line at a time helps avoid overwhelming users and ensures that important messages aren't lost in clutter.

Each file under auto-alerts/ must be a valid Kubernetes ConfigMap, including at minimum:
- What does “first active” actually mean?

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: konflux-auto-alert-xyz
namespace: konflux-info
labels:
konflux-auto-alert: "true" # Required. UI filter alerts out by this label.
data:
auto-alert-content.yaml: |
enable: true
summary: "Builds are delayed due to maintenance"
type: "warning"
```
**The term 'first' doesn't imply priority or severity** — it simply refers to the first banner that is currently active based on time and repeat configuration.

🔐 The data.banner-content.yaml should follow the schema defined in `auto-alert-schema.json`
If a banner was scheduled in the past, it should already have been displayed.

### Folder Structure
If it's scheduled in the future, it will show when its time comes.

```bash
At any given moment, the system checks which banner is active right now, and picks the first one that matches the criteria.

auto-alerts/ # Alert ConfigMaps (one file = one alert)
.
├── alert-1.yaml # Fully valid ConfigMap YAML
├── alert-2.yaml
└── kustomization.yaml # Auto-generated, includes all alert YAMLs
🕒 Banners use fields like `startTime`, `endTime`, `dayOfWeek`, etc., to precisely define when they should appear.

```
**📝 If multiple messages need to be shared at the same time, consider combining them into a well-written summary inside a single banner.**
24 changes: 0 additions & 24 deletions components/konflux-info/auto-alert-schema.json

This file was deleted.

This file was deleted.

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1 +1 @@
[]
[]
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

This file was deleted.

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

This file was deleted.

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

Loading