[main] RHIDP-5605 - Plugin installation documentation improvement for adding 'forceDownload' field (redhat-developer#996)

* RHIDP-5605 - Plugin installation documentation improvement for adding 'forceDownload' field

* Update modules/dynamic-plugins/con-dynamic-plugins-cache.adoc

Co-authored-by: Lindsey Frazier <[email protected]>

* Update modules/dynamic-plugins/con-dynamic-plugins-cache.adoc

Co-authored-by: Lindsey Frazier <[email protected]>

* Update modules/dynamic-plugins/con-dynamic-plugins-cache.adoc

Co-authored-by: Lindsey Frazier <[email protected]>

* Update modules/dynamic-plugins/con-dynamic-plugins-cache.adoc

Co-authored-by: Lindsey Frazier <[email protected]>

* RHIDP-5605 - Plugin installation documentation improvement for adding 'forceDownload' field

---------

Co-authored-by: Gerry-Forde <[email protected]>
Co-authored-by: Gerry-Forde <[email protected]>
Co-authored-by: Lindsey Frazier <[email protected]>

Author: 3 people

modules/dynamic-plugins/con-dynamic-plugins-cache.adoc

@@ -55,14 +55,24 @@ Future versions of the {product-very-short} operator are planned to automaticall
 ====
 
 == Configuring the dynamic plugins cache
-You can set the following optional dynamic plugin cache parameters:
+You can set the following optional dynamic plugin cache parameters in your `dynamic-plugins.yaml` file:
 
-* `forceDownload`: Set to `true` to force a reinstall of the plugin, bypassing the cache. Default is `false`. For example, modify your `dynamic-plugins.yaml` file as follows:
+* `forceDownload`: Set the value to `true` to force a reinstall of the plugin, bypassing the cache. The default value is `false`. 
+
+* `pullPolicy`: Similar to the `forceDownload` parameter and is consistent with other image container platforms. You can use one of the following values for this key:
+
+** `Always`: This value compares the image digest in the remote registry and downloads the artifact if it has changed, even if the plugin was previously downloaded.
+** `IfNotPresent`: This value downloads the artifact if it is not already present in the dynamic-plugins-root folder, without checking image digests.
 +
+[NOTE] 
+The `pullPolicy` setting is also applied to the NPM downloading method, although `Always` will download the remote artifact without a digest check. The existing `forceDownload` option remains functional, however, the `pullPolicy` option takes precedence. The `forceDownload` option may be deprecated in a future {product-short} release.
+
+.Example `dynamic-plugins.yaml` file configuration to download the remote artifact without a digest check:
+
 [source,yaml]
 ----
 plugins:
   - disabled: false
-    forceDownload: true
+    pullPolicy: Always
     package: 'oci://quay.io/example-org/example-plugin:v1.0.0!internal-backstage-plugin-example'
 ----

modules/dynamic-plugins/con-install-dynamic-plugin-helm.adoc

@@ -7,15 +7,25 @@
 [id="con-install-dynamic-plugin-helm_{context}"]
 = Installing dynamic plugins using the Helm chart
 
-You can deploy a {product-short} instance using a Helm chart, which is a flexible installation method. With the Helm chart, you can sideload dynamic plugins into your {product-short} instance without having to recompile your code or rebuild the container.
+You can deploy a {product-short} instance by using a Helm chart, which is a flexible installation method. With the Helm chart, you can sideload dynamic plugins into your {product-short} instance without having to recompile your code or rebuild the container.
 
 To install dynamic plugins in {product-short} using Helm, add the following `global.dynamic` parameters in your Helm chart:
 
-* `plugins`: the dynamic plugins list intended for installation. By default, the list is empty. You can populate the plugins list with the following fields:
-** `package`: a package specification for the dynamic plugin package that you want to install. You can use a package for either a local or an external dynamic plugin installation. For a local installation, use a path to the local folder containing the dynamic plugin. For an external installation, use a package specification from a public NPM repository.
-** `integrity` (required for external packages): an integrity checksum in the form of `<alg>-<digest>` specific to the package. Supported algorithms include `sha256`, `sha384` and `sha512`.
-** `pluginConfig`: an optional plugin-specific `app-config` YAML fragment. See plugin configuration for more information.
+* `plugins`: The dynamic plugins list intended for installation. By default, the list is empty. You can populate the plugins list with the following fields:
+** `package`: A package specification for the dynamic plugin package that you want to install. You can use a package for either a local or an external dynamic plugin installation. For a local installation, use a path to the local folder containing the dynamic plugin. For an external installation, use a package specification from a public NPM repository.
+** `integrity` (required for external packages): An integrity checksum in the form of `<alg>-<digest>` specific to the package. Supported algorithms include `sha256`, `sha384` and `sha512`.
+** `pluginConfig`: An optional plugin-specific `app-config` YAML fragment. See plugin configuration for more information.
 ** `disabled`: disables the dynamic plugin if set to `true`. Default: `false`.
+** `forceDownload`: Set the value to `true` to force a reinstall of the plugin, bypassing the cache. The default value is `false`. 
+
+** `pullPolicy`: Similar to the `forceDownload` parameter and is consistent with other image container platforms. You can use one of the following values for this key:
+
+*** `Always`: This value compares the image digest in the remote registry and downloads the artifact if it has changed, even if the plugin was previously downloaded.
+*** `IfNotPresent`: This value downloads the artifact if it is not already present in the dynamic-plugins-root folder, without checking image digests.
++
+[NOTE] 
+The `pullPolicy` setting is also applied to the NPM downloading method, although `Always` will download the remote artifact without a digest check. The existing `forceDownload` option remains functional, however, the `pullPolicy` option takes precedence. The `forceDownload` option may be deprecated in a future {product-short} release.
+
 * `includes`: a list of YAML files utilizing the same syntax.
 
 [NOTE]