×

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

Creating a dynamic plugin is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

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 plugins

To get started using the dynamic plugin, you must set up your environment to write a new OpenShift Console dynamic plugin.

Prerequisites
  • Ensure you have Node.js installed.

  • Ensure you have yarn installed.

Procedure
  1. Visit this repository containing a template for creating plugins.

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

  3. Re-name the template with the name of your plugin.

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

  5. Edit the plugin 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 plugin.
    2 Update the version.
    3 Update the display name for your plugin.
    4 Update the description with a synopsis about your plugin.

Running your dynamic plugin

You can run the plugin 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

Adding a tab to the pods page

The following procedure adds a tab to the Pod Details page as an example extension to your plugin.

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

    {
      "type": "console.tab/horizontalNav",
      "properties": {
        "page": {
          "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 plugin.</p>
        );
    }
Verification
  • Visit a Pod page to view the added tab.

Adding a new extension to your plugin

You can add extensions to your plugin that are loaded at runtime.

Build an image with Docker

To deploy your plugin 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 plugin on a cluster

After pushing an image with your changes to a registry, you can deploy the plugin to a cluster.

Procedure
  1. To deploy your plugin 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 plugin.
    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 plugin.

PLUGIN_NAME must match the plugin name you used in the consolePlugin declaration of package.json.
  1. Patch the Console Operator configuration to enable the plugin by running the following command:

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