How grafana/grafana-operator works
Project Type & Purpose
• The Grafana Operator is a cloud-native Kubernetes Operator (using the Operator pattern via controller-runtime/Operator-SDK).
• Its purpose is to reconcile Custom Resources (Grafana, GrafanaDashboard, GrafanaDataSource, etc.) and drive Kubernetes resources (Deployments, Services, ConfigMaps, Secrets, Ingress) and external Grafana API calls to stand up and configure Grafana instances.
Key Architectural Components
A. Developer Tooling & CI/CD
– GitHub repo with code, docs, examples, CI workflows (.github/workflows).
– Build tooling: Makefile, Toolchain.mk, hack scripts, ko.yaml (for building container images), Dockerfile.
– Packaging: Helm Chart (deploy/helm/grafana-operator), OLM Bundle (bundle/*), Kustomize overlays (deploy/kustomize).
B. Kubernetes Cluster Runtime
1. API Server & etcd
– Hosts CustomResourceDefinitions (config/crd/bases).
2. Grafana Operator Pod
– Main Manager (main.go)
• Installs controllers via controller-runtime Manager.
– Controllers (controllers/*.go)
• One per CR type (Grafana, Dashboard, DataSource, Folder, AlertRuleGroup, etc.).
– Reconcilers (controllers/reconcilers/grafana/*)
– Shared sub-systems
• API client (controllers/client/*) to talk to Grafana HTTP API.
• Content fetchers/resolver (controllers/content/*) to pull dashboards via JSON, Jsonnet, URLs, ConfigMaps.
• Metrics for operator health (controllers/metrics/metrics.go).
• Model layer (controllers/model/*) mapping CRs → Grafana JSON payloads.
• Webhook patches via Kustomize for admission (config/crd/patches).
C. External Systems
– Grafana Instances
• Managed inside the cluster (Deployment + Service).
• Optionally external Grafana (CR “externalInstance” flag).
– Grafana.com (for fetching community dashboards via controllers/content/grafana_com_fetcher.go).
– GitOps tools (ArgoCD/Flux): apply CR YAML from Git repositories.
Relationships & Data Flow
• The Operator Pod watches the Kubernetes API for CR events.
• On CR creation/update/delete:
– Controllers trigger Reconciler chains → compute desired state.
– Reconciler talks back to Kubernetes API (create/update child resources: Deployments, Services, ConfigMaps, Secrets, RBAC).
– Reconciler uses Grafana HTTP client to configure dashboards, datasources, alerting rules on the target Grafana instance.
• Packaging pipelines push container images & OLM bundles → OperatorHub/OCI registry.
• Users install via Helm or Kustomize → Kubernetes cluster → CRDs + Operator Pod.
Architectural Patterns & Principles
• Operator Pattern / Controller-Reconciler loop.
• Custom Resource Definitions (CRD) per resource type.
• Modular Reconcilers for single-responsibility (admin-secret, deployment, service, PVC, plugins).
• Pluggable content fetchers (Strategy pattern: URL / GitHub / ConfigMap / Jsonnet).
• Upstream Grafana API client library to standardize API interactions.
• Standard Kubernetes RBAC, ServiceAccount, LeaderElection.
• Packaging via Helm, Kustomize, OLM.
• Declarative GitOps & Infrastructure-as-Code.