mirror of https://github.com/grafana/grafana
Docs: What's new, Upgrade guide, and breaking changes v12.0 (#102748)
Co-authored-by: Jacob Valdez <jacob.valdez@grafana.com> Co-authored-by: Timur Olzhabayev <timur.olzhabayev@grafana.com>pull/104909/head^2
Jacob Valdez
8 months ago
committed by
GitHub
parent
44447c0ca0
commit
d5e3be1b02
@ -0,0 +1,25 @@ |
||||
--- |
||||
headless: true |
||||
labels: |
||||
products: |
||||
- enterprise |
||||
- oss |
||||
title: Upgrade guide introduction |
||||
--- |
||||
|
||||
We recommend that you upgrade Grafana often to stay current with the latest fixes and enhancements. |
||||
Because Grafana upgrades are backward compatible, the upgrade process is straightforward, and dashboards and graphs will not change. |
||||
|
||||
In addition to common tasks you should complete for all versions of Grafana, there might be additional upgrade tasks to complete for a version. |
||||
|
||||
{{% admonition type="note" %}} |
||||
There might be breaking changes in some releases. We outline all these changes in the [What's New](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/whatsnew/) document. |
||||
{{% /admonition %}} |
||||
|
||||
For versions of Grafana prior to v9.2, we published additional information in the [Release Notes](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/release-notes/). |
||||
|
||||
When available, we list all changes with links to pull requests or issues in the [Changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md). |
||||
|
||||
{{% admonition type="note" %}} |
||||
When possible, we recommend that you test the Grafana upgrade process in a test or development environment. |
||||
{{% /admonition %}} |
||||
@ -0,0 +1,82 @@ |
||||
--- |
||||
description: Guide for upgrading to Grafana v12.0 |
||||
keywords: |
||||
- grafana |
||||
- configuration |
||||
- documentation |
||||
- upgrade |
||||
- '12.0' |
||||
title: Upgrade to Grafana v12.0 |
||||
menuTitle: Upgrade to v12.0 |
||||
weight: 600 |
||||
--- |
||||
|
||||
# Upgrade to Grafana v12.0 |
||||
|
||||
{{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="<GRAFANA_VERSION>" >}} |
||||
|
||||
{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}} |
||||
|
||||
{{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="<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. |
||||
@ -0,0 +1,95 @@ |
||||
--- |
||||
description: Feature and improvement highlights for Grafana v12.0 |
||||
keywords: |
||||
- grafana |
||||
- new |
||||
- documentation |
||||
- '12.0' |
||||
- release notes |
||||
labels: |
||||
products: |
||||
- cloud |
||||
- enterprise |
||||
- oss |
||||
title: What's new in Grafana v12.0 |
||||
posts: |
||||
- title: Observability as Code |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-14-git-sync-for-grafana-dashboards.md |
||||
- docs/grafana-cloud/whats-new/2025-04-11-new-dashboards-schema.md |
||||
- docs/grafana-cloud/whats-new/2025-05-05-new-dashboard-apis-released-as-experimental.md |
||||
- title: Drilldown apps |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-28-metrics-drilldown-improvements.md |
||||
- docs/grafana-cloud/whats-new/2025-04-28-logs-drilldown-improvements.md |
||||
- docs/grafana-cloud/whats-new/2025-04-17-ga-release-of-grafana-traces-drilldown.md |
||||
- docs/grafana-cloud/whats-new/2025-04-28-introducing-investigations |
||||
- title: Cloud Migration Assistant |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-11-grafana-cloud-migration-assistant-now-generally-available.md |
||||
- title: Dashboards and visualizations |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-11-dynamic-dashboards.md |
||||
- docs/grafana-cloud/whats-new/2025-04-11-blazing-fast-table-panel.md |
||||
- docs/grafana-cloud/whats-new/2025-04-07-sql-expressions.md |
||||
- title: Authentication and authorization |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-14-scim-user-and-team-provisioning.md |
||||
- title: Alerting |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-10-alert-rule-migration-tool.md |
||||
- docs/grafana-cloud/whats-new/2025-04-10-grafana-managed-alert-rule-recovering-state.md |
||||
- docs/grafana-cloud/whats-new/2025-04-11-grafana-managed-alert-rule-improvements.md |
||||
- title: Experimental themes |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-10-experimental-themes.md |
||||
- title: Explore |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-15-new-controls-for-logs-in-explore.md |
||||
- title: Traces |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-30-trace-correlations-instant-context-hops-from-any-trace.md |
||||
- title: Breaking Changes |
||||
items: |
||||
- docs/grafana-cloud/whats-new/2025-04-28-removal-of-editors_can_admin-configuration.md |
||||
- docs/grafana-cloud/whats-new/2025-04-28-dashboard-v2-schema-and-next-gen-dashboards.md |
||||
- docs/grafana-cloud/whats-new/2025-04-29-deduplication-and-renaming-of-metric-cache_size.md |
||||
- docs/grafana-cloud/whats-new/2025-04-28-removal-of-optional-actions-property-from-datalinkscontextmenu-component.md |
||||
- docs/grafana-cloud/whats-new/2025-04-29-enforcing-stricter-data-source-uid-format.md |
||||
- docs/grafana-cloud/whats-new/2025-04-28-removal-of-angular.md |
||||
- docs/grafana-cloud/whats-new/2025-04-29-deprecated-apis-for-ui-extensions-will-be-removed.md |
||||
- docs/grafana-cloud/whats-new/2025-04-29-enforcing-stricter-version-compatibility-checks-in-plugin-cli-install-commands.md |
||||
- docs/grafana-cloud/whats-new/2025-04-28-removal-of-‘aggregate-by’-in-tempo.md |
||||
- docs/grafana-cloud/whats-new/2025-04-28-removing-the-feature-toggle-ui-from-grafana-cloud.md |
||||
whats_new_grafana_version: 12.0 |
||||
weight: -49 |
||||
--- |
||||
|
||||
# What’s new in Grafana v12.0 |
||||
|
||||
Welcome to Grafana 12.0! We have a _lot_ to share. This release marks general availability for Grafana Drilldown (previously Explore Metrics, Logs, and Traces), Grafana-managed alerts and recording rules, Cloud migration, and plugin management tooling. You can also try new [preview and experimental](https://grafana.com/docs/release-life-cycle/) tools: Sync your dashboards directly to a GitHub repository with Git Sync, and try our new Terraform provider and CLI. Add tabs, new layouts and conditional logic to your dashboards, and load tables and geomaps far faster. Join and transform data limitlessly from multiple sources with SQL Expressions. In Grafana Cloud and Enterprise, sync your users and teams instantly from your SAML identity provider using SCIM (the System for Cross-Domain Identity Management). Lastly, don't forget to try on one of several new color themes for the user interface. |
||||
|
||||
Read on to learn about these and more improvements to Grafana! |
||||
|
||||
{{< youtube id=4uJkHC-IvGU >}} |
||||
|
||||
For even more detail about all the changes in this release, refer to the [changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md). For the specific steps we recommend when you upgrade to v12.0, check out our [Upgrade Guide](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/upgrade-guide/upgrade-v12.0/). |
||||
|
||||
## Breaking changes in Grafana v12.0 |
||||
|
||||
For Grafana v12.0, we've also provided a list of [breaking changes](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v12-0/#breaking-changes) to help you upgrade with greater confidence. For our purposes, a breaking change is any change that requires users or operators to do something. This includes: |
||||
|
||||
- Changes in one part of the system that could cause other components to fail |
||||
- Deprecations or removal of a feature |
||||
- Changes to an API that could break automation |
||||
- Changes that affect some plugins or functions of Grafana |
||||
- Migrations that can’t be rolled back |
||||
|
||||
For each change, the provided information: |
||||
|
||||
- Helps you determine if you’re affected |
||||
- Describes the change or relevant background information |
||||
- Guides you in how to mitigate for the change or migrate |
||||
- Provides more learning resources |
||||
|
||||
{{< docs/whats-new >}} |
||||
Loading…
Reference in new issue