Grafana Dashboard Improvements Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add missing dashboards, reorganize into layer-based folders, migrate Velero to CRD, and rename misleading directory.

Architecture: All dashboards use GrafanaDashboard CRDs with URL references to Grafana.com (pinned revisions) or GitHub (project-maintained). Organized into layer folders: Infrastructure, Platform, Applications, Kubernetes, Logs.

Tech Stack: Grafana Operator CRDs, Kustomize, ArgoCD GitOps

Task 1: Create Directory Structure

Files:

Create: argocd/app-configs/grafana/dashboards/infrastructure/
Create: argocd/app-configs/grafana/dashboards/platform/
Create: argocd/app-configs/grafana/dashboards/applications/
Create: argocd/app-configs/grafana/dashboards/kubernetes/
Create: argocd/app-configs/grafana/dashboards/logs/

Step 1: Create subdirectories

cd /Volumes/Code/github.com/fzymgc-house/selfhosted-cluster/.worktrees/grafana-dashboards
mkdir -p argocd/app-configs/grafana/dashboards/{infrastructure,platform,applications,kubernetes,logs}

Step 2: Verify structure

ls -la argocd/app-configs/grafana/dashboards/

Expected: Five new directories created

Task 2: Add Alloy Dashboard (Infrastructure)

Files:

Create: argocd/app-configs/grafana/dashboards/infrastructure/alloy.yaml

Step 1: Create Alloy dashboard CRD

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: alloy
  namespace: grafana
  labels:
    grafana.integreatly.org/instance: grafana
spec:
  instanceSelector:
    matchLabels:
      dashboards: grafana
  folder: Infrastructure
  url: https://raw.githubusercontent.com/grafana/alloy/main/operations/alloy-mixin/dashboards/alloy-resources.json

Step 2: Validate YAML

Run: yamllint argocd/app-configs/grafana/dashboards/infrastructure/alloy.yaml Expected: No errors

Task 3: Add Longhorn Dashboard (Infrastructure)

Files:

Create: argocd/app-configs/grafana/dashboards/infrastructure/longhorn.yaml

Step 1: Create Longhorn dashboard CRD

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: longhorn
  namespace: grafana
  labels:
    grafana.integreatly.org/instance: grafana
spec:
  instanceSelector:
    matchLabels:
      dashboards: grafana
  folder: Infrastructure
  url: https://grafana.com/api/dashboards/16888/revisions/9/download

Step 2: Validate YAML

Run: yamllint argocd/app-configs/grafana/dashboards/infrastructure/longhorn.yaml Expected: No errors

Task 4: Add Traefik Dashboard (Infrastructure)

Files:

Create: argocd/app-configs/grafana/dashboards/infrastructure/traefik.yaml

Step 1: Create Traefik dashboard CRD

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: traefik
  namespace: grafana
  labels:
    grafana.integreatly.org/instance: grafana
spec:
  instanceSelector:
    matchLabels:
      dashboards: grafana
  folder: Infrastructure
  url: https://grafana.com/api/dashboards/17346/revisions/10/download

Step 2: Validate YAML

Run: yamllint argocd/app-configs/grafana/dashboards/infrastructure/traefik.yaml Expected: No errors

Task 5: Add MetalLB Dashboard (Infrastructure)

Files:

Create: argocd/app-configs/grafana/dashboards/infrastructure/metallb.yaml

Step 1: Create MetalLB dashboard CRD

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: metallb
  namespace: grafana
  labels:
    grafana.integreatly.org/instance: grafana
spec:
  instanceSelector:
    matchLabels:
      dashboards: grafana
  folder: Infrastructure
  url: https://grafana.com/api/dashboards/14127/revisions/1/download

Step 2: Validate YAML

Run: yamllint argocd/app-configs/grafana/dashboards/infrastructure/metallb.yaml Expected: No errors

Task 6: Move Node Exporter Dashboard (Infrastructure)

Files:

Move: argocd/app-configs/monitoring-prometheus/node-exporter-dashboard.yaml → argocd/app-configs/grafana/dashboards/infrastructure/node-exporter.yaml
Modify: Update folder to “Infrastructure”

Step 1: Read current file

cat argocd/app-configs/monitoring-prometheus/node-exporter-dashboard.yaml

Step 2: Create updated version in new location

Update the folder: field to Infrastructure and save to new location.

Step 3: Delete old file

rm argocd/app-configs/monitoring-prometheus/node-exporter-dashboard.yaml

Step 4: Update monitoring-prometheus kustomization if it references this file

Check and remove reference from argocd/app-configs/monitoring-prometheus/kustomization.yaml

Task 7: Add CNPG/PostgreSQL Dashboard (Platform)

Files:

Create: argocd/app-configs/grafana/dashboards/platform/cnpg.yaml

Step 1: Create CNPG dashboard CRD

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: cnpg
  namespace: grafana
  labels:
    grafana.integreatly.org/instance: grafana
spec:
  instanceSelector:
    matchLabels:
      dashboards: grafana
  folder: Platform
  url: https://raw.githubusercontent.com/cloudnative-pg/grafana-dashboards/main/charts/cluster/grafana-dashboard.json

Step 2: Validate YAML

Run: yamllint argocd/app-configs/grafana/dashboards/platform/cnpg.yaml Expected: No errors

Task 8: Add Vault Dashboard (Platform)

Files:

Create: argocd/app-configs/grafana/dashboards/platform/vault.yaml

Step 1: Create Vault dashboard CRD

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: vault
  namespace: grafana
  labels:
    grafana.integreatly.org/instance: grafana
spec:
  instanceSelector:
    matchLabels:
      dashboards: grafana
  folder: Platform
  url: https://grafana.com/api/dashboards/12904/revisions/2/download

Step 2: Validate YAML

Run: yamllint argocd/app-configs/grafana/dashboards/platform/vault.yaml Expected: No errors

Task 9: Move NATS Dashboard (Platform)

Files:

Move: argocd/app-configs/grafana/dashboards/nats.yaml → argocd/app-configs/grafana/dashboards/platform/nats.yaml
Modify: Update folder to “Platform”

Step 1: Move and update folder

mv argocd/app-configs/grafana/dashboards/nats.yaml argocd/app-configs/grafana/dashboards/platform/nats.yaml

Edit to change folder: NATS to folder: Platform

Task 10: Move Cert-Manager Dashboard (Platform)

Files:

Move: argocd/app-configs/cert-manager-config/dashboard.yaml → argocd/app-configs/grafana/dashboards/platform/cert-manager.yaml
Modify: Update folder to “Platform”
Modify: argocd/app-configs/cert-manager-config/kustomization.yaml - remove dashboard reference

Step 1: Read current file and check structure

Step 2: Create in new location with updated folder

Step 3: Remove from cert-manager-config kustomization

Task 11: Move ArgoCD Dashboard (Applications)

Files:

Move: argocd/app-configs/grafana/dashboards/argocd.yaml → argocd/app-configs/grafana/dashboards/applications/argocd.yaml
Modify: Update folder to “Applications”

Step 1: Move and update folder

mv argocd/app-configs/grafana/dashboards/argocd.yaml argocd/app-configs/grafana/dashboards/applications/argocd.yaml

Edit to change folder: ArgoCD to folder: Applications

Task 12: Migrate Velero Dashboard (Applications)

Files:

Create: argocd/app-configs/grafana/dashboards/applications/velero.yaml
Delete: argocd/app-configs/velero/monitoring/grafana-dashboard.yaml
Modify: argocd/app-configs/velero/monitoring/kustomization.yaml - remove dashboard reference

Step 1: Create new CRD-based dashboard

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: velero
  namespace: grafana
  labels:
    grafana.integreatly.org/instance: grafana
spec:
  instanceSelector:
    matchLabels:
      dashboards: grafana
  folder: Applications
  url: https://grafana.com/api/dashboards/11055/revisions/2/download

Step 2: Delete old ConfigMap-based dashboard

rm argocd/app-configs/velero/monitoring/grafana-dashboard.yaml

Step 3: Update velero monitoring kustomization

Remove grafana-dashboard.yaml from resources list.

Task 13: Move Kubernetes Overview Dashboard (Kubernetes)

Files:

Move: argocd/app-configs/grafana/dashboards/kubernetes-overview.yaml → argocd/app-configs/grafana/dashboards/kubernetes/api-server.yaml
Modify: Update name and folder

Step 1: Move and update

mv argocd/app-configs/grafana/dashboards/kubernetes-overview.yaml argocd/app-configs/grafana/dashboards/kubernetes/api-server.yaml

Edit to change name: kubernetes-overview to name: api-server and folder: Kubernetes to folder: Kubernetes

Task 14: Move Loki Dashboard (Logs)

Files:

Move: argocd/app-configs/grafana/dashboards/loki-logs-overview.yaml → argocd/app-configs/grafana/dashboards/logs/loki-overview.yaml
Modify: Update folder to “Logs”

Step 1: Move and update folder

mv argocd/app-configs/grafana/dashboards/loki-logs-overview.yaml argocd/app-configs/grafana/dashboards/logs/loki-overview.yaml

Edit to update folder if needed.

Task 15: Update Main Kustomization

Files:

Modify: argocd/app-configs/grafana/dashboards/kustomization.yaml

Step 1: Update to include all subdirectories

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: grafana

resources:
  - infrastructure/alloy.yaml
  - infrastructure/longhorn.yaml
  - infrastructure/traefik.yaml
  - infrastructure/metallb.yaml
  - infrastructure/node-exporter.yaml
  - platform/cnpg.yaml
  - platform/vault.yaml
  - platform/nats.yaml
  - platform/cert-manager.yaml
  - applications/argocd.yaml
  - applications/velero.yaml
  - kubernetes/api-server.yaml
  - logs/loki-overview.yaml

Step 2: Validate kustomization

Run: kubectl kustomize argocd/app-configs/grafana/dashboards/ Expected: All resources rendered without errors

Task 16: Update Temporal Dashboard Folder (Terraform)

Files:

Modify: tf/grafana/dashboard_temporal.tf:9-11

Step 1: Update folder title

Change:

resource "grafana_folder" "temporal" {
  title = "Temporal"

To:

resource "grafana_folder" "temporal" {
  title = "Applications"

Step 2: Note for future

Temporal dashboard will move to Applications folder on next Terraform apply.

Task 17: Rename system-dashboards Directory

Files:

Rename: argocd/app-configs/system-dashboards/ → argocd/app-configs/service-ingresses/
Modify: argocd/cluster-app/templates/dashboards-and-entrypoints.yaml - update path reference

Step 1: Rename directory

git mv argocd/app-configs/system-dashboards argocd/app-configs/service-ingresses

Step 2: Update cluster-app reference

Check argocd/cluster-app/templates/dashboards-and-entrypoints.yaml for path references and update.

Task 18: Validate and Commit

Step 1: Run full validation

yamllint argocd/app-configs/grafana/dashboards/
kubectl kustomize argocd/app-configs/grafana/dashboards/ | head -50
kubectl kustomize argocd/app-configs/grafana/ | head -50

Step 2: Git status and add

git status
git add -A

Step 3: Commit

git commit -m "feat(grafana): reorganize dashboards with layer-based folders

- Add new dashboards: Alloy, Longhorn, Traefik, MetalLB, CNPG, Vault
- Reorganize into layer folders: Infrastructure, Platform, Applications, Kubernetes, Logs
- Migrate Velero from ConfigMap to GrafanaDashboard CRD
- Rename system-dashboards to service-ingresses
- Update Temporal dashboard folder to Applications

Issue: selfhosted-cluster-78q

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

Task 19: Push and Create PR

Step 1: Push branch

git push -u origin feat/grafana-dashboards

Step 2: Create PR

gh pr create --title "feat(grafana): reorganize dashboards with layer-based folders" --body "## Summary
- Add 6 new dashboards: Alloy, Longhorn, Traefik, MetalLB, CNPG, Vault
- Reorganize into layer folders: Infrastructure, Platform, Applications, Kubernetes, Logs
- Migrate Velero from ConfigMap to GrafanaDashboard CRD
- Rename system-dashboards to service-ingresses

## Changes
See design doc: docs/plans/2026-01-11-grafana-dashboards-design.md

## Test Plan
- [ ] ArgoCD syncs successfully
- [ ] All dashboards appear in Grafana with correct folders
- [ ] Existing dashboards still work
- [ ] Velero dashboard shows improved panels

🤖 Generated with [Claude Code](https://claude.com/claude-code)"