Skip to content

docs(adrs): add proposed ADR for OAC dashboard strategy - #3

Open
schwesig wants to merge 2 commits into
mainfrom
fm/ops-docs-dashboard-adr
Open

schwesig wants to merge 2 commits into
mainfrom
fm/ops-docs-dashboard-adr

Conversation

@schwesig

Copy link
Copy Markdown
Owner

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

  • Adds a proposed ADR, adrs/2026-09-04-dashboard-strategy/README.md, that lists the dashboards running today from oac-apps (mco-capacity on Perses and on the console's Observe > Dashboards list, and the per-project project-overview in 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.
  • Decides the tool by audience: Perses on thanos-querier port 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>.yaml file name with project-overview named as the exception.
  • Requires one short document per owned dashboard at 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.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
The new ADR's frontmatter passes the repository validator used by pre-commit ✅ pass live node _scripts/validate-frontmatter.js adrs/2026-09-04-dashboard-strategy/README.md exit 0
Adversarial: a copy of the ADR with the title key renamed is rejected by the validator ✅ pass live validate-frontmatter.js printed "/ must have required property 'title'" and exited 1
The site build renders the ADR page with its tables and working links, and no reference link is left unresolved ✅ pass live npx eleventy wrote _site/adrs/2026-09-04-dashboard-strategy/index.html: 2 tables, 0 unresolved refs, 12 links. Screenshot adr-page.png
A reader browsing the ADR index finds the new ADR with its title ✅ pass live adrs-index.png shows adrs/2026-09-04-dashboard-strategy with its full title
The ADR covers the agreed strategy: tool by audience, datasources, dashboards as code, naming (with the project-overview exception) and ownership, links to the existing ADRs in ops-docs PRs CCI-MOC#36 and #3… ✅ pass live Sections Tool by audience, Datasource follows the audience, Dashboards as code, Naming and Ownership and documentation are visible in the rendered adr-page.png

Rendered ADR page (full page, headless Firefox)
ADR index listing the new dashboard-strategy ADR

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 warning
  • ⚠️ 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-capacity and project-overview get 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 &lt;route&gt;-dashboard-&lt;name&gt;.yaml. The line just above it gives project-overview as an example name, but that dashboard is defined inline in charts/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-capacity and project-overview get 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.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
The new ADR's frontmatter passes the repository validator used by pre-commit ✅ pass live node _scripts/validate-frontmatter.js adrs/2026-09-04-dashboard-strategy/README.md exit 0
Adversarial: a copy of the ADR with the title key renamed is rejected by the validator ✅ pass live validate-frontmatter.js printed "/ must have required property 'title'" and exited 1
The site build renders the ADR page with its tables and working links, and no reference link is left unresolved ✅ pass live npx eleventy wrote _site/adrs/2026-09-04-dashboard-strategy/index.html: 2 tables, 0 unresolved refs, 12 links. Screenshot adr-page.png
A reader browsing the ADR index finds the new ADR with its title ✅ pass live adrs-index.png shows adrs/2026-09-04-dashboard-strategy with its full title
The ADR covers the agreed strategy: tool by audience, datasources, dashboards as code, naming (with the project-overview exception) and ownership, links to the existing ADRs in ops-docs PRs CCI-MOC#36 and #3… ✅ pass live Sections Tool by audience, Datasource follows the audience, Dashboards as code, Naming and Ownership and documentation are visible in the rendered adr-page.png
  • git archive HEAD | tar -x -C /tmp/opsdocs-test.ENlQ &amp;&amp; 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 the title key renamed, run through validate-frontmatter.js (rejected with "must have required property 'title'", exit 1)
  • npx eleventy site 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, &lt;route&gt;-dashboard-&lt;name&gt;.yaml naming rule shown
  • Served _site on 127.0.0.1:8765 and took full-page screenshots with headless Firefox of the ADR page and the /adrs/ index
  • Read 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.

…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant