×

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

Creating a dynamic plug-in 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 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

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.

PLUGIN_NAME must match the plug-in name you used in the consolePlugin declaration of package.json.
  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