opensource/grafana
1
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-07-28 07:52:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Plugins doc reorganization, part 1 (#69864)

Browse Source 
* Initial commit

* Prettier fixes

* Doc-validator fixes part 1

* Doc-validator fixes part 2

* More doc-validator fixes

* More doc-validator fixes

* Test

* link test

* Linnk test

* Link test

* More fixes

* More fixes

* Doc-validator fixes

* Doc-validator fixes

* fix broken link

* Fix

* Testing

* Doc fixes

* Link fixes

* Fix links

* Update docs/sources/developers/plugins/create-a-grafana-plugin/_index.md

Co-authored-by: David Harris <david.harris@grafana.com>

* Testing

* Testing

* Testing

* Testing

* Doc-validator fixes

* Doc-validator fixes

* Doc-validator fixes

* Fix broken links for plugins reorganization project

* Prettier fixes

* Prettier fixes

* Incorporate reviewer feedback

* Link fixes

* Link fixes

* Link fixes

* Link fix

* Deleted space

* Codeowners fix

* Change grafana.com links to absolute URLs for Hugo

---------

Co-authored-by: David Harris <david.harris@grafana.com>
This commit is contained in:
Joseph Perez
2023-07-05 11:25:11 -07:00
committed by GitHub
parent bdf60d69de
commit f9df1f3051
70 changed files with 563 additions and 412 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/sources/developers/plugins/publish-a-plugin/_index.md
View File

@ -1,11 +1,21 @@
---
description: Topics related to plugin publishing
title: Publish a plugin
title: Publish or sign a plugin
menuTitle: Publish a plugin
keywords:
- grafana
- plugins
- plugin
- publish
- publishing
description: An index to documentation related to plugin publishing and signing.
weight: 400
---
# Publish a plugin
# Publish or sign a plugin
This section contains topics related to publishing Grafana plugins.
This section contains topics related to publishing and signing Grafana plugins.
- [Publishing and signing criteria]({{< relref "../publishing-and-signing-criteria.md">}})
- [Publish or update a plugin]({{< relref "../publish-or-update-a-plugin.md">}})
- [Package a plugin]({{< relref "./package-a-plugin.md" >}})
- [Publishing and signing criteria]({{< relref "./publishing-and-signing-criteria.md" >}})
- [Publish or update a plugin]({{< relref "./publish-or-update-a-plugin.md" >}})
- [Sign a plugin]({{< relref "./sign-a-plugin.md" >}})

76
docs/sources/developers/plugins/publish-a-plugin/package-a-plugin.md Normal file
View File

@ -0,0 +1,76 @@
---
title: Package a plugin
keywords:
- grafana
- plugins
- plugin
- links
- package
- packaging
- packages
description: How to package a plugin
weight: 100
---
# Package a plugin
Package a plugin to organize the plugin code and make it ready for use in your organization. Follow these steps to package the plugin in a ZIP file.
1. Build the plugin
```
yarn install --pure-lockfile
yarn build
```
1. Optional: If your data source plugin has a backend plugin, build it as well.
```
mage
```
Make sure that all the binaries are executable and have a `0755` (`-rwxr-xr-x`) permission.
1. Sign the plugin. To learn more, refer to [Sign a plugin]({{< relref "./sign-a-plugin" >}}).
1. Rename the `dist` directory to match your plugin ID, and then create a ZIP archive.
```
mv dist/ myorg-simple-panel
zip myorg-simple-panel-1.0.0.zip myorg-simple-panel -r
```
1. Optional: Verify that your plugin is packaged correctly using [zipinfo](https://linux.die.net/man/1/zipinfo).
It should look like this:
```
zipinfo grafana-clickhouse-datasource-1.1.2.zip
Archive: grafana-clickhouse-datasource-1.1.2.zip
Zip file size: 34324077 bytes, number of entries: 22
drwxr-xr-x 0 bx stor 22-Mar-24 23:23 grafana-clickhouse-datasource/
-rw-r--r-- 1654 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/CHANGELOG.md
-rw-r--r-- 11357 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/LICENSE
-rw-r--r-- 2468 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/MANIFEST.txt
-rw-r--r-- 8678 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/README.md
drwxr-xr-x 0 bx stor 22-Mar-24 23:23 grafana-clickhouse-datasource/dashboards/
-rw-r--r-- 42973 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/dashboards/cluster-analysis.json
-rw-r--r-- 56759 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/dashboards/data-analysis.json
-rw-r--r-- 39406 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/dashboards/query-analysis.json
-rwxr-xr-x 16469136 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_darwin_amd64
-rwxr-xr-x 16397666 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_darwin_arm64
-rwxr-xr-x 14942208 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_linux_amd64
-rwxr-xr-x 14155776 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_linux_arm
-rwxr-xr-x 14548992 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_linux_arm64
-rwxr-xr-x 15209472 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_windows_amd64.exe
drwxr-xr-x 0 bx stor 22-Mar-24 23:23 grafana-clickhouse-datasource/img/
-rw-r--r-- 304 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/img/logo.png
-rw-r--r-- 1587 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/img/logo.svg
-rw-r--r-- 138400 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/module.js
-rw-r--r-- 808 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/module.js.LICENSE.txt
-rw-r--r-- 487395 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/module.js.map
-rw-r--r-- 1616 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/plugin.json
22 files, 92516655 bytes uncompressed, 34319591 bytes compressed: 62.9%
```
When you've packaged your plugin, you can proceed to [publishing a plugin]({{< relref "./publish-or-update-a-plugin.md" >}}) or [installing a packaged plugin](/docs/grafana/latest/administration/plugin-management/#install-a-packaged-plugin).

136
docs/sources/developers/plugins/publish-a-plugin/publish-or-update-a-plugin.md Normal file
View File

@ -0,0 +1,136 @@
---
title: Publish or update a plugin
aliases:
- ../../plugins/publish-a-plugin/
- share-a-plugin/
keywords:
- grafana
- plugins
- plugin
- publish plugin
- update plugin
description: Learn how to package and share your plugin.
type: docs
weight: 300
---
# Publish or update a plugin
You've just built your plugin; now you want to share it with the world.
In this guide, you'll learn how to package and share your plugin with others.
The best way to share your plugin with the world is to publish it in the [Grafana plugin catalog]{{< relref "/plugins" >}}).
By having your plugin published on Grafana.com, more users will be able to discover your plugin.
## Before you begin
When you build a plugin from source, a `dist` folder is created. This folder contains the production build or _plugin assets_ for your plugin.
To package a plugin, refer to [Package a plugin]({{< relref "./package-a-plugin.md" >}}).
### Follow our guidelines
Get familiar with our plugin [publishing and signing criteria]({{< relref "./publishing-and-signing-criteria" >}})
### Do this for best results
To speed up the time it takes to review your plugin:
- Check that your plugin is ready for review using the [plugin validator](https://github.com/grafana/plugin-validator).
- Read our [6 tips for improving your Grafana plugin before you publish](/blog/2021/01/21/6-tips-for-improving-your-grafana-plugin-before-you-publish/).
- Refer to [plugin-examples](https://github.com/grafana/grafana-plugin-examples) to review best practices for building your plugin.
## Publish your plugin
Follow these steps to publish your plugin for the first time.
1. [Sign in](/auth/sign-in) to your Grafana Cloud account.
1. In the left menu, under **Org settings**, click **My Plugins**.
1. Click **Submit Plugin**. The Create Plugin Submission dialog appears.
{{< figure src="/static/img/docs/plugins/plugins-submission-create2.png" class="docs-image--no-shadow" max-width="650px" >}}
1. Enter the information requested by the form.
- **OS & Architecture:**
- Select **Single** if your plugin archive contains binaries for multiple architectures.
- Select **Multiple** if you'd like to submit separate plugin archives for each architecture.
This can lead to faster downloads since users can select the specific architecture on which they want to install the plugin.
- **URL:** A URL that points to a ZIP archive of your packaged plugin.
- **Source Code URL:** A URL that points to a public Git repository or ZIP archive of your complete plugin source code.
- **MD5:** The MD5 hash of the plugin specified by the **URL**.
- The remaining questions help us determine the [signature level]({{< relref "./sign-a-plugin#plugin-signature-levels" >}}) for your plugin.
1. Click **Submit**.
After you submit your plugin, we run an automated validation to make sure it adheres to our guidelines.
Once your submission passes the validation, it's placed in a review queue.
All submissions are manually inspected by a plugin reviewer.
For every new plugin, we perform a manual review that includes the following checks:
- **Code review:** For quality and security purposes, we review the source code for the plugin.
If you're unable to make the source code publicly available, let us know in a comment on your plugin submission.
- **Tests:** We install your plugin on one of our Grafana instances to test it for basic use.
For more advanced plugins, we may ask you to assist us in configuring a test environment for the plugin.
We use the test environment whenever you submit a plugin update.
## Update your plugin
To submit an **update** for an already published plugin:
1. [Sign in](/auth/sign-in) to your Grafana Cloud account.
1. In the left menu, under **Org settings**, click **My Plugins**.
1. Click **Submit Update** for the plugin you want to update. The Create Plugin Submission dialog appears.
{{< figure src="/static/img/docs/plugins/plugins-submission-create2.png" class="docs-image--no-shadow" max-width="650px" >}}
1. Enter the information requested by the form.
- **OS & Architecture:**
- Select **Single** if your plugin archive contains binaries for multiple architectures.
- Select **Multiple** if you'd like to submit separate plugin archives for each architecture.
This can lead to faster downloads since users can select the specific architecture they want to install the plugin on.
- **URL:** A URL that points to a ZIP archive of your packaged plugin.
- **Source Code URL:** A URL that points to a public Git repository or ZIP archive of your complete plugin source code. See [examples](#what-source-code-url-formats-are-supported).
- **MD5:** The MD5 hash of the plugin specified by the **URL**.
1. Click **Submit**.
## Frequently asked questions
### Do I need to submit a private plugin?
- No. Please only submit plugins that you wish to make publicly available for the Grafana community.
### How long does it take to review my submission?
- We're not able to give an estimate at this time, though we're constantly working on improving the time it takes to review a plugin.
### Can I decide a date when my plugin will be published?
- No. We cannot guarantee specific publishing dates, as plugins are immediately published after a review based on our internal prioritization.
### Can I see metrics of my plugin installs, downloads or usage?
- No. We don't offer this information at the moment to plugin authors.
### How can I update my plugin's catalog page?
- The plugin's catalog page content is extracted from the plugin README file.
To update the plugin's catalog page, submit an updated plugin with the new content included in the README file.
### Can I unlist my plugin from the Grafana plugin catalog in case of a bug?
- In the event of a bug, unlisting the plugin from our catalog may be possible in exceptional cases, such as security concerns. However, we don't have control over the instances where the plugin is installed.
### Can I distribute my plugin somewhere else other than the Grafana plugin catalog?
- The official method for distributing Grafana plugins is through our catalog. Alternative methods, such as installing private or development plugins on local Grafana instances, are available as per the guidelines provided in [this guide]({{< relref "../../../administration/plugin-management#install-plugin-on-local-grafana" >}}).
### Can I still use Angular for my plugin?
- No. We will not accept any new plugin submissions written in Angular. For more information, refer to our [Angular support deprecation documentation]({{< relref "../../angular_deprecation" >}}).
### Do plugin signatures expire?
- Plugin signatures do not currently expire.
### What source code URL formats are supported?
- Using a tag or branch: `https://github.com/grafana/clock-panel/tree/v2.1.3`
- Using a tag or branch and the code is in a subdirectory (important for mono repos): `https://github.com/grafana/clock-panel/tree/v2.1.3/plugin/` (here, the plugin contains the plugin code)
- Using the latest main or master branch commit: `https://github.com/grafana/clock-panel/` (not recommended, it's better to pass a tag or branch)

34
docs/sources/developers/plugins/publish-a-plugin/publishing-and-signing-criteria.md Normal file
View File

@ -0,0 +1,34 @@
---
title: Plugin publishing and signing criteria
description: Acceptance criteria for publishing and signing Grafana plugins.
aliases:
- ../../plugins/publishing-and-signing-criteria/
keywords:
- grafana
- plugins
- plugin
- publish plugin
- sign plugin
- publishing
- signing
weight: 200
---
# Plugin publishing and signing criteria
Grafana plugins must adhere to the Grafana Labs [Plugin Policy](/legal/plugins/). Our review process for publishing and signing will examine your compliance with this policy.
> **Important:** Grafana Labs reserves the right to decline or remove any plugin at its discretion. Failure to comply with publishing and signing criteria may result in immediate removal from the Grafana plugin catalog.
## Plugin licensing
Plugins must be licensed under one of the following AGPL compliant licenses for publishing to the Grafana plugin catalog:
- AGPL-3.0
- Apache-2.0
- BSD
- GPL-3.0
- LGPL-3.0
- MIT
If contributing a plugin on behalf of an organization, be sure to seek guidance from your legal team.

137
docs/sources/developers/plugins/publish-a-plugin/sign-a-plugin.md Normal file
View File

@ -0,0 +1,137 @@
---
title: Sign a plugin
aliases:
- ../../sign-a-plugin
- ../../sign-a-plugin/
description: How to sign a Grafana plugin.
keywords:
- grafana
- plugins
- plugin
- sign plugin
- signing plugin
weight: 400
---
# Sign a plugin
Grafana requires all plugins to be signed so that we can verify their authenticity with [signature verification]({{< relref "../../../administration/plugin-management#plugin-signatures" >}}).
All Grafana Labs-authored backend plugins, including Enterprise plugins, are signed. By [default]({{< relref "../../../administration/plugin-management#allow-unsigned-plugins" >}}), Grafana **requires** all plugins to be signed in order for them to be loaded.
Before you can sign your plugin, you need to decide whether you want to sign it as a _public_ or a _private_ plugin.
To make your plugin publicly available outside of your organization, sign your plugin under a _community_ or _commercial_ [signature level](#plugin-signature-levels). Public plugins are available from the [Grafana plugin catalog](/plugins) and can be installed by anyone.
If you intend to only use the plugin within your organization, sign it under a _private_ [signature level](#plugin-signature-levels).
## Generate an API key
To verify ownership of your plugin, generate an API key that you'll use every time you need to sign a new version of your plugin.
1. [Create a Grafana Cloud account](/signup).
1. Make sure that the first part of the plugin ID matches the slug of your Grafana Cloud account.
You can find the plugin ID in the `plugin.json` file inside your plugin directory. For example, if your account slug is `acmecorp`, you need to prefix the plugin ID with `acmecorp-`.
1. [Create a Grafana Cloud API key](/docs/grafana-cloud/reference/create-api-key/) with the **PluginPublisher** role.
## Sign a public plugin
Public plugins need to be reviewed by the Grafana team before you can sign them.
1. Submit your plugin for [review]({{< relref "./publish-or-update-a-plugin.md#publish-your-plugin" >}}).
1. If we approve your plugin, you're granted a plugin signature level. You need this signature level to proceed.
1. In your plugin directory, sign the plugin with the API key you just created. Grafana Sign Plugin creates a [MANIFEST.txt](#plugin-manifest) file in the `dist` directory of your plugin:
```bash
export GRAFANA_API_KEY=<YOUR_API_KEY>
npx @grafana/sign-plugin@latest
```
## Sign a private plugin
1. In your plugin directory, sign the plugin with the API key you just created. Grafana Sign Plugin creates a [MANIFEST.txt](#plugin-manifest) file in the `dist` directory of your plugin.
```bash
export GRAFANA_API_KEY=<YOUR_API_KEY>
npx @grafana/sign-plugin@latest --rootUrls https://example.com/grafana
```
1. After the `rootUrls` flag, enter a comma-separated list of URLs for the Grafana instances where you intend to install the plugin.
## Plugin signature levels
To sign a plugin, you need to select the _signature level_ that you want to sign it under. The signature level of your plugin determines how you can distribute it.
You can sign your plugin under three different _signature levels_: _private_, _community_, and _commercial_.
| **Plugin Level** | **Paid Subscription Required?** | **Description** |
| ---------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Private | No;<br>Free of charge | <p>You can create and sign a Private plugin for any technology at no charge.</p><p>Private plugins are intended for use on your own installation of Grafana. They may not be distributed to the Grafana community, and they are not published in the Grafana plugin catalog.</p> |
| Community | No;<br>Free of charge | <p>You can create, sign, and distribute plugins at no charge, provided that all dependent technologies are open source and not for profit.</p><p>Community plugins are published in the official Grafana catalog, and are available to the entire Grafana community.</p> |
| Commercial | Yes;<br>Commercial plugin subscription required | <p>You can create, sign, and distribute plugins with dependent technologies that are closed source or commercially backed. To do so, enter into a Commercial plugin subscription with Grafana Labs.</p><p>Commercial plugins are published on the Grafana plugin catalog, and are available to the entire Grafana community.</p> |
For instructions on how to sign a plugin under the Community and Commercial signature level, refer to [Sign a public plugin](#sign-a-public-plugin).
For instructions on how to sign a plugin under the Private signature level, refer to [Sign a private plugin](#sign-a-private-plugin).
## Plugin manifest
For Grafana to verify the digital signature of a plugin, the plugin must include a signed manifest file, `MANIFEST.txt`. The signed manifest file contains two sections:
- **Signed message -** Contains plugin metadata and plugin files with their respective checksums (SHA256).
- **Digital signature -** Created by encrypting the signed message using a private key. Grafana has a public key built-in that can be used to verify that the digital signature has been encrypted using the expected private key.
**Example**
```txt
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
{
"manifestVersion": "2.0.0",
"signatureType": "community",
"signedByOrg": "myorgid",
"signedByOrgName": "My Org",
"plugin": "myorgid-simple-panel",
"version": "1.0.0",
"time": 1602753404133,
"keyId": "7e4d0c6a708866e7",
"files": {
"LICENSE": "12ab7a0961275f5ce7a428e662279cf49bab887d12b2ff7bfde738346178c28c",
"module.js.LICENSE.txt": "0d8f66cd4afb566cb5b7e1540c68f43b939d3eba12ace290f18abc4f4cb53ed0",
"module.js.map": "8a4ede5b5847dec1c6c30008d07bef8a049408d2b1e862841e30357f82e0fa19",
"plugin.json": "13be5f2fd55bee787c5413b5ba6a1fae2dfe8d2df6c867dadc4657b98f821f90",
"README.md": "2d90145b28f22348d4f50a81695e888c68ebd4f8baec731fdf2d79c8b187a27f",
"module.js": "b4b6945bbf3332b08e5e1cb214a5b85c82557b292577eb58c8eb1703bc8e4577"
}
}
-----BEGIN PGP SIGNATURE-----
Version: OpenPGP.js v4.10.1
Comment: https://openpgpjs.org
wqEEARMKAAYFAl+IE3wACgkQfk0ManCIZudpdwIHTCqjVzfm7DechTa7BTbd
+dNIQtwh8Tv2Q9HksgN6c6M9nbQTP0xNHwxSxHOI8EL3euz/OagzWoiIWulG
7AQo7FYCCQGucaLPPK3tsWaeFqVKy+JtQhrJJui23DAZLSYQYZlKQ+nFqc9x
T6scfmuhWC/TOcm83EVoCzIV3R5dOTKHqkjIUg==
=GdNq
-----END PGP SIGNATURE-----
```
## Troubleshooting
### Why do I get a "Modified signature" error?
In some cases an invalid `MANIFEST.txt` is generated because of an issue when signing the plugin on Windows. You can fix this by replacing all double backslashes, `\\`, with a forward slash, `/`, in the `MANIFEST.txt` file. You need to do this every time you sign your plugin.
### Why do I get a "Field is required: `rootUrls`" error for my public plugin?
With a **public** plugin, your plugin doesn't have a plugin signature level assigned to it yet. A Grafana team member will assign a signature level to your plugin once it has been reviewed and approved. For more information, refer to [Sign a public plugin](#sign-a-public-plugin).
### Why do I get a "Field is required: `rootUrls`" error for my private plugin?
With a **private** plugin, you need to add a `rootUrls` flag to the `plugin:sign` command. The `rootUrls` must match the [root_url]({{< relref "../../../setup-grafana/configure-grafana#root_url" >}}) configuration. For more information, refer to [Sign a private plugin](#sign-a-private-plugin).
If you still get this error, make sure that the API key was generated by a Grafana Cloud account that matches the first part of the plugin ID.