RHIDP-7560 - Install and configure plugins from Extensions page

assemblies/dynamic-plugins/assembly-extensions-plugins.adoc

@@ -32,12 +32,44 @@ include::../modules/dynamic-plugins/con-catalog-searching-and-filtering.adoc[lev
 // Viewing a plugin - screenshots added post 1.5 GA, so this section is no longer necessary
 // include::../modules/dynamic-plugins/ref-catalog-plugin.adoc[leveloffset=+2]
 
-// Installing a plugin
-include::../modules/dynamic-plugins/proc-extensions-installing.adoc[leveloffset=+1]
-
 // Disabling Extensions 
 include::../modules/dynamic-plugins/proc-extensions-disabling.adoc[leveloffset=+1]
 
+// START RHDH 1.7.0
+// ==========
+// Managing plugins installation by using Extensions
+include::../modules/dynamic-plugins/con-extensions-managing-plugins.adoc[leveloffset=+1]
+
+// Configuring an RBAC role to manage Extensions 
+include::../modules/dynamic-plugins/proc-extensions-configuring-rbac-role.adoc[leveloffset=+2]
+
+// Enabling plugins installation by using Extensions
+include::../modules/dynamic-plugins/proc-extensions-enabling-plugins-installation.adoc[leveloffset=+2]
+
+// Installing plugins by using Extensions
+include::../modules/dynamic-plugins/proc-extensions-installing-plugins.adoc[leveloffset=+2]
+
+// Configuring plugins by using Extensions
+include::../modules/dynamic-plugins/proc-extensions-configuring-plugins.adoc[leveloffset=+2]
+
+// Troubleshooting plugins installation by using Extensions [Stretch]
+// include::../modules/dynamic-plugins/con-extensions-troubleshooting-plugins-installation.adoc[leveloffset=+1]
+// ==========
+
+// Enabling plugins installation by using Extensions
+// include::../modules/dynamic-plugins/proc-extensions-enabling.adoc[leveloffset=+1]
+
+// Managing plugins [TBC]
+//include::../modules/dynamic-plugins/proc-extensions-managing.adoc[leveloffset=+1]
+
+// Installing a plugin [TBC]
+//include::../modules/dynamic-plugins/proc-extensions-installing.adoc[leveloffset=+1]
+
+// END RHDH 1.7.0
+
+// Operator installation by using plugin extension
+//include::../modules/dynamic-plugins/proc-operator-installing-a-plugin-using-extensions.adoc[leveloffset=+1]
+
 // Managing the extensions plugin entries - For 1.6+
 //include::../modules/dynamic-plugins/proc-extensions-managing.adoc[leveloffset=+1]
 

modules/dynamic-plugins/con-extensions-managing-plugins.adoc

@@ -0,0 +1,19 @@
+[id="con-extensions-managing-plugins_{context}"]
+= Managing plugins by using Extensions
+
+You can install and configure plugins by using Extensions.
+
+[WARNING]
+Installation and configuration of plugins by using Extensions will only work in development environments. This feature is not supported in production environments.
+
+In a production environment, users will be notified that plugin installation is not permitted.
+
+image::rhdh/extensions-restart-plugin-1.png[]
+
+In a development environment: 
+
+* Administrators can install a plugin using the default configuration preloaded in the editor, or modify the configuration before installing. Upon successful installation, users will be notified that a backend restart is required to complete the installation process.
+* When a plugin is installed, administrators can access the Actions drop-down in the plugin’s side panel. Available actions include:
+** Editing the configuration used during installation
+** Disabling or enabling the plugin
+** After performing any of these actions, users will be notified that a backend restart is required for the changes to take effect.

modules/dynamic-plugins/proc-extensions-configuring-plugins.adoc

@@ -0,0 +1,27 @@
+[id="proc-extensions-configuring-plugins_{context}"]
+= Enabling and disabling plugins by using Extensions
+
+.Prerequisites
+* You have configured {product-very-short} to allow plugins installation from *Extensions*.
+* You have configured RBAC to allow the current user to access to manage plugin configuration.
+
+.Procedure
+. Navigate to *Extensions*.
+. Select a plugin to enable or disable.
+. Click on the Enable/Disable slider.
++
+image::rhdh/extensions-enable-plugin-1.png[]
+. To view the plugins that require a restart, click *View plugins* in the alert message.
++
+image::rhdh/extensions-install-plugin-3.png[]
+. Restart your {product-very-short} application.
+
+.Verification
+. After you restart your {product-very-short} application, navigate to *Extensions*.
+. Select the plugin that you have installed.
+. The Enable/Disable slider is updated.
+
+
+
+
+

modules/dynamic-plugins/proc-extensions-enabling-plugins-installation.adoc

@@ -0,0 +1,92 @@
+[id="proc-extensions-enabling-plugins-installation_{context}"]
+= Configuring {product-very-short} to install plugins by using Extensions
+
+When you install a plugin, the configuration that you use is saved to a dynamic plugins cache to ensure that the same configuration is available when you edit, or re-enable the plugin. 
+
+You must create a persistent volume cache (PVC) to ensure that the cache persists when you restart the {product-very-short} application. For more information about using the dynamic plugins cache, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/configuring_red_hat_developer_hub/index#using-the-dynamic-plugins-cache_running-behind-a-proxy[Using the dynamic plugins cache].
+
+.Prequisites
+* You have created a persistent volume claim (PVC) for the dynamic plugins cache with the name *dynamic-plugins-route*.
+* You have installed Red Hat Developer Hub using the Helm chart.
+* You have installed the OpenShift CLI (`oc`).
+
+.Procedure
+. Create the marketplace configuration file and save it as `dynamic-plugins.marketplace.yaml`. For example:
++
+[source,yaml]
+----
+plugins:
+  - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic
+    disabled: false
+    pluginConfig:
+      extensions:
+        installation:
+          enabled: true
+          saveToSingleFile:
+            file: /opt/app-root/src/dynamic-plugins-root/dynamic-plugins.marketplace.yaml
+----
+. Copy the file to your cluster by running the following commands:
++
+[source,yaml]
+----
+oc get pods -n <your-namespace>
+
+oc cp ./dynamic-plugins.marketplace.yaml <your-namespace>/<pod-name>:/opt/app-root/src/dynamic-plugins-root/dynamic-plugins.marketplace.yaml
+----
+. Upgrade the Helm release to use this file and update environment variable to development:
++
+[source,yaml]
+----
+global:
+ auth:
+   backend:
+     enabled: true
+ clusterRouterBase: apps.rosa.iuosa-vcqyd-ek4.jryo.p3.openshiftapps.com
+ dynamic:
+   includes:
+     - dynamic-plugins.default.yaml
+     - /dynamic-plugins-root/dynamic-plugins.marketplace.yaml
+upstream:
+ backstage:
+   extraEnvVars:
+     - name: NODE_ENV
+       value: development
+----
+. Click *Upgrade*
+
+. Add the following configuration for the Extensions UI package in your `redhat-developer-hub-dynamic-plugins` config map, to include the newly added mount point:
++
+[source,yaml,subs="+attributes"]
+----
+data:
+  dynamic-plugins.yaml: |
+    includes:
+    - dynamic-plugins.default.yaml
+    - /dynamic-plugins-root/dynamic-plugins.marketplace.yaml
+    plugins: 
+    - package: ./dynamic-plugins/dist/backstage-community-plugin-rbac
+    - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace
+      disabled: false
+      pluginConfig:
+        dynamicPlugins:
+            frontend:
+            red-hat-developer-hub.backstage-plugin-marketplace:
+                appIcons:
+                - name: marketplace
+                    importName: MarketplaceIcon
+                dynamicRoutes:
+                - path: /extensions/catalog
+                    importName: DynamicMarketplacePluginRouter
+                mountPoints:
+                - mountPoint: application/provider
+                    importName: InstallationContextProvider
+                - mountPoint: internal.plugins/tab
+                    importName: DynamicMarketplacePluginContent
+                    config:
+                    path: marketplace
+                    title: Catalog
+----
+. Click *Save*
+
+
+// .Validation

modules/dynamic-plugins/proc-extensions-enabling.adoc

@@ -0,0 +1,51 @@
+[id="rhdh-extensions-plugins-enabling_{context}"]
+= Enabling plugins installation by using Extensions
+Using the extensions UI, the extensions backend now requires additional configuration in the app config, users must explicitly enable the installation and specify the file path from which the plug-in configuration should be read if the file path is missing or invalid installation will be disabled.
+
+[NOTE]
+When you visit *Extensions*, before you enable extensions plugin installation, you will see an information message saying that the plugin installation is disabled.
+
+.Prerequisites
+* You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.
+* You are in development mode.
+* You have created the plugin configuration file and added the file path in your `app-config.yaml` file.
+* You have the correct RBAC permissions.
+// * You have installed the `oc` CLI [TBC].
+
+////  
+ISSUES
+I dont't see a warning message when I access RHDH in production mode - Is this the latest version?
+Configure RBAC
+Add PVC
+////
+
+.Procedure
+. Switch to *development* mode by editing your app-config.yaml file as follows:
++
+.`app-config.yaml` fragment
+[source,yaml]
+----
+auth:
+  environment: development # Set to 'development' for development mode
+  providers:
+    # ... your providers configured for development mode ...
+    guest: # Example: Guest provider often has specific settings for dev
+      dangerouslyAllowOutsideDevelopment: true # Allows guest login outside of dev mode only if explicitly enabled
+----
+. Create a plugin configuration file to store plugin configuration data when you enable a plugin by using Extensions.
+// dynamic-plugins-test.yaml as configmap
+
+. To enable extensions plugin installation, you must update your `app-config.yaml` file as follows:
++
+.`app-config.yaml` fragment
+[source,yaml]
+----
+extensions:
+  installation:
+    enabled: true
+    saveToSingleFile:
+      file: /<path-to>/dynamic-plugins.yaml
+----
+
+[NOTE]
+If a specific plug-in configuration is not found in the provided file, it will fall back to fetching it from the dynamic artifacts.

modules/dynamic-plugins/proc-extensions-installing-plugins.adoc

@@ -0,0 +1,34 @@
+[id="proc-extensions-installing-plugins_{context}"]
+= Installing plugins by using Extensions
+You can install and configure plugins by using Extensions.
+
+.Prequisites
+* You have configured {product-very-short} to allow plugins installation from *Extensions*.
+// * You have configured RBAC to allow the current user to manage plugin configuration.
+
+.Procedure
+. Navigate to *Extensions*.
+. Select a plugin to install.
+. Click on the *Install* button.
++
+image::rhdh/extensions-install-plugin-1.png[]
+The code editor is displayed which displays the plugin default configuration.
+. Update the plugin configuration, if necessary.
++
+image::rhdh/extensions-install-plugin-2.png[]
+. Click *Install*
+. To view the plugins that require a restart, click *View plugins* in the alert message.
++
+image::rhdh/extensions-install-plugin-3.png[]
+. Restart your {product-very-short} application.
+
+.Verification
+. After you restart your {product-very-short} application, navigate to *Extensions*.
+. Select the plugin that you have installed.
+. The *Actions* button is displayed.
+// . Click on *Edit* to view the configuration that you used to install the plugin.
+
+
+
+
+

modules/dynamic-plugins/proc-extensions-installing.adoc

@@ -1,11 +1,19 @@
 [id="rhdh-extensions-plugins-installing_{context}"]
 = Installing a plugin by using Extensions
+
+[WARNING]
+Installation and configuration of plugins by using Extensions will only work in development environments. This feature is not supported in production environments.
+
 You can install a plugin and configure it by updating the `dynamic-plugins.yaml` file by using *Extensions*.
 
-== Prerequisites
+.Prerequisites
+* Your {product-short} instance running development mode.
+* You have enabled installation of plugins by Extensions.
 * You have the necessary permissions to modify plugin configurations and access the application environment.
 * You have identified and set the required environment variables referenced by the plugin's default configuration. These environment variables must be defined in the Helm Chart or Operator configuration.
 
+
+
 .Procedure
 . Open your {product-short} application and click *Administration* > *Extensions*.
 . Use the search bar on the *Extensions* page to find the plugin you wish to install, then click on the card. For example, search for Tekton and click *Read more* on the *Pipelines With Tekton* card.
@@ -21,36 +29,52 @@ image::rhdh-plugins-reference/rhdh-extensions-tekton-editor-1.png[Extensions cat
 . Click the *Examples* tab to display the default plugin configuration.
 . Click *Apply* to copy the default plugin configuration to the YAML editor.
 . In the YAML editor, click the copy icon to copy the plugin configuration.
+[TODO] Update screenshot to include active Install button.
 +
 image::rhdh-plugins-reference/rhdh-extensions-tekton-editor-2.png[Extensions catalog with Tekton configuration]
-+
-[NOTE]
-In {product-very-short} {product-version}, the *Install* button is disabled, so you must copy the plugin configuration to the `dynamic-plugins.yaml` file.
-. In the `dynamic-plugins.yaml` file, add the plugin configuration that you copied in the previous step to the `plugins` definitions.
+. Click *Install* to install the plugin.
+
+// See also https://gitlab.cee.redhat.com/rhidp/rhdh-team-docs/-/blob/main/docs/teams/ui/plugins-setup-guide.md?ref_type=heads#servicenow for exapmle of installing Service Now from extensions
+
+// +
+// [NOTE]
+// In {product-very-short} {product-version}, the *Install* button is disabled, so you must copy the plugin configuration to the `dynamic-plugins.yaml` file.
+// . In the `dynamic-plugins.yaml` file, add the plugin configuration that you copied in the previous step to the `plugins` definitions.
 +
 [NOTE]
 If you have installed {product-very-short} by using the Helm Chart, to enable the plugin, you may need to roll out your {product-very-short} project manually.
++
+[TODO] Add step about message being displayed to restart pod, remove previous note and include screenshot.
+
+
+Once the RHDH pod is running, navigate to the extensions plugin.
+Select any plugin that you would like to install.
+The install button is disabled because the current user does not have access to manage plugin configurations.
+In RBAC, we need to create a role for this user to enable plugin installation.
+
+Select extensions from the plugin dropdown, expand it to view the newly added permissions for the extensions plugin.
+Select both and click next to create the role.
+Refresh the application 
+Now when I navigate to the extensions plugin and click on a plugin I see an Actions dropdown which means the plugin is preinstalled for me and I now have the access to edit or disable the plugin.
+
+If I disable the plugin, I’m notified to restart the backend to complete the action.
+
+Before I restart let’s install a plugin.
+I’ll filter out the custom plugins, and select the Service Now plugin
+
+I can see that the plugin is not already installed, so I’ll click on Install which takes me to the code editor. If I want to make any changes to this plugin configuration, I can. I’ll apply the default configuration for the front-end package:
+
+You can add a comment and click Install
+In this alert you can view all the plugins that require a backend restart
+
+Switch to my Openshift application and restart my RHDH pod (scale down/up).
+Once the pod is running, switch back to your RHDH application and refresh the browser.
+Verification
+Switch to the Adoption Insights plugin and I can see that it is disabled. The Service Now plugin shows the Actions dropdown with the option to edit and disable the plugin.
+If I click on Edit, the configuration that I used to install the plugin has been loaded in the editor.
+
 
 .Verification
 . Click on *Administration* > *Extensions*.
 . Go to the *Installed* tab to view a list of installed plugins.
 . Search for the plugin that you installed to confirm that it is available and enabled.
-
-////
-. To disable the the Extensions feature plugins, edit your `dynamic-plugins.yaml` with the following content.
-+
-.`dynamic-plugins.yaml` fragment
-[source,yaml]
-----
-plugins:
-  - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace
-    disabled: true
-  - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-catalog-backend-module-marketplace-dynamic
-    disabled: true
-  - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic
-    disabled: true
-----
-
-[NOTE]
-If you disable the Extensions feature plugins, the *Catalog* and *Installed* tabs will also be removed. You can still view installed plugins by clicking on *Administration* > *Extensions*.
-////