# Upgrade Guide # Upgrade to Grafana v11.0 {{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes # Upgrade to Grafana v11.1 {{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes # Upgrade to Grafana v11.2 {{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes ### Grafana data source UID format enforcement **Ensure that your data source UIDs follow the correct standard** We've had a standard ways to define UIDs for Grafana objects for years (at least [since Grafana v5](https://github.com/grafana/grafana/issues/7883)). While all of our internal code complies to this format, we didn't yet have strict enforcement of this format in REST APIs and provisioning paths that allow the creation and update of data sources. In Grafana v11.1, we [introduced](https://github.com/grafana/grafana/pull/86598) a warning that is sent to Grafana server logs every time a data source instance is being created or updated using an invalid UID format. In Grafana v11.2, we [added](https://github.com/grafana/grafana/pull/89363/files) a new feature flag called `failWrongDSUID` that is turned off by default. When enabled, the REST APIs and provisioning start rejecting any requests to create or update data source instances that have an incorrect UID. In Grafana v11.5, we're going to turn feature flag `failWrongDSUID` on by default, but there will still be an option to turn it off. In Grafana v12, this will be the default behavior and will not be configurable. #### Correct UID format You can find the exact regex definition [in the grafana repository](https://github.com/grafana/grafana/blob/c92f5169d1c83508beb777f71a93336179fe426e/pkg/util/shortid_generator.go#L32-L45). A data source UID can only contain: - Latin characters (`a-Z`) - Numbers (`0-9`) - Dash symbols (`-`) #### How do I know if I'm affected? - You can fetch all your data sources using the `/api/datasources` API. Review the `uid` fields, comparing them to the correct format, as shown [in the docs](https://grafana.com/docs/grafana/latest/developers/http_api/data_source/#get-all-data-sources). Following is a script that can help, but note that it's missing authentication that you [have to add yourself](https://grafana.com/docs/grafana/latest/developers/http_api/#authenticating-api-requests): ``` curl http://localhost:3000/api/datasources | jq '.[] | select((.uid | test("^[a-zA-Z0-9\\-_]+$") | not) or (.uid | length > 40)) | {id, uid, name, type}' ``` - Alternatively, you can check the server logs for the `Invalid datasource uid` [error](https://github.com/grafana/grafana/blob/68751ed3107c4d15d33f34b15183ee276611785c/pkg/services/datasources/service/store.go#L429). #### What do I do if I'm affected? You'll need to create a new data source with the correct UID and update your dashboards and alert rules to use it. #### How do I update my dashboards to use the new or updated data source? 1. Go to the dashboard using the data source and update it by selecting the new or updated data source from the picker below your panel. 1. Update the dashboard's JSON model directly using search and replace. Navigate to [dashboard json model](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/view-dashboard-json-model/) and carefully replace all the instances of old `uid` with the newly created `uid`. {{< figure src="/media/docs/grafana/screenshot-grafana-11-datasource-uid-enforcement.png" alt="Updating JSON Model of a Dashboard">}} #### How do I update my alert rules to use the new or updated data source? Open the alert rule you want to adjust and search for the data source that is being used for the query/alert condition. From there, select the new data source from the drop-down list and save the alert rule. # Upgrade to Grafana v11.3 {{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes # Upgrade to Grafana v11.4 {{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes # Upgrade to Grafana v11.5 {{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes # Upgrade to Grafana v11.6 {{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes # Upgrade to Grafana v12.0 {{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes ### Grafana data source UID format enforcement **Ensure that your data source UIDs follow the correct standard** We've had standard ways to define UIDs for Grafana objects for years (at least [since Grafana v5](https://github.com/grafana/grafana/issues/7883)). While all of our internal code complies with this format, we haven't strictly enforced this format in REST APIs and provisioning paths that allow the creation and update of data sources. In Grafana v11.1, we [introduced](https://github.com/grafana/grafana/pull/86598) a warning that is sent to Grafana server logs every time a data source instance is created or updated using an invalid UID format. In Grafana v11.2, we [added](https://github.com/grafana/grafana/pull/89363/files) a new feature flag called `failWrongDSUID` that is turned off by default. When enabled, the REST APIs and provisioning reject any requests to create or update data source instances that have an incorrect UID. In Grafana v12.0, we're turning the feature flag `failWrongDSUID` on by default. #### Correct UID format You can find the exact regex definition [in the `grafana/grafana` repository](https://github.com/grafana/grafana/blob/c92f5169d1c83508beb777f71a93336179fe426e/pkg/util/shortid_generator.go#L32-L45). A data source UID can only contain: - Latin characters (`a-Z`) - Numbers (`0-9`) - Dash symbols (`-`) #### How do I know if I'm affected? - You can fetch all your data sources using the `/api/datasources` API. Review the `uid` fields, comparing them to the correct format, as shown [in the docs](https://grafana.com/docs/grafana/latest/developers/http_api/data_source/#get-all-data-sources). The following script can help, but note that it's missing authentication that you [have to add yourself](https://grafana.com/docs/grafana/latest/developers/http_api/#authenticating-api-requests): ``` curl http://localhost:3000/api/datasources | jq '.[] | select((.uid | test("^[a-zA-Z0-9\\-_]+$") | not) or (.uid | length > 40)) | {id, uid, name, type}' ``` - Alternatively, you can check the server logs for the `Invalid datasource uid` [error](https://github.com/grafana/grafana/blob/68751ed3107c4d15d33f34b15183ee276611785c/pkg/services/datasources/service/store.go#L429). #### What do I do if I'm affected? You'll need to create a new data source with the correct UID and update your dashboards and alert rules to use it. #### How do I update my dashboards to use the new or updated data source? - Go to the dashboard using the data source and update it by selecting the new or updated data source from the picker below your panel. OR - Update the dashboard's JSON model directly using search and replace. Navigate to [dashboard json model](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/view-dashboard-json-model/) and carefully replace all the instances of the old `uid` with the newly created `uid`. {{< figure src="/media/docs/grafana/screenshot-grafana-11-datasource-uid-enforcement.png" alt="Updating JSON Model of a Dashboard">}} #### How do I update my alert rules to use the new or updated data source? Open the alert rule you want to adjust and search for the data source that is being used for the query/alert condition. From there, select the new data source from the drop-down list and save the alert rule. ### Enforcing stricter version compatibility checks in plugin CLI install commands Since Grafana 10.2, the endpoint to check compatible versions when installing a plugin using `grafana cli plugins install` changed, which led to Grafana dependency version no longer being taken into account. This might have led to some behavior where the CLI would install plugins that are not fully compatible based on the plugins definition of compatibility via `grafanaDependency` property in the `plugin.json` file. #### What if I want to ignore the compatibility check? We _do not_ recommend installing plugins declared as incompatible. However, if you need to force install a plugin despite it being declared as incompatible, refer to the [Installing a plugin from a ZIP](https://grafana.com/docs/grafana/latest/administration/plugin-management/#install-a-plugin-from-a-zip-file) guidance. ### Annotation table migration **Plan for increased disk usage when upgrading from Grafana v11.x** Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the `annotation` table. The migration populates the new `dashboard_uid` column, which causes the database to rewrite the entire table and rebuild its indexes. Environments with large annotation datasets can experience significant temporary disk usage increase, which may lead to: - Rapid disk consumption on the database data volume - Database migration failures (for example, "could not extend file: No space left on device") - Grafana startup failures - Extended downtime during the upgrade process #### How do I know if I'm affected? You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your database. To check your annotation table size, connect to your database and check the table size. For PostgreSQL, run the following query: ```sql SELECT pg_size_pretty(pg_relation_size('annotation')) AS table_size, pg_size_pretty(pg_indexes_size('annotation')) AS indexes_size, pg_size_pretty(pg_total_relation_size('annotation')) AS total_size; ``` For MySQL, run the following query: ```sql SELECT ROUND(data_length / 1024 / 1024, 2) AS table_size_mb, ROUND(index_length / 1024 / 1024, 2) AS indexes_size_mb, ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_size_mb FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = 'annotation'; ``` For SQLite, check the database file size directly, as SQLite stores all tables in a single file. You can run the following command from your terminal: ```bash ls -lh ``` If your total size is several gigabytes or more, you should plan accordingly before upgrading. #### What should I do before upgrading? Before you upgrade, take the following steps: 1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your database data volume. 1. **Review your annotation data**: Consider whether you need to retain all historical annotations. 1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. 1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). #### What should I do after upgrading? After successfully upgrading to Grafana v12.x, you can reclaim disk space by performing database maintenance operations during a maintenance window. For PostgreSQL, run a `VACUUM FULL` operation on the `annotation` table: ```sql VACUUM FULL annotation; ``` For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table: ```sql OPTIMIZE TABLE annotation; ``` For SQLite, run a `VACUUM` operation on the database: ```sql VACUUM; ``` These operations require a lock on the table and may take significant time depending on the table size. Plan to run these during a low-traffic period. # Upgrade to Grafana v12.1 {{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes ### Annotation table migration **Plan for increased disk usage when upgrading from Grafana v11.x** Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the `annotation` table. The migration populates the new `dashboard_uid` column, which causes the database to rewrite the entire table and rebuild its indexes. Environments with large annotation datasets can experience significant temporary disk usage increase, which may lead to: - Rapid disk consumption on the database data volume - Database migration failures (for example, "could not extend file: No space left on device") - Grafana startup failures - Extended downtime during the upgrade process #### How do I know if I'm affected? You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your database. To check your annotation table size, connect to your database and check the table size. For PostgreSQL, run the following query: ```sql SELECT pg_size_pretty(pg_relation_size('annotation')) AS table_size, pg_size_pretty(pg_indexes_size('annotation')) AS indexes_size, pg_size_pretty(pg_total_relation_size('annotation')) AS total_size; ``` For MySQL, run the following query: ```sql SELECT ROUND(data_length / 1024 / 1024, 2) AS table_size_mb, ROUND(index_length / 1024 / 1024, 2) AS indexes_size_mb, ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_size_mb FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = 'annotation'; ``` For SQLite, check the database file size directly, as SQLite stores all tables in a single file. You can run the following command from your terminal: ```bash ls -lh ``` If your total size is several gigabytes or more, you should plan accordingly before upgrading. #### What should I do before upgrading? Before you upgrade, take the following steps: 1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your database data volume. 1. **Review your annotation data**: Consider whether you need to retain all historical annotations. 1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. 1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). #### What should I do after upgrading? After successfully upgrading to Grafana v12.x, you can reclaim disk space by performing database maintenance operations during a maintenance window. For PostgreSQL, run a `VACUUM FULL` operation on the `annotation` table: ```sql VACUUM FULL annotation; ``` For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table: ```sql OPTIMIZE TABLE annotation; ``` For SQLite, run a `VACUUM` operation on the database: ```sql VACUUM; ``` These operations require a lock on the table and may take significant time depending on the table size. Plan to run these during a low-traffic period. # Upgrade to Grafana v12.2 {{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes ### Annotation table migration **Plan for increased disk usage when upgrading from Grafana v11.x** Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the `annotation` table. The migration populates the new `dashboard_uid` column, which causes the database to rewrite the entire table and rebuild its indexes. Environments with large annotation datasets can experience significant temporary disk usage increase, which may lead to: - Rapid disk consumption on the database data volume - Database migration failures (for example, "could not extend file: No space left on device") - Grafana startup failures - Extended downtime during the upgrade process #### How do I know if I'm affected? You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your database. To check your annotation table size, connect to your database and check the table size. For PostgreSQL, run the following query: ```sql SELECT pg_size_pretty(pg_relation_size('annotation')) AS table_size, pg_size_pretty(pg_indexes_size('annotation')) AS indexes_size, pg_size_pretty(pg_total_relation_size('annotation')) AS total_size; ``` For MySQL, run the following query: ```sql SELECT ROUND(data_length / 1024 / 1024, 2) AS table_size_mb, ROUND(index_length / 1024 / 1024, 2) AS indexes_size_mb, ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_size_mb FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = 'annotation'; ``` For SQLite, check the database file size directly, as SQLite stores all tables in a single file. You can run the following command from your terminal: ```bash ls -lh ``` If your total size is several gigabytes or more, you should plan accordingly before upgrading. #### What should I do before upgrading? Before you upgrade, take the following steps: 1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your database data volume. 1. **Review your annotation data**: Consider whether you need to retain all historical annotations. 1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. 1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). #### What should I do after upgrading? After successfully upgrading to Grafana v12.x, you can reclaim disk space by performing database maintenance operations during a maintenance window. For PostgreSQL, run a `VACUUM FULL` operation on the `annotation` table: ```sql VACUUM FULL annotation; ``` For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table: ```sql OPTIMIZE TABLE annotation; ``` For SQLite, run a `VACUUM` operation on the database: ```sql VACUUM; ``` These operations require a lock on the table and may take significant time depending on the table size. Plan to run these during a low-traffic period. # Upgrade to Grafana v12.3 {{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes ### Annotation table migration **Plan for increased disk usage when upgrading from Grafana v11.x** Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the `annotation` table. The migration populates the new `dashboard_uid` column, which causes the database to rewrite the entire table and rebuild its indexes. Environments with large annotation datasets can experience significant temporary disk usage increase, which may lead to: - Rapid disk consumption on the database data volume - Database migration failures (for example, "could not extend file: No space left on device") - Grafana startup failures - Extended downtime during the upgrade process #### How do I know if I'm affected? You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your database. To check your annotation table size, connect to your database and check the table size. For PostgreSQL, run the following query: ```sql SELECT pg_size_pretty(pg_relation_size('annotation')) AS table_size, pg_size_pretty(pg_indexes_size('annotation')) AS indexes_size, pg_size_pretty(pg_total_relation_size('annotation')) AS total_size; ``` For MySQL, run the following query: ```sql SELECT ROUND(data_length / 1024 / 1024, 2) AS table_size_mb, ROUND(index_length / 1024 / 1024, 2) AS indexes_size_mb, ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_size_mb FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = 'annotation'; ``` For SQLite, check the database file size directly, as SQLite stores all tables in a single file. You can run the following command from your terminal: ```bash ls -lh ``` If your total size is several gigabytes or more, you should plan accordingly before upgrading. #### What should I do before upgrading? Before you upgrade, take the following steps: 1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your database data volume. 1. **Review your annotation data**: Consider whether you need to retain all historical annotations. 1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. 1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). #### What should I do after upgrading? After successfully upgrading to Grafana v12.x, you can reclaim disk space by performing database maintenance operations during a maintenance window. For PostgreSQL, run a `VACUUM FULL` operation on the `annotation` table: ```sql VACUUM FULL annotation; ``` For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table: ```sql OPTIMIZE TABLE annotation; ``` For SQLite, run a `VACUUM` operation on the database: ```sql VACUUM; ``` These operations require a lock on the table and may take significant time depending on the table size. Plan to run these during a low-traffic period. # Upgrade to Grafana v12.4 {{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} # Upgrade to Grafana v13.0 {{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes {{< admonition type="warning" >}} **Git Sync early adopters:** A migration bug in Grafana v13.0.0 might cause dashboards and folders to be lost or reverted when upgrading from Grafana v12.x.x with Git Sync enabled. Upgrading from v13.0.0 to v13.0.1 does **not** recover lost data, and if you already upgraded, you must restore your database first, then upgrade to v13.0.1. The bug only affects self-managed instances with Git Sync feature flags (`provisioning`, `kubernetesClientDashboardsFolders`, and `kubernetesDashboards`) enabled on Grafana v12.x.x. Grafana v13.0.0 has been removed from distribution and the fix has shipped in Grafana v13.0.1. If you're affected, use the following recovery paths: - **If your instance used mixed local and Git Sync content:** restore from the database backup you took before upgrading, then upgrade to Grafana v13.0.1. - **If your instance used full-instance Git Sync:** upgrade to Grafana v13.0.1 and resync from your Git repository. - **If unsure:** restore from your database backup before upgrading to v13.0.1. {{< /admonition >}} ### React 19 related updates As part of [the migration to React 19 in Grafana 13](https://grafana.com/blog/react-19-is-coming-to-grafana-what-plugin-developers-need-to-know/#next-steps-and-how-to-learn-more), make the following updates to ensure that your plugins are working properly and you don't experience any disruptions during the Grafana 13 upgrade. Follow this sequence for best results: #### Upgrade your Grafana to latest patch version for the version you are running To ensure that the changes required for the upgrade to React 19 are in place in your Grafana version, update to the latest minor version available for your Grafana instance. You can check the available versions on the [downloads page](https://grafana.com/grafana/download). #### Update all of your plugins Update all of your installed plugins and check if they are still working properly. By using the latest version of a plugin you facilitate support to React 19. #### Upgrade to Grafana 13 Finally you can continue your upgrade to Grafana 13. ### Legacy `/api` endpoints are now deprecated Grafana is migrating existing APIs to the new `/apis` model, a Kubernetes-style API layer which follows a standardized API structure alongside consistent API versioning. Refer to the [New API structure in Grafana](https://grafana.com/docs/grafana//developer-resources/api-reference/http-api/apis) documentation for more details. **Legacy APIs are not being disabled for the moment**. Removal of legacy APIs is planned for a future major release, and any breaking changes will be announced well in advance to avoid disruptions. For more information and migration guidance, refer to [Migrate to the new APIs](https://grafana.com/docs/grafana//developer-resources/api-reference/http-api/apis-migration). ### Deprecated data source APIs disabled Data source APIs that reference data sources by numeric `id` have been deprecated since Grafana 9. In Grafana 13, they're disabled by default. #### You are affected if You use data source API endpoints that reference data sources by numeric `id` rather than `uid`. #### Migration Update your API calls to reference data sources by `uid` instead of numeric `id`. To temporarily re-enable the deprecated APIs, enable the `datasourceLegacyIdApi` feature flag. Both the deprecated APIs and the feature toggle will be removed in a future release. ### Image Renderer plugin support removed In Grafana 13, support for the Image Renderer plugin is removed. #### You are affected if You run the Image Renderer as a Grafana plugin. After upgrading, the plugin no longer works for rendering screenshots or scheduled reports. #### Migration Deploy the image renderer as a separate service alongside Grafana. For setup instructions, refer to [Set up image rendering](https://grafana.com/docs/grafana//setup-grafana/image-rendering/#set-up-image-rendering). ### Image Renderer default authentication changed to JWTs The Image Renderer previously authenticated with Grafana using opaque tokens stored in the database when generating screenshots and PDFs. Grafana v13.0 enables the `renderAuthJWT` feature toggle by default, which switches authentication to stateless JSON Web Tokens (JWTs) that don't depend on the database. #### Action required After upgrading to Grafana v13.0, if you use the Image Renderer, you must set a `[rendering]renderer_token` in your Grafana configuration file to a value that isn't empty or the default value (`-`), and configure the Image Renderer with the same token value. Restart your Grafana instance for the changes to take effect. For more information, refer to the [Image Renderer security configuration documentation](https://grafana.com/docs/grafana//setup-grafana/image-rendering/#security). #### Reverting to the previous behavior After upgrading to Grafana v13.0, to revert to opaque token authentication, disable the feature toggle in your Grafana configuration file: ```ini [feature_toggles] renderAuthJWT = false ``` Restart your Grafana instance for the changes to take effect. ### Unified storage for folders and dashboards Grafana v13.0 automatically migrates folders and dashboards from the legacy SQL database to unified storage on startup. The migration runs once and is tracked in the `unifiedstorage_migration_log` table. After the migration completes, the following legacy tables are deprecated: - `dashboard` - `dashboard_acl` - `dashboard_provisioning` - `dashboard_version` - `dashboard_tag` - `library_element_connection` - `folder` These tables will be removed in a future release. If you downgrade to an earlier Grafana version after the migration, the older version reads the stale legacy tables and doesn't reflect changes made in unified storage. To roll back, restore from the database backup you took before upgrading. If you downgrade and then upgrade again without restoring a backup, any folders or dashboards created or modified during the downgrade aren't migrated automatically. If a backup isn't available, contact Grafana support for assistance. #### SQLite deployments If you use SQLite, the migration might fail with `database is locked` or `database table is locked` errors due to lock contention. Grafana automatically retries using the Parquet buffer, but if errors persist, increase `migration_cache_size_kb` or enable `migration_parquet_buffer` in the `[unified_storage]` section of your configuration file: | Setting | Description | Default | | -------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------- | | `migration_cache_size_kb` | SQLite page cache size during migration. | `1000000` (~1 GB) | | `migration_parquet_buffer` | Stage data through a temporary Parquet file to separate read and write phases, avoiding lock contention. | `false` | ### Removal of `grafana-cli` and `grafana-server` commands The `grafana-cli` and `grafana-server` commands, deprecated since Grafana v10.0, are removed in Grafana v13.0. Update any scripts, systemd units, Docker entrypoints, CI pipelines, or other automation to use `grafana cli` and `grafana server` instead. ### Legacy Alertmanager configuration API endpoints changed Several legacy Alertmanager configuration API endpoints are removed or restricted in Grafana v13.0: - `DELETE /api/alertmanager/grafana/config/api/v1/alerts` is removed. - `POST /api/alertmanager/grafana/config/api/v1/receivers/test` is removed. - `GET /api/alertmanager/grafana/config/api/v1/alerts` is restricted to admin users. - `GET /api/alertmanager/grafana/config/history` is restricted to admin users. - `POST /api/alertmanager/grafana/config/history/{id}/_activate` is restricted to admin users. #### You are affected if You call any of these endpoints in automation scripts, Terraform providers, or custom tooling. #### Migration Migrate to the Kubernetes-style resource APIs under `notifications.alerting.grafana.app/v1beta1`: | Resource | API path | | --------------------- | ---------------------------------------------------------------------------------------------- | | Receivers | `/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers` | | Notification policies | `/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees` | | Templates | `/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups` | | Mute timings | `/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals` | | Inhibition rules | `/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules` | | Receiver testing | `/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{uid}/test` | ### Alertmanager status endpoint requires a new permission #### You are affected if You use the `GET /api/alertmanager/grafana/api/v2/status` endpoint and rely on the `alert.notifications:read` permission to access it. #### Description The `GET /api/alertmanager/grafana/api/v2/status` endpoint previously required the legacy `alert.notifications:read` permission. It now requires a dedicated `alert.notifications.system-status:read` permission. This new permission is included in the `fixed:alerting.notifications:writer` role, which is granted to Admin users by default. #### Migration If you have custom roles that need access to this endpoint, add the `alert.notifications.system-status:read` action to those roles. Admin users are unaffected as they receive this permission automatically through the built-in alerting notifications writer role. ### RBAC enforcement changes for custom roles Grafana v13.0 tightens RBAC enforcement for custom roles, Terraform-managed roles, and role provisioning. Roles that contain deprecated permissions may fail during create, update, delete, or assignment operations. We recommend reviewing and updating affected roles proactively. #### You are affected if You manage custom RBAC roles through Terraform, the API, or provisioning, and those roles contain any of the following: - Data source UID-scoped permissions (`datasources:uid:`) on a global role - `fixed:annotations.dashboard:writer` or `fixed:annotations.dashboard:reader` - `annotations:type:dashboard` - `annotations:*` #### Migration **Data source permissions on global roles:** If a Terraform-managed `grafana_role` combines `global = true` with `datasources:uid:`, recreate the role as a non-global role with a new UID. Grafana can't change the scope of an existing role in place. Set `datasource_type` on data source permission resources when possible. **Dashboard annotation fixed roles:** Remove `fixed:annotations.dashboard:writer` and `fixed:annotations.dashboard:reader` from your configurations. Use dashboard or folder permissions (View, Edit, Admin) to control dashboard annotation access instead. Use `annotations:type:organization` for organization-level annotations. **`annotations:*` wildcard scope:** Replace with specific scopes: `annotations:type:organization` for organization annotations, and dashboard or folder permissions for dashboard annotations. Don't recreate `annotations:*` in Terraform after it has been removed. If a role is stuck because Grafana refuses to update or delete it, the role may contain a deprecated permission that must be removed before Terraform or API updates can succeed. Contact Grafana support for assistance. For detailed examples and troubleshooting, refer to [RBAC behavior changes with Grafana 13](https://grafana.com/docs/grafana//whatsnew/whats-new-in-v13/whats-new-in-v13-0/#rbac-behavior-changes-with-grafana-13). # Upgrade to Grafana v13.1 {{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes # Upgrade to Grafana v13.2 {{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes # Upgrade to Grafana v13.3 {{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="" >}} {{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} # Strategies for upgrading your self-managed Grafana instance At Grafana Labs, we believe in shipping features early and often, and in recent years we’ve increased our commitment to that philosophy. We no longer wait for the yearly major release to give you access to the next big improvement. Instead, we regularly make new features, bug fixes, and security patches available to our self-managing users ([Grafana OSS](https://grafana.com/oss/grafana/) and [Grafana Enterprise](https://grafana.com/products/enterprise/)) throughout the year. Having a dependable release process provides users like you with the best Grafana experience possible, and it provides the flexibility to upgrade in a manner that works best for you and your organization. {{< admonition type="note" >}} Grafana Cloud follows a different release cadence than Grafana OSS and Enterprise. In Cloud, Grafana uses Rolling release channels. To learn more about release channels, refer to [Rolling release channels for Grafana Cloud](https://grafana.com/docs/rolling-release/). {{< /admonition >}} ## What to expect from each release type We split Grafana OSS and Grafana Enterprise releases into three main categories: - **Minor release (every other month)**: These releases can include new features, deprecation notices, notices about upcoming breaking changes, previously announced breaking changes, bug fixes, and security vulnerability patches. - **Major release (once a year, in April/May)**: These are like a minor release, but accompanied by [GrafanaCON](https://grafana.com/events/grafanacon/) and a comprehensive upgrade guide for users who like to upgrade only once a year. - **Patching release (at least every month)**: These include bug fixes for currently supported versions, as well as any security vulnerability patches. You can choose your cadence: For frequent self-managed updates, you should follow the minor release (for example, upgrade 11.1 to 11.2), which also gives you access to the latest features. If you need a longer period to review our new releases, you should follow the major releases. Both strategies get patching releases with security fixes (high severity security fixes also result in ad-hoc patch releases). We’ll get into additional guidance on upgrade cadences later in this guide. ## How to find the specifics for a release We love sharing all our great features with you so you can leverage Grafana to its fullest. We also understand that complete release documentation allows you to upgrade with confidence. Whether it’s knowing that a bug has been fixed, seeing that a security vulnerability is patched, or understanding how to mitigate the impact of breaking changes, proper documentation allows you to make informed decisions about when to upgrade your local Grafana instances. We provide release documentation in multiple places to address different needs: - [**What’s new**](https://grafana.com/docs/grafana/latest/whatsnew/?pg=blog&plcmt=body-txt) outlines new features debuting in each major and minor release, along with breaking changes that could impact you and recommendations to mitigate them. - [**Upgrade guides**](https://grafana.com/docs/grafana/latest/upgrade-guide/?pg=blog&plcmt=body-txt) instruct you on how to upgrade to a newer minor or major version. - And finally, a [**changelog**](https://github.com/grafana/grafana/blob/main/CHANGELOG.md) is generated for every release (major, minor, patching, security) and outlines all changes included in that release. ## When to expect releases Grafana releases a new minor version every other month, with patching releases in between. Below are the planned releases for the rest of 2026. However, these dates may be subject to change: | **Release date** | **Grafana versions** | **Release type** | | ---------------- | ------------------------- | ---------------- | | Feb. 24, 2026 | 12.4 & Supported versions | Minor & patching | | Apr. 14, 2026 | Grafana 13 | Major | | Jun. 23, 2026 | 13.1 & Supported versions | Minor & patching | | Jul. 21, 2026 | Supported versions | Patching | | Aug. 4, 2026 | Supported versions | Patching | | Aug. 18, 2026 | 13.2 & Supported versions | Minor & patching | | Sept. 1, 2026 | Supported versions | Patching | | Oct. 20, 2026 | 13.3 & Supported versions | Minor & patching | ### A few important notes - The schedule above outlines how we plan release dates. However, unforeseen events and circumstances may cause dates to change. - High severity security and feature degradation incidents will result in ad-hoc releases that are not scheduled ahead of time. - Patching releases are for all supported minor versions of Grafana. Each supported minor version receives patch releases with bug fixes and security patches until its end of life. - Release freezes: Each year Grafana implements two release freezes to accommodate for the holiday season. During these times, no scheduled releases will be executed. However, this does not apply to changes that may be required during the course of an operational or security incident. ## Grafana security releases: improved version naming convention We've enhanced our naming convention for security release versions to make it easier to clearly identify our security releases from our standard patching releases. In the past, critical vulnerabilities triggered unscheduled releases that incremented the patch version (e.g., 10.3.0 to 10.3.1). However, we found that the naming convention for these releases didn't clearly communicate the nature of the update. For example, if there was a version change from 11.3.0 to 11.3.1, there was no indication whether it was a security fix, a bug fix, or a minor feature update. This lack of clarity led to confusion about the urgency and nature of the update.
{{< admonition type="note" >}} Docker does not allow the plus sign (`+`) in image tag names. A plus sign (`+`) will be a rendered as a dash (`-`) in the docker tag. {{< /admonition >}} Our new approach directly addresses this issue. Going forward, security releases will be appended with "+security" to indicate that the release is the indicated version PLUS the security fix. **For example**: A release named "11.2.3+security-01" would consist of what was released in 11.2.3 PLUS the indicated security fix. Once released, the security fix will also then be automatically included in all future releases of the impacted version. This naming convention should make it easier to identify security updates and the Grafana version they're based on, allowing for a better understanding of the importance and urgency of each release. ## What to know about version support Self-managed Grafana users have control over when they upgrade to a new version of Grafana. To help you make an informed decision about whether it’s time to upgrade, it’s important that you understand the level of support provided for your current version. For self-managed Grafana (both Enterprise and OSS), the support for versions follows these rules: - Each minor release is supported for 9 months after its release date - The last minor release of a major version receives extended support for 15 months after its release date - Support levels change as new versions are released: - **Full Support**: The current major version receives new features through new minor releases - **Patch Support**: Individual minor versions receive patch releases (bug fixes and security patches) until end of life - **Not Supported**: Versions beyond their support period receive no updates Here is an overview of version support through 2027: | **Version** | **Release date** | **Support end date** | **Support level** | | ------------------------- | ------------------ | -------------------- | ----------------- | | 11.4.x | December 5, 2024 | September 5, 2025 | Not Supported | | 11.5.x | January 28, 2025 | October 28, 2025 | Not Supported | | 11.6.x (Last minor of 11) | March 25, 2025 | June 25, 2026 | Not Supported | | 12.0.x | May 5, 2025 | February 5, 2026 | Not Supported | | 12.1.x | July 22, 2025 | April 22, 2026 | Not Supported | | 12.2.x | September 23, 2025 | June 23, 2026 | Not Supported | | 12.3.x | November 19, 2025 | August 19, 2026 | Not Supported | | 12.4.x (Last minor of 12) | February 24, 2026 | May 24, 2027 | Patch Support | | 13.0.x | April 14, 2026 | January 9, 2027 | Patch Support | | 13.1.x | June 23, 2026 | March 20, 2027 | Patch Support | | 13.2.x | August 18, 2026 | May 18, 2027 | Patch Support | | 13.3.x | October 20, 2026 | July 20, 2027 | Patch Support | ## How are these versions supported? Self-managed Grafana follows semantic-like versioning (MAJOR.MINOR.PATCH). Here's how different types of releases work: - **Major releases** (e.g., 12.0.0, 13.0.0): - Awesome new features as well as significant architectural improvements and modernizations - May include breaking changes that require migration steps - Released once per year - **Minor releases** (e.g., 12.3.0, 12.4.0): - Contain new features and enhancements - Include bug fixes and security patches - Released every other month - **Patch releases** (e.g., 12.3.1, 12.3.2): - **Only** contain bug fixes and security patches - **No new features** - these wait until the next minor release - Released monthly **Support levels by version:** - **Full Support** (current major version): - Gets new minor releases with new features approximately every other month - All minor versions within the major receive patch releases until end of life - Example: Major 12.x gets new features via 12.1.0, 12.2.0, 12.3.0, etc. - **Patch Support** (individual minor versions): - Each minor version receives patch releases (bug fixes and security patches) until end of life - No new features - these only come with new minor releases - Example: 12.3.x gets 12.3.1, 12.3.2, etc. with fixes only - **Not Supported**: Versions beyond their support period receive no updates and should be upgraded. **Example**: When 12.3.0 is released, it includes new features. Subsequent releases like 12.3.1 and 12.3.2 only include bug fixes and security updates. All new features developed after 12.3.0 wait until 12.4.0 is released. ### What is a critical feature degradation? A critical feature degradation usually meets one of the following criteria: - Major functionality is universally unavailable (for example, cannot create dashboards, unable to authenticate). - Major (critical) impact to a significant amount of customers. - Major escalated incident for one or many customers. ## Self-managing upgrade strategies Based on your needs, choose your ideal upgrade strategy. Here’s what that might look like in practice: | **Strategy/cadence** | **Advantages/disadvantages** | **Example upgrade procedure** | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Minor / bi-monthly (11.1 to 11.2)** | Our recommended strategy. It combines up-to-date, secure releases with access to latest features as soon as they're released.
  • Small changelog to review
  • Highest compatibility with actively maintained plugins
  • Easy migration to [Grafana Cloud](https://grafana.com/products/cloud)
|
  • **January 2025**: You review the 11.5 changelog and deploy the release to testing
  • **February 2025**: You deploy 11.5 to production
  • **March 2025**: 11.6 is released
| | **Major / yearly (10.0 to 11.0)** | Yearly upgrade path that still gives access to up-to-date features presented at GrafanaCON.
  • Big changelog to review
  • High compatibility with plugins
  • Relatively easy migration to [Grafana Cloud](https://grafana.com/products/cloud)
|
  • **May 2024**: 11.0 is released, you start a big changelog review
  • **June 2024**: You deploy 11.0 to testing
  • **July 2024**: You deploy 11.0 to production
  • **May 2025**: 12.0 is released
| | **Previous major / yearly (10.4 to 11.6)** | Release with extended support timeline
  • Limited compatibility with actively developed plugins
  • Big changelog to review
  • Migrations to Grafana Cloud might require professional support
|
  • **May 2025**: 12.0 is released, marking the previous minor (11.6.x) with extended support, you start a big changelog review (10.4.x to 11.6.x)
  • **June 2025**: You deploy 11.6.x to testing
  • **July 2025**: You deploy 11.6.x to production
| Follow the “minor” strategy for the most flexibility, as you can also occasionally lengthen the cadence to a full quarter and still rely on your currently deployed minor release being supported with security fixes. ## How the Grafana team catches bugs and breaks during the release process 1. Each team writes automated tests for their code and we run [automated tests](https://github.com/grafana/grafana/blob/HEAD/contribute/developer-guide.md#test-grafana) which include unit tests, integration tests, end-to-end tests, and load tests. For plugins specifically, we test the frontend and backend parts of a data source (unit), integrating a data source with a matrix of Grafana versions (E2E), and the contract between the data source and the API it consumes (integration). 2. We perform manual acceptance and smoke testing internally for new features by deploying to our internal observability stack. After that, we progressively roll out in Grafana Cloud, and then cut an OSS and Enterprise release. Each stage catches bugs. 3. We ship new features in Experimental or Private Preview [release stages](https://grafana.com/docs/release-life-cycle/), behind feature toggles. This helps us improve the feature during development. If you are interested in gaining early access to features (including in your development or test environments), please let us know. 4. We scan Grafana, all plugins and their dependencies continuously for security vulnerabilities. ## Minimize the likelihood of bugs and problems during upgrade Despite thorough testing, you can experience problems when upgrading: ### Bugs Bugs are unexpected side effects of code changes in the release, which cause problems. Some bugs occur for all users, and we usually catch these in the early stages of testing. Others occur in a small number of Grafana instances with specific configuration or unusual use cases; for example a specific authentication setup or a combination of feature toggles. Grafana plugins also interact with external services via API to query data, and sometimes these APIs change without notice, causing issues for your dashboards that depend on these datasources. Grafana Labs has monitoring in place to regularly test these APIs, but at times they break in unexpected ways. Reduce the risk of bugs by staying current and rolling out upgrades across dev or test environments before production. A Grafana Enterprise license entitles you to an additional dev and test instance for this purpose, available through your account team, and in Grafana Cloud you can create dev and test stacks that upgrade before production by using [rolling release channels](https://grafana.com/docs/rolling-release/). - Back up your database on a regular basis, and especially before you upgrade. - Roll back and report issues if you experience problems in dev or test. - In Cloud, run a dev or test stack on the `fast` channel, and run your production stack on `steady` or `slow`. To change your release channel, open a support ticket. ### Known breaking changes As a rule we always seek backward compatibility and migration, and reserve breaking changes for Grafana’s once-yearly major release. However occasionally small breaking changes (like updates to API payloads) will ship in minor releases. These are announced in [upgrade guides](https://grafana.com/docs/grafana/latest/upgrade-guide/), [What’s New](https://grafana.com/docs/grafana-cloud/whats-new/), and our [changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md). Always read the [upgrade guide](https://grafana.com/docs/grafana/latest/upgrade-guide/) and [changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md) prior to upgrading to learn about and account for breaking changes. ### Plugin incompatibility **Grafana core** ships as a single binary and consists of Dashboards, Alerts, Explore, Authentication and Authorization, Reporting, some core data sources, and other components. However, almost everyone who uses Grafana also uses **plugins**: panels, data sources, and applications that are released independently of Grafana. Every plugin version lists its Grafana version dependencies (you can see them at [https://grafana.com/grafana/plugins/](https://grafana.com/grafana/plugins/)) but different versions of different plugins can also interact with each other - for example you might visualize data from a data source in a panel in Grafana, all three of which are versioned independently of each other. That can create issues that are hard to catch in testing. To minimize the likelihood of plugin incompatibility issues, run the latest available version of plugins and update them regularly. Always [update plugins](https://grafana.com/docs/grafana/latest/administration/plugin-management/#update-a-plugin) before updating Grafana. Plugins also follow Semver patterns, so review the plugin’s changelog for breaking changes before upgrading to a new major version of that plugin.