ArkMQ Broker Operator OpenShift UI

OpenShift Console plugin for the ArkMQ Broker Operator. It extends the admin perspective with workflows for provisioning messaging infrastructure and connecting applications to brokers. It requires OpenShift 4.22 or higher.

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.

Using the latest v1 API version of ConsolePlugin CRD requires OpenShift 4.12 and higher. For the older v1alpha1 API version, use OpenShift 4.10 or 4.11.

For examples targeting older OpenShift versions, see the upstream OpenShift Console Plugin Template release-4.11 and release-4.10 branches.

Node.js and yarn are required to build and run the plugin. To run OpenShift console in a container, either Docker or podman 3.2.0+ and oc are required.

Getting started

The plugin adds BrokerService and BrokerApp pages in the Workloads navigation section. Extensions are declared in console-extensions.json, and React components live under src/brokerapps and src/brokerservices.

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

Development

Option 1: Local

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. cd ./bridge-auth-http/ && ./setup.sh && cd ..
3. 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've logged into. The plugin HTTP server runs on port 9001 with CORS enabled. Navigate to http://localhost:9000 to see the running plugin.

To view our plugin on OpenShift, navigate to the Workloads section. The plugin will be listed as BrokerServices and BrokerApps.

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

Option 2: Docker + VSCode Remote Container

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.

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

OC_PLUGIN_NAME=arkmq-org-broker-operator-openshift-ui
OC_URL=https://api.example.com:6443
OC_USER=kubeadmin
OC_PASS=<password>

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

Docker 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, providing the location of the image within the plugin.image parameter:

helm upgrade -i  my-plugin charts/openshift-console-plugin -n my-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.

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, this plugin uses the plugin__arkmq-org-broker-operator-openshift-ui namespace. You can use the useTranslation hook with this namespace as follows:

const Header: React.FC = () => {
  const { t } = useTranslation('plugin__arkmq-org-broker-operator-openshift-ui');
  return <h1>{t('Hello, World!')}</h1>;
};

For labels in console-extensions.json, you can use the format %plugin__arkmq-org-broker-operator-openshift-ui~My Label%. Console will replace the value with the message for the current language from the plugin__arkmq-org-broker-operator-openshift-ui namespace. For example:

  {
    "type": "console.navigation/section",
    "properties": {
      "id": "admin-demo-section",
      "perspective": "admin",
      "name": "%plugin__arkmq-org-broker-operator-openshift-ui~Plugin Template%"
    }
  }

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

Certificate Management for BrokerService and BrokerApp

This project includes a certificate management script for setting up the required PKI infrastructure to deploy BrokerService and BrokerApp resources.

Prerequisites

Before using the certificate management script, ensure you have:

• kubectl configured and connected to your cluster
• cert-manager installed in your cluster
• trust-manager installed in your cluster (with secretTargets.enabled=true)
• Appropriate permissions to create cluster-wide resources
• The ArkMQ operator installed in your cluster

Installing the ArkMQ Operator

Install the operator using Helm:

helm install my-arkmq-org-broker-operator \
  oci://quay.io/arkmq-org/helm-charts/arkmq-org-broker-operator \
  --version 0.0.0-dev.latest

Installing cert-manager

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.1/cert-manager.yaml
kubectl wait deployment --for=condition=Available -n cert-manager --timeout=600s \
  cert-manager cert-manager-cainjector cert-manager-webhook

Installing trust-manager

helm repo add jetstack https://charts.jetstack.io --force-update
helm upgrade trust-manager jetstack/trust-manager --install \
  --namespace cert-manager \
  --set secretTargets.enabled=true \
  --set secretTargets.authorizedSecretsAll=true \
  --wait

Quick Start

1. Setup PKI Infrastructure (one-time setup):

   yarn chain-of-trust setup

   This creates:

   • Self-signed root ClusterIssuer and CA certificate
   • CA-signed ClusterIssuer for issuing broker certificates
   • Trust bundle that distributes the CA to all namespaces
   • Operator certificate in the operator's namespace

2. Create BrokerService Certificate:

   yarn chain-of-trust create-service-cert --name messaging-service --namespace my-namespace

   This creates a certificate with the correct DNS names for the BrokerService.

3. Create BrokerApp Certificate:

   yarn chain-of-trust create-app-cert --name first-app --namespace my-namespace

   This creates a certificate for the BrokerApp to authenticate with the service.

4. Cleanup (removes all PKI resources):

   yarn chain-of-trust cleanup

Usage Examples

Setup with explicit namespace:

yarn chain-of-trust setup --namespace my-operator-namespace

Create certificates in different namespaces:

# Service in namespace X
yarn chain-of-trust create-service-cert --name messaging-service --namespace service-namespace

# App in namespace Y
yarn chain-of-trust create-app-cert --name first-app --namespace app-namespace

Get help:

yarn chain-of-trust --help

What Gets Created

The setup command creates:

• ClusterIssuer/root-issuer - Self-signed root issuer
• Certificate/root-cert (in cert-manager namespace) - Root CA certificate
• ClusterIssuer/broker-ca-issuer - CA issuer for signing broker certificates
• Bundle/arkmq-org-broker-manager-ca - Trust bundle distributed to all namespaces
• Certificate/arkmq-org-broker-manager-cert - Operator certificate

The create-service-cert command creates:

• Certificate/<service-name>-broker-cert - Service certificate with proper DNS names
• Secret/<service-name>-broker-cert - Secret containing the certificate

The create-app-cert command creates:

• Certificate/<app-name>-app-cert - App certificate
• Secret/<app-name>-app-cert - Secret containing the certificate

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!

Prometheus Monitoring

This project includes scripts to manage Prometheus user workload monitoring and secure metrics scraping with mTLS authentication.

Enabling User Workload Monitoring

Enable user workload monitoring:

yarn prometheus-config enable

Applies the cluster-monitoring-config ConfigMap to enable user workload monitoring.

Verify monitoring setup:

yarn prometheus-config verify

Waits for the openshift-user-workload-monitoring namespace to exist and for all monitoring pods to be ready.

Disable monitoring (cleanup):

yarn prometheus-config disable

Removes the cluster-monitoring-config ConfigMap to disable user workload monitoring.

Secure Metrics Scraping with mTLS

For locked-down brokers that require mutual TLS authentication, you can set up secure metrics scraping:

1. Create Prometheus Certificate:

First, create a Prometheus client certificate using the PKI infrastructure:

yarn chain-of-trust create-prometheus-cert --namespace my-namespace

This creates a prometheus-cert secret with CN=prometheus that Prometheus will use to authenticate to the broker's metrics endpoint.

2. Generate ServiceMonitor YAML:

Generate the ServiceMonitor configuration for mTLS metrics scraping:

yarn prometheus-config create-servicemonitor \
  --broker-name my-broker \
  --namespace my-namespace

3. Apply the ServiceMonitor:

Save the output to a file or pipe directly to kubectl:

yarn prometheus-config create-servicemonitor \
  --broker-name my-broker \
  --namespace my-namespace | kubectl apply -f -

The ServiceMonitor will configure Prometheus to:

• Scrape metrics over HTTPS
• Authenticate using the Prometheus client certificate
• Validate the broker's server certificate using the CA bundle
• Target the broker's metrics endpoint (port 8888)

Configuration for Non-OpenShift Platforms

The script defaults to OpenShift namespace names, but can be customized using environment variables:

Environment Variable	Default	Description
MONITORING_NAMESPACE	openshift-user-workload-monitoring	Namespace where user workload monitoring pods run
CLUSTER_MONITORING_NAMESPACE	openshift-monitoring	Namespace where cluster monitoring config is stored
MONITORING_CONFIG	cluster-monitoring-config	Name of the ConfigMap that enables monitoring

Example for custom platforms:

MONITORING_NAMESPACE=monitoring \
CLUSTER_MONITORING_NAMESPACE=kube-monitoring \
MONITORING_CONFIG=monitoring-config \
yarn prometheus-config enable

Manual Configuration

The script applies this ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-monitoring-config
  namespace: openshift-monitoring
data:
  config.yaml: |
    enableUserWorkload: true

And verifies by checking:

kubectl -n openshift-user-workload-monitoring get pods

Testing

Unit tests

yarn test

E2E Tests with Playwright

This project includes Playwright E2E tests for UI testing and infrastructure validation.

UI Tests

With all prerequisites in place and the webpack server running:

1. Start the Console: In a second terminal, start the OpenShift console:

   yarn start-console

2. Run Tests: In a third terminal, choose one of the following options:

Interactive Mode with UI (recommended for development and debugging):

KUBEADMIN_PASSWORD=kubeadmin yarn pw:ui

Opens Playwright's UI Mode with a visual timeline, DOM snapshots, network inspection, and step-by-step debugging capabilities.

Headed Mode (browser visible, without UI):

KUBEADMIN_PASSWORD=kubeadmin yarn pw:headed

Runs tests with a visible browser window but without the interactive debugger.

Headless Mode (for CI or quick runs):

KUBEADMIN_PASSWORD=kubeadmin yarn pw:test

Runs tests in the terminal without opening a browser window.

Monitoring Tests

The project includes Playwright tests for monitoring (playwright/e2e/monitoring.spec.ts). These tests:

1. Enable user workload monitoring via yarn prometheus-config enable
2. Verify monitoring is ready via yarn prometheus-config verify
3. Verify ServiceMonitor CRD is available (scaffolding for future plugin metrics tests)
4. Clean up by running yarn prometheus-config disable

The tests are skipped by default (including in CI) to avoid requiring cluster admin permissions and additional resources.

To run the monitoring infrastructure smoke test locally:

TEST_MONITORING=true KUBEADMIN_PASSWORD=kubeadmin yarn pw:test monitoring

Certificate Management Tests

The project includes E2E tests for the certificate management workflow:

# Run all tests (including certificate management)
yarn pw:test

# Run only certificate management tests
yarn pw:test certificate-management

These tests validate:

• PKI infrastructure setup
• Certificate creation for BrokerService and BrokerApp
• Resource deployment and readiness
• Cleanup functionality

Note: Certificate management tests require:

• cert-manager installed
• trust-manager installed
• ArkMQ operator installed
• Cluster access configured with kubectl

References

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