feat(observability): repo-owned dashboards-as-code + Scratch folder convention#202
Merged
Merged
Conversation
…onvention Establish the hybrid dashboard workflow from ADR-0007 / PRD #176 user stories 1, 9, and 19: production dashboards live as JSON in the repo and provision read-only; a manually-created Scratch folder stays writable for in-flight investigations. - dashboards/nodes.json — repo-authored 6-node CPU/mem/disk/network overview (story 2), reads node-exporter + kube-state-metrics. - dashboards/addon-health.json — repo-authored cluster + addon health overview (story 1). The workload-health row reads kube-state-metrics and has data from first sync; the addon-exporter row fills in per addon as ServiceMonitors land. - dashboards/kustomization.yaml — register both dashboards as their own configMapGenerator entries; record per-dashboard provenance; stamp every ConfigMap with grafana_folder: Homelab. - helm-values.yaml — sidecar folderAnnotation: grafana_folder plus provider.foldersFromFilesStructure: true, so repo dashboards land in a read-only "Homelab" Grafana folder, distinct from the writable operator-created "Scratch" folder. - README — folder convention (folderAnnotation chosen over tags, with rationale), the promote-from-Scratch workflow, and smoke-test steps for provisioning, edit-and-resync, and the Scratch folder. Closes: #182 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
1 participant
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.
What
Establishes the hybrid dashboard workflow promised by ADR-0007 / PRD #176 (user stories 1, 9, 19): production dashboards live as JSON in the repo and provision read-only; a manually-created Scratch folder stays writable for in-flight investigations.
Changes
dashboards/nodes.json— repo-authored 6-node CPU / memory / disk / network overview (story 2). Readsnode-exporter+kube-state-metricsseries kube-prometheus-stack ships out of the box, so it has data from first sync.dashboards/addon-health.json— repo-authored cluster + addon health overview (story 1). The Cluster & workload health row (kube-state-metrics) has data immediately; the Addon exporters row (ArgoCD, cert-manager, ESO, Longhorn) reads "No data" until each addon ships aServiceMonitor— wide-open discovery scrapes it the moment it does.dashboards/kustomization.yaml— both dashboards registered as their ownconfigMapGeneratorentries; per-dashboard provenance recorded viahomelab.jackhall.dev/dashboard-source; every ConfigMap stampedgrafana_folder: Homelab.helm-values.yaml— sidecarfolderAnnotation: grafana_folder+provider.foldersFromFilesStructure: true, so repo-owned dashboards land in a read-only Homelab Grafana folder, distinct from the writable operator-created Scratch folder.README.md— new Dashboards-as-code section: the folder convention (folderAnnotationchosen over dashboardtags, with rationale), the promote-from-Scratch workflow, and smoke-test steps for provisioning, edit-and-resync, and the Scratch folder.Folder convention
folderAnnotationwas chosen over dashboardtags: tags label a dashboard but cannot place it in a folder, so they cannot give Scratch its own read/write boundary. Chart-bundled dashboards carry no annotation and stay in Grafana's "General" folder. The "Scratch" folder is operator-created in the UI (the sidecar provisions dashboards, not empty folders) and intentionally absent from Git.Validation
python3 -m json.tool— both new dashboards are valid JSON.kubectl kustomize dashboards/— renders 3 ConfigMaps, eachgrafana_folder: Homelab, labelgrafana_dashboard: "1", namespaceobservability.scripts/lint-apps.sh kubernetes/apps/kube-prometheus-stack— passes unmodified.helm template— confirmsFOLDER_ANNOTATION=grafana_folderon the sidecar andfoldersFromFilesStructure: truein the provisioning provider.In-cluster acceptance checks (Grafana not reachable from this environment) are documented as smoke-test steps 9–11 in the README.
Closes: #182
🤖 Generated with Claude Code