Adding a dynamic plug-in to the OKD web console

You can create and deploy a dynamic plug-in on your cluster that is loaded at run-time.

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.

Key features

A dynamic plug-in allows you to make the following customizations to the OKD 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 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 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.

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 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.

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 Node.js installed.

• Ensure you have yarn installed.

Procedure

1. Visit this repository containing a template for creating plug-ins.

2. Select Use this Template from the <> Code tab to create a GitHub repository.

3. Re-name the template with the name of your plug-in.

4. From your copied repository, clone it your local machine so you can edit the code.

5. Edit the plug-in metadata in the consolePlugin declaration of package.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.

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 Docker or at least v3.2.0 of Podman installed.

Procedure

• Open two terminal windows in the local directory of your cloned repository.

  1. Run the following commands in the first terminal:

     $ yarn install

     $ yarn run start

  2. Run the following commands in the second terminal window:

     $ oc login

     $ yarn run start-console

Verification

• Visit local host to view the running plug-in.

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

1. Add the following to the console-extensions.json file:

   {
       "type": "console.page/resource/tab",
       "properties": {
           "name": "Example Tab",
           "href": "example",
           "model": {
               "group": "core",
               "version": "v1",
               "kind": "Pod"
           },
           "component": { "$codeRef": "ExampleTab" }
   }

2. Edit the package.json file to include the following changes:

           "exposedModules": {
               "ExamplePage": "./components/ExamplePage",
               "ExampleTab": "./components/ExampleTab"
           }

3. 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:

   import * as React from 'react';
   export default function ExampleTab() {
       return (
           <p>This is a custom tab added to a resource using a dynamic plug-in.</p>
       );
   }

Verification

• Visit a Pod page to view the added tab.

Adding a new extension to your plug-in

You can add extensions to your plug-in that are loaded at runtime.

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

1. Build the image with the following command:

   $ docker build -t quay.io/my-repositroy/my-plugin:latest .

2. Optional: If you want to test your image, run the following command:

   $ docker run -it --rm -d -p 9001:80 quay.io/my-repository/my-plugin:latest

3. Push the image by running the following command:

   $ docker push quay.io/my-repository/my-plugin:latest

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

1. To deploy your plug-in to a cluster, instantiate the template by running the following command:

   $ 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.

1. Patch the Console Operator configuration to enable the plug-in by running the following command:

   $ oc patch consoles.operator.openshift.io cluster --patch '{ "spec": { "plugins": ["my-plugin"] } }' --type=merge

Additional resources

• Console customization plug-in.

• Console plug-in SDK README

• Dynamic plug-in enhancement proposal