repository·master·Indexed 23 days ago
https://github.com/grafana/grafana-operatorA Kubernetes operator that automates the lifecycle management of Grafana instances and associated resources, such as dashboards and data sources. It supports both in-cluster and external deployments, providing installation options via Helm, Terraform, and Kustomize. Key features include support for Grafonnet for programmatic dashboard generation, cross-namespace resource syncing, and flexible CRD management modes (immutable and mutable).
The Grafana Operator is a Kubernetes-native tool designed to manage Grafana instances and resources (like dashboards, data sources, and plugins) both inside and outside of Kubernetes. It is optimized for Infrastructure as Code (IaC) and GitOps workflows (e.g., using ArgoCD or Flux CD).
Key benefits include:
The grafana-operator has migrated to the official grafana GitHub organization. For existing users, this migration is designed to be non-breaking:
https://github.com/grafana/grafana-operator to https://github.com/grafana/grafana-operator (within the grafana organization). GitHub provides automatic redirects for the old address.In Grafana Operator v4, the Grafana resource was responsible for finding its dashboards via the dashboardLabelSelector field in its spec.
In v5, this relationship is inverted: the GrafanaDashboard resource is responsible for selecting its target Grafana instance using the instanceSelector field. This allows a single Grafana instance to manage multiple dashboards and enables support for multiple, potentially external, Grafana instances.
v4 Pattern (Push-based selection):
Grafana spec defines which labels to look for in GrafanaDashboard resources.
v5 Pattern (Pull-based selection):
GrafanaDashboard spec defines which Grafana instance labels to match via instanceSelector.
# v4: Selection is in the Grafana spec
apiVersion: integreatly.org/v1alpha1
kind: Grafana
spec:
dashboardLabelSelector:
- matchExpressions:
- { key: app, operator: In, values: [grafana] }
---
apiVersion: integreatly.org/v1alpha1
kind: GrafanaDashboard
metadata:
labels:
app: grafana
# v5: Selection is in the GrafanaDashboard spec
apiVersion: grafana.integreatly.org/v1beta1
kind: Grafana
metadata:
labels:
dashboards: "grafana"
---
apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
spec:
instanceSelector:
matchLabels:
dashboards: "grafana"std.extVar) to inject values into your dashboards. To define these, you must modify your JaaS deployment to include environment variables following the pattern JAAS_EXT_VAR_* (for example, JAAS_EXT_VAR_description).GrafanaManifest resource allows you to manage Kubernetes resources that are not natively implemented in the Grafana operator. It utilizes Kubernetes-style APIs to support resources provided by plugins or other extensions. You can also use the patch capability within a GrafanaManifest to dynamically replace values in the manifest.To sync dashboards to a specific Grafana instance (whether internal or external), use the instanceSelector field on the GrafanaDashboard resource. This selector must match the labels defined on the Grafana instance.
For example, if a Grafana instance has the label dashboards: "external-grafana", the corresponding GrafanaDashboard must have an instanceSelector that selects that label to ensure it is applied to the correct instance.
The Grafana.status.conditions array contains details about specific aspects of the Grafana resource's state. Each condition follows the standard Kubernetes condition pattern.
Fields:
type (string): The type of condition (e.g., Ready) in CamelCase.status (enum): The state of the condition. Values: True, False, Unknown.reason (string): A CamelCase programmatic identifier for the last transition.message (string): A human-readable message describing the transition.lastTransitionTime (string): The timestamp of the last status change (date-time format).observedGeneration (integer): The .metadata.generation that the condition was based on. If this is lower than the current metadata generation, the condition is out of date.The Helm chart supports two modes for managing Custom Resource Definitions (CRDs) via the crds.immutable boolean key:
crds.immutable: true, default): CRDs are installed once from the crds/ directory. They are not updated by Helm upgrades and require manual updates using kubectl apply.crds.immutable: false): CRDs are managed and upgraded alongside the Helm chart using the templates/ directory. This allows for automatic upgrades during helm upgrade.Important: If you are switching from immutable to mutable CRDs for the first time, you must run:
helm upgrade -i --take-ownership.
Both types of CRDs are protected from deletion during a helm uninstall to prevent accidental cascading deletions of managed resources.
The Grafana Operator does not provide a native abstraction for managing Grafana Organizations. The recommended pattern is to deploy multiple independent Grafana instances and manage them via CI/CD.
If you must use organizations within a single instance, you can configure the spec.client.headers map in your Grafana CR to set the X-Grafana-Org-Id header for API calls.
Use spec.instanceSelector to define which Grafana instances the GrafanaAlertRuleGroup should be imported into. This field is immutable.
You can select instances using two methods:
matchLabels: A map of {key, value} pairs. All pairs must match (ANDed logic).matchExpressions: A list of label selector requirements. All requirements are ANDed.matchExpressions operators:
In: values must be non-empty.NotIn: values must be non-empty.Exists: values must be empty.DoesNotExist: values must be empty.