mirror of
https://github.com/grafana/grafana.git
synced 2024-11-25 10:20:29 -06:00
Docs/usman plugin mgmt (#85424)
* fixed text and better formatting * added examples of community and partners plugins * added more clarity to apps plugin usage * added and also fixed more * added clarity to the server and org admin roles * run prettier * fixed some minor typos * Apply suggestions from code review thanks. looks good now- Co-authored-by: David Harris <david.harris@grafana.com> * Technical edit * restorted the changes in panel and datasource examples as requested * revert duplicated change * Apply suggestions from code review Thanks Jack for the suggestions. Looks good!! Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * added minor adjustment * fixed typo * added bash syntax * revert changes * added changes from PR 87168 for index.md file * Delete docs/sources/shared/find-and-use-plugins.md removed this file from the PR as was not intended to be part of this PR. This PR is only for the Grafana OSS and not for the Grafana Cloud * run prettier * Apply suggestions from code review Co-authored-by: David Harris <david.harris@grafana.com> * Update docs/sources/administration/plugin-management/index.md Co-authored-by: David Harris <david.harris@grafana.com> * Update docs/sources/administration/plugin-management/index.md Co-authored-by: David Harris <david.harris@grafana.com> * added a small text fix * added cloud tag in product labels * run prettier * Apply suggestions from code review thanks for the review Co-authored-by: Joseph Perez <45749060+josmperez@users.noreply.github.com> * fixed typo for note section * run prettier to fix --------- Co-authored-by: David Harris <david.harris@grafana.com> Co-authored-by: Joe Perez <joseph.perez@grafana.com> Co-authored-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Joseph Perez <45749060+josmperez@users.noreply.github.com>
This commit is contained in:
Usman Ahmad
GitHub
parent
bffd87107b
commit
6bf69d141e
@ -8,6 +8,7 @@ aliases:
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- cloud
|
||||
- oss
|
||||
title: Plugin management
|
||||
weight: 600
|
||||
@ -15,11 +16,17 @@ weight: 600
|
||||
|
||||
# Plugin management
|
||||
|
||||
Besides the wide range of visualizations and data sources that are available immediately after you install Grafana, you can extend your Grafana experience with _plugins_.
|
||||
You can enhance your Grafana experience with _plugins_, extensions to Grafana beyond the wide range of visualizations and data sources that are built-in.
|
||||
|
||||
You can [install](#install-a-plugin) one of the plugins built by the Grafana community, or [build one yourself](/developers/plugin-tools).
|
||||
This guide shows you how to [install](#install-a-plugin) plugins that are built by Grafana Labs, commercial partners, our community, or plugins that you have [built yourself](/developers/plugin-tools).
|
||||
|
||||
Grafana supports three types of plugins: [panels](/grafana/plugins?type=panel), [data sources](/plugins?type=datasource), and [apps](/grafana/plugins?type=app).
|
||||
## Types of plugins
|
||||
|
||||
Grafana supports three types of plugins:
|
||||
|
||||
- [Panels](/grafana/plugins/panel-plugins) - These plugins make it easy to create and add any kind of panel, to show your data, or improve your favorite dashboards.
|
||||
- [Data sources](/grafana/plugins/data-source-plugins) - These plugins allow you to pull data from various data sources such as databases, APIs, log files, and so on, and display it in the form of graphs, charts, and dashboards in Grafana.
|
||||
- [Apps](/grafana/plugins/app-plugins) - These plugins enable the bundling of data sources, panels, dashboards, and Grafana pages into a cohesive experience.
|
||||
|
||||
## Panel plugins
|
||||
|
||||
@ -37,7 +44,7 @@ Data source plugins add support for new databases, such as [Google BigQuery](/gr
|
||||
|
||||
Data source plugins communicate with external sources of data and return the data in a format that Grafana understands. By adding a data source plugin, you can immediately use the data in any of your existing dashboards.
|
||||
|
||||
Use data source plugins when you want to import data from external systems.
|
||||
Use data source plugins when you want to query data from external or third-party systems.
|
||||
|
||||
## App plugins
|
||||
|
||||
@ -47,29 +54,29 @@ Apps can also add custom pages for things like control panels.
|
||||
|
||||
Use app plugins when you want an out-of-the-box monitoring experience.
|
||||
|
||||
### Managing app plugins access
|
||||
### Managing access for app plugins
|
||||
|
||||
With [RBAC]({{< relref "../roles-and-permissions/access-control/#about-rbac" >}}), it is now possible to customize access to app plugins.
|
||||
Customize access to app plugins with [RBAC]({{< relref "../roles-and-permissions/access-control/#about-rbac" >}}).
|
||||
|
||||
By default, Viewers, Editors and Admins have access to all App Plugins that their organization role allows them to access, thanks to the `fixed:plugins.app:reader` role.
|
||||
By default, the Viewer, Editor and Admin roles have access to all app plugins that their Organization role allows them to access. Access is granted by the `fixed:plugins.app:reader` role.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Revoking this RBAC role from some users, will prevent them from accessing app plugins. But granting this RBAC role to users will only allow them to see app plugins their organization role allows them to see.
|
||||
To prevent users from seeing an app plugin, refer to [these permissions scenarios]({{< relref "../roles-and-permissions/access-control/plan-rbac-rollout-strategy#prevent-viewers-from-accessing-an-app-plugin" >}}).
|
||||
{{% /admonition %}}
|
||||
|
||||
To prevent users from seeing an app plugin, refer to [this permissions scenarios]({{< relref "../roles-and-permissions/access-control/plan-rbac-rollout-strategy#prevent-viewers-from-accessing-an-app-plugin" >}}).
|
||||
|
||||
## Plugin catalog
|
||||
|
||||
The Plugin catalog allows you to browse and manage plugins from within Grafana. Only Grafana server administrators and organization administrators can access and use the plugin catalog. The following access rules apply depending on the user role:
|
||||
The Grafana plugin catalog allows you to browse and manage plugins from within Grafana. Only Grafana server administrators and Organization administrators can access and use the plugin catalog. For more information about Grafana roles and permissions, refer to [Roles and permissions]({{< relref "../administration/roles-and-permissions" >}}).
|
||||
|
||||
| Org Admin | Server Admin | Permissions |
|
||||
| --------- | ------------ | ------------------------------------------------------------------------------------------- |
|
||||
| ✓ | ✓ | <ul><li>Can configure app plugins</li><li>Can install/uninstall/update plugins</li></ul> |
|
||||
| ✓ | × | <ul><li>Can configure app plugins</li><li>Cannot install/uninstall/update plugins</li></ul> |
|
||||
| × | ✓ | <ul><li>Cannot configure app plugins</li><li>Can install/uninstall/update plugins</li></ul> |
|
||||
The following access rules apply depending on the user role:
|
||||
|
||||
> **Note:** The Plugin catalog is designed to work with a single Grafana server instance only. Support for Grafana clusters will be added in future Grafana releases.
|
||||
- If you are an **Org Admin**, you can configure app plugins, but you can't install, uninstall, or update them.
|
||||
- If you are a **Server Admin**, you can't configure app plugins, but you can install, uninstall, or update them.
|
||||
- If you are both **Org Admin** and **Server Admin**, you can configure app plugins and also install, uninstall, or update them.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
The Grafana plugin catalog is designed to work with a single Grafana server instance only. Support for Grafana clusters is planned for future Grafana releases.
|
||||
{{% /admonition %}}
|
||||
|
||||
<div class="medium-6 columns">
|
||||
<video width="700" height="600" controls>
|
||||
@ -80,81 +87,79 @@ The Plugin catalog allows you to browse and manage plugins from within Grafana.
|
||||
|
||||
_Video shows the Plugin catalog in a previous version of Grafana._
|
||||
|
||||
In order to be able to install / uninstall / update plugins using plugin catalog, you must enable it via the `plugin_admin_enabled` flag in the [configuration]({{< relref "../../setup-grafana/configure-grafana/#plugin_admin_enabled" >}}) file.
|
||||
Before following the steps below, make sure you are logged in as a Grafana administrator.
|
||||
{{% admonition type="note" %}}
|
||||
If required, the Grafana plugin catalog can be disabled using the `plugin_admin_enabled` flag in the [configuration]({{< relref "../../setup-grafana/configure-grafana/#plugin_admin_enabled" >}}) file.
|
||||
{{% /admonition %}}
|
||||
|
||||
<a id="#plugin-catalog-entry"></a>
|
||||
|
||||
Administrators can find the Plugin catalog at **Administration > Plugins and data > Plugins**.
|
||||
|
||||
### Browse plugins
|
||||
|
||||
To browse for available plugins:
|
||||
|
||||
1. In Grafana, click **Administration > Plugins and data > Plugins** in the side navigation menu to view installed plugins.
|
||||
1. Click the **All** filter to browse all available plugins.
|
||||
1. While logged into Grafana as an administrator, click **Administration > Plugins and data > Plugins** in the side menu to view installed and available plugins.
|
||||
1. Use the search to filter based on name, keywords, organization and other metadata.
|
||||
1. Click the **Data sources**, **Panels**, or **Applications** buttons to filter by plugin type.
|
||||
|
||||
### Install a plugin
|
||||
|
||||
To install a plugin:
|
||||
|
||||
1. In Grafana, click **Administration > Plugins and data > Plugins** in the side navigation menu to view installed plugins.
|
||||
1. Click the **All** filter to browse all available plugins.
|
||||
1. In Grafana, click **Administration > Plugins and data > Plugins** in the side navigation menu to view all plugins.
|
||||
1. Browse and find a plugin.
|
||||
1. Click on the plugin logo.
|
||||
1. Click the plugin's logo.
|
||||
1. Click **Install**.
|
||||
|
||||
When the update is complete, you see a confirmation message that the installation was successful.
|
||||
When the update is complete, you'll see a confirmation message that the installation was successful.
|
||||
|
||||
### Update a plugin
|
||||
|
||||
To update a plugin:
|
||||
|
||||
1. In Grafana, click **Administration > Plugins and data > Plugins** in the side navigation menu to view installed plugins.
|
||||
1. Click on the plugin logo.
|
||||
1. In Grafana, click **Administration > Plugins and data > Plugins** in the side navigation menu to view all plugins.
|
||||
1. Click the **Installed** filter to show only installed plugins.
|
||||
1. Click the plugin's logo.
|
||||
1. Click **Update**.
|
||||
|
||||
When the update is complete, you see a confirmation message that the update was successful.
|
||||
When the update is complete, you'll see a confirmation message that the update was successful.
|
||||
|
||||
### Uninstall a plugin
|
||||
|
||||
To uninstall a plugin:
|
||||
|
||||
1. In Grafana, click **Administration > Plugins and data > Plugins** in the side navigation menu to view installed plugins.
|
||||
1. Click on the plugin logo.
|
||||
1. In Grafana, click **Administration > Plugins and data > Plugins** in the side navigation menu to view all plugins.
|
||||
1. Click the plugin's logo.
|
||||
1. Click the **Installed** filter to show only installed plugins.
|
||||
1. Click **Uninstall**.
|
||||
|
||||
When the update is complete, you see a confirmation message that the uninstall was successful.
|
||||
When the update is complete, you'll see a confirmation message that the uninstall was successful.
|
||||
|
||||
## Install Grafana plugins
|
||||
|
||||
Grafana supports data source, panel, and app plugins. Having panels as plugins makes it easy to create and add any kind of panel, to show your data, or improve your favorite dashboards. Apps enable the bundling of data sources, panels, dashboards, and Grafana pages into a cohesive experience.
|
||||
Grafana supports data source, panel, and app plugins.
|
||||
|
||||
1. In a web browser, navigate to the official [Grafana Plugins page](/plugins) and find a plugin that you want to install.
|
||||
1. In a web browser, navigate to the [Grafana plugin catalog](https://grafana.com/plugins) and find a plugin that you want to install.
|
||||
1. Click the plugin, and then click the **Installation** tab.
|
||||
|
||||
### Install plugin on Grafana Cloud
|
||||
|
||||
On the Installation tab, in the **For** field, click the name of the Grafana instance that you want to install the plugin on.
|
||||
On the **Installation tab**, in the **For** field, click the name of the Grafana instance on which you want to install the plugin.
|
||||
|
||||
Grafana Cloud handles the plugin installation automatically.
|
||||
|
||||
If you are logged in to Grafana Cloud when you add a plugin, log out and back in again to use the new plugin.
|
||||
If you're logged in to Grafana Cloud when you add a plugin, log out and then log back in again to use the new plugin.
|
||||
|
||||
### Install plugin on local Grafana
|
||||
|
||||
Follow the instructions on the Install tab. You can either install the plugin with a Grafana CLI command or by downloading and uncompress a .zip file into the Grafana plugins directory. We recommend using Grafana CLI in most instances. The .zip option is available if your Grafana server does not have access to the internet.
|
||||
Follow the instructions on the **Install** tab. You can either install the plugin with a Grafana CLI command or by downloading and uncompressing a zip file into the Grafana plugins directory. We recommend using Grafana CLI in most instances. The zip option is available if your Grafana server doesn't have access to the internet.
|
||||
|
||||
For more information about Grafana CLI plugin commands, refer to [Plugin commands]({{< relref "../../cli/#plugins-commands" >}}).
|
||||
|
||||
As of Grafana v8.0, a plugin catalog app was introduced in order to make managing plugins easier. For more information, refer to [Plugin catalog]({{< relref "#plugin-catalog" >}}).
|
||||
|
||||
#### Install a packaged plugin
|
||||
|
||||
After the user has downloaded the archive containing the plugin assets, they can install it by extracting the archive into their plugin directory.
|
||||
After the user has downloaded the archive containing the plugin assets, they can install it by extracting the archive into their plugin directory. For example:
|
||||
|
||||
```
|
||||
```bash
|
||||
unzip my-plugin-0.2.0.zip -d YOUR_PLUGIN_DIR/my-plugin
|
||||
```
|
||||
|
||||
@ -162,9 +167,9 @@ The path to the plugin directory is defined in the configuration file. For more
|
||||
|
||||
## Plugin signatures
|
||||
|
||||
Plugin signature verification (signing) is a security measure to make sure plugins haven't been tampered with. Upon loading, Grafana checks to see if a plugin is signed or unsigned when inspecting and verifying its digital signature.
|
||||
Plugin signature verification, also known as _signing_, is a security measure to make sure plugins haven't been tampered with. Upon loading, Grafana checks to see if a plugin is signed or unsigned when inspecting and verifying its digital signature.
|
||||
|
||||
At startup, Grafana verifies the signatures of every plugin in the plugin directory. If a plugin is unsigned, then Grafana does not load nor start it. To see the result of this verification for each plugin, navigate to **Configuration** -> **Plugins**.
|
||||
At startup, Grafana verifies the signatures of every plugin in the plugin directory. If a plugin is unsigned, then Grafana neither loads nor starts it. To see the result of this verification for each plugin, navigate to **Configuration** -> **Plugins**.
|
||||
|
||||
Grafana also writes an error message to the server log:
|
||||
|
||||
@ -177,26 +182,28 @@ If you are a plugin developer and want to know how to sign your plugin, refer to
|
||||
| Signature status | Description |
|
||||
| ------------------ | ------------------------------------------------------------------------------- |
|
||||
| Core | Core plugin built into Grafana. |
|
||||
| Invalid signature | The plugin has a invalid signature. |
|
||||
| Invalid signature | The plugin has an invalid signature. |
|
||||
| Modified signature | The plugin has changed since it was signed. This may indicate malicious intent. |
|
||||
| Unsigned | The plugin is not signed. |
|
||||
| Signed | The plugin signature was successfully verified. |
|
||||
|
||||
### Plugin signature levels
|
||||
|
||||
All plugins is signed under a _signature level_. The signature level determines how the plugin can be distributed.
|
||||
All plugins are signed under a _signature level_. The signature level determines how the plugin can be distributed.
|
||||
|
||||
| **Plugin Level** | **Description** |
|
||||
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Private | <p>Private plugins are for use on your own Grafana. They may not be distributed to the Grafana community, and are not published in the Grafana catalog.</p> |
|
||||
| Community | <p>Community plugins have dependent technologies that are open source and not for profit.</p><p>Community plugins are published in the official Grafana catalog, and are available to the Grafana community.</p> |
|
||||
| Commercial | <p>Commercial plugins have dependent technologies that are closed source or commercially backed.</p><p>Commercial Plugins are published on the official Grafana catalog, and are available to the Grafana community.</p> |
|
||||
| Commercial | <p>Commercial plugins have dependent technologies that are closed source or commercially backed.</p><p>Commercial plugins are published on the official Grafana catalog, and are available to the Grafana community.</p> |
|
||||
|
||||
### Allow unsigned plugins
|
||||
|
||||
> **Note:** Unsigned plugins are not supported in Grafana Cloud.
|
||||
{{% admonition type="note" %}}
|
||||
Unsigned plugins are not supported in Grafana Cloud.
|
||||
{{% /admonition %}}
|
||||
|
||||
We strongly recommend that you don't run unsigned plugins in your Grafana instance. If you're aware of the risks and you still want to load an unsigned plugin, refer to [Configuration]({{< relref "../../setup-grafana/configure-grafana/#allow_loading_unsigned_plugins" >}}).
|
||||
We strongly recommend that you don't run unsigned plugins in your Grafana instance. However, if you're aware of the risks and you still want to load an unsigned plugin, refer to [Configuration]({{< relref "../../setup-grafana/configure-grafana/#allow_loading_unsigned_plugins" >}}).
|
||||
|
||||
If you've allowed loading of an unsigned plugin, then Grafana writes a warning message to the server log:
|
||||
|
||||
@ -210,4 +217,6 @@ If you're developing a plugin, then you can enable development mode to allow all
|
||||
|
||||
## Learn more
|
||||
|
||||
- Browse the available [Plugins](/grafana/plugins)
|
||||
- [Browse plugins](/grafana/plugins)
|
||||
- [Develop plugins](/developers/plugin-tools)
|
||||
- [Plugin development Community](https://community.grafana.com/c/plugin-development/30)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user