How to develop and deploy OpenShift console dynamic plugin

Dynamic plugins allow you to extend the Red Hat OpenShift UI at runtime, adding custom pages and other extensions. They are based on the webpack module federation. Plugins are registered with the console using the ConsolePlugin custom resource and enabled in the console operator config by a cluster administrator.

Prerequisites

• Node.js
• yarn
• Docker or podman 3.2.0+
• oc

Getting started

To clone console plugin template repo, you should update the plugin metadata, such as the plugin name in the ConsolePlugin declaration of package.json.

"consolePlugin": {
  "name": "plugin-name",
  "version": "0.0.1",
  "displayName": "Dynamic Plugin",
  "description": "OpenShift console dynamic plugin",
  "exposedModules": {
    "ExamplePage": "./components/ExamplePage"
  },
  "dependencies": {
    "@console/pluginAPI": "*"
  }
}

The template adds a single example page in the home navigation section. The extension is in the console-extensions.json file and the react component is declared in: src/components/ExamplePage.tsx.

You can run the plugin using a local development environment or build an image to deploy it to a cluster.

There are two ways for development.

Development option 1: Local

In the terminal window, run the following commands:

• yarn install
• yarn run start

In another terminal window, run these commands:

• oc login (requires oc and an OpenShift cluster)
• yarn run start-console (requires Docker or Podman 3.2.0+)

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

Running start-console with Apple silicon and Podman

If you are using podman on a Mac with Apple silicon, yarn run start-console might fail since it runs an amd64 image. You can workaround the problem with qemu-user-static by running these commands:

podman machine ssh
sudo -i
rpm-ostree install qemu-user-static
systemctl reboot

Note: If you are facing issues related to tls while oc loggedIn, skip tls by adding below flag --insecure-skip-tls-verify=true with oc loggedIn command.

oc login -u kubeadmin -p <password> --insecure-skip-tls-verify=true

Development option 2: Docker and VSCode remote containers

Make sure the remote containers extension is installed. This method uses Docker Compose where one container is the OpenShift console and the second container is the plugin. It requires that you have access to an existing OpenShift cluster. After the initial build, the cached containers will help you start developing in seconds.

• Create a dev.env file inside the .devcontainer folder with the correct values for your cluster:

OC_PLUGIN_NAME=my-plugin
OC_URL=https://api.example.com:6443
OC_USER=kubeadmin
OC_PASS=<password>

• (Ctrl+Shift+P) => Remote Containers: Open Folder in Container...
• yarn run start
• Navigate to: http://localhost:9000/example

Build the docker image

You can deploy your plugin on a cluster. You must build an image and push it to an image registry. Create an account for Red Hat Quay.io.

• Build the image:

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

• Run the image:

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

• 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 the cluster

Download the yaml template file and update plugin name PLUGIN_NAME , namespace NAMESPACE, docker image IMAGE etc.

You can deploy the plugin to a cluster by applying template.yaml.

oc apply -f template.yaml

Once deployed, patch the console operator config to enable the plugin.

oc patch consoles.operator.openshift.io cluster --patch '{ "spec": { "plugins": ["plugin-name"] } }' --type=merge

Deployment by Helm chart

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 my-plugin-namespace 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 my-plugin-namespace --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.

Learn more about the OpenShift console plugin

This article guided you through getting started in the dynamic plugin for Red Hat OpenShift. For more information, refer to the Console Plugin SDK README and ActiveMQ Artemis Self Provisioning Plugin.