From 1565c3c392530d5da5c0bb719f9389b010b793b3 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Tue, 7 Sep 2021 10:26:12 +0200 Subject: [PATCH 01/31] restructuring to new storybook inspired structure. --- .../developers/plugins/migration-guide.md | 72 ++++++++----------- 1 file changed, 31 insertions(+), 41 deletions(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 3762fa411fb9d..f284445878a25 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -4,44 +4,59 @@ title = "Plugin migration guide" # Plugin migration guide -This guide explains how to migrate pre-Grafana 7.0 plugins from Angular to the new React-based plugin platform introduced in Grafana 7.0. +## Introduction -It's written for: +This guide explains how to migrate Grafana plugins from previous version to the latest version available. It is structured in a way where you easily should be able to identify what steps you need to take given the Grafana version your plugin currently support. -- Plugin authors who want to migrate their plugins to Grafana 7.0+. -- Plugin users who are using custom plugins and want to know whether they can upgrade to Grafana 7.0 without losing functionality. +> If you've successfully migrated your plugin by using this guide and think something is missing, please [submit an issue on GitHub](https://github.com/grafana/grafana/issues/new?title=Docs%20feedback:%20/developers/plugins/migration-guide.md) and share your experiences with us so that we can improve this guide! -> If you've successfully migrated your plugin from Angular to React, please [submit an issue on GitHub](https://github.com/grafana/grafana/issues/new?title=Docs%20feedback:%20/developers/plugins/migration-guide.md) and share your experiences with us so that we can improve this guide! +## Table of contents -## What's new in Grafana 7.0? +- [From version 7.x.x to 8.x.x](#from-version-7xx-to-8xx) + - [8.0 deprecations](#80-deprecations) +- [From version 6.x.x to 7.x.x](#from-version-6xx-to-7xx) + - [What's new in Grafana 7.0?](#whats-new-in-grafana-70) + - [Migrate a plugin from Angular to React](#migrate-a-plugin-from-angular-to-react) + - [Migrate a panel plugin](#migrate-a-panel-plugin) + - [Migrate a data source plugin](#migrate-a-data-source-plugin) + - [Migrate to data frames](#migrate-to-data-frames) + - [Troubleshoot plugin migration](#troubleshoot-plugin-migration) + +## From version 7.x.x to 8.x.x + +### 8.0 deprecations + +## From version 6.x.x to 7.x.x + +### What's new in Grafana 7.0? Grafana 7.0 introduced a whole new plugin platform based on React. The new platform supersedes the previous Angular-based plugin platform. Plugins built using Angular still work for the foreseeable future, but we encourage new plugin authors to develop with the new platform. -### New data format +#### New data format Along with the move to React, the new plugin platform introduced a new internal data format called [data frames]({{< relref "data-frames.md" >}}). Previously, data source plugins could send data either as time series or tables. With data frames, data sources can send any data in a table-like structure. This gives you more flexibility to visualize your data in Grafana. -### Improved TypeScript support +#### Improved TypeScript support While the previous Angular-based plugin SDK did support TypeScript, for the React platform, we’ve greatly improved the support. All our APIs are now TypeScript, which might require existing code to update to the new stricter type definitions. Grafana 7.0 also introduced several new APIs for plugin developers that take advantage of many of the new features in Grafana 7.0. -### Grafana Toolkit +#### Grafana Toolkit With Grafana 7.0, we released a new tool for making it easier to develop plugins. Before, you’d use Gulp, Grunt, or similar tools to generate the minified assets. Grafana Toolkit takes care of building and testing your plugin without complicated configuration files. For more information, refer to [@grafana/toolkit](https://www.npmjs.com/package/@grafana/toolkit). -### Field options +#### Field options Grafana 7.0 introduced the concept of _field options_, a new way of configuring your data before it gets visualized. Since this was not available in previous versions, any plugin that enables field-based configuration will not work in previous versions of Grafana. For plugins prior to Grafana 7.0, all options are considered _Display options_. The tab for field configuration isn't available. -### Backend plugins +#### Backend plugins While backend plugins were available as an experimental feature in previous versions of Grafana, the support has been greatly improved for Grafana 7. Backend plugins for Grafana 7.0 are backwards-compatible and will continue to work. However, the old backend plugin system has been deprecated, and we recommend that you use the new SDK for backend plugins. @@ -49,32 +64,7 @@ Since Grafana 7.0 introduced [signing of backend plugins]({{< relref "../../plug To learn more, refer to [Backend plugins]({{< relref "backend" >}}). -## Why should I migrate my plugin? - -There are several benefits in using the new plugin platform. - -- **Better performance:** Components written in React are more responsive. -- **Support for field options:** By migrating to the new data frame format, you can leverage the new field options to let users customize their data and display options. - -## Compatibility between Grafana versions - -A plugin developed for Grafana 6 will work for Grafana 7.0. However, plugins developed using the new plugin platform in Grafana 7.0 will only work for Grafana 7.0 and up. - -### Interoperability between data formats - -Grafana detects the data format sent by the data source and transforms it for the panel, if needed. - -For example: - -- A legacy panel with data source that returns data frames: Grafana converts the response to the legacy format. -- A legacy data source with a panel using data frames: Grafana converts the response to the data frame format. -- If both panel and data source use the same format, no transformations are made. Data is passed as is. - -### target and jsonData are unchanged - -The query model, `target`, and the configuration model, jsonData, are still the same. This means that if you use the same query model and configuration for your plugin, then the migrated plugin will use existing queries and configuration. You don’t have to worry about breaking existing dashboards. - -## Migrate a plugin from Angular to React +### Migrate a plugin from Angular to React If you’re looking to migrate a plugin to the new plugin platform, then we recommend that you release it under a new major version. Consider keeping a release branch for the previous version to be able to roll out patch releases for versions prior to Grafana 7. @@ -84,7 +74,7 @@ While there's no 1-to-1 migration path from an Angular plugin to the new React p 1. Start from scratch with one of the templates provided by Grafana Toolkit. 1. Move the existing code into the new plugin incrementally, one component at a time. -### Migrate a panel plugin +#### Migrate a panel plugin Prior to Grafana 7.0, you would export a MetricsPanelCtrl from module.ts. @@ -122,7 +112,7 @@ export const MyPanel: React.FC = ({ options, data, width, height }) => { }; ``` -### Migrate a data source plugin +#### Migrate a data source plugin While all plugins are different, we'd like to share a migration process that has worked for some of our users. @@ -135,7 +125,7 @@ By now, you should be able to release your new version. To fully migrate to the new plugin platform, convert the time series response to a data frame response. -### Migrate to data frames +#### Migrate to data frames Before 7.0, data source and panel plugins exchanged data using either time series or tables. Starting with 7.0, plugins use the new data frame format to pass data from data sources to panels. @@ -162,6 +152,6 @@ async query(options: DataQueryRequest): Promise { For more information, refer to [Data frames]({{< relref "data-frames.md">}}). -## Troubleshoot plugin migration +### Troubleshoot plugin migration As of Grafana 7.0, backend plugins can now be cryptographically signed to verify their origin. By default, Grafana ignores unsigned plugins. For more information, refer to [Allow unsigned plugins]({{< relref "../../plugins/plugin-signatures.md#allow-unsigned-plugins" >}}). From 5b4b742b3af7ce4ac6d79731bed78e3f9f2ecfd7 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Tue, 7 Sep 2021 11:36:15 +0200 Subject: [PATCH 02/31] added instructions on how to handle breaking changes in the legend. --- .../developers/plugins/migration-guide.md | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index f284445878a25..182c3dcd64fa1 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -12,9 +12,11 @@ This guide explains how to migrate Grafana plugins from previous version to the ## Table of contents -- [From version 7.x.x to 8.x.x](#from-version-7xx-to-8xx) +- [From version 7.x.x to 8.0.0](#from-version-7xx-to-800) - [8.0 deprecations](#80-deprecations) -- [From version 6.x.x to 7.x.x](#from-version-6xx-to-7xx) +- [From version 6.2.x to 7.4.0](#from-version-62x-to-740) + - [Legend components](#legend-components) +- [From version 6.x.x to 7.0.0](#from-version-6xx-to-700) - [What's new in Grafana 7.0?](#whats-new-in-grafana-70) - [Migrate a plugin from Angular to React](#migrate-a-plugin-from-angular-to-react) - [Migrate a panel plugin](#migrate-a-panel-plugin) @@ -26,6 +28,24 @@ This guide explains how to migrate Grafana plugins from previous version to the ### 8.0 deprecations +## From version 6.2.x to 7.4.0 + +### Legend components + +The Legend components have been refactored and introduced the following changes within the `@grafana/ui` package. + +```ts +// before +import { LegendItem, LegendOptions, GraphLegend } from '@grafana/ui'; + +// after +import { VizLegendItem, VizLegendOptions, VizLegend } from '@grafana/ui'; +``` + +The values for the `LegendPlacement` has been updated from `'under' | 'right' | 'over'` to `'bottom' | 'right'` so you can not place the legend above the visualization anymore. + +The `isVisible` in the `LegendItem` has been renamed to `disabled` in `VizLegendItem`. + ## From version 6.x.x to 7.x.x ### What's new in Grafana 7.0? From f94c4f53d9ae8f61c3eb1fa5fcf215f5cb5f43ee Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Tue, 7 Sep 2021 16:28:58 +0200 Subject: [PATCH 03/31] start adding migration steps for 7 -> 8 --- docs/sources/developers/plugins/migration-guide.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 182c3dcd64fa1..5ff906ad6c4d6 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -13,7 +13,9 @@ This guide explains how to migrate Grafana plugins from previous version to the ## Table of contents - [From version 7.x.x to 8.0.0](#from-version-7xx-to-800) - - [8.0 deprecations](#80-deprecations) + - [Backend plugin v1 support has been dropped](#backend-plugin-v1-support-has-been-dropped) + - [Unsigned backend plugins will not be loaded](#unsigned-backend-plugins-will-not-be-loaded) + - [Data frames can now be in either wide or long format](#data-frames-can-now-be-in-either-wide-or-long-format) - [From version 6.2.x to 7.4.0](#from-version-62x-to-740) - [Legend components](#legend-components) - [From version 6.x.x to 7.0.0](#from-version-6xx-to-700) @@ -26,6 +28,8 @@ This guide explains how to migrate Grafana plugins from previous version to the ## From version 7.x.x to 8.x.x +### Backend plugin v1 support has been dropped + ### 8.0 deprecations ## From version 6.2.x to 7.4.0 @@ -42,9 +46,8 @@ import { LegendItem, LegendOptions, GraphLegend } from '@grafana/ui'; import { VizLegendItem, VizLegendOptions, VizLegend } from '@grafana/ui'; ``` -The values for the `LegendPlacement` has been updated from `'under' | 'right' | 'over'` to `'bottom' | 'right'` so you can not place the legend above the visualization anymore. - -The `isVisible` in the `LegendItem` has been renamed to `disabled` in `VizLegendItem`. +- `LegendPlacement` has been updated from `'under' | 'right' | 'over'` to `'bottom' | 'right'` so you can not place the legend above the visualization anymore. +- The `isVisible` in the `LegendItem` has been renamed to `disabled` in `VizLegendItem`. ## From version 6.x.x to 7.x.x @@ -175,3 +178,5 @@ For more information, refer to [Data frames]({{< relref "data-frames.md">}}). ### Troubleshoot plugin migration As of Grafana 7.0, backend plugins can now be cryptographically signed to verify their origin. By default, Grafana ignores unsigned plugins. For more information, refer to [Allow unsigned plugins]({{< relref "../../plugins/plugin-signatures.md#allow-unsigned-plugins" >}}). + +### 7.0 Deprecations From e57608b8830e23ba373b5c5da0fe4e994061e189 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Wed, 8 Sep 2021 10:24:32 +0200 Subject: [PATCH 04/31] added information about the data frame format changes. --- .../developers/plugins/migration-guide.md | 57 ++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 5ff906ad6c4d6..9fa0bb67f105b 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -15,7 +15,12 @@ This guide explains how to migrate Grafana plugins from previous version to the - [From version 7.x.x to 8.0.0](#from-version-7xx-to-800) - [Backend plugin v1 support has been dropped](#backend-plugin-v1-support-has-been-dropped) - [Unsigned backend plugins will not be loaded](#unsigned-backend-plugins-will-not-be-loaded) - - [Data frames can now be in either wide or long format](#data-frames-can-now-be-in-either-wide-or-long-format) + - [Time series data can now be in wide or many format](#time-series-data-can-now-be-in-wide-or-many-format) + - [Update react-hook-form from v6 to v7](#update-react-hook-form-from-v6-to-v7) + - [Update the plugin.json](#update-the-pluginjson) + - [Update imports to match emotion 11](#update-imports-to-match-emotion-11) + - [8.0 Deprecations](#80-deprecations) + - [Grafana theme v1](#grafana-theme-v1) - [From version 6.2.x to 7.4.0](#from-version-62x-to-740) - [Legend components](#legend-components) - [From version 6.x.x to 7.0.0](#from-version-6xx-to-700) @@ -28,10 +33,60 @@ This guide explains how to migrate Grafana plugins from previous version to the ## From version 7.x.x to 8.x.x +This guide will help you migrate Grafana v7.x.x plugins to the updated plugin system released with Grafana v8.x.x. All the changes described below might not be applicable to your plugin but we will try to cover all breaking changes in Grafana v8.x.x and what steps you need to take to upgrade your plugin. + ### Backend plugin v1 support has been dropped +### Unsigned backend plugins will not be loaded + +We strongly recommend our Grafana users not to allow unsigned plugins in their Grafana installation. By allowing unsigned plugins, we can’t guarantee the authenticity of the plugin which could compromise the security of your Grafana installation. + +This means that you, as a plugin developer, need to get your plugin signed if you want it to be able to run on all Grafana installations. + +Follow the following [steps](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#sign-a-plugin) to get instructions on how to set up plugin signing. + +You will still be able to run and develop your plugin during development by running your Grafana [instance in development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). + +### Time series data can now be structured in a wide or many format. + +Starting in Grafana 8 time series data can either be structured in either `wide` or `many` format. Prior to this version time series data was delivered in the following format (which is the `many` format). + +| time | temperature | +| -------------------- | ----------- | +| 2021-05-08T07:31:45Z | 23 | +| 2021-05-08T09:31:45Z | 25 | +| 2021-05-08T11:31:45Z | 27 | + +| time | humidity | +| -------------------- | -------- | +| 2021-05-08T07:31:45Z | 60 | +| 2021-05-08T09:31:45Z | 55 | +| 2021-05-08T11:31:45Z | 55 | + +> Data delivered as an array of data frames (time field needs to be repeated). + +That made it possible to detect time series data by inspecting the data frame. If it had two fields (time + value) it most likley was time series data. This is no longer possible since the same data can be delivered in the following `wide` format. + +| time | temperature | humidity | +| -------------------- | ----------- | -------- | +| 2021-05-08T07:31:45Z | 23 | 60 | +| 2021-05-08T09:31:45Z | 25 | 55 | +| 2021-05-08T11:31:45Z | 27 | 55 | + +> Data delivered as one single data frame (the values share the same time field). + +If your plugin should support time series data we recommend you to make sure to support both. + +### Update react-hook-form from v6 to v7 + +### Update the plugin.json + +### Update imports to match emotion 11 + ### 8.0 deprecations +#### Grafana theme v1 + ## From version 6.2.x to 7.4.0 ### Legend components From 842ebfacc63b1edca68bc9b5c6c10bf66655b2a8 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Wed, 8 Sep 2021 10:30:43 +0200 Subject: [PATCH 05/31] added plugin.json changes. --- .../developers/plugins/migration-guide.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 9fa0bb67f105b..4ee4b6e6e1f08 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -81,6 +81,26 @@ If your plugin should support time series data we recommend you to make sure to ### Update the plugin.json +The property of defining what Grafana version your plugin support has been renamed. + +```json +// before +{ +"dependencies": { + "grafanaVersion": "7.5.x", + "plugins": [] + } +} + +// after +{ + "dependencies": { + "grafanaDependency": "8.0.0", + "plugins": [] + } +} +``` + ### Update imports to match emotion 11 ### 8.0 deprecations From 122bf21b78752a8c8f5f5ca708b07d6252666146 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Wed, 8 Sep 2021 11:08:57 +0200 Subject: [PATCH 06/31] added emotion 11 imports. --- docs/sources/developers/plugins/migration-guide.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 4ee4b6e6e1f08..df1017d269325 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -103,6 +103,16 @@ The property of defining what Grafana version your plugin support has been renam ### Update imports to match emotion 11 +Grafana uses emotion to manage the styling of the frontend. The emotion package has now been updated which might affect your frontend plugin if you have any custom styling in it. Luckily you only need to update the import statements to get it working in Grafana 8. + +```ts +// before +import { cx, css } from 'emotion'; + +// after +import { cx, css } from '@emotion/css'; +``` + ### 8.0 deprecations #### Grafana theme v1 From b1d99f27c4c0f80c0d60652bb547d93089c2fd89 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Wed, 8 Sep 2021 11:18:59 +0200 Subject: [PATCH 07/31] added information about theme v1 being deprecated. --- .../developers/plugins/migration-guide.md | 76 ++++++++++++++++++- 1 file changed, 74 insertions(+), 2 deletions(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index df1017d269325..59bafbfb4296e 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -117,6 +117,80 @@ import { cx, css } from '@emotion/css'; #### Grafana theme v1 +In Grafana 8 we have introduced a new improved version of our theming system. The previous version of the theming system is still available but deprecated and will be removed in the next major version of Grafana. + +You can find more detailed information on how to apply the v2 theme [here](https://github.com/grafana/grafana/blob/main/contribute/style-guides/themes.md#theming-grafana). + +**How to use the theme in a functional component** + +```ts +// before +import React, { ReactElement } from 'react'; +import { useTheme } from '@grafana/ui'; + +function Component(): ReactElement | null { + const theme = useTheme(); +} + +// after +import React, { ReactElement } from 'react'; +import { useTheme2 } from '@grafana/ui'; + +function Component(): ReactElement | null { + const theme = useTheme2(); + // Your component has access to the theme variables now +} +``` + +**How to use the theme in a class component** + +```ts +// before +import React from 'react'; +import { Themeable, withTheme } from '@grafana/ui'; + +type Props = {} & Themeable; + +class Component extends React.Component { + render() { + const { theme } = this.props; + // Your component has access to the theme variables now + } +} + +export default withTheme(Component); + +// after +import React from 'react'; +import { Themeable2, withTheme2 } from '@grafana/ui'; + +type Props = {} & Themeable2; + +class Component extends React.Component { + render() { + const { theme } = this.props; + // Your component has access to the theme variables now + } +} + +export default withTheme2(Component); +``` + +**Gradually migrating components** + +If you end up in a situation where you need to use both the v1 and v2 theme due to using migraded and non-migrated components in the same context you can handle that by using the `v1` property on the `v2` theme as described below. + +```ts +function Component(): ReactElement | null { + const theme = useTheme2(); + return ( + + + + ); +}; +``` + ## From version 6.2.x to 7.4.0 ### Legend components @@ -263,5 +337,3 @@ For more information, refer to [Data frames]({{< relref "data-frames.md">}}). ### Troubleshoot plugin migration As of Grafana 7.0, backend plugins can now be cryptographically signed to verify their origin. By default, Grafana ignores unsigned plugins. For more information, refer to [Allow unsigned plugins]({{< relref "../../plugins/plugin-signatures.md#allow-unsigned-plugins" >}}). - -### 7.0 Deprecations From bb94e8951e133186d709e7c0cbae950f072f1de9 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Wed, 8 Sep 2021 15:00:25 +0200 Subject: [PATCH 08/31] added steps for backend plugin migration. --- .../developers/plugins/migration-guide.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 59bafbfb4296e..ba8dd026bab4c 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -14,6 +14,9 @@ This guide explains how to migrate Grafana plugins from previous version to the - [From version 7.x.x to 8.0.0](#from-version-7xx-to-800) - [Backend plugin v1 support has been dropped](#backend-plugin-v1-support-has-been-dropped) + - [1. Add dependency on grafana-plugin-sdk-go](#1-add-dependency-on-grafana-plugin-sdk-go) + - [2. Update the way you bootrap your plugin](#2-update-the-way-you-bootrap-your-plugin) + - [3. Update the plugin package](#3-update-the-plugin-package) - [Unsigned backend plugins will not be loaded](#unsigned-backend-plugins-will-not-be-loaded) - [Time series data can now be in wide or many format](#time-series-data-can-now-be-in-wide-or-many-format) - [Update react-hook-form from v6 to v7](#update-react-hook-form-from-v6-to-v7) @@ -37,6 +40,137 @@ This guide will help you migrate Grafana v7.x.x plugins to the updated plugin sy ### Backend plugin v1 support has been dropped +To get your backend plugin running in Grafana 8 you need to use the new [plugin sdk](https://github.com/grafana/grafana-plugin-sdk-go). + +#### 1. Add dependency on grafana-plugin-sdk-go + +Add a dependency on the `https://github.com/grafana/grafana-plugin-sdk-go`. We recommend using [go modules](https://go.dev/blog/using-go-modules) to manage your dependencies. + +#### 2. Update the way you bootrap your plugin + +Update your `main` package to bootstrap via the new plugin sdk. + +```go +// before +package main + +import ( + "github.com/grafana/grafana_plugin_model/go/datasource" + hclog "github.com/hashicorp/go-hclog" + plugin "github.com/hashicorp/go-plugin" + + "github.com/myorgid/datasource/pkg/plugin" +) + +func main() { + pluginLogger.Debug("Running GRPC server") + + ds, err := NewSampleDatasource(pluginLogger); + if err != nil { + pluginLogger.Error("Unable to create plugin"); + } + + plugin.Serve(&plugin.ServeConfig{ + HandshakeConfig: plugin.HandshakeConfig{ + ProtocolVersion: 1, + MagicCookieKey: "grafana_plugin_type", + MagicCookieValue: "datasource", + }, + Plugins: map[string]plugin.Plugin{ + "myorgid-datasource": &datasource.DatasourcePluginImpl{Plugin: ds}, + }, + GRPCServer: plugin.DefaultGRPCServer, + }) +} + +// after +package main + +import ( + "os" + + "github.com/grafana/grafana-plugin-sdk-go/backend/log" + "github.com/grafana/grafana-plugin-sdk-go/backend/datasource" + + "github.com/myorgid/datasource/pkg/plugin" +) + +func main() { + log.DefaultLogger.Debug("Running GRPC server") + + if err := datasource.Manage("myorgid-datasource", NewSampleDatasource, datasource.ManageOpts{}); err != nil { + log.DefaultLogger.Error(err.Error()) + os.Exit(1) + } +} +``` + +#### 3. Update the plugin package + +Update your `plugin` package to use the new plugin sdk. + +```go +// before +package plugin + +import ( + "context" + + "github.com/grafana/grafana_plugin_model/go/datasource" + "github.com/hashicorp/go-hclog" +) + +func NewSampleDatasource(pluginLogger hclog.Logger) (*SampleDatasource, error) { + return &SampleDatasource{ + logger: pluginLogger, + }, nil +} + +type SampleDatasource struct{ + logger hclog.Logger +} + +func (d *SampleDatasource) Query(ctx context.Context, tsdbReq *datasource.DatasourceRequest) (*datasource.DatasourceResponse, error) { + d.logger.Info("QueryData called", "request", req) + // logic for querying your datasource. +} + +// after +package plugin + +import ( + "context" + + "github.com/grafana/grafana-plugin-sdk-go/backend" + "github.com/grafana/grafana-plugin-sdk-go/backend/instancemgmt" + "github.com/grafana/grafana-plugin-sdk-go/backend/log" + "github.com/grafana/grafana-plugin-sdk-go/data" +) + +func NewSampleDatasource(_ backend.DataSourceInstanceSettings) (instancemgmt.Instance, error) { + return &SampleDatasource{}, nil +} + +type SampleDatasource struct{} + + +func (d *SampleDatasource) Dispose() { + // Clean up datasource instance resources. +} + +func (d *SampleDatasource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) { + log.DefaultLogger.Info("QueryData called", "request", req) + // logic for querying your datasource. +} + +func (d *SampleDatasource) CheckHealth(_ context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) { + log.DefaultLogger.Info("CheckHealth called", "request", req) + // The main use case for these health checks is the test button on the + // datasource configuration page which allows users to verify that + // a datasource is working as expected. +} +``` + ### Unsigned backend plugins will not be loaded We strongly recommend our Grafana users not to allow unsigned plugins in their Grafana installation. By allowing unsigned plugins, we can’t guarantee the authenticity of the plugin which could compromise the security of your Grafana installation. From 0b20009c4ef3a7a8bfe57b237f7c741764f89a77 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Wed, 8 Sep 2021 15:12:31 +0200 Subject: [PATCH 09/31] added reference to the migrate hooks v6 -> v7. --- docs/sources/developers/plugins/migration-guide.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index ba8dd026bab4c..3d15464369634 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -213,6 +213,8 @@ If your plugin should support time series data we recommend you to make sure to ### Update react-hook-form from v6 to v7 +We have upgrade the react-hook-form from version 6 to version 7. We recommend follow the [react-hook-form-migration-guide](#https://react-hook-form.com/migrate-v6-to-v7/) to get make your forms compatible with that version. + ### Update the plugin.json The property of defining what Grafana version your plugin support has been renamed. From 79b49b811622a01aa2428d5339cc2eae9791f594 Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Wed, 8 Sep 2021 15:36:25 +0100 Subject: [PATCH 10/31] docs(pluginmigration): introduce getColorForTheme changes --- .../developers/plugins/migration-guide.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 3d15464369634..a40165347d1b2 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -344,6 +344,32 @@ import { VizLegendItem, VizLegendOptions, VizLegend } from '@grafana/ui'; - `LegendPlacement` has been updated from `'under' | 'right' | 'over'` to `'bottom' | 'right'` so you can not place the legend above the visualization anymore. - The `isVisible` in the `LegendItem` has been renamed to `disabled` in `VizLegendItem`. +## From version 6.5.x to 7.3.0 + +### getColorForTheme changes + +The `getColorForTheme` function arguments have changed from `(color: ColorDefinition, theme?: GrafanaThemeType)` to `(color: string, theme: GrafanaTheme)`. + +```ts +// before +const color: ColorDefinition = { + hue: 'green'; + name: 'dark-green'; + variants: { + light: '#19730E' + dark: '#37872D' + }; +} +const themeType: GrafanaThemeType = 'dark'; +const themeColor = getColorForTheme(color, themeType); + +// after +const color = 'green'; +const theme: GrafanaTheme = useTheme(); +const themeColor = getColorForTheme(color, theme); + +``` + ## From version 6.x.x to 7.x.x ### What's new in Grafana 7.0? From 36f249cf982fbd9e3f9134d4a4b78aa69f7aadd4 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Thu, 9 Sep 2021 09:58:00 +0200 Subject: [PATCH 11/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: Levente Balogh --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index a40165347d1b2..0a96825d4d11c 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -213,7 +213,7 @@ If your plugin should support time series data we recommend you to make sure to ### Update react-hook-form from v6 to v7 -We have upgrade the react-hook-form from version 6 to version 7. We recommend follow the [react-hook-form-migration-guide](#https://react-hook-form.com/migrate-v6-to-v7/) to get make your forms compatible with that version. +We have upgraded the react-hook-form from version 6 to version 7. We recommend follow the [react-hook-form-migration-guide](https://react-hook-form.com/migrate-v6-to-v7/) to get make your forms compatible with that version. ### Update the plugin.json From 696288ad84fc35a836aaeb3e858b9f30e9cdb273 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Thu, 9 Sep 2021 09:58:12 +0200 Subject: [PATCH 12/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: Jack Westbrook --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 0a96825d4d11c..48eb6c04a09dd 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -46,7 +46,7 @@ To get your backend plugin running in Grafana 8 you need to use the new [plugin Add a dependency on the `https://github.com/grafana/grafana-plugin-sdk-go`. We recommend using [go modules](https://go.dev/blog/using-go-modules) to manage your dependencies. -#### 2. Update the way you bootrap your plugin +#### 2. Update the way you bootstrap your plugin Update your `main` package to bootstrap via the new plugin sdk. From a417125f4b15637a72cfae6fdfef6180fa26c15d Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Thu, 9 Sep 2021 09:58:20 +0200 Subject: [PATCH 13/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: Levente Balogh --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 48eb6c04a09dd..85b55dc2371b7 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -217,7 +217,7 @@ We have upgraded the react-hook-form from version 6 to version 7. We recommend f ### Update the plugin.json -The property of defining what Grafana version your plugin support has been renamed. +The property of defining what Grafana version your plugin supports has been renamed. ```json // before From 2ad9ea378b23d5bba36365c64215a1abaef1ff26 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Thu, 9 Sep 2021 09:58:27 +0200 Subject: [PATCH 14/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: Levente Balogh --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 85b55dc2371b7..5541ff55d310b 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -253,7 +253,7 @@ import { cx, css } from '@emotion/css'; #### Grafana theme v1 -In Grafana 8 we have introduced a new improved version of our theming system. The previous version of the theming system is still available but deprecated and will be removed in the next major version of Grafana. +In Grafana 8 we have introduced a new improved version of our theming system. The previous version of the theming system is still available but is deprecated and will be removed in the next major version of Grafana. You can find more detailed information on how to apply the v2 theme [here](https://github.com/grafana/grafana/blob/main/contribute/style-guides/themes.md#theming-grafana). From 0ee2d15433f9f38e097383cf07101bbf260574e6 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Thu, 9 Sep 2021 09:58:33 +0200 Subject: [PATCH 15/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: Levente Balogh --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 5541ff55d310b..e97dc636ca885 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -314,7 +314,7 @@ export default withTheme2(Component); **Gradually migrating components** -If you end up in a situation where you need to use both the v1 and v2 theme due to using migraded and non-migrated components in the same context you can handle that by using the `v1` property on the `v2` theme as described below. +If you end up in a situation where you need to use both the v1 and v2 theme due to using migrated and non-migrated components in the same context you can handle that by using the `v1` property on the `v2` theme as described below. ```ts function Component(): ReactElement | null { From 2ab648ee7552088cbe0014fd155efe3d73a580c8 Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Thu, 9 Sep 2021 15:27:05 +0100 Subject: [PATCH 16/31] docs(migration-guide): introduce useStyles to v8 deprecation notes --- .../developers/plugins/migration-guide.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index e97dc636ca885..1c065c02516f2 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -257,6 +257,46 @@ In Grafana 8 we have introduced a new improved version of our theming system. Th You can find more detailed information on how to apply the v2 theme [here](https://github.com/grafana/grafana/blob/main/contribute/style-guides/themes.md#theming-grafana). +**How to style a functional component** + +The `useStyles` hook is the preferred way to access the theme when styling. It provides basic memoization and access to the theme object. + +```ts +// before +import React, { ReactElement } from 'react'; +import css from 'emotion'; +import { GrafanaTheme } from '@grafana/data'; +import { useStyles } from '@grafana/ui'; + +function Component(): ReactElement | null { + const styles = useStyles(getStyles); +} + +const getStyles = (theme: GrafanaTheme) => ({ + myStyle: css` + background: ${theme.colors.bodyBg}; + display: flex; + `, +}); + +// after +import React, { ReactElement } from 'react'; +import { css } from '@emotion/css'; +import { GrafanaTheme2 } from '@grafana/data'; +import { useStyles2 } from '@grafana/ui'; + +function Component(): ReactElement | null { + const theme = useStyles2(getStyles); +} + +const getStyles = (theme: GrafanaTheme2) => ({ + myStyle: css` + background: ${theme.colors.background.canvas}; + display: flex; + `, +}); +``` + **How to use the theme in a functional component** ```ts From e34d16796db070a78c5f686065baa47a41bfc7f5 Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Fri, 10 Sep 2021 16:06:24 +0200 Subject: [PATCH 17/31] Apply suggestions from code review Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- .../developers/plugins/migration-guide.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 1c065c02516f2..06f1d851530aa 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -6,16 +6,16 @@ title = "Plugin migration guide" ## Introduction -This guide explains how to migrate Grafana plugins from previous version to the latest version available. It is structured in a way where you easily should be able to identify what steps you need to take given the Grafana version your plugin currently support. +This guide helps you identify the steps you need to take based on the Grafana version your plugin supports and explains how to migrate the plugin to the 8.2.x or a later version. -> If you've successfully migrated your plugin by using this guide and think something is missing, please [submit an issue on GitHub](https://github.com/grafana/grafana/issues/new?title=Docs%20feedback:%20/developers/plugins/migration-guide.md) and share your experiences with us so that we can improve this guide! +> **Note:** If you've successfully migrated your plugin using this guide, then share your experiences with us! If you find missing information, then we encourage you to [submit an issue on GitHub](https://github.com/grafana/grafana/issues/new?title=Docs%20feedback:%20/developers/plugins/migration-guide.md) so that we can improve this guide! ## Table of contents - [From version 7.x.x to 8.0.0](#from-version-7xx-to-800) - [Backend plugin v1 support has been dropped](#backend-plugin-v1-support-has-been-dropped) - [1. Add dependency on grafana-plugin-sdk-go](#1-add-dependency-on-grafana-plugin-sdk-go) - - [2. Update the way you bootrap your plugin](#2-update-the-way-you-bootrap-your-plugin) + - [2. Update the way you bootstrap your plugin](#2-update-the-way-you-bootstrap-your-plugin) - [3. Update the plugin package](#3-update-the-plugin-package) - [Unsigned backend plugins will not be loaded](#unsigned-backend-plugins-will-not-be-loaded) - [Time series data can now be in wide or many format](#time-series-data-can-now-be-in-wide-or-many-format) @@ -36,11 +36,11 @@ This guide explains how to migrate Grafana plugins from previous version to the ## From version 7.x.x to 8.x.x -This guide will help you migrate Grafana v7.x.x plugins to the updated plugin system released with Grafana v8.x.x. All the changes described below might not be applicable to your plugin but we will try to cover all breaking changes in Grafana v8.x.x and what steps you need to take to upgrade your plugin. +This section explains how to migrate Grafana v7.x.x plugins to the updated plugin system available in Grafana v8.x.x. Depending on your plugin, you need to perform one or more of the following steps. We have documented the breaking changes in Grafana v8.x.x and the steps you need to take to upgrade your plugin. ### Backend plugin v1 support has been dropped -To get your backend plugin running in Grafana 8 you need to use the new [plugin sdk](https://github.com/grafana/grafana-plugin-sdk-go). +Use the new [plugin sdk](https://github.com/grafana/grafana-plugin-sdk-go) to run your backend plugin running in Grafana 8. #### 1. Add dependency on grafana-plugin-sdk-go @@ -173,11 +173,9 @@ func (d *SampleDatasource) CheckHealth(_ context.Context, req *backend.CheckHeal ### Unsigned backend plugins will not be loaded -We strongly recommend our Grafana users not to allow unsigned plugins in their Grafana installation. By allowing unsigned plugins, we can’t guarantee the authenticity of the plugin which could compromise the security of your Grafana installation. +Before you can run a backend plugin on Grafana installations, you must sign the plugin. Grafana Labs strongly recommends you upload signed plugins since we cannot guarantee the integrity of unsigned plugins. -This means that you, as a plugin developer, need to get your plugin signed if you want it to be able to run on all Grafana installations. - -Follow the following [steps](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#sign-a-plugin) to get instructions on how to set up plugin signing. +For instructions on plugin signing, refer to the [Plugin signatures](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#sign-a-plugin) topic. You will still be able to run and develop your plugin during development by running your Grafana [instance in development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). @@ -213,7 +211,7 @@ If your plugin should support time series data we recommend you to make sure to ### Update react-hook-form from v6 to v7 -We have upgraded the react-hook-form from version 6 to version 7. We recommend follow the [react-hook-form-migration-guide](https://react-hook-form.com/migrate-v6-to-v7/) to get make your forms compatible with that version. +We have upgraded react-hook-form from version 6 to version 7. We recommend following the [react-hook-form-migration-guide](https://react-hook-form.com/migrate-v6-to-v7/) to make your forms compatible with version 7. ### Update the plugin.json From 5cf84353fa572f74afba4b0862a7ac8336c78965 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Mon, 13 Sep 2021 10:36:47 +0200 Subject: [PATCH 18/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/developers/plugins/migration-guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 06f1d851530aa..41b3269bf0788 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -181,7 +181,9 @@ You will still be able to run and develop your plugin during development by runn ### Time series data can now be structured in a wide or many format. -Starting in Grafana 8 time series data can either be structured in either `wide` or `many` format. Prior to this version time series data was delivered in the following format (which is the `many` format). +In Grafana 8.x, you can structure time series data in either `wide` or `many` formats. If your plugin supports time series data, we recommend that you support both formats. + +Grafana supported only the `many` format before. For example: | time | temperature | | -------------------- | ----------- | From 90067bb5af2e69b66942317010d6efbe257cefb9 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Mon, 13 Sep 2021 11:53:47 +0200 Subject: [PATCH 19/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 41b3269bf0788..a7828f3c7f0f5 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -197,7 +197,7 @@ Grafana supported only the `many` format before. For example: | 2021-05-08T09:31:45Z | 55 | | 2021-05-08T11:31:45Z | 55 | -> Data delivered as an array of data frames (time field needs to be repeated). +> Data is delivered as an array of data frames where the `time` field is repeated. That made it possible to detect time series data by inspecting the data frame. If it had two fields (time + value) it most likley was time series data. This is no longer possible since the same data can be delivered in the following `wide` format. From deabba2832a4eb1d41019287e5a6e33d15d371ab Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Mon, 13 Sep 2021 11:55:10 +0200 Subject: [PATCH 20/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index a7828f3c7f0f5..d66cef74737cf 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -217,7 +217,7 @@ We have upgraded react-hook-form from version 6 to version 7. We recommend follo ### Update the plugin.json -The property of defining what Grafana version your plugin supports has been renamed. +The property that defines which Grafana version your plugin supports has been renamed. ```json // before From be60dc410cd6bb14c03429fed03e186fb7b1811b Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Mon, 13 Sep 2021 11:56:06 +0200 Subject: [PATCH 21/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index d66cef74737cf..b2c5b8216b78f 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -239,7 +239,7 @@ The property that defines which Grafana version your plugin supports has been re ### Update imports to match emotion 11 -Grafana uses emotion to manage the styling of the frontend. The emotion package has now been updated which might affect your frontend plugin if you have any custom styling in it. Luckily you only need to update the import statements to get it working in Grafana 8. +Grafana uses Emotion library to manage frontend styling. We have updated the Emotion package and this can affect your frontend plugin if you have custom styling. You only need to update the import statements to get it working in Grafana 8. ```ts // before From a7d2fa35801a01a3705870818a7e6a551526287e Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Mon, 13 Sep 2021 11:57:48 +0200 Subject: [PATCH 22/31] suggestion from review. --- docs/sources/developers/plugins/migration-guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 41b3269bf0788..36bda9577b576 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -6,9 +6,9 @@ title = "Plugin migration guide" ## Introduction -This guide helps you identify the steps you need to take based on the Grafana version your plugin supports and explains how to migrate the plugin to the 8.2.x or a later version. +This guide helps you identify the steps you need to take based on the Grafana version your plugin supports and explains how to migrate the plugin to the 8.2.x or a later version. -> **Note:** If you've successfully migrated your plugin using this guide, then share your experiences with us! If you find missing information, then we encourage you to [submit an issue on GitHub](https://github.com/grafana/grafana/issues/new?title=Docs%20feedback:%20/developers/plugins/migration-guide.md) so that we can improve this guide! +> **Note:** If you've successfully migrated your plugin using this guide, then share your experiences with us! If you find missing information, then we encourage you to [submit an issue on GitHub](https://github.com/grafana/grafana/issues/new?title=Docs%20feedback:%20/developers/plugins/migration-guide.md) so that we can improve this guide! ## Table of contents @@ -36,7 +36,7 @@ This guide helps you identify the steps you need to take based on the Grafana ve ## From version 7.x.x to 8.x.x -This section explains how to migrate Grafana v7.x.x plugins to the updated plugin system available in Grafana v8.x.x. Depending on your plugin, you need to perform one or more of the following steps. We have documented the breaking changes in Grafana v8.x.x and the steps you need to take to upgrade your plugin. +This section explains how to migrate Grafana v7.x.x plugins to the updated plugin system available in Grafana v8.x.x. Depending on your plugin, you need to perform one or more of the following steps. We have documented the breaking changes in Grafana v8.x.x and the steps you need to take to upgrade your plugin. ### Backend plugin v1 support has been dropped @@ -177,7 +177,7 @@ Before you can run a backend plugin on Grafana installations, you must sign the For instructions on plugin signing, refer to the [Plugin signatures](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#sign-a-plugin) topic. -You will still be able to run and develop your plugin during development by running your Grafana [instance in development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). +You can still run and develop an unsigned plugin by running your Grafana instance in [development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). ### Time series data can now be structured in a wide or many format. From b7ba113ffa992c35760f76275581e37a08ecd9f8 Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Tue, 14 Sep 2021 16:52:20 +0200 Subject: [PATCH 23/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index b8fcc27903c33..9db0805331a07 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -207,7 +207,7 @@ That made it possible to detect time series data by inspecting the data frame. I | 2021-05-08T09:31:45Z | 25 | 55 | | 2021-05-08T11:31:45Z | 27 | 55 | -> Data delivered as one single data frame (the values share the same time field). +> Data is delivered as a single data frame where multiple values share the same `time` field. If your plugin should support time series data we recommend you to make sure to support both. From 94780024891b0f2fcdca3fa2c6effe2a6f626e06 Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Wed, 15 Sep 2021 11:21:17 +0200 Subject: [PATCH 24/31] docs(Migration Guide): update the example for `grafanaDependency` --- docs/sources/developers/plugins/migration-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 9db0805331a07..7b64d1016b801 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -217,7 +217,7 @@ We have upgraded react-hook-form from version 6 to version 7. We recommend follo ### Update the plugin.json -The property that defines which Grafana version your plugin supports has been renamed. +The property that defines which Grafana version your plugin supports has been renamed and now it is a range instead of a specific version. ```json // before @@ -231,7 +231,7 @@ The property that defines which Grafana version your plugin supports has been re // after { "dependencies": { - "grafanaDependency": "8.0.0", + "grafanaDependency": ">=8.0.0", "plugins": [] } } From d4fc48acbc80b38747588157c4390f156db0125c Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Wed, 15 Sep 2021 11:32:09 +0200 Subject: [PATCH 25/31] docs(Migration Guide): remove the time-series migration part for now --- .../developers/plugins/migration-guide.md | 33 ------------------- 1 file changed, 33 deletions(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 7b64d1016b801..730248be632eb 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -18,7 +18,6 @@ This guide helps you identify the steps you need to take based on the Grafana ve - [2. Update the way you bootstrap your plugin](#2-update-the-way-you-bootstrap-your-plugin) - [3. Update the plugin package](#3-update-the-plugin-package) - [Unsigned backend plugins will not be loaded](#unsigned-backend-plugins-will-not-be-loaded) - - [Time series data can now be in wide or many format](#time-series-data-can-now-be-in-wide-or-many-format) - [Update react-hook-form from v6 to v7](#update-react-hook-form-from-v6-to-v7) - [Update the plugin.json](#update-the-pluginjson) - [Update imports to match emotion 11](#update-imports-to-match-emotion-11) @@ -179,38 +178,6 @@ For instructions on plugin signing, refer to the [Plugin signatures](https://gra You can still run and develop an unsigned plugin by running your Grafana instance in [development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). -### Time series data can now be structured in a wide or many format. - -In Grafana 8.x, you can structure time series data in either `wide` or `many` formats. If your plugin supports time series data, we recommend that you support both formats. - -Grafana supported only the `many` format before. For example: - -| time | temperature | -| -------------------- | ----------- | -| 2021-05-08T07:31:45Z | 23 | -| 2021-05-08T09:31:45Z | 25 | -| 2021-05-08T11:31:45Z | 27 | - -| time | humidity | -| -------------------- | -------- | -| 2021-05-08T07:31:45Z | 60 | -| 2021-05-08T09:31:45Z | 55 | -| 2021-05-08T11:31:45Z | 55 | - -> Data is delivered as an array of data frames where the `time` field is repeated. - -That made it possible to detect time series data by inspecting the data frame. If it had two fields (time + value) it most likley was time series data. This is no longer possible since the same data can be delivered in the following `wide` format. - -| time | temperature | humidity | -| -------------------- | ----------- | -------- | -| 2021-05-08T07:31:45Z | 23 | 60 | -| 2021-05-08T09:31:45Z | 25 | 55 | -| 2021-05-08T11:31:45Z | 27 | 55 | - -> Data is delivered as a single data frame where multiple values share the same `time` field. - -If your plugin should support time series data we recommend you to make sure to support both. - ### Update react-hook-form from v6 to v7 We have upgraded react-hook-form from version 6 to version 7. We recommend following the [react-hook-form-migration-guide](https://react-hook-form.com/migrate-v6-to-v7/) to make your forms compatible with version 7. From 4bc40f065f4353bacc40b313eb37db2ffab4c731 Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Wed, 15 Sep 2021 13:23:16 +0200 Subject: [PATCH 26/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: Will Browne --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 730248be632eb..19c80d20efd40 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -176,7 +176,7 @@ Before you can run a backend plugin on Grafana installations, you must sign the For instructions on plugin signing, refer to the [Plugin signatures](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#sign-a-plugin) topic. -You can still run and develop an unsigned plugin by running your Grafana instance in [development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). +You can still run and develop an unsigned plugin by running your Grafana instance in [development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). Alternatively, you can use [this configuration setting.]({{< relref "../administration/#allow_loading_unsigned_plugins" >}}) ### Update react-hook-form from v6 to v7 From 2f418ba5710594d72b3de0177d00e3e0d8cd1aa7 Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Wed, 15 Sep 2021 13:29:33 +0200 Subject: [PATCH 27/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: Ursula Kallio <73951760+osg-grafana@users.noreply.github.com> --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 19c80d20efd40..3c75c76f329c3 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -170,7 +170,7 @@ func (d *SampleDatasource) CheckHealth(_ context.Context, req *backend.CheckHeal } ``` -### Unsigned backend plugins will not be loaded +### Sign and load backend plugins Before you can run a backend plugin on Grafana installations, you must sign the plugin. Grafana Labs strongly recommends you upload signed plugins since we cannot guarantee the integrity of unsigned plugins. From e11fa23f25d26ce162ddb4432fe2c6d909f01176 Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Wed, 15 Sep 2021 13:40:55 +0200 Subject: [PATCH 28/31] docs(Migration Guide): update wording about plugin signing --- docs/sources/developers/plugins/migration-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 3c75c76f329c3..59a69b7f01471 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -172,9 +172,9 @@ func (d *SampleDatasource) CheckHealth(_ context.Context, req *backend.CheckHeal ### Sign and load backend plugins -Before you can run a backend plugin on Grafana installations, you must sign the plugin. Grafana Labs strongly recommends you upload signed plugins since we cannot guarantee the integrity of unsigned plugins. +We strongly recommend that you not allow unsigned plugins in your Grafana installation. By allowing unsigned plugins, we cannot guarantee the authenticity of the plugin, which could compromise the security of your Grafana installation. -For instructions on plugin signing, refer to the [Plugin signatures](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#sign-a-plugin) topic. +To sign your plugin, see [Sign a plugin](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#sign-a-plugin). You can still run and develop an unsigned plugin by running your Grafana instance in [development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). Alternatively, you can use [this configuration setting.]({{< relref "../administration/#allow_loading_unsigned_plugins" >}}) From 6aeaa19029646dd407a7a484a6ab25d3041b076d Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Wed, 15 Sep 2021 15:48:45 +0200 Subject: [PATCH 29/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 59a69b7f01471..fb85784222d30 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -180,7 +180,7 @@ You can still run and develop an unsigned plugin by running your Grafana instanc ### Update react-hook-form from v6 to v7 -We have upgraded react-hook-form from version 6 to version 7. We recommend following the [react-hook-form-migration-guide](https://react-hook-form.com/migrate-v6-to-v7/) to make your forms compatible with version 7. +We have upgraded react-hook-form from version 6 to version 7. To make your forms compatible with version 7, refer to the [react-hook-form-migration-guide](https://react-hook-form.com/migrate-v6-to-v7/). ### Update the plugin.json From 930926394f57e57db5c4c25a450ced5e814ca468 Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Wed, 15 Sep 2021 15:49:00 +0200 Subject: [PATCH 30/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index fb85784222d30..d50f20dac310d 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -176,7 +176,7 @@ We strongly recommend that you not allow unsigned plugins in your Grafana instal To sign your plugin, see [Sign a plugin](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#sign-a-plugin). -You can still run and develop an unsigned plugin by running your Grafana instance in [development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). Alternatively, you can use [this configuration setting.]({{< relref "../administration/#allow_loading_unsigned_plugins" >}}) +You can still run and develop an unsigned plugin by running your Grafana instance in [development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). Alternatively, you can use the [allow_loading_unsigned_plugins configuration setting.]({{< relref "../administration/#allow_loading_unsigned_plugins" >}}) ### Update react-hook-form from v6 to v7 From 39e2e5f3ff12f5e39ddb9fef8b02b984a9bcc427 Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Wed, 15 Sep 2021 15:49:21 +0200 Subject: [PATCH 31/31] Update docs/sources/developers/plugins/migration-guide.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/developers/plugins/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index d50f20dac310d..46e6d43ce0cb1 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -321,7 +321,7 @@ export default withTheme2(Component); **Gradually migrating components** -If you end up in a situation where you need to use both the v1 and v2 theme due to using migrated and non-migrated components in the same context you can handle that by using the `v1` property on the `v2` theme as described below. +If you need to use both the v1 and v2 themes due to using migrated and non-migrated components in the same context, use the `v1` property on the `v2` theme as described in the following example. ```ts function Component(): ReactElement | null {