OpenShift Playground Console Plugin

This project is an OpenShift console plugin for Kubernetes playground. It is developed with:

• Plugin Template is a minimal template for writing a new OpenShift Console dynamic plugin.
• Dynamic plugins allow you to extend the OpenShift UI at runtime, adding custom pages and other extensions. They are based on webpack module federation. Plugins are registered with console using the ConsolePlugin custom resource and enabled in the console operator config by a cluster administrator.

Requirements

Node.js and yarn are required to build and run the example. To run OpenShift console in a container, use podman 3.2.0+ and oc are required.

Development

In one terminal window, run:

1. yarn install
2. yarn run start

In another terminal window, run:

1. oc login (requires oc and an OpenShift cluster)
2. yarn run start-console (requires podman 3.2.0+)

This will run the OpenShift console in a container connected to the cluster you've logged into. The plugin HTTP server runs on port 9001 with CORS enabled. Navigate to http://localhost:9000/example to see the running plugin.

Container Image

Before you can deploy your plugin on a cluster, you must build an image and push it to an image registry.

1. Build the image:

   docker build -t quay.io/my-repository/my-plugin:latest .

2. Run the image:

   docker run -it --rm -d -p 9001:80 quay.io/my-repository/my-plugin:latest

3. Push the image:

   docker push quay.io/my-repository/my-plugin:latest

NOTE: If you have a Mac with Apple silicon, you will need to add the flag --platform=linux/amd64 when building the image to target the correct platform to run in-cluster.

Deployment on cluster

A Helm chart is available to deploy the plugin to an OpenShift environment.

The following Helm parameters are required:

plugin.image: The location of the image containing the plugin that was previously pushed

Additional parameters can be specified if desired. Consult the chart values file for the full set of supported parameters.

Installing the Helm Chart

Install the chart using the name of the plugin as the Helm release name into a new namespace or an existing namespace as specified by the plugin_console-plugin-template parameter and providing 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 plugin__console-plugin-template --create-namespace --set plugin.image=my-plugin-image-location

NOTE: When deploying on OpenShift 4.10, it is recommended to add the parameter --set plugin.securityContext.enabled=false which will omit configurations related to Pod Security.

NOTE: When defining i18n namespace, adhere plugin__<name-of-the-plugin> format. The name of the plugin should be extracted from the consolePlugin declaration within the package.json file.

i18n

The plugin template demonstrates how you can translate messages in with react-i18next. The i18n namespace must match the name of the ConsolePlugin resource with the plugin__ prefix to avoid naming conflicts. For example, the plugin template uses the plugin__console-plugin-template namespace. You can use the useTranslation hook with this namespace as follows:

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

For labels in console-extensions.json, you can use the format %plugin__console-plugin-template~My Label%. Console will replace the value with the message for the current language from the plugin__console-plugin-template namespace. For example:

  {
    "type": "console.navigation/section",
    "properties": {
      "id": "admin-demo-section",
      "perspective": "admin",
      "name": "%plugin__console-plugin-template~Plugin Template%"
    }
  }

Running yarn i18n updates the JSON files in the locales folder of the plugin template when adding or changing messages.

Linting

This project adds prettier, eslint, and stylelint. Linting can be run with yarn run lint.

The stylelint config disallows hex colors since these cause problems with dark mode (starting in OpenShift console 4.11). You should use the PatternFly global CSS variables for colors instead.

The stylelint config also disallows naked element selectors like table and .pf- or .co- prefixed classes. This prevents plugins from accidentally overwriting default console styles, breaking the layout of existing pages. The best practice is to prefix your CSS classnames with your plugin name to avoid conflicts. Please don't disable these rules without understanding how they can break console styles!

Reporting

Steps to generate reports

1. In command prompt, navigate to root folder and execute the command yarn run cypress-merge
2. Then execute command yarn run cypress-generate The cypress-report.html file is generated and should be in (/integration-tests/screenshots) directory

References

• Console Plugin SDK README
• Customization Plugin Example
• Dynamic Plugin Enhancement Proposal