1. Documentation
×

Adding a dynamic plugin to the OKD web console

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

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 Technology Preview Features Support Scope.

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 OKD experience:

  • Add custom pages.

  • Add perspectives beyond administrator and developer.

  • Add navigation items.

  • Add tabs and actions to resource pages.

General guidelines

When creating your plugin, follow these general guidelines:

  • Node.js and yarn are required to build and run your plugin.

  • 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:

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

  • Avoid selectors that could affect markup outside of your plugin’s components, such as element selectors. These are not APIs and are subject to change. Using them might break your plugin.

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

  • Make your plugin accessible by following PatternFly’s accessibility fundamentals.

  • Avoid using other CSS libraries such as Bootstrap or Tailwind. They can conflict with PatternFly and will not match the console look and feel.

Getting started with dynamic plugins

There are different customizations you can make to the OKD web console. Set up your environment to write a new OpenShift Console dynamic plugin, and add a tab to the Pod details page as an example extension to your plugin.

The OKD web console runs in a container connected to the cluster you have logged into. See "Running your dynamic plugin" for information to test the plugin before creating your own.
Prerequisites

  • Ensure you have Node.js installed.

  • Ensure you have yarn installed.

Procedure

  1. In a new tab, open the console-plugin-template repository, which contains a template for creating plugins in a new tab.

    Custom plugin code is not supported by Red Hat. Only Cooperative community support is available for your plugin.

  2. Create a GitHub repository for the template by clicking Use this template → Create new repository.

  3. Rename the new repository with the name of your plugin.

  4. Clone the new repository to your local machine so you can edit the code.

  5. Edit the package.json file, adding your plugin’s metadata to the consolePlugin declaration. For example:

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

  6. 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" }
  }
}

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

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

  8. 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>
    );
}

  9. Install a Helm chart with the name of the plugin as the Helm release name into a new namespace or an existing namespace as specified by the -n command-line option to deploy your plugin on a cluster. Provide the location of the image within the plugin.image parameter by using the following command:

    $ helm upgrade -i  my-plugin charts/openshift-console-plugin -n my-plugin-namespace --create-namespace --set plugin.image=my-plugin-image-location

    For more information on deploying your plugin on a cluster, see "Deploy your plugin on a cluster".
Verification

  • Visit a Pod page to view the added tab.

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

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

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, install a Helm chart with the name of the plugin as the Helm release name into a new namespace or an existing namespace as specified by the -n command-line option. Provide the location of the image within the plugin.image parameter by using the following command:

    $ helm upgrade -i  my-plugin charts/openshift-console-plugin -n my-plugin-namespace --create-namespace --set plugin.image=my-plugin-image-location

    Where:

    n <my-plugin-namespace>

    Specifies an existing namespace to deploy your plugin into.

    --create-namespace

    Optional: If deploying to a new namespace, use this parameter.

    --set plugin.image=my-plugin-image-location

    Specifies the location of the image within the plugin.image parameter.

  2. Optional: You can specify any additional parameters by using the set of supported parameters in the charts/openshift-console-plugin/values.yaml file.

    plugin:
  name: ""
  description: ""
  image: ""
  imagePullPolicy: IfNotPresent
  replicas: 2
  port: 9443
  securityContext:
    enabled: true
  podSecurityContext:
    enabled: true
    runAsNonRoot: true
    seccompProfile:
      type: RuntimeDefault
  containerSecurityContext:
    enabled: true
    allowPrivilegeEscalation: false
    capabilities:
      drop:
        - ALL
  resources:
    requests:
      cpu: 10m
      memory: 50Mi
  basePath: /
  certificateSecretName: ""
  serviceAccount:
    create: true
    annotations: {}
    name: ""
  patcherServiceAccount:
    create: true
    annotations: {}
    name: ""
  jobs:
    patchConsoles:
      enabled: true
      image: "registry.redhat.io/openshift4/ose-tools-rhel8@sha256:e44074f21e0cca6464e50cb6ff934747e0bd11162ea01d522433a1a1ae116103"
      podSecurityContext:
        enabled: true
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      containerSecurityContext:
        enabled: true
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
      resources:
        requests:
          cpu: 10m
          memory: 50Mi
Verification

  • You can view the list of the enabled plugins by navigating from Administration → Cluster Settings → Configuration → Console operator.openshift.io → Console plugins or on the Overview page.

It can take a few minutes for the new plugin configuration to appear. If you do not see your plugin, you might need to refresh your browser if the plugin was recently enabled. If you recieve any errors at runtime, check the JS console in browser developer tools to look for any errors in your plugin code.

Additional resources