diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 2f7f0d985e1b..3be345d00228 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -570,6 +570,9 @@ Topics: - Name: Customizing the web console File: customizing-the-web-console Distros: openshift-enterprise,openshift-origin +- Name: Dynamic plug-ins + File: dynamic-plug-ins + Distros: openshift-enterprise,openshift-origin - Name: Developer perspective File: odc-about-developer-perspective - Name: Web terminal diff --git a/modules/about-dynamic-plug-ins.adoc b/modules/about-dynamic-plug-ins.adoc new file mode 100644 index 000000000000..146af455ea10 --- /dev/null +++ b/modules/about-dynamic-plug-ins.adoc @@ -0,0 +1,34 @@ +// Module is included in the following assemblies: +// +// * openshift-docs/web_console/dynamic-plug-ins.adoc + +:_content-type: CONCEPT +[id="about-dynamic-plugins_{context}"] += About dynamic plug-ins + +A dynamic plug-in allows you to add custom pages and other extensions to your interface at runtime. The `ConsolePlugin` custom resource registers plug-ins with the console, and a cluster administrator enables plug-ins in the `console-operator` configuration. + +[id="dynamic-plugins-features"] +== Key features + +A dynamic plug-in allows you to make the following customizations to the {product-title} experience: + +* Add custom pages. +* Add perspectives and update navigation items. +* Add tabs and actions to resource pages. + +== PatternFly 4 guidelines +When creating your plug-in, follow these guidelines for using PatternFly: + +* Use link:https://www.patternfly.org/v4/[PatternFly4] components and PatternFly CSS variables. Core PatternFly components are available through the SDK. Using PatternFly components and variables will help your plug-in look consistent in future console versions. +* Make your plug-in accessible by following link:https://www.patternfly.org/v4/accessibility/accessibility-fundamentals/[PatternFly's accessibility fundamentals]. +* _Do not_ use other CSS libraries such as Bootstrap or Tailwind. They can conflict with PatternFly and will not match the console look and feel. + +[id="general-plug-in-guidelines"] +== General guidelines +When creating your plug-in, follow these general guidelines: + +* Prefix your CSS class names with your plug-in name to avoid collisions. For example, `my-plugin_\_heading` and `my-plugin_\_icon`. +* Maintain a consistent look, feel, and behavior with other console pages. +* Use link:https://github.com/openshift/enhancements/blob/master/enhancements/console/dynamic-plugins.md#localization[react-i18next] for localization. +* _Do not_ use console CSS classes in your markup or override console CSS classes. These are not APIs and are subject to change. Using them might break your plug-in. Avoid selectors like element selectors that could affect markup outside of your plug-in’s components. diff --git a/modules/adding-new-extension-dynamic-plug-in.adoc b/modules/adding-new-extension-dynamic-plug-in.adoc new file mode 100644 index 000000000000..4cb931fcf641 --- /dev/null +++ b/modules/adding-new-extension-dynamic-plug-in.adoc @@ -0,0 +1,8 @@ +// Module included in the following assemblies: +// +// * web_console/dynamic-plug-ins.adoc + +:_content-type: CONCEPT +[id="adding-new-extension-dynamic-plugin_{context}"] += Adding a new extension to your plug-in +You can add extensions to your plug-in that are loaded at runtime. diff --git a/modules/adding-tab-pods-page.adoc b/modules/adding-tab-pods-page.adoc new file mode 100644 index 000000000000..24be06c56f11 --- /dev/null +++ b/modules/adding-tab-pods-page.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * web_console/dynamic-plug-ins.adoc + +:_content-type: PROCEDURE +[id="adding-tab-to-pods-page_{context}"] += Adding a tab to the pods page +The following procedure adds a tab to the *Pod Details* page as an example extension to your plug-in. + +.Procedure + +. Add the following to the `console-extensions.json` file: ++ +[source,json] + +---- +{ + "type": "console.page/resource/tab", + "properties": { + "name": "Example Tab", + "href": "example", + "model": { + "group": "core", + "version": "v1", + "kind": "Pod" + }, + "component": { "$codeRef": "ExampleTab" } +} +---- + +. Edit the `package.json` file to include the following changes: ++ +[source,json] + +---- + "exposedModules": { + "ExamplePage": "./components/ExamplePage", + "ExampleTab": "./components/ExampleTab" + } +---- + +. Write a message to display on a new custom tab on the *Pods* page by creating a new file `src/components/ExampleTab.tsx` and adding the following script: ++ +[source,tsx] + +---- +import * as React from 'react'; + +export default function ExampleTab() { + return ( +

This is a custom tab added to a resource using a dynamic plug-in.

+ ); +} +---- + +.Verification +* Visit a *Pod* page to view the added tab. diff --git a/modules/build-image-docker.adoc b/modules/build-image-docker.adoc new file mode 100644 index 000000000000..19a5e56cb123 --- /dev/null +++ b/modules/build-image-docker.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * web_console/dynamic-plug-ins.adoc + +:_content-type: PROCEDURE +[id="build-image-with-docker_{context}"] += Build an image with Docker + +To deploy your plug-in on a cluster, you need to build an image and push it to an image registry. + +.Procedure + +. Build the image with the following command: ++ +[source,terminal] +---- +$ docker build -t quay.io/my-repositroy/my-plugin:latest . +---- + +. Optional: If you want to test your image, run the following command: ++ +[source,terminal] +---- +$ docker run -it --rm -d -p 9001:80 quay.io/my-repository/my-plugin:latest +---- + +. Push the image by running the following command: ++ +[source,terminal] +---- +$ docker push quay.io/my-repository/my-plugin:latest +---- diff --git a/modules/deployment-plug-in-cluster.adoc b/modules/deployment-plug-in-cluster.adoc new file mode 100644 index 000000000000..b940d611c296 --- /dev/null +++ b/modules/deployment-plug-in-cluster.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * web_console/dynamic-plug-ins.adoc + +:_content-type: PROCEDURE +[id="deploy-on-cluster_{context}"] += Deploy your plug-in on a cluster + +After pushing an image with your changes to a registry, you can deploy the plug-in to a cluster. + +.Procedure + +. To deploy your plug-in to a cluster, instantiate the link:https://github.com/spadgett/console-plugin-template/blob/main/template.yaml[template] by running the following command: ++ +[source,terminal] +---- +$ oc process -f template.yaml \ + -p PLUGIN_NAME=my-plugin \ <1> + -p NAMESPACE=my-plugin-namespace \ <2> + -p IMAGE=quay.io/my-repository/my-plugin:latest \ <3> + | oc create -f - +---- +<1> Update with the name of your plug-in. +<2> Update with the namespace. +<3> Update with the name of the image you created. ++ +This command runs a light-weight NGINX HTTP server to serve the assets for your plug-in. + +IMPORTANT: `PLUGIN_NAME` must match the plug-in name you used in the `consolePlugin` declaration of `package.json`. + +[start=2] +. Patch the *Console Operator* configuration to enable the plug-in by running the following command: ++ +[source,terminal] + +---- +$ oc patch consoles.operator.openshift.io cluster --patch '{ "spec": { "plugins": ["my-plugin"] } }' --type=merge +---- diff --git a/modules/dynamic-plug-ins-get-started.adoc b/modules/dynamic-plug-ins-get-started.adoc new file mode 100644 index 000000000000..9786634ea37d --- /dev/null +++ b/modules/dynamic-plug-ins-get-started.adoc @@ -0,0 +1,46 @@ +// Module included in the following assemblies: +// +// * web_console/dynamic-plug-ins.adoc + +:_content-type: PROCEDURE +[id="getting-started-with-dynamic-plugins_{context}"] += Getting started with dynamic plug-ins + +To get started using the dynamic plug-in, you must set up your environment to write a new OpenShift Console dynamic plug-in. + +.Prerequisites +* Ensure you have link:https://nodejs.org/en/[`Node.js`] installed. +* Ensure you have link:https://yarnpkg.com/[`yarn`] installed. + +.Procedure + +. Visit this link:https://github.com/spadgett/console-plugin-template[repository] containing a template for creating plug-ins. + +. Select `Use this Template` from the *<> Code* tab to create a GitHub repository. + +. Re-name the template with the name of your plug-in. + +. From your copied repository, clone it your local machine so you can edit the code. + +. Edit the plug-in metadata in the `consolePlugin` declaration of `package.json`. ++ +[source,json] + +---- +"consolePlugin": { + "name": "my-plugin", <1> + "version": "0.0.1", <2> + "displayName": "My Plugin", <3> + "description": "Enjoy this shiny, new console plugin!", <4> + "exposedModules": { + "ExamplePage": "./components/ExamplePage" + }, + "dependencies": { + "@console/pluginAPI": "*" + } +} +---- +<1> Update the name of your plug-in. +<2> Update the version. +<3> Update the display name for your plug-in. +<4> Update the description with a synopsis about your plug-in. diff --git a/modules/running-your-dynamic-plug-in.adoc b/modules/running-your-dynamic-plug-in.adoc new file mode 100644 index 000000000000..8dfe5e76ee19 --- /dev/null +++ b/modules/running-your-dynamic-plug-in.adoc @@ -0,0 +1,46 @@ +// Module included in the following assemblies: +// +// * web_console/dynamic-plug-ins.adoc + +:_content-type: PROCEDURE +[id="running-your-dynamic-plugin_{context}"] += Running your dynamic plug-in + +You can run the plug-in using a local development environment. The OpenShift console runs in a container connected to the cluster you have logged into. + +.Prerequisites +* You must have the OpenShift CLI (`oc`) installed. +* You must have an OpenShift cluster running. +* You must have link:https://www.docker.com/[Docker] or at least v3.2.0 of link:https://podman.io/[Podman] installed. + +.Procedure + +* Open two terminal windows in the local directory of your cloned repository. ++ + +a. Run the following commands in the first terminal: ++ +[source,terminal] +---- +$ yarn install +---- ++ +[source,terminal] +---- +$ yarn run start +---- + +b. Run the following commands in the second terminal window: ++ +[source,terminal] +---- +$ oc login +---- ++ +[source,terminal] +---- +$ yarn run start-console +---- + +.Verification +* Visit link:http://localhost:9000/example[local host] to view the running plug-in. diff --git a/web_console/dynamic-plug-ins.adoc b/web_console/dynamic-plug-ins.adoc new file mode 100644 index 000000000000..cbf83511a61d --- /dev/null +++ b/web_console/dynamic-plug-ins.adoc @@ -0,0 +1,35 @@ +:_content-type: ASSEMBLY +[id="adding-dynamic-plugin-to-console"] += Adding a dynamic plug-in to the {product-title} web console +include::modules/common-attributes.adoc[] +:context: dynamic-plugins + +toc::[] + +You can create and deploy a dynamic plug-in on your cluster that is loaded at run-time. + +:FeatureName: Creating a dynamic plug-in +include::snippets/technology-preview.adoc[leveloffset=+1] +// + +include::modules/about-dynamic-plug-ins.adoc[leveloffset=+1] + +include::modules/dynamic-plug-ins-get-started.adoc[leveloffset=+1] + +include::modules/running-your-dynamic-plug-in.adoc[leveloffset=+1] + +include::modules/adding-tab-pods-page.adoc[leveloffset=+2] + +include::modules/adding-new-extension-dynamic-plug-in.adoc[leveloffset=+1] + +include::modules/build-image-docker.adoc[leveloffset=+1] + +include::modules/deployment-plug-in-cluster.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="dynamic-plugin-additional-resources"] +== Additional resources + +* link:https://github.com/spadgett/console-customization-plugin[Console customization plug-in]. +* link:https://github.com/openshift/console/tree/master/frontend/packages/console-dynamic-plugin-sdk#openshift-console-dynamic-plugins[Console plug-in SDK README] +* link:https://github.com/openshift/enhancements/blob/master/enhancements/console/dynamic-plugins.md[Dynamic plug-in enhancement proposal]