From 85e006935ee11ca4c6abf7687eb71aca9449a1f6 Mon Sep 17 00:00:00 2001 From: Andres Martinez Gotor Date: Wed, 4 Dec 2024 15:12:08 +0100 Subject: [PATCH] Docs: Document the plugins preinstall feature (#96464) --- .../administration/plugin-management/index.md | 8 ++++++++ .../sources/setup-grafana/configure-docker.md | 6 +++--- .../setup-grafana/configure-grafana/_index.md | 18 +++++++++++++++++ .../installation/docker/index.md | 20 +++++++++---------- 4 files changed, 39 insertions(+), 13 deletions(-) diff --git a/docs/sources/administration/plugin-management/index.md b/docs/sources/administration/plugin-management/index.md index 9e051c06b70..b4cb6983958 100644 --- a/docs/sources/administration/plugin-management/index.md +++ b/docs/sources/administration/plugin-management/index.md @@ -128,6 +128,14 @@ unzip my-plugin-0.2.0.zip -d YOUR_PLUGIN_DIR/my-plugin The path to the plugin directory is defined in the configuration file. For more information, refer to [Configuration]({{< relref "../../setup-grafana/configure-grafana/#plugins" >}}). +#### Install a plugin using Grafana configuration + +{{% admonition type="note" %}} +This feature requires Grafana 11.5.0 or later. +{{% /admonition %}} + +You can install plugins by adding the plugin ID to the `plugins.preinstall` section in the Grafana configuration file. This prevents the plugin from being accidentally uninstalled and can be auto-updated. For more information, refer to [Configuration]({{< relref "../../setup-grafana/configure-grafana/#plugins" >}}). + #### Install a plugin in air-gapped environment Plugin installation usually requires an internet connection. You can check which endpoints are used during the installation on your instance and add them to your instance’s allowlist. diff --git a/docs/sources/setup-grafana/configure-docker.md b/docs/sources/setup-grafana/configure-docker.md index f70ca7a37b5..0ad1aecabbd 100644 --- a/docs/sources/setup-grafana/configure-docker.md +++ b/docs/sources/setup-grafana/configure-docker.md @@ -103,15 +103,15 @@ You can install publicly available plugins and plugins that are private or used ### Install plugins from other sources -To install plugins from other sources, you must define the custom URL and specify it immediately before the plugin name in the `GF_INSTALL_PLUGINS` environment variable: `GF_INSTALL_PLUGINS=;`. +To install plugins from other sources, you must define the custom URL and specify it immediately before the plugin name in the `GF_PLUGINS_PREINSTALL` environment variable: `GF_PLUGINS_PREINSTALL=@[]@`. Example: -The following command runs Grafana Enterprise on **port 3000** in detached mode and installs the custom plugin, which is specified as a URL parameter in the `GF_INSTALL_PLUGINS` environment variable. +The following command runs Grafana Enterprise on **port 3000** in detached mode and installs the custom plugin, which is specified as a URL parameter in the `GF_PLUGINS_PREINSTALL` environment variable. ```bash docker run -d -p 3000:3000 --name=grafana \ - -e "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;custom-plugin,grafana-clock-panel" \ + -e "GF_PLUGINS_PREINSTALL=custom-plugin@@http://plugin-domain.com/my-custom-plugin.zip,grafana-clock-panel" \ grafana/grafana-enterprise ``` diff --git a/docs/sources/setup-grafana/configure-grafana/_index.md b/docs/sources/setup-grafana/configure-grafana/_index.md index ac5c27f35bc..cbd476fef97 100644 --- a/docs/sources/setup-grafana/configure-grafana/_index.md +++ b/docs/sources/setup-grafana/configure-grafana/_index.md @@ -2288,6 +2288,24 @@ Force download of the public key for verifying plugin signature on startup. The Enter a comma-separated list of plugin identifiers to avoid loading (including core plugins). These plugins will be hidden in the catalog. +### preinstall + +Enter a comma-separated list of plugin identifiers to preinstall. These plugins will be installed on startup, using the Grafana catalog as the source. Preinstalled plugins cannot be uninstalled from the Grafana user interface; they need to be removed from this list first. + +To pin plugins to a specific version, use the format `plugin_id@version`, for example,`grafana-piechart-panel@1.6.0`. If no version is specified, the latest version is installed. _The plugin is automatically updated_ to the latest version when a new version is available in the Grafana plugin catalog on startup (except for new major versions). + +To use a custom URL to download a plugin, use the format `plugin_id@version@url`, for example, `grafana-piechart-panel@1.6.0@https://example.com/grafana-piechart-panel-1.6.0.zip`. + +By default, Grafana preinstalls some suggested plugins. Check the default configuration file for the list of plugins. + +### preinstall_async + +By default, plugins are preinstalled asynchronously, as a background process. This means that Grafana will start up faster, but the plugins may not be available immediately. If you need a plugin to be installed for provisioning, set this option to `false`. This causes Grafana to wait for the plugins to be installed before starting up (and fail if a plugin can't be installed). + +### preinstall_disabled + +This option disables all preinstalled plugins. The default is `false`. To disable a specific plugin from being preinstalled, use the `disable_plugins` option. +
## [live] diff --git a/docs/sources/setup-grafana/installation/docker/index.md b/docs/sources/setup-grafana/installation/docker/index.md index 7e7e0bef06f..91ab60a7764 100644 --- a/docs/sources/setup-grafana/installation/docker/index.md +++ b/docs/sources/setup-grafana/installation/docker/index.md @@ -132,37 +132,37 @@ Grafana currently supports three types of plugins: panel, data source, and app. To install plugins in the Docker container, complete the following steps: -1. Pass the plugins you want to be installed to Docker with the `GF_INSTALL_PLUGINS` environment variable as a comma-separated list. +1. Pass the plugins you want to be installed to Docker with the `GF_PLUGINS_PREINSTALL` environment variable as a comma-separated list. - This sends each plugin name to `grafana-cli plugins install ${plugin}` and installs them when Grafana starts. + This starts a background process that installs the list of plugins while Grafana server starts. For example: ```bash docker run -d -p 3000:3000 --name=grafana \ - -e "GF_INSTALL_PLUGINS=grafana-clock-panel, grafana-simple-json-datasource" \ + -e "GF_PLUGINS_PREINSTALL=grafana-clock-panel, grafana-simple-json-datasource" \ grafana/grafana-enterprise ``` -1. To specify the version of a plugin, add the version number to the `GF_INSTALL_PLUGINS` environment variable. +1. To specify the version of a plugin, add the version number to the `GF_PLUGINS_PREINSTALL` environment variable. For example: ```bash docker run -d -p 3000:3000 --name=grafana \ - -e "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1" \ + -e "GF_PLUGINS_PREINSTALL=grafana-clock-panel 1.0.1" \ grafana/grafana-enterprise ``` > **Note:** If you do not specify a version number, the latest version is used. -1. To install a plugin from a custom URL, use the following convention to specify the URL: `;`. +1. To install a plugin from a custom URL, use the following convention to specify the URL: `@[]@`. For example: ```bash docker run -d -p 3000:3000 --name=grafana \ - -e "GF_INSTALL_PLUGINS=https://github.com/VolkovLabs/custom-plugin.zip;custom-plugin" \ + -e "GF_PLUGINS_PREINSTALL=custom-plugin@@https://github.com/VolkovLabs/custom-plugin.zip" \ grafana/grafana-enterprise ``` @@ -180,7 +180,7 @@ docker volume create grafana-storage docker run -d -p 3000:3000 --name=grafana \ --volume grafana-storage:/var/lib/grafana \ -e "GF_SERVER_ROOT_URL=http://my.grafana.server/" \ - -e "GF_INSTALL_PLUGINS=grafana-clock-panel" \ + -e "GF_PLUGINS_PREINSTALL=grafana-clock-panel" \ grafana/grafana-enterprise ``` @@ -355,7 +355,7 @@ services: restart: unless-stopped environment: - GF_SERVER_ROOT_URL=http://my.grafana.server/ - - GF_INSTALL_PLUGINS=grafana-clock-panel + - GF_PLUGINS_PREINSTALL=grafana-clock-panel ports: - '3000:3000' volumes: @@ -364,7 +364,7 @@ volumes: grafana_storage: {} ``` -> **Note:** If you want to specify the version of a plugin, add the version number to the `GF_INSTALL_PLUGINS` environment variable. For example: `-e "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5"`. If you do not specify a version number, the latest version is used. +> **Note:** If you want to specify the version of a plugin, add the version number to the `GF_PLUGINS_PREINSTALL` environment variable. For example: `-e "GF_PLUGINS_PREINSTALL=grafana-clock-panel@1.0.1,grafana-simple-json-datasource@1.3.5"`. If you do not specify a version number, the latest version is used. ## Next steps