The Grafana Catalog application is one of our favorite features introduced in Grafana 8. It allows installing registered plugins from the official Grafana repository when connected to the Internet, but how do you upgrade and manage Grafana plugins without access to the external network?
With an increasing number of companies moving to the Cloud, there are still many use cases when Grafana instances are deployed offline, have firewall restrictions, and cannot connect to the official repository. Working on such a project, we examined various options to install Grafana plugins.
This article will talk about installing plugins using Grafana CLI (Command-Line Interface) and explain how to create a Private repository.
Manual installation
The easiest way to distribute the plugin to a single Grafana instance is
- Download from the Grafana or GitHub repository.
- Extract it to the particular folder specified in the configuration.
- Restart Grafana.
The advantage of this method is its simplicity. Deploying multiple Grafana instances with various plugins will require custom procedures to install and upgrade utilizing this solution.
Grafana CLI
Grafana CLI is a tool bundled with the Grafana server, which allows the performing of various administrative tasks and managing plugins.
Before Grafana 8, it was the most convenient way to install plugins on Grafana instances from the Grafana repository. It is also used for automated installation.
The general syntax for commands in Grafana CLI is:
grafana-cli [global options] command [command options] [arguments...]
Grafana CLI allows overriding
- Location of the plugin's archive.
- Repository URL to download from.
- Plugins folder, etc.
You can learn more about all those options in the Documentation.
Update from URL
Installing a plugin by overriding the location of the plugin's archive is the most effortless way, which requires copying the plugin's archive to the HTTP(S) server reachable from the Grafana instance and repeating the same step to upgrade in the future.
grafana-cli --insecure --pluginUrl https://company.com/plugins/<plugin-id>-<plugin-version>.zip plugins install <plugin-id>
Update from Repository
The ultimate solution is to create a Private repository with a list of available plugins and versions. Overriding the repository URL allows installing and updating all plugins with the latest versions at once.
The syntax is:
grafana-cli --repo "https://example.com/plugins" plugins install <plugin-id>
Private Repository
Looking around, we couldn't find any information on creating a Private repository so decided to share this information with the community.
Grafana CLI looks for the /plugins/repo subfolder when setting a repository location. If plugins are found, it will display their names with the latest versions.
$ grafana-cli --repo https://volkovlabs.io/plugins plugins list-remote
id: volkovlabs-env-datasource version: 2.2.0
id: volkovlabs-rss-datasource version: 2.3.0
id: volkovlabs-image-panel version: 3.3.0
id: volkovlabs-form-panel version: 2.7.0
id: volkovlabs-echarts-panel version: 4.0.0
id: marcusolsson-calendar-panel version: 1.1.0
id: marcusolsson-dynamictext-panel version: 2.1.0
id: marcusolsson-static-datasource version: 2.1.0
The format for the index file is to create a JSON array with the definition of the plugin and the latest version.
{
"plugins": [
{
"id": "volkovlabs-env-datasource",
"type": "datasource",
"url": "https://github.com/VolkovLabs/volkovlabs-env-datasource",
"versions": [
{
"version": "2.2.0"
}
]
}
]
}
Versions
To list available versions for the specific plugin, provide the plugin's name for the list-versions command.
$ grafana-cli --repo https://volkovlabs.io/plugins plugins list-versions volkovlabs-env-datasource
2.2.0
2.1.0
2.0.0
1.2.0
1.1.0
Grafana CLI will request a file /plugins/repo/volkovlabs-env-datasource and display available versions.
Backend plugins can be stored as separate files for each architecture build or specified as any for an archive with all supporting architecture.
{
"versions": [
{
"arch": {
"any": {}
},
"version": "2.2.0"
},
{
"arch": {
"any": {}
},
"version": "2.1.0"
},
{
"arch": {
"any": {}
},
"version": "2.0.0"
},
{
"arch": {
"any": {}
},
"version": "1.2.0"
},
{
"arch": {
"any": {}
},
"version": "1.1.0"
}
]
}
Download
The next step is to upload plugins to specific locations and install them. To install the latest version of the volkovlabs-env-datasource plugin Grafana CLI will look for the download file in the particular location.
/plugins/volkovlabs-env-datasource/versions/1.1.0/download
Here is an example of how to install the plugin from the Private repository we just created.
$ grafana-cli --repo https://volkovlabs.io/plugins plugins install volkovlabs-env-datasource
✔ Downloaded volkovlabs-env-datasource v2.2.0 zip successfully
Please restart Grafana after installing plugins.
To update all plugins at once, execute.
$ grafana-cli --repo https://volkovlabs.io/plugins plugins update-all
Environment Data Source
If not used correctly, the Environment Data Source plugin might expose environment variables with sensitive information (password, access token, etc.). That limits it from being a part of the official Grafana repository.
As discussed in our previous article, we utilize it for our IoT (Internet of Things) projects, and our Private repository helps us install and update this plugin.
We are constantly updating and improving our Grafana plugins. A private repository has become a part of our workflow to verify and test plugins on our demo server and projects.
