Skip to content

Commit 6b31df8

Browse files
testcaratestcara
authored
feat(KFLUXUI-587): improve the Readme.md for banner and banner content file (#7288)
1 parent 643e2af commit 6b31df8

File tree

13 files changed

+290
-86
lines changed

13 files changed

+290
-86
lines changed

‎components/konflux-info/README.md

Lines changed: 194 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -29,24 +29,208 @@ Each cluster directory contains:
2929

3030
## ✅ Banner Content Validation
3131

32-
A GitHub workflow named `banner-validate` automatically checks that each `banner-content.yaml` file conforms to the schema defined in `banner-schema.json`.
33-
This workflow runs whenever either the schema or any `banner-content.yaml` file is changed.
34-
The schema (`banner-schema.json`) specifies the required structure and fields for banner content, ensuring consistency and correctness across environments.
32+
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).
33+
34+
**When does it run?**
35+
36+
- On any pull request that changes:
37+
- `banner-schema.json` (schema definition)
38+
- Any `banner-content.yaml` file (banner configurations)
39+
40+
**What does it check?**
41+
42+
- Ensures the YAML structure matches the schema (e.g., required fields, allowed values, date/time format).
43+
- Prevents invalid or misconfigured banners from being merged.
44+
45+
**How to fix validation errors?**
46+
47+
- Review the error message in the PR checks.
48+
- Compare your changes with the [schema](./banner-schema.json) and [examples in README](#usage-scenarios--examples).
49+
50+
## ✅ Banner Content Specification
51+
52+
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`).
53+
54+
### **Schema**
55+
56+
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.
57+
58+
The file must contain a **YAML list** where each item represents a banner configuration.
3559

3660
---
3761

38-
## 📝 How to submit a PR for Banner
62+
### **Important Behavior**
63+
64+
- The **UI displays only the first valid active banner** from the list, based on current date, time, and optional recurrence settings.
65+
- If multiple banners are configured, **order matters**. Place the highest-priority banner **at the top of the list**.
66+
67+
---
68+
69+
### **Required and Optional Fields for Each Banner**
70+
71+
📎 For the full schema used in CI validation, see banner-schema.json. This table is a human-friendly reference for banner authors.
72+
73+
| Field | Type | Required | Description |
74+
| ------------ | ------ | -------- | ------------------------------------------------------------------------- |
75+
| `summary` | string | ✅ | Banner text (5–500 chars). **Supports Markdown** (e.g., bold, links). |
76+
| `type` | string | ✅ | Banner type: `info`, `warning`, or `danger`. |
77+
| `startTime` | string | ⚠️\* | Start time in `HH:mm` (24-hour). Required if date-related fields are set. |
78+
| `endTime` | string | ⚠️\* | End time in `HH:mm` (24-hour). Required if date-related fields are set. |
79+
| `timeZone` | string | ❌ | Optional IANA timezone (e.g., `UTC`, `Asia/Shanghai`). Defaults to UTC. |
80+
| `year` | number | ❌ | Year (1970–9999) for one-time banners. |
81+
| `month` | number | ❌ | Month (1–12). |
82+
| `dayOfWeek` | number | ❌ | Day of week (0=Sunday, 6=Saturday) for weekly recurrence. |
83+
| `dayOfMonth` | number | ❌ | Day of month (1–31). Required if `year` or `month` is specified. |
84+
85+
⚠️ **If any of `year`, `month`, `dayOfWeek`, or `dayOfMonth` is specified, both `startTime` and `endTime` are required.**
86+
87+
---
88+
89+
### **Usage Scenarios & Examples**
90+
91+
#### ✅ **1. Multiple Banners**
92+
93+
Example of a `banner-content.yaml` with multiple banners (first active one is shown in UI):
94+
95+
```yaml
96+
- summary: "Scheduled downtime on July 25"
97+
type: "warning"
98+
year: 2025
99+
month: 7
100+
dayOfMonth: 25
101+
startTime: "10:00"
102+
endTime: "14:00"
103+
timeZone: "UTC"
104+
105+
- summary: "Maintenance every Sunday"
106+
type: "info"
107+
dayOfWeek: 0
108+
startTime: "02:00"
109+
endTime: "04:00"
110+
timeZone: "UTC"
111+
```
112+
113+
#### ✅ **2. One-Time Banner**
114+
115+
For a single event on a specific date:
116+
117+
```yaml
118+
- summary: "Scheduled downtime on July 25"
119+
type: "warning"
120+
year: 2025
121+
month: 7
122+
dayOfMonth: 25
123+
startTime: "10:00"
124+
endTime: "14:00"
125+
timeZone: "UTC"
126+
```
127+
128+
For a single event in today
39129
40-
1. Modify only the files relevant to your target cluster, e.g.: `staging/stone-stage-p01/banner-content.yaml` or `production/kflux-ocp-p01/banner-content.yaml`
41-
2. In your PR description, include:
130+
```yaml
131+
- summary: "Scheduled downtime on July 25"
132+
type: "warning"
133+
startTime: "10:00"
134+
endTime: "14:00"
135+
timeZone: "UTC"
136+
```
137+
138+
#### ✅ **2. Weekly Recurring Banner**
139+
140+
For an event that repeats every week:
141+
142+
```yaml
143+
- summary: "Maintenance every Sunday"
144+
type: "info"
145+
dayOfWeek: 0
146+
startTime: "02:00"
147+
endTime: "04:00"
148+
timeZone: "UTC"
149+
```
150+
151+
#### ✅ **3. Monthly Recurring Banner**
152+
153+
For an event that happens on the same day each month:
154+
155+
```yaml
156+
- summary: "Patch release on 1st of every month"
157+
type: "info"
158+
dayOfMonth: 1
159+
startTime: "01:00"
160+
endTime: "03:00"
161+
timeZone: "Asia/Shanghai"
162+
```
163+
164+
#### ✅ **4. Always-On Banner**
165+
166+
For an event that requires immediate notification:
167+
168+
```yaml
169+
- summary: "New feature: Pipeline Insights is live!"
170+
type: "info"
171+
```
42172
43-
- Target cluster (e.g. kflux-ocp-p01)
44-
- Type of change (e.g. new banner / update info / typo fix)
45-
- Purpose of change (e.g. downgrade notification / release announcement)
173+
#### ✅ **5. Empty Banner**
174+
175+
When there are no events to announce:
176+
177+
```
178+
[]
179+
```
46180

47181
---
48182

49-
## 📢 Auto Alerts
183+
## 📝 How to submit a PR for Banner
184+
185+
1. Locate the target cluster directory:
186+
187+
- For staging: `staging/<cluster-name>/banner-content.yaml`
188+
- For production: `production/<cluster-name>/banner-content.yaml`
189+
190+
2. Edit banner-content.yaml:
191+
192+
- Insert the new banner at the top of the list (highest priority).
193+
- Remove obsolete banners to keep the list clean.
194+
195+
Example:
196+
197+
```yaml
198+
# New banner on top
199+
- summary: "New feature rollout on July 30"
200+
type: "info"
201+
year: 2025
202+
month: 7
203+
dayOfMonth: 30
204+
startTime: "09:00"
205+
endTime: "17:00"
206+
timeZone: "UTC"
207+
208+
# Keep other active banners below
209+
- summary: "Maintenance every Sunday"
210+
type: "info"
211+
dayOfWeek: 0
212+
startTime: "02:00"
213+
endTime: "04:00"
214+
timeZone: "UTC"
215+
```
216+
217+
3. Submit a Pull Request:
218+
219+
- Modify only the target cluster’s banner-content.yaml.
220+
In the PR description, include:
221+
- Target cluster (e.g., kflux-ocp-p01)
222+
- Type of change (e.g., new banner / update / remove obsolete)
223+
- Purpose of change (e.g., release announcement, downtime notice)
224+
225+
Example:
226+
227+
```yaml
228+
Target cluster: kflux-ocp-p01
229+
Type: New banner
230+
Purpose: Release announcement for Konflux 1.2
231+
```
232+
233+
## 📢 Auto Alerts(WIP)
50234
51235
We enables the infrastructure team to automatically surface specific operational issues or warnings in the Konflux UI.
52236

‎components/konflux-info/banner-schema.json

Lines changed: 80 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,84 @@
11
{
22
"$schema": "http://json-schema.org/draft-07/schema#",
3-
"type": "object",
4-
"properties": {
5-
"enable": {
6-
"type": "boolean",
7-
"description": "Whether the banner is enabled or not."
3+
"type": "array",
4+
"items": {
5+
"type": "object",
6+
"properties": {
7+
"summary": {
8+
"type": "string",
9+
"description": "The banner text (5–500 chars). **Supports Markdown** for formatting.",
10+
"minLength": 5,
11+
"maxLength": 500
12+
},
13+
"type": {
14+
"type": "string",
15+
"enum": ["info", "warning", "danger"],
16+
"description": "The type of banner: 'info', 'warning', or 'danger'."
17+
},
18+
"startTime": {
19+
"type": "string",
20+
"pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$",
21+
"description": "Start time in HH:mm (24-hour). Required if any of year, month, dayOfWeek, or dayOfMonth is specified."
22+
},
23+
"endTime": {
24+
"type": "string",
25+
"pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$",
26+
"description": "End time in HH:mm (24-hour). Required if any of year, month, dayOfWeek, or dayOfMonth is specified."
27+
},
28+
"timeZone": {
29+
"type": "string",
30+
"pattern": "^[A-Za-z]+(?:/[A-Za-z_]+)+$",
31+
"description": "Optional IANA time zone (e.g., 'UTC', 'Asia/Shanghai'). Defaults to UTC."
32+
},
33+
"year": {
34+
"type": "integer",
35+
"minimum": 1970,
36+
"maximum": 9999,
37+
"description": "Optional year (1970–9999)."
38+
},
39+
"month": {
40+
"type": "integer",
41+
"minimum": 1,
42+
"maximum": 12,
43+
"description": "Optional month (1–12)."
44+
},
45+
"dayOfWeek": {
46+
"type": "integer",
47+
"minimum": 0,
48+
"maximum": 6,
49+
"description": "Optional day of the week (0 = Sunday, 6 = Saturday)."
50+
},
51+
"dayOfMonth": {
52+
"type": "integer",
53+
"minimum": 1,
54+
"maximum": 31,
55+
"description": "Optional day of the month (1–31). Required when year or month is specified."
56+
}
857
},
9-
"type": {
10-
"type": "string",
11-
"enum": ["info", "warning", "danger"],
12-
"description": "The type of banner to display. Can be 'info', 'warning', or 'danger'."
13-
},
14-
"summary": {
15-
"description": "The summary text to display in the banner. Allows only alphanumeric characters, spaces, and specific punctuation marks.",
16-
"type": "string",
17-
"minLength": 5,
18-
"maxLength": 200,
19-
"pattern": "^[a-zA-Z0-9 ,.!?:;\"'()\\[\\]{}@#&*+=\\-_/]*$"
20-
},
21-
"startTime": {
22-
"type": "string",
23-
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$",
24-
"description": "The start time when the banner should be displayed, in ISO 8601 date-time format (e.g., 2023-01-01T12:00:00Z)."
25-
},
26-
"endTime": {
27-
"type": "string",
28-
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$",
29-
"description": "The end time when the banner should stop being displayed, in ISO 8601 date-time format (e.g., 2023-01-01T12:00:00Z)."
30-
}
31-
},
32-
"required": ["enable", "summary", "type"],
33-
"additionalProperties": false
58+
"required": ["summary", "type"],
59+
"additionalProperties": false,
60+
"allOf": [
61+
{
62+
"if": {
63+
"anyOf": [
64+
{ "required": ["year"] },
65+
{ "required": ["month"] },
66+
{ "required": ["dayOfWeek"] },
67+
{ "required": ["dayOfMonth"] }
68+
]
69+
},
70+
"then": {
71+
"required": ["startTime", "endTime"]
72+
}
73+
},
74+
{
75+
"if": {
76+
"anyOf": [{ "required": ["year"] }, { "required": ["month"] }]
77+
},
78+
"then": {
79+
"required": ["dayOfMonth"]
80+
}
81+
}
82+
]
83+
}
3484
}

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

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1 @@
1-
enable: false
2-
type: warning # options: info, warning, danger
3-
summary: The Konflux platform will undergo scheduled maintenance tonight. Temporary service interruptions may occur.
4-
startTime: "2025-05-15T21:00:00Z"
5-
endTime: "2025-05-15T23:00:00Z"
1+
[]

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
[]

‎components/konflux-info/production/kflux-osp-p01/kustomization.yaml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,14 @@ resources:
44
- ../../base
55

66
generatorOptions:
7-
disableNameSuffixHash: true
7+
disableNameSuffixHash: true
88

99
configMapGenerator:
1010
- name: konflux-public-info
1111
files:
1212
- info.json
13+
- name: konflux-banner-configmap
14+
files:
15+
- banner-content.yaml
1316

1417
namespace: konflux-info

‎components/konflux-info/production/kflux-prd-rh02/banner-content.yaml

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1 @@
1-
enable: false
2-
type: warning # options: info, warning, danger
3-
summary: The Konflux platform will undergo scheduled maintenance tonight. Temporary service interruptions may occur.
4-
startTime: "2025-05-15T21:00:00Z"
5-
endTime: "2025-05-15T23:00:00Z"
1+
[]

‎components/konflux-info/production/kflux-prd-rh03/banner-content.yaml

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1 @@
1-
enable: false
2-
type: warning # options: info, warning, danger
3-
summary: The Konflux platform will undergo scheduled maintenance tonight. Temporary service interruptions may occur.
4-
startTime: "2025-05-15T21:00:00Z"
5-
endTime: "2025-05-15T23:00:00Z"
1+
[]

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

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1 @@
1-
enable: false
2-
type: warning # options: info, warning, danger
3-
summary: The Konflux platform will undergo scheduled maintenance tonight. Temporary service interruptions may occur.
4-
startTime: "2025-05-15T21:00:00Z"
5-
endTime: "2025-05-15T23:00:00Z"
1+
[]

‎components/konflux-info/production/stone-prd-rh01/banner-content.yaml

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1 @@
1-
enable: false
2-
type: warning # options: info, warning, danger
3-
summary: The Konflux platform will undergo scheduled maintenance tonight. Temporary service interruptions may occur.
4-
startTime: "2025-05-15T21:00:00Z"
5-
endTime: "2025-05-15T23:00:00Z"
1+
[]

‎components/konflux-info/production/stone-prod-p01/banner-content.yaml

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1 @@
1-
enable: false
2-
type: warning # options: info, warning, danger
3-
summary: The Konflux platform will undergo scheduled maintenance tonight. Temporary service interruptions may occur.
4-
startTime: "2025-05-15T21:00:00Z"
5-
endTime: "2025-05-15T23:00:00Z"
1+
[]

0 commit comments

Comments
 (0)