# grafana/grafana-operator architecture

> Architecture diagram of the GitHub repository grafana/grafana-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grafana/grafana-operator
- Repository: https://github.com/grafana/grafana-operator

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Dev & Package
    subgraph "Dev & Package"
        direction TB
        CI["GitHub Workflows"]:::packaging
        Build["Build Tooling\n(Makefile, Toolchain.mk, .ko.yaml, Dockerfile)"]:::packaging
        Hack["Hack Scripts"]:::packaging
        Helm["Helm Chart\ndeploy/helm/grafana-operator"]:::packaging
        OLM["OLM Bundle\nbundle/"]:::packaging
        Kustomize["Kustomize Overlays\ndeploy/kustomize"]:::packaging
    end

    %% Cluster Runtime
    subgraph "Cluster Runtime"
        direction TB
        APIServer["API Server & etcd\n(config/crd/bases)"]:::k8s
        OperatorPod["Grafana Operator Pod"]:::k8s
        GrafanaDeploy["Grafana Deployment & Service"]:::k8s

        subgraph "Operator Pod Internals"
            direction TB
            Manager["Manager\nmain.go"]:::operatorInternals
            Controllers["Controllers\ncontrollers/*.go"]:::operatorInternals
            Reconcilers["Grafana Reconcilers\ncontrollers/reconcilers/grafana/"]:::operatorInternals
            GenericRec["Generic Reconciler Interface\ncontrollers/reconcilers/reconciler.go"]:::operatorInternals
            Client["API Client Layer\ncontrollers/client/"]:::operatorInternals
            Content["Content Fetchers & Resolver\ncontrollers/content/"]:::operatorInternals
            ContentFetchers["Fetchers\ncontrollers/content/fetchers/"]:::operatorInternals
            Cache["Content Cache\ncontrollers/content/cache/cache.go"]:::operatorInternals
            Model["Model Layer\ncontrollers/model/"]:::operatorInternals
            Metrics["Operator Metrics\ncontrollers/metrics/metrics.go"]:::operatorInternals
            CRDPatches["Webhook Patches\nconfig/crd/patches"]:::operatorInternals
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        GrafanaDotCom["Grafana.com"]:::external
        GitOps["GitOps Tool\n(ArgoCD/Flux)"]:::external
    end

    %% Connections
    CI -->|"Build & publish"| OLM
    CI -->|"Build & publish"| Helm
    CI -->|"Build & publish"| Kustomize
    OLM -->|"Container Registry"| OperatorPod
    Helm -->|"Helm install"| APIServer
    Kustomize -->|"kubectl apply"| APIServer

    GitOps -->|"apply CR YAML"| APIServer
    APIServer -->|"Watch CRs"| OperatorPod
    OperatorPod -->|"Reconcile → create child resources"| APIServer
    OperatorPod -->|"HTTP API calls"| GrafanaDeploy
    ContentFetchers -->|"fetch dashboards"| Content
    Content -->|"cache/store"| Cache
    Controllers -->|"use reconcilers"| Reconcilers
    Reconcilers -->|"generic logic"| GenericRec
    Reconcilers -->|"call client"| Client
    Client -->|"HTTP calls"| GrafanaDeploy
    GitOps -.->|"fetch community dashboards"| GrafanaDotCom

    %% Click Events
    click CI "https://github.com/grafana/grafana-operator/tree/master/.github/workflows/"
    click Build "https://github.com/grafana/grafana-operator/tree/master/Makefile"
    click Build "https://github.com/grafana/grafana-operator/blob/master/Toolchain.mk"
    click Build "https://github.com/grafana/grafana-operator/blob/master/.ko.yaml"
    click Build "https://github.com/grafana/grafana-operator/tree/master/Dockerfile"
    click Hack "https://github.com/grafana/grafana-operator/tree/master/hack/"
    click Helm "https://github.com/grafana/grafana-operator/tree/master/deploy/helm/grafana-operator/"
    click OLM "https://github.com/grafana/grafana-operator/tree/master/bundle/"
    click OLM "https://github.com/grafana/grafana-operator/blob/master/bundle.Dockerfile"
    click Kustomize "https://github.com/grafana/grafana-operator/tree/master/deploy/kustomize/"
    click APIServer "https://github.com/grafana/grafana-operator/tree/master/config/crd/bases/"
    click CRDPatches "https://github.com/grafana/grafana-operator/tree/master/config/crd/patches/"
    click Manager "https://github.com/grafana/grafana-operator/blob/master/main.go"
    click Controllers "https://github.com/grafana/grafana-operator/tree/master/controllers/"
    click Reconcilers "https://github.com/grafana/grafana-operator/tree/master/controllers/reconcilers/grafana/"
    click GenericRec "https://github.com/grafana/grafana-operator/blob/master/controllers/reconcilers/reconciler.go"
    click Client "https://github.com/grafana/grafana-operator/tree/master/controllers/client/"
    click Content "https://github.com/grafana/grafana-operator/tree/master/controllers/content/"
    click ContentFetchers "https://github.com/grafana/grafana-operator/tree/master/controllers/content/fetchers/"
    click Cache "https://github.com/grafana/grafana-operator/blob/master/controllers/content/cache/cache.go"
    click Model "https://github.com/grafana/grafana-operator/tree/master/controllers/model/"
    click Metrics "https://github.com/grafana/grafana-operator/blob/master/controllers/metrics/metrics.go"

    %% Styles
    classDef k8s fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef operatorInternals fill:#90EE90,stroke:#333,stroke-width:1px
    classDef packaging fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
