Why a Grafana 11 to 12 upgrade needs a plan before the release
Read the Grafana 12.0 upgrade guide before you change the binary, package or container image. A self-hosted Grafana 11.x instance that other teams rely on for dashboards, alert rules and plugins can break in ways that only show up after the restart. Grafana 12.0, released on May 5, 2025, turns on the failWrongDSUID feature flag by default, so REST APIs and provisioning reject data sources whose UID contains anything other than Latin letters, numbers and dashes. It also removes the remaining Angular plugin support that Grafana 11 had already switched off by default. Both changes touch objects your users see every day, so the work belongs in the plan, not in the post-upgrade cleanup.
Start by inventorying what the instance holds: data source UIDs, provisioning files, dashboards and alert rules that reference those UIDs, and every installed plugin with its version and whether it is Angular-based. Decide who owns each data source and dashboard group, who signs off on the change, and how a broken panel or alert will be reported during the window. Confirm the supported path with the Grafana upgrade guide for v12.0 and the minor release sequence within 12.x, since the upgrade notes for each step decide what must be fixed first. Confirm the exact target minor version against the current release list rather than assuming the first 12.0 build is the right landing point.
Plan the sequence before you schedule the window. The data source UID fixes, the stricter checks in grafana cli plugins install, the annotation table migration and the Angular plugin replacements each have steps that run before or after the upgrade, and some cannot be reversed by a simple downgrade. Write down the backup you will take of the database and configuration, the rollback trigger, and the people who can make the call to roll back. If your team cannot name the owner of each step and each affected dashboard, the upgrade is not ready to start.
What changes in Grafana 12 and what each change asks of your team
This table compares the four changes that most often stop a Grafana 11 upgrade cold, with the impact of each and the action your team needs before or after the upgrade. Read each row as a pre-upgrade checklist item, since the first two can break dashboards, alert rules and automation without any visible error in the UI.
| Change | Impact | Action needed |
|---|---|---|
| failWrongDSUID enforcement | On by default in 12.0. REST APIs and provisioning reject data source UIDs containing anything other than Latin letters, numbers and dashes, so existing data sources with other characters fail to update. | List every data source UID, recreate the non-conforming ones, then repoint the dashboards and alert rules that reference the old UIDs. Read the Grafana 12.0 upgrade guide before changing anything. |
| Stricter plugin version checks in grafana cli plugins install | Plugin installs that previously passed may fail when the plugin's version does not match what the CLI expects for your Grafana release. | Confirm each plugin version against the Grafana 12 release in a staging instance. Update install scripts, Ansible roles or Dockerfiles so they pin compatible versions and fail loudly. |
| Annotation table migration | Annotation data is migrated in the database during the upgrade, so the schema changes and the migration has steps both before and after the upgrade. | Back up the Grafana database first, follow the pre-upgrade steps in the 12.0 guide, then run the post-upgrade steps and check that annotations on key dashboards still render. Confirm the exact steps for your database engine in the guide. |
| Angular plugin retirement | Angular support was turned off by default in Grafana 11 and remaining Angular plugin support is planned for removal in 12. Plugins that still rely on Angular stop working, while legacy core panels such as Graph and Table-old have automatic migrations. | Inventory installed panels and data sources, then find out which use Angular. Let the automatic migrations convert Graph and Table-old panels, and replace or update third-party Angular plugins before the upgrade. The Angular support deprecation page explains the migration path. |
Which parts of the estate are most exposed to the UID and plugin changes
Data sources and dashboards defined as YAML or JSON files and loaded at startup are the easiest exposure to find, because the definitions already live in a repository. Provisioning files carry the data source uid field directly, so a search for UIDs that contain characters outside Latin letters, numbers and dashes shows the affected entries before the upgrade starts. Because the Grafana 12.0 upgrade guide says REST APIs and provisioning reject these UIDs when the failWrongDSUID feature flag is on by default, a provisioning file with a bad UID can stop the instance from loading its configuration after the upgrade.
- Search the repository: Run a pattern search across every provisioning directory for
uid:values and flag any that contain underscores, dots, spaces or other symbols. - Check dashboard JSON: Dashboard files reference data sources by UID inside panels and template variables, so a rename in the data source file must be carried into every dashboard file.
- Review pull requests: Changes should go through the same review path as application code, with the platform owner approving UID changes.
- Sign-off: The platform team owns the provisioning repository, and the owners of each dashboard should confirm their panels still point at the intended data source.
Confirm that the staging instance loads the same provisioning directory the production instance uses before you trust the search results.
Data sources created through the user interface often have UIDs generated by Grafana or chosen by hand during early setup. These objects are invisible to a repository search, so they need to be listed from the running instance. Older manual entries are the most likely to contain characters the new rules reject, and they are also the ones least likely to have an owner who remembers why they exist. The upgrade guide says affected data sources must be recreated, which means dashboards and alert rules that reference them will need to be repointed at the new objects.
- List from the API: Use the data source list endpoint with an administrative token to export every UID, name and type, then check each UID against the allowed character set.
- Record dependencies: For each flagged data source, note which dashboards and alert rules use it, since recreating it will change those references.
- Assign an owner: Each data source should have a named team responsible for its connection details and its consumers.
- Plan the cutover: Recreation and repointing should happen in a maintenance window agreed with the teams that use the affected dashboards.
- Sign-off: The owning team and the platform team should both approve the new UID before dashboards are changed.
Check that the export includes data sources in every organization on the instance, not only the default organization.
Alert rules store the data source UID for each query, so a recreated data source leaves rules pointing at an object that no longer exists. Alert rules are also easy to overlook because they are edited less often than dashboards and may be managed by a different team. The check should cover both alert rules created in the interface and those provisioned from files, since each source needs a different update path. Rules that continue to evaluate against a stale UID can fail silently in the sense that no notification arrives, so verification has to be explicit.
- Export rule definitions: Use the alerting provisioning export to capture every rule with its data source references before any change.
- Compare against the UID list: Match each rule's data source UID against the flagged list from the previous step.
- Test after repointing: Confirm each affected rule evaluates to the expected state and that its notification route still fires.
- Update provisioned rules in Git: Rules defined in files should be changed in the repository, not in the interface, so the next load does not revert the fix.
- Sign-off: The team that receives the alerts should confirm the routing and severity still match their on-call expectations.
Record the rule count before and after the change so the owners can see that none were dropped during the update.
Plugins installed by scripts, container builds or configuration management are a separate exposure because the installed version is set by the automation, not by a person who notices a change. The Grafana 12.0 upgrade guide says grafana cli plugins install applies stricter version compatibility checks, so an install command that worked on 11.x may fail or install a different version on 12. Automation that runs during image builds or on each restart can also hide the problem until a new container starts. Angular plugins that the Grafana Angular deprecation page describes as removed in version 12 need to be identified separately.
- Find install commands: Search Dockerfiles, Ansible roles, cloud-init scripts and Helm values for
grafana-cliand plugin install variables. - Record installed versions: Capture the plugin list from a running instance and compare it against the versions your automation pins.
- Identify Angular plugins: Flag any plugin that still depends on Angular, since it will not run on 12.
- Test the install path: Run the install commands against a staging build on 12 before changing the production image.
- Sign-off: The platform team owns the automation, and the team that depends on each panel or data source should confirm replacements work.
Confirm that the plugin list on staging matches production, because a plugin installed by hand on one node is not visible in the automation.
What to prepare before touching the 11.x instance
The work before a Grafana 11 to 12 upgrade is mostly inventory and safety nets. Each item below answers one question: can you get back to a known state, and do you know what the upgrade will touch? Backup and rollback detail sits in the separate rollback topic, so this section covers what to prepare and check.
Full backup of database and configuration
Take a complete copy of the Grafana database, whether that is SQLite grafana.db or a MySQL or PostgreSQL database, together with the configuration file, provisioning files and installed plugins. Test that the copy can be restored on a separate host before you rely on it. The backup must be restorable, not just present. Record which Grafana version and database engine the backup came from. Rollback steps and downgrade risks are covered in the separate rollback topic.
Inventory of data sources and UIDs
List every data source with its name, type and UID, and note which dashboards, panels and alert rules reference each UID. The Grafana 12.0 upgrade guide makes UID format a hard requirement, so identify any UID that contains characters other than Latin letters, numbers and dashes. Export provisioning files and API responses so you can compare them after the upgrade. Confirm which owners depend on each data source before anything changes.
Dashboard and alert rule inventory
Export dashboards and alert rules as JSON from the instance and record the folder, owner and last-modified date for each. Search exported files for data source references that use the bad UIDs found in the previous step. Keep a count of dashboards and rules per folder so you can confirm the same set exists after the upgrade. Ask dashboard owners to flag panels they consider business critical.
Plugin and Angular panel audit
List every installed plugin with its version and source, and mark each one that relies on Angular. Grafana 11 turned Angular support off by default, and remaining Angular plugin support was planned for removal in version 12. Identify legacy core panels such as Graph and Table-old, which have automatic migrations, and separately flag any community plugin that has no Grafana 12 release. Confirm the plugin install commands and versions you will use after the upgrade.
Staging copy of production
Build a staging instance from a recent production backup, with the same database engine, plugins, provisioning files and data source connections where safe. Run the full upgrade there first and capture the errors, warnings and changed UIDs it produces. Use the same steps and order for production so the staging run is a real rehearsal. Confirm that staging cannot send alert notifications or write to production data sources.
Freeze window with dashboard owners
Agree a change freeze with the teams that own dashboards and alert rules, covering the period from the final backup to the end of post-upgrade checks. Ask owners to avoid editing data sources, folders and rules during that window. Name one person who can approve a rollback and one who runs the checks. Confirm the freeze length and communication channel in writing before the change date.
The order of work for the 11 to 12 move, with checks and rollback points
This sequence moves a self-hosted Grafana 11.x instance to 12 in an order that clears data source UID problems, Angular dependencies and plugin compatibility before production is touched. Each step ends with a check and a point you can roll back to.
Inventory instance, plugins and automation
Record the running Grafana 11.x version, the database engine, the installed plugins and every automation that touches Grafana, including provisioning files, Terraform, Git Sync and scripts that call the REST API. The owner of the instance and the owner of each automation should sign off on the list. Take a full backup of the database, configuration and plugin directory before anything else changes, and confirm you can restore it on a separate host. The step is done when the inventory is stored with the change record and the backup restore has been tested.
Audit data source UIDs against the 12.0 rules
Export the list of data sources and identify any UID that contains characters other than Latin letters, numbers and dashes. The 12.0 upgrade guide says the failWrongDSUID feature flag is on by default, so these data sources will be rejected by the REST APIs and by provisioning. Pull the dashboard and alert rule references to each affected UID so you know the full blast radius. The check is a written list of non-conforming data sources and the dashboards and alert rules that depend on them.
Fix or recreate non-conforming data sources
For each non-conforming data source, decide whether to recreate it with a conforming UID or keep the existing connection and change the identifier through a controlled edit. Recreating a data source changes its UID, so every reference must be repointed in the next step. Apply the change on the staging copy first and keep the original data source in place until the dependent objects are verified. Confirm the exact procedure, flags and API calls in the 12.0 upgrade guide before running them. The check is a clean list of data sources that pass the UID rule in staging.
Repoint dashboards and alert rules to new UIDs
Update dashboard panels, template variables and alert rule queries so they reference the conforming UIDs. Review alert rules with the team that owns the notification routing, because a rule that silently stops querying its data source can stop firing without an error you would see on the dashboard. Compare the number of dashboards, panels and alert rules before and after the change and open each alert rule to confirm its query still resolves. The check is that every alert rule evaluates against a live data source in staging and no panel shows a missing data source error.
Replace Angular panels and plugins
Grafana 11 turned off Angular support by default and the plan was to remove remaining Angular plugin support in version 12. Identify Angular panels and plugins from the inventory and replace them with supported versions or alternatives. For legacy core panels such as Graph and Table-old, use the automatic migrations described in the Angular deprecation documentation and review each migrated panel by eye, since automatic conversion does not guarantee identical output. Keep a record of each plugin version you replaced. The check is a staging dashboard review where no panel depends on Angular rendering.
Upgrade staging and run the annotation migration
Upgrade a staging copy of the instance, built from the production backup, to 12.x. Follow the annotation table migration steps in the 12.0 upgrade guide in the order the guide gives them, including the steps that apply before and after the upgrade. Check that existing annotations appear on dashboards with the expected times, tags and text. Record how long the migration took on your data so you can plan the production window. The check is a staging instance with a passing annotation review and a documented rollback to the 11.x backup.
Validate CLI plugin installs on staging
The 12.0 upgrade guide describes stricter version compatibility checks in grafana cli plugins install. Run the plugin install and update commands your automation uses against staging, using the exact flags the guide lists, and confirm each plugin installs at a version compatible with 12.x. Update the scripts, provisioning files or container build steps that fail the new checks. The check is a clean run of every plugin install in the inventory with no compatibility errors recorded in the logs.
Upgrade production with a tested rollback
Schedule the production change using the staging results and the rollback plan. Take a fresh backup immediately before the upgrade, stop writes where your process allows, apply the upgrade and then run the same UID, dashboard, alert rule, annotation and plugin checks you ran in staging. Keep the 11.x backup and the rollback procedure available until the checks pass and users have confirmed their dashboards. The check is a signed-off production validation list, and the rollback decision point is recorded before the change window closes.
What makes the 11 to 12 upgrade take longer for some teams
The biggest driver is how many data sources have UIDs that the new release rejects. Grafana 12.0 turns on the failWrongDSUID feature flag by default, so REST APIs and provisioning reject any data source UID containing characters other than Latin letters, numbers and dashes. Each affected data source has to be recreated and every dashboard and alert rule that points at it has to be repointed. Count the affected data sources first, then count the dashboards and alert rules that reference each one. A small instance with a handful of bad UIDs can finish this in a single pass, while a shared instance with years of hand-built dashboards can turn it into a long review. Export your dashboards and alert rules and search them for the old UIDs before you schedule the window.
How the instance was configured changes the effort more than its size. Teams that manage data sources, dashboards and alert rules through provisioning files or as-code tooling can correct the UIDs in version control, test the change in a staging instance and roll it out in one step. Teams that built everything by hand in the user interface have to find each object, recreate it and check that alerts still fire against the correct source. Ask who owns each data source and whether it is defined in a provisioning file, because that answer tells you how much of the work is a text edit and how much is manual rebuilding. Plugins without a Grafana 12 replacement also add work, since the Angular plugin retirement planned for version 12 may leave some panels or data sources with no working path. Confirm each plugin's status with its maintainer before you commit to a date.
Two smaller items can still extend the plan. Scripts that call grafana cli plugins install now face stricter version compatibility checks, so any automation that pins or installs plugins should be tested against a staging copy before production. The annotation table migration also runs against your database, so a large annotation history will take longer to migrate and needs a verified backup and the pre-upgrade steps in the upgrade guide. Check the size of your annotation table and the database backup window early, because both determine how long the database is unavailable to users.
Effort drivers and how each one moves the schedule
This table lists the factors that most change how long a Grafana 11 to 12 upgrade takes and how much rework it creates. Read each row as a question to answer about your instance before agreeing on a timeline. The main takeaway is that UID remediation, Angular plugin replacement and the annotation migration usually set the critical path, while HA ordering and environment count multiply the effort.
| Driver | Why it moves the schedule | What to confirm with the team |
|---|---|---|
| UID remediation scope | The failWrongDSUID flag is on by default in 12.0, so data sources with UIDs containing characters other than Latin letters, numbers and dashes must be recreated and the dashboards and alert rules that point to them repointed. | How many data sources have non-conforming UIDs, and how many dashboards and alert rules reference each one? |
| Angular plugin replacement | Grafana 11 turned off Angular support by default and planned to remove remaining Angular plugin support in 12. Each Angular panel or data source needs a replacement, an automatic migration where one exists, or removal before the upgrade. | Which installed plugins and panels still rely on Angular, and who owns the replacement decision for each? |
| Plugin version checks in automation | Stricter compatibility checks in grafana cli plugins install can make existing install scripts, Dockerfiles, Helm values or configuration management fail on the new version. | Which scripts, images or provisioning files install plugins, and do they pin plugin versions compatible with 12.0? |
| Annotation table size and migration window | The annotation table migration has steps before and after the upgrade. Large annotation tables take longer to migrate, so the database downtime or read-only window grows with data volume. | How many rows the annotation table holds, and how long a full backup and test migration takes on a copy of production data? |
| Provisioning maturity | Data sources, dashboards and alerting defined as YAML or JSON files can be corrected once and reloaded across environments. Instances configured by hand need each UID fix and repointing done in the UI, which adds review time. | Are data sources, dashboards and alert rules provisioned from files or Git, or edited manually in the UI? |
| Number of environments | Each environment repeats the UID audit, plugin checks, annotation migration and rollback test. Development and staging copies also need the same plugin set and data source connections to be meaningful. | How many Grafana instances exist, which are production, and whether staging mirrors production's databases and plugins? |
| HA setup and upgrade order | Two or more active-active servers share one MySQL or PostgreSQL database behind a load balancer. Nodes must be upgraded in a controlled order, with the database backed up first, and the team should check that alerting and Grafana Live behave as documented during the mixed-version period. | How many nodes run, which database backs them, how traffic is drained from each node during the upgrade, and whether alerting already has the extra configuration to avoid duplicate notifications? |
Questions teams ask before a Grafana 11 to 12 upgrade
What does a Grafana 11 to 12 upgrade cost, and what drives the quote?
The cost depends on the written scope, which is agreed before work starts, and on how much of your estate needs action. Most of the effort sits in three places: data sources whose UIDs fail the new format rule, dashboards and alert rules that reference them, and installed plugins that need checking against the stricter CLI version checks. Ask for a quote that separates the audit, the remediation of data sources and references, the annotation table migration, the upgrade rehearsal, and the post-upgrade verification. Also ask which items are one-time work and which recur, such as a retainer for later minor releases. DeployOpen does not publish a price list, so the quote follows from your scope. Ask your own team to count data sources, dashboards, alert rules and plugins first, since those counts are the inputs a quote needs.
How long does the upgrade take, and does the audit set the schedule?
Yes, the audit sets most of the schedule. Until someone inventories data sources, dashboards, alert rules, plugins and automation, nobody can say how many UIDs need replacing or how many dashboards need repointing. Duration therefore depends on the number of affected objects, how many teams own them, and whether provisioning files and Terraform or Git-managed definitions also reference old UIDs. Ask for the schedule to show the audit as its own phase with a written output, then rehearsal on a copy of your production database, then the production window. Confirm with your change board how long a freeze must last, and confirm the upgrade notes for your exact target version before you commit to dates.
Can our in-house team run the Grafana 12 upgrade alone?
A capable platform team can do it alone if it has time, access to the database and provisioning repository, and clear ownership of dashboards. The harder parts are usually not the upgrade command. They are finding every reference to a non-conforming data source UID, recreating those data sources, repointing dashboards and alert rules, and checking that nothing silently stops firing. Ask whether your team has done a major Grafana upgrade before, whether it can rehearse against a restored backup, and who signs off on alert behavior after the change. A partner is most useful for the audit, a rehearsal, and an independent check of the result, while your team keeps ownership of the running system.
What do dashboard owners and the platform team need to provide?
Dashboard owners and the platform team each have a defined part. Platform engineers provide access to the Grafana database or backups, the provisioning files or as-code repository, the plugin list, and the change window. Dashboard owners confirm which dashboards and alert rules they rely on, which ones are business critical, and whose panels can be tested after repointing. Both groups should agree on a rollback plan before the window. Plan for owners to review their own dashboards after the change, because only they can judge whether a panel shows the right series. Ask for a named contact per team and a sign-off step in the scope document.
Will our Angular dashboards and plugins break after the upgrade?
They can. Grafana 11 turned off Angular support by default, and the plan was to remove remaining Angular plugin support in version 12. The Grafana Angular deprecation page points to automatic migrations for legacy core panels such as Graph and Table-old, so some panels may convert without manual work. Community or custom Angular plugins need a check against their vendor or author, and some will need replacing. Ask for an inventory of every panel type and plugin in use, mark each as migrated, replaced or unsupported, and test those dashboards on a copy before production. Confirm the exact behavior for your target release in the Grafana documentation.
Does Grafana Enterprise or Grafana Cloud change the upgrade work?
The core technical steps are the same for self-hosted open source and Enterprise installs, but your authentication, provisioning and access model may differ. Authentication features such as SAML, team sync, active sync and SCIM are available only in Grafana Enterprise and Grafana Cloud, so an Enterprise installation has more configuration to re-verify after the upgrade. Grafana Cloud moves hosting and some upgrade responsibility to the vendor, which changes the scope and the questions you ask. Confirm your edition and license terms before you scope the work. Grafana Cloud pricing is listed on the Grafana pricing page, and Enterprise pricing requires a direct commercial quote from Grafana Labs.
Which versions to move through and what the support windows mean
Plan the move from 11.x to a specific 12.x minor and patch release, and confirm that target in the release notes before the change window opens. Grafana Labs ships major releases once a year, in April or May, and Grafana 12.0.0 was released on May 5, 2025. Minor releases arrive every other month and patch releases at least monthly. The GitHub releases page also lists 13.x versions, so confirm which 12.x minor is current when you plan, and decide whether your project lands on 12.x now or includes a later step to 13 as a separate change.
Each minor release is supported for 9 months, and the last minor release of a major version is supported for 15 months. A minor you choose today can therefore age out of support before a slow approval process finishes. Check the support end date for your chosen minor against your change calendar. If your team cannot absorb frequent minor changes, the longer window on the last minor of a major gives you more room, but you still need to apply its patch releases on schedule.
Before you pick a target, record your current 11.x version, the 12.x minor you intend to run and that minor's support end date. Then check all three against the latest release notes and the Grafana upgrade guidance on when to upgrade. Treat patch releases as routine maintenance inside your standard window. Treat the move to a new minor or major as a planned change with a verified backup and a test run on a copy of your instance.
How DeployOpen scopes, delivers and supports the Grafana 11 to 12 upgrade
DeployOpen plans and carries out self-hosted Grafana upgrades inside your own infrastructure, starting with a written, fixed scope. We inventory data source UIDs, dashboards, alert rules, plugins and the annotation table before any change, then document the work so your team can run Grafana afterward.
How we scope
- We inventory your Grafana version, database, installed plugins, provisioning files and automation before agreeing scope.
- The written scope lists which data source UIDs, dashboards and alert rules need repointing or recreation.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
How we build
- We test the upgrade on a copy of your instance, including a check of the failWrongDSUID behavior and stricter plugin installs.
- We correct non-conforming data source UIDs in provisioning files and repoint dependent dashboards and alert rules.
- We run the annotation table migration steps before and after the upgrade and verify results against a backup.
How we hand over
- You receive a runbook covering pre-upgrade backups, each change made, and the verification checks performed.
- We document plugin versions, replaced Angular panels and any remaining items your team must confirm.
- Configuration changes are recorded so provisioning and automation match the upgraded instance.
How we support
- Ongoing support, upgrades for later minor releases and continuous testing are available as a retainer.
- Support scope and response arrangements are agreed in writing, so you know what is covered before you need it.
- We can plan the next upgrade step as Grafana publishes new minor and patch releases under its support window.
