Managing Grafana with the Grafana Operator

When a Grafana Operator setup pays off for your team

Choose the Grafana Operator when several Grafana instances or environments are changed by hand and nobody can show who changed a dashboard, data source or alert rule, or why. The Operator runs in a Kubernetes cluster and manages Grafana through custom resources for the instance, dashboards, data sources and alerting, and it can also target Grafana instances that run outside the cluster. Because those resources are ordinary Kubernetes objects, a change becomes a file in a repository, a pull request a second person can review, and a reconciliation that applies the same definition to each environment. The payoff grows with the number of instances, the number of people editing them and the number of changes each month. A single instance edited by two people may not justify the extra moving parts.

Grafana already has a provisioning baseline. The Grafana provisioning documentation describes defining data sources, dashboards, plugins and alerting resources in YAML or JSON files that load at startup, and it lists further as-code options including Terraform and Git Sync. Those options work without Kubernetes, so the first question is whether your platform already runs Kubernetes and whether you want Grafana configuration to follow the same reconciliation loop as your other workloads. The Operator sits between the file-based baseline and a general-purpose tool: it expresses the same kinds of definitions as Kubernetes objects that a controller keeps in the state you declared. Before committing, confirm with the Operator's own documentation which Grafana versions, resource kinds and drift behavior it supports, since this section does not set those details.

Decide on the Operator only after you have answered three questions. Do you already run Argo CD or Flux, so Grafana resources can sync from Git through a tool your team knows? Who approves a change to a production dashboard or alert rule, and will that approval happen in a pull request? Can your team operate the Grafana database and secrets in a way the controller can reference? If the answer to the first is no and Grafana is a single instance on virtual machines, Terraform or Git Sync may deliver most of the review benefit with less to run. Ask any partner or vendor to map each environment to a resource model and to show the rollback path before work starts.

Which custom resources to use and when each fits

This table compares the Grafana Operator resources for defining a Grafana instance, dashboards, data sources and alerting, along with the choice between an in-cluster and an external instance. Read each row for what the resource owns and where it fits, then confirm field names and API versions against the Operator release you install. The main takeaway is that where the instance runs determines how much of the stack your cluster operations team must carry.

Resource	What it manages	When it fits	Main trade-off
Grafana (in-cluster)	Deploys and manages a Grafana instance inside the cluster, including its configuration and database connection.	One team owns Grafana and wants its lifecycle tied to the cluster's GitOps workflow.	Upgrades, database and secrets become cluster operations. Production needs MySQL or PostgreSQL.
Grafana (external)	Connects to an existing Grafana instance through its API and manages resources there without deploying it.	Grafana runs on virtual machines, another cluster or a shared platform team's instance.	Access depends on API credentials and network reach, so unreachable instances stay unmanaged.
Dashboard	Dashboard definitions stored as Kubernetes objects and applied to a target Grafana instance.	Dashboards are reviewed and versioned in Git like other platform configuration.	Large dashboard JSON is hard to review, and manual UI edits can drift from Git.
Data source	Connection settings for metrics, logs, traces and SQL systems, applied to a target instance.	Teams need stable, reviewed connections to shared backends across environments.	Credentials must come from Kubernetes Secrets, and each environment needs its own endpoints.
Alerting resources	Alert rules, contact points and notification policies defined as declarative objects.	Alerts follow the same review and promotion path as application and platform changes.	High availability setups need extra alerting configuration to avoid duplicate notifications.
Argo CD or Flux	Applies the custom resources from Git to the cluster and reports sync status.	Your team already runs either tool for other platform components.	Sync order must ensure instances exist before dashboards and data sources that depend on them.

Argo CD or Flux for Grafana resources

If Argo CD already manages your clusters, the simplest path is usually to add the Grafana Operator manifests to the Git repositories Argo CD already watches. Argo CD is Apache-2.0 licensed, comes from the Argo project, and has a release cadence in which only the three most recent minor versions receive patch releases, so the controller version you run needs to stay on that list. Access control follows Argo CD's own model: SSO runs through the bundled Dex or directly through an existing OIDC provider, and RBAC decides who can sync or view applications.

Application boundaries: Put Grafana custom resources in an Argo CD project that limits source repositories, destination namespaces and resource kinds.
Repository definitions: Argo CD 3.0 removed repository entries from the argocd-cm ConfigMap, so define each Git repository as a Kubernetes Secret.
RBAC claims: Dex-based RBAC in 3.0 uses the federated_claims.user_id claim, so check that existing role mappings still match.
Admin account: Use the built-in admin user only for setup and disable it with admin.enabled set to false after SSO works.
Sync permissions: Confirm which groups can sync Grafana applications, since update and delete rights apply to the application itself.

Confirm your Argo CD minor version against the current release process before adding the Grafana resources, and check the 2.14 to 3.0 upgrade notes if any cluster still runs an older release.

How to set up the Grafana Operator through GitOps

This sequence takes a Kubernetes cluster from version confirmation to a Grafana instance managed from Git, with its data sources, dashboards and alerting resources reconciled and checked for drift. The result is a Grafana configuration your team can review, roll back and audit like any other infrastructure change.

Confirm Kubernetes version and support status
The platform engineer checks the cluster's Kubernetes minor version against the upstream release page and confirms it is still within the supported window before adding anything to it. Kubernetes maintains only the three most recent minor releases, so an end-of-life cluster should be upgraded first. Confirm the Grafana Operator's supported Kubernetes versions and its custom resource definition (CRD) versions in the project's own documentation, since these are not covered here. You know this step is done when the cluster version, the supported-version list and the chosen Operator release all match in a written record.
Install the Operator through the chosen GitOps tool
The platform team commits the Grafana Operator manifests, or the Helm or Kustomize source the Operator documents, to a Git repository that Argo CD or Flux watches. Argo CD and Flux both reconcile from Git, so the install itself becomes a tracked change rather than a manual apply. Confirm the install method and the CRD versions in the Operator documentation before the first sync, because they change between releases. You know this step is done when the Operator deployment reports healthy in the GitOps tool and its CRDs are registered in the cluster.
Define the Grafana instance and its database
The platform team writes a Grafana custom resource that sets the replica count, image version, ingress and a secret reference for the database credentials. Grafana production should use MySQL 8.0 or later, or PostgreSQL 12 or later, because the default SQLite store does not scale for production or high availability. Store the database password in a Kubernetes Secret or an external secrets store, never in the Git repository in plain text. You know this step is done when the Grafana pods start, connect to the external database and pass their health checks.
Add data sources and dashboards from Git
The team adds GrafanaDatasource and GrafanaDashboard resources to the same repository, with each data source pointing at a credential Secret and each dashboard stored as JSON or generated from a reviewed source. Changes go through pull requests so an engineer reviews each new data source and panel before it reaches the instance. Confirm which fields the Operator version supports for each resource type. You know this step is done when the data sources show as connected and the dashboards load in Grafana with the same content as the committed files.
Add alerting resources to the repository
The team defines alert rules, contact points and notification policies as custom resources in the same Git repository, so alert routing changes are reviewed like any other code change. Test notification delivery with a non-production contact point before routing real alerts, and confirm how the Operator handles alerting in a high-availability setup, since duplicate notifications are a known risk. You know this step is done when a test alert fires, reaches the intended contact point once, and the rule appears in Grafana with the same definition as the committed file.
Verify reconciliation and drift
The platform engineer checks that the GitOps tool reports every Grafana resource as synced and healthy, then makes a deliberate change in the Grafana UI to confirm the controller reverts it or flags it, depending on the sync policy chosen. Review how the Operator and the GitOps tool handle manual edits and deletions before relying on either behavior. You know this step is done when a manual change is detected or reverted as the policy predicts, and the resource status in the cluster matches the repository.

Securing secrets, access and the GitOps pipeline

A Grafana Operator setup puts Grafana, its data sources and its alerting rules into Git and a Kubernetes cluster, so the same controls protect both. Credentials, access rights, cluster secret storage, Grafana's own hardening and the review path for changes each need an owner and a check.

Keep credentials out of Git

Data source passwords, API tokens and the Grafana admin password should live in Kubernetes Secrets or an external secret store, with the Git repository holding only references. Any plain value committed to a manifest stays in history even after removal, so scan every commit for credentials before the first sync. Confirm which secret mechanism your team uses and who can read each Secret.

Least-privilege RBAC for Grafana resources

Decide who may create, change or delete Grafana, dashboard, data source and alert rule resources, and bind those rights to narrow Kubernetes roles per namespace. Read access for viewers and write access for pipeline service accounts should be separate grants. Review these bindings whenever a team joins, leaves or changes its alerting ownership.

Disable the Argo CD admin account

If you run Argo CD to deliver these resources, use the built-in admin user only for first setup. After SSO or local users are configured, set admin.enabled to false so no shared password can change deployments. Check that at least one SSO group keeps a break-glass path before you disable it.

Encrypt Secrets and limit list access

Kubernetes stores Secrets unencrypted in etcd by default, so configure encryption at rest for the cluster before storing Grafana admin or data source credentials. Restrict list and watch on Secrets to the operator and pipeline service accounts, since those verbs expose values across a namespace. Confirm encryption status with your cluster provider or distribution.

Harden the Grafana instance

The Grafana instance the operator manages still needs its own settings reviewed: secure and SameSite cookies, a Content Security Policy, Trusted Types, hidden version strings, authenticated metrics endpoints and domain verification against DNS rebinding. Set these in the Grafana custom resource or config so they survive redeployment. Test OAuth sign-in after each change, since cookie and redirect settings can break it.

Protect the Git branch and review path

Git is the source of truth for what Grafana runs, so protect the main branch, require pull request review for dashboard and alert changes, and block direct pushes from humans. Pair this with signed commits or tags if your policy requires them. Confirm which reviewers can approve changes to alert routing, since a bad route can silence a production page.

How reconciliation handles drift, deletes and external instances

Plan for reconciliation behavior before you put the Grafana Operator under GitOps control, because a Git repository only describes the desired state. When someone edits a dashboard in the Grafana UI, the Operator's job is to compare that live object with the custom resource in Git and push the declared version back, which is the drift you want the team to see. Confirm in your chosen Operator release whether edits made in the UI are reverted automatically, flagged only in status, or left alone until the next sync, and whether your Argo CD or Flux sync policy self-heals the same object at a different interval. Two controllers fighting over one dashboard produces churn that looks like a Grafana bug, so decide early which system owns each resource type.

Deletes need a separate decision. Removing a dashboard or data source manifest from Git should, in a typical GitOps setup, remove the matching object from the Grafana instance, but whether that happens depends on the finalizer and prune settings in your release and on whether the Operator or the GitOps tool issues the delete. Confirm what happens to dashboards that were created manually in the UI, since the Operator may not own them at all. A resource that points at a data source that does not exist yet will typically sit in an error or pending state until the data source reconciles, so order the data source, the Grafana instance and any dependent alert rules in your sync waves or Flux dependencies, and test that ordering on a disposable cluster.

External instances add another layer. If the Operator manages a Grafana you did not deploy through its own Grafana resource, confirm which credentials it uses, how it authenticates against the instance API, and what it does when the instance is unreachable. Separately, the Grafana high availability documentation notes that alerting needs additional configuration to avoid duplicate notifications when two or more active-active servers share a database, and that Grafana Live has limitations in HA. Confirm with the Operator documentation whether alert rule resources are reconciled once per instance or once per replica, and test that a single alert produces a single notification before go-live.

Limits to confirm before you commit

Each limit below changes what a GitOps workflow for Grafana can rely on, from the versions you can pin to the features your identity design needs. Confirm them against your target Kubernetes, Argo CD or Flux, and Grafana editions before you write the first custom resource.

Operator and Grafana version match

The Grafana Operator reconciles custom resources against the Grafana API of a specific release, so an operator upgrade and a Grafana upgrade can drift apart. Ask the project for its compatibility matrix and check which Grafana minor versions each operator release is tested against. Grafana minor releases arrive every other month, and each minor is supported for 9 months, so plan operator and Grafana upgrades on one shared calendar.

Kubernetes minors still in support

The Kubernetes project maintains only the three most recent minor releases, so your cluster version sets how long the whole GitOps control plane stays supported. As of September 2026, 1.37 ends support on October 28, 2027, 1.36 on June 28, 2027 and 1.35 on February 28, 2027. Check your target minor against the Flux installation minimums and the Operator manifests you plan to run, and schedule the cluster upgrade well before end of life.

Enterprise-only identity features

SAML, team sync, active sync and SCIM provisioning are available only in Grafana Enterprise and Grafana Cloud. LDAP, generic OAuth, Entra ID, Okta and the other OAuth providers work in every edition. If your GitOps design expects identity groups to map to Grafana teams automatically, that mapping does not exist in open-source Grafana, so confirm the group-to-role mechanism before you write the access custom resources.

Grafana Live limits in HA

Grafana high availability runs two or more active-active servers behind a load balancer on a shared MySQL or PostgreSQL database. The docs note that Grafana Live has limitations in this topology, so live-streaming panels on dashboards delivered by the operator need testing at your planned replica count. Alerting also needs additional configuration to avoid duplicate notifications, which affects how alert resources reach contact points on each node.

Argo CD 3.0 repository configuration

Argo CD 3.0 removed repository configuration from the argocd-cm ConfigMap, so repositories must be defined as Kubernetes Secrets. Dex-based RBAC also moved to the federated_claims.user_id claim. If your runbooks or older manifests still use the ConfigMap, the Grafana resources will not sync as expected. Confirm the Argo CD line you will run, since the latest patch published in October 2026 was v3.5.5, and test the repository Secrets in a non-production cluster first.

No official vendor partnership

DeployOpen is not an official partner, reseller or certified provider of Grafana Labs, the Grafana Operator project, Argo CD or Flux. Ask any provider, including us, which vendor relationships exist and which support terms come from the upstream project and which come from the implementer. Get in writing who answers for Operator defects, Grafana security fixes and Kubernetes version questions, and under which contract each layer is covered.

Questions teams ask before running the Grafana Operator

How much effort does a GitOps migration to the Grafana Operator take?

The effort depends mostly on how many dashboards, data sources, folders and alert rules already exist and how they are created today. Teams that build dashboards by hand in the UI need time to export or rebuild them as custom resources, review them, and agree on folder and naming rules before anything is moved. Other drivers are the number of Grafana instances, whether the Grafana Operator will manage external instances or one it creates, how many people must approve changes, and how much of the Argo CD or Flux setup already exists. Ask any provider for a written scope that lists the resource types, instance count, cluster count and cutover approach, because those items set the quote and the schedule.

Can our in-house team run the Grafana Operator without outside help?

Yes, many teams can, provided they already run Kubernetes workloads and have someone who can review Git-based changes. The skills you need are Kubernetes resource management, a GitOps controller, basic Grafana administration and a plan for secrets. The harder parts are the first build, the design of repository layout and access rules, and the first few incidents where a resource does not reconcile. Consider an outside partner for the initial design and cutover, then move to an in-house run book. Any quote should separate one-time build work from recurring support, which can be handled through a retainer if you want ongoing help.

What do we need to provide: Git, cluster access and Grafana admin rights?

You will need a Git repository that your GitOps controller can read, a Kubernetes cluster where the operator and Grafana can run, and an account with rights to create the namespaces, custom resources and secrets involved. For existing instances, you will also need an admin or service account on each Grafana server so the operator can manage it. Expect to supply a named technical owner, change approval rules and a test environment. Keep the access you grant to the implementation team time-limited and recorded. Confirm in the quote which of these items the partner needs during design and which are needed only at cutover.

Should we choose Argo CD or Flux for the Grafana Operator workflow?

Either tool can deliver the custom resources from Git to the cluster, so the choice usually depends on what your platform team already runs and how it prefers to work. Argo CD ships a web UI, manages multiple clusters and integrates SSO over OIDC, OAuth2, LDAP and SAML 2.0 with RBAC, and it is Apache-2.0 licensed with no paid edition from the project. Flux is also Apache-2.0 licensed, built from GitOps Toolkit controllers, uses Kubernetes RBAC with impersonation for multi-tenancy, and supports Helm, Kustomize and OCI artifacts. Check your current cluster and Kubernetes version against each project's supported versions before deciding.

How do we bring existing hand-built dashboards under GitOps control?

Start by inventorying which dashboards, data sources and alert rules are used, who owns them, and which ones are safe to retire. Then export the important ones and convert them into custom resources or provisioning files, keeping the same UIDs where possible so links and alert references do not break. Plan a period where both the UI and Git may be used, and decide how UI edits are blocked or reconciled afterward. Grafana provisioning loads data sources, dashboards, plugins and alerting resources from files at startup, which is useful background for this migration. Ask any partner how they will handle dashboards that users changed directly and how they will test each converted item.

What does Grafana Enterprise cost compared with open source if we need SAML or SCIM?

SAML, team sync, active sync and SCIM provisioning are available only in Grafana Enterprise and Grafana Cloud, according to the Grafana authentication documentation. Open-source Grafana supports LDAP, generic OAuth, Entra ID, Okta, GitHub, GitLab, Google OAuth, auth proxy and JWT. Grafana Enterprise is a commercial, non-AGPL option, so you should obtain its license terms from Grafana Labs directly. Grafana's pricing page lists a Pro tier starting with a 19 US dollar monthly platform fee plus usage and an Enterprise tier with a minimum commitment of 25,000 US dollars per year, but those figures apply to Grafana Cloud. Ask Grafana Labs for an Enterprise quote for a self-hosted instance, and confirm whether your identity provider can meet your needs through an open-source method first.

What does a fixed-scope DeployOpen engagement include for the Grafana Operator?

Most DeployOpen engagements are fixed-scope, so the scope, deliverables and timeline are agreed in writing before work starts. For this topic, a written scope typically covers the target clusters and Grafana instances, the GitOps tool and repository layout, the custom resources to build or migrate, access and secrets handling, testing and cutover steps, and handover documentation. Ongoing support, upgrades and continuous testing are available as retainers. DeployOpen does not publish a price list, so a quote follows from the written scope. Ask for the exclusions in writing, including any changes to your Grafana Enterprise licensing or identity provider configuration.

Where to confirm Grafana and GitOps behavior

Start with the Grafana provisioning documentation before writing any custom resource that touches data sources, dashboards or alerting. The provisioning model defines what Grafana itself loads from YAML or JSON files at startup, and the Operator's resources have to produce output that Grafana accepts. Check the Grafana provisioning docs for the exact file formats and loading behavior of the Grafana version you run, then compare them with what the Operator generates in your cluster. Confirm that the version of Grafana you pin is one the Operator supports, because the Operator and Grafana releases move on separate schedules.

The Operator's own release notes are the authority for CRD fields, defaults and removals, so read them for each Operator version before you upgrade and before you change a manifest. Do not copy field names from older examples or blog posts. For the GitOps layer, use the Argo CD documentation for sync, health and application behavior, and the Flux documentation for its controllers and reconciliation model. Confirm the controller version your team has chosen, since Argo CD and Flux each publish their own upgrade notes and minimum Kubernetes requirements.

Check Kubernetes compatibility against the Kubernetes release pages before each cluster change, because the Argo CD and Flux installation guides set their own minimum supported Kubernetes patch versions and advise against running end-of-life releases in production. Record the Kubernetes minor version, the GitOps controller version, the Operator version and the Grafana version together in your change record. Ask your platform team or partner to show which of these combinations has been tested in your own environment, since a combination that installs cleanly may still fail on the first CRD upgrade.

How DeployOpen scopes and delivers Grafana as code

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, and that includes Grafana managed through the Grafana Operator. Each engagement starts from a written, fixed scope that defines the Grafana instances, the Git repositories, the GitOps controller and the handover material before any build begins.

How we scope

Inventory which Grafana instances the operator will own and which external instances it will only manage.
Record the Kubernetes clusters, namespaces and Git repositories that hold Grafana custom resources.
Agree the data sources, dashboards and alerting resources that move into version control in the first phase.
Confirm the GitOps controller choice, Argo CD or Flux, along with its access model and tenancy boundaries.
Define the database, ingress and identity assumptions the written scope depends on and who owns each one.

How we build

Write Grafana, dashboard, data source and alerting custom resources in your repository layout and naming conventions.
Wire secrets through your chosen secrets mechanism so no credentials sit in plain manifests in Git.
Test reconciliation in a non-production cluster, including drift correction and deletion behavior of managed resources.
Check operator and Grafana version compatibility against the Kubernetes version your clusters run.
Verify that changes made in the UI are either blocked or clearly reconciled back to the declared state.

How we hand over

Document the repository structure, the reconciliation flow and the steps to add a dashboard or data source.
Provide runbooks for rolling back a bad commit and for recovering the operator after a cluster failure.
Walk your platform and Grafana teams through the change process, review gates and ownership of each resource type.
Deliver test evidence from the non-production run, so your team can repeat it before future upgrades.
Hand over the list of open decisions, such as external Alertmanager routing, for your own sign-off.

How we support

Support after handover is available as a retainer covering patches and operator version upgrades on your schedule.
Retainers can include periodic review of the Grafana version, operator release notes and Kubernetes support timelines.
Retainer scope, response expectations and included work are written down before the retainer starts.
Changes to the Grafana or GitOps setup after handover are scoped as new written work when they fall outside the retainer.
Ask for the retainer terms in the written quote so you can compare them against your in-house capacity.