Docs: Document the plugins preinstall feature (#96464)

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.

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=<url to plugin zip>;<plugin name>`.
+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=<plugin ID>@[<plugin version>]@<url to plugin zip>`.
 
 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
 ```
 

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.
+
 <hr>
 
 ## [live]

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: `<url to plugin zip>;<plugin install directory name>`.
+1. To install a plugin from a custom URL, use the following convention to specify the URL: `<plugin ID>@[<plugin version>]@<url to plugin zip>`.
 
    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