Repository navigation
Conversation
…ument each one Proposed strategy ADR for the OAC dashboards in Perses, Grafana and the console: which tool serves which reader, how the datasource follows the audience, dashboards as code, naming, and one ops-docs document per dashboard. References the per-project metric separation ADR and the MCO allowlist ADR instead of repeating them.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Intent
Dashboards are built for the OAC clusters (Grafana, Perses, OpenShift Console Observe), today only in oac-apps (https://github.com/schwesig/OA_oac-apps, fork of CCI-MOC/oac-apps). The goal is to always know why a dashboard was created and why it is fed with which metrics:
"ich baue ja auch dashboards, ich wuerde gerne entweder ein ADR pro Dashboard oder ein ADT fuer mehrere Dashboards (Grafana, Perses, OpenSHift COnsole Ob serve) erstellen, damit man immer weiss, warum man was erstellt und mit diesen metriken etc gefuettert hat."
Agreed split ("ja passt, bisher nur in OAC-APPS"): one ADR for the dashboard strategy (which tool for which audience and purpose, data sources, dashboards as code, naming and ownership; referencing rather than repeating the existing per-project Grafana ADR in CCI-MOC#37 and the MCO allowlist ADR in CCI-MOC#36), plus one short document per dashboard in ops-docs docs/ (what question it answers and for whom, tool and repo location, data source, metrics with PromQL and why/where each metric comes from, thresholds, dependencies such as the MCO allowlist, owner, related ADRs). A separate ADR per dashboard only where a dashboard forces a real decision.
All work and PRs only on the fork schwesig/ops-docs; never on CCI-MOC.
What Changed
adrs/2026-09-04-dashboard-strategy/README.md, that lists the dashboards running today from oac-apps (mco-capacityon Perses and on the console's Observe > Dashboards list, and the per-projectproject-overviewin Grafana). For each one it records how it got there, using the oac-apps PRs, and what Perses/COO, the console ConfigMap route, and MCO's Grafana can and cannot do, citing the COO, OCP 4.22 and ACM 2.17 docs.thanos-querierport 9091 for cluster operators, the project Grafana on port 9092 for project members, and MCO's Grafana for the fleet. The console ConfigMap is only a second route for an operator dashboard, and each dashboard uses the datasource that matches its reader. The ADR also sets dashboards-as-code rules (each dashboard is a resource in the oac-apps chart that owns its instance, behind a values switch) and a kebab-case naming scheme, including a<route>-dashboard-<name>.yamlfile name withproject-overviewnamed as the exception.docs/<date>-dashboard-<name>/README.md, covering the question it answers and for whom, the tool and where it lives, the datasource, each metric with its PromQL and source, thresholds, dependencies, owner and related ADRs. A dashboard gets its own ADR only when it forces a new decision. The ADR points to the per-project Grafana ADR (adr: Separate project metrics with one Grafana per project on the tenancy port CCI-MOC/ops-docs#37) and the MCO allowlist ADR (adr: Collect central metrics using MultiClusterObservability allowlist keeping exclusion lists as a future change CCI-MOC/ops-docs#36) instead of repeating them, and lists the alternatives it rejected, the consequences and the open points. The per-dashboard documents themselves are left for a separate change.🤖 Generated with Claude Code
Risk Assessment
✅ Low: This change adds one documentation-only ADR. Its frontmatter and directory name follow the repo conventions. Its external references were checked against GitHub and are accurate: the oac-apps PR numbers, states and merge dates, commit 457b659, the template paths, the values defaults and the chart names. The only material gap is that the per-dashboard docs the intent asks for are deferred to a later change.
Testing
I built the real ops-docs Eleventy site from the target commit in a disposable /tmp copy. The new ADR's frontmatter passed the repository validator, and the validator rejected a deliberately broken copy. The page rendered with its tables and resolved links, and it appears in the ADR index. Full-page headless Firefox screenshots of the ADR page and the index are saved as evidence. Every scenario passed. The temporary build and the local server were removed, and the worktree is clean.
node _scripts/validate-frontmatter.js adrs/2026-09-04-dashboard-strategy/README.mdexit 0npx eleventywrote _site/adrs/2026-09-04-dashboard-strategy/index.html: 2 tables, 0 unresolved refs, 12 links. Screenshot adr-page.pngPipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
adrs/2026-09-04-dashboard-strategy/README.md:216- The intent asks for two things: "one ADR for the dashboard strategy ... plus one short document per dashboard in ops-docs docs/ (what question it answers and for whom, tool and repo location, data source, metrics with PromQL and why/where each metric comes from, thresholds, dependencies such as the MCO allowlist, owner, related ADRs)". This change adds only the ADR. Open point 6 defers the documents: "The per-dashboard documents are pending.mco-capacityandproject-overviewget theirs in a separate change". Nothing under docs/ is added. Please confirm that moving the docs/ documents for mco-capacity and project-overview to a follow-up change is acceptable, or add them to this change.adrs/2026-09-04-dashboard-strategy/README.md:130- The naming rule says template files are named<route>-dashboard-<name>.yaml. The line just above it givesproject-overviewas an example name, but that dashboard is defined inline incharts/user-projects/templates/grafana.yaml(checked at oac-apps 457b659), so it does not follow the rule. Either say the rule covers only dashboards in their own template file, or list project-overview as a known exception, so readers don't take it for an existing example.🔧 Fix applied.
1 warning still open:
adrs/2026-09-04-dashboard-strategy/README.md:216- The intent asks for two things: "one ADR for the dashboard strategy ... plus one short document per dashboard in ops-docs docs/ (what question it answers and for whom, tool and repo location, data source, metrics with PromQL and why/where each metric comes from, thresholds, dependencies such as the MCO allowlist, owner, related ADRs)". This change adds only the ADR. Open point 6 defers the documents: "The per-dashboard documents are pending.mco-capacityandproject-overviewget theirs in a separate change". Nothing under docs/ is added. Please confirm that moving the docs/ documents for mco-capacity and project-overview to a follow-up change is acceptable, or add them to this change.✅ **Test** - passed
✅ No issues found.
node _scripts/validate-frontmatter.js adrs/2026-09-04-dashboard-strategy/README.mdexit 0npx eleventywrote _site/adrs/2026-09-04-dashboard-strategy/index.html: 2 tables, 0 unresolved refs, 12 links. Screenshot adr-page.pnggit archive HEAD | tar -x -C /tmp/opsdocs-test.ENlQ && npm ci(disposable copy outside the worktree)node _scripts/validate-frontmatter.js adrs/2026-09-04-dashboard-strategy/README.md(exit 0)Adversarial: copy of the ADR with thetitlekey renamed, run throughvalidate-frontmatter.js(rejected with "must have required property 'title'", exit 1)npx eleventysite build (11 files written, including _site/adrs/2026-09-04-dashboard-strategy/index.html)Checked the rendered HTML: 2 tables, no unresolved][ref]links, 12 links to oac-apps, ops-docs PRs and Red Hat docs, page title set,<route>-dashboard-<name>.yamlnaming rule shownServed _site on 127.0.0.1:8765 and took full-page screenshots with headless Firefox of the ADR page and the /adrs/ indexRead the ADR against the intent: tool by audience, datasources, dashboards as code, naming and ownership, links to ops-docs PRs #36 and #37, per-dashboard document template, ADR per dashboard only when it forces a decision, project-overview naming exception✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.