1. Documentation
    2. history bug_report picture_as_pdf
×

Adding a dynamic plugin to the OpenShift Container Platform web console

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 plugins

A dynamic plugin allows you to add custom pages and other extensions to your interface at runtime. The ConsolePlugin custom resource registers plugins with the console, and a cluster administrator enables plugins in the console-operator configuration.

Key features

A dynamic plugin allows you to make the following customizations to the OpenShift Container Platform experience:

  • Add custom pages.

  • Add perspectives and update navigation items.

  • Add tabs and actions to resource pages.

PatternFly 4 guidelines

When creating your plugin, 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 plugin look consistent in future console versions.

  • Make your plugin 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 plugin, follow these general guidelines:

  • Prefix your CSS class names with your plugin name to avoid collisions. For example, my-plugin__heading and my-plugin_\_icon.

  • Maintain a consistent look, feel, and behavior with other console pages.

  • Follow react-i18next localization guidelines when creating your plugin. You can use the useTranslation hook like the one in the following example:

    conster Header: React.FC = () => {
  const { t } = useTranslation('plugin__console-demo-plugin');
  return <h1>{t('Hello, World!')}</h1>;
};

  • 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 plugin. Avoid selectors like element selectors that could affect markup outside of your plugin’s components.

Enable dynamic plugins in the web console

Cluster administrators can enable plugins in the web console browser. Dynamic plugins are disabled by default. In order to enable, a cluster administrator will need to enable them in the console-operator configuration.

Procedure

  1. In the Administration → Cluster Settings page of the web console, click the Configuration tab.

  2. Click the Console operator.openshift.io configuration resource.

  3. From there, click the Console plugins tab to view the dynamic plugins running.

  4. In the Status column, click Enable console plugin in the pop-over menu, which will launch the Console plugin enablement modal.

  5. Click Enable and Save.

Verification

  • Refresh the browser to view the enabled plugin.

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. 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 Container Platform web 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

  1. Build a plugin and generate the output to the dist directory by running

    $ yarn build

  2. Start an HTTP server by running

    $ yarn http-server

  3. The HTTP server, which runs on port 9001, generates the following assets with caching disabled and CORS enabled.

    Starting up http-server, serving ./dist
Available on:
  http://127.0.0.1:9001
  http://192.168.1.190:9001
  http://10.40.192.80:9001
Hit CTRL-C to stop the server

  4. Optional: Add additional server options to the script by running

    $ yarn http-server -a <server name>

  5. Direct bridge to proxy requests to your local plugin asset server by running

    $ ./bin/bridge -plugins console-demo-plugin=http://localhost:9001/
Verification

  • Visit local host to view the running plugin. Inspect the value of window.SERVER_FLAGS.consolePlugins to see the list of plugins which load at runtime.

Adding a new extension to your plugin

You can add extensions that allow you to customize your plugin. Those extensions are then loaded to the console at run-time.

  1. Edit the console-extensions.json file:

    [
 {
    "type": "console.flag", (1)
    "properties": {
      "handler": { "$codeRef": "barUtils.testHandler" } (2)
    }
  },
  {
    "type": "console.flag/model",
    "properties": {
      "flag": "EXAMPLE",
      "model": {
        "group": "kubevirt.io",
        "version": "v1alpha3",
        "kind": "ExampleModel"
      }
    }
  }
]
    1 Add the extension type(s) you want to include with this plugin. You can include multiple extensions separated with a comma.
    2 The $codeRef value should be formatted as either moduleName.exportName for a named export or moduleName for the default export. Only the plugin’s exported modules can be used in code references.

Dynamic plugin extension types

console.action/filter

Summary

ActionFilter can be used to filter an action.

Properties
Name Value Type Optional Description

contextId

string

no

The context ID helps to narrow the scope of contributed actions to a particular area of the application. Examples include topology and helm.

filter

CodeRef<(scope: any, action: Action) ⇒ boolean>

no

A function that will filter actions based on some conditions. scope: The scope in which actions should be provided for. A hook might be required if you want to remove the ModifyCount action from a deployment with a horizontal pod autoscaler (HPA).

console.action/group

Summary

ActionGroup contributes an action group that can also be a submenu.

Properties
Name Value Type Optional Description

id

string

no

ID used to identify the action section.

label

string

yes

The label to display in the UI. Required for submenus.

submenu

boolean

yes

Whether this group should be displayed as submenu.

insertBefore

string | string[]

yes

Insert this item before the item referenced here. For arrays, the first one found in order is used.

insertAfter

string | string[]

yes

Insert this item after the item referenced here. For arrays, the first one found in order is used. The insertBefore value takes precedence.

console.action/provider

Summary

ActionProvider contributes a hook that returns list of actions for specific context.

Properties
Name Value Type Optional Description

contextId

string

no

The context ID helps to narrow the scope of contributed actions to a particular area of the application. Examples include topology and helm.

provider

CodeRef<ExtensionHook<Action[], any>>

no

A React hook that returns actions for the given scope. If contextId = resource, then the scope will always be a Kubernetes resource object.

console.action/resource-provider

Summary

ResourceActionProvider contributes a hook that returns list of actions for specific resource model.

Properties
Name Value Type Optional Description

model

ExtensionK8sKindVersionModel

no

The model for which this provider provides actions for.

provider

CodeRef<ExtensionHook<Action[], any>>

no

A react hook which returns actions for the given resource model

console.alert-action

Summary

(not available)

Properties
Name Value Type Optional Description

alert

string

no

text

string

no

action

CodeRef<(alert: any) ⇒ void>

no

console.catalog/item-filter

Summary

(not available)

Properties