1. Documentation
    2. history bug_report picture_as_pdf
×

Adding a dynamic plug-in to the OpenShift Container Platform web console

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

  • Follow react-i18next localization guidelines when creating your plug-in. 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 plug-in. Avoid selectors like element selectors that could affect markup outside of your plug-in’s components.

Enable dynamic plug-ins in the web console

Cluster administrators can enable plug-ins in the web console browser. Dynamic plug-ins 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 plug-ins 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 plug-in.

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. 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 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 plug-in 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 plug-in asset server by running

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

  • Visit local host to view the running plug-in. Inspect the value of window.SERVER_FLAGS.consolePlugins to see the list of plug-ins which load at runtime.

Adding a new extension to your plug-in

You can add extensions that allow you to customize your plug-in. 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 plug-in. 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 plug-in’s exported modules can be used in code references.

Dynamic plug-in 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. Ex - topology, helm

filter

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

no

A function which will filter actions based on some conditions.scope: The scope in which actions should be provided for.Note: hook may be required if we want to remove the ModifyCount action from a deployment with 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. Ex - topology, helm

provider

CodeRef<ExtensionHook<Action[], any>>

no

A react hook which returns actions for the given scope.If contextId = resource then the scope will always be a K8s 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
Name Value Type Optional Description

catalogId

string | string[]

no

The unique identifier for the catalog this provider contributes to.

type

string

no

Type ID for the catalog item type.

filter

CodeRef<(item: CatalogItem) ⇒ boolean>

no

Filters items of a specific type. Value is a function that takes CatalogItem[] and returns a subset based on the filter criteria.

console.catalog/item-metadata

Summary

(not available)

Properties
Name Value Type Optional Description

catalogId

string | string[]

no

The unique identifier for the catalog this provider contributes to.

type

string

no

Type ID for the catalog item type.

provider

CodeRef<ExtensionHook<CatalogItemMetadataProviderFunction, CatalogExtensionHookOptions>>

no

A hook which returns a function that will be used to provide metadata to catalog items of a specific type.

console.catalog/item-provider

Summary

(not available)

Properties
Name Value Type Optional Description

catalogId

string | string[]

no

The unique identifier for the catalog this provider contributes to.

type

string

no

Type ID for the catalog item type.

title

string

no

Title for the catalog item provider

provider

CodeRef<ExtensionHook<CatalogItem<any>[], CatalogExtensionHookOptions>>

no

Fetch items and normalize it for the catalog. Value is a react effect hook.

priority

number

yes

Priority for this provider. Defaults to 0. Higher priority providers may override catalogitems provided by other providers.

console.catalog/item-type

Summary

(not available)

Properties
Name Value Type Optional Description

type

string

no

Type for the catalog item.

title

string

no

Title for the catalog item.

catalogDescription

string | CodeRef<React.ReactNode>

yes

Description for the type specific catalog.

typeDescription

string

yes

Description for the catalog item type.

filters

CatalogItemAttribute[]

yes

Custom filters specific to the catalog item.

groupings

CatalogItemAttribute[]

yes

Custom groupings specific to the catalog item.

console.catalog/item-type-metadata

Summary

(not available)

Properties
Name Value Type Optional Description

type

string

no

Type for the catalog item.

filters

CatalogItemAttribute[]

yes

Custom filters specific to the catalog item.

groupings

CatalogItemAttribute[]

yes

Custom groupings specific to the catalog item.

console.cluster-overview/inventory-item

Summary

Adds a new inventory item into cluster overview page.

Properties
Name Value Type Optional Description

component

CodeRef<React.ComponentType<{}>>

no

The component to be rendered.

console.cluster-overview/multiline-utilization-item

Summary

Adds a new cluster overview multiline utilization item.

Properties
Name Value Type Optional Description

title

string

no

The title of the utilization item.

getUtilizationQueries