Using the management console on OpenShift

By Harald Pehl | December 18, 2024

In this blog post I’d like to show how you can use the management console (aka HAL) for WildFly instances running on OpenShift.

Prerequisites

The console is an integral part of WildFly and is activated by default when running on-premise. For instances running on OpenShift, the console is not available by default, though. To use the console on OpenShift, you need a WildFly image that meets the following requirements:

Management user:
The management console is protected by default and requires a management user added with the add-user.sh script.
Public route to the management interface:
The management interface has to be publicly available from the outside.
Allowed origin:
The console uses the fetch API to talk to the management interface of a running WildFly instance. In an OpenShift environment, the origins of the public route and the management interface itself are different. That’s why we need to tell WildFly that it is ok to make requests to the management interface from another origin (see CORS policies for more details).

You can build such an image on your own based on the official WildFly images available at quay.io/wildfly/wildfly (see "Extending the image"). Another way is to use the pre-built images from quay.io/halconsole/wildfly. These images are mainly meant for HAL development and testing but already meet these requirements, which makes them suitable for our use case. In particular the images add a management user admin:admin and have a list of preconfigured allowed origins.

Warning

The additions in the quay.io/halconsole/wildfly images are only meant for development and testing purposes. Under no circumstances must this be used in production! Do not rely on the management user admin:admin or the preconfigured allowed origins.

To add the allowed origin for the public route, we make use of the jboss-cli kubectl plugin. This plugin makes it straightforward to connect to a WildFly instance running on OpenShift and execute CLI commands. Please visit https://github.com/jmesnil/kubectl-jboss-cli/ to find out how to install and use the plugin.

Instructions

The steps below assume you have access to an OpenShift cluster and installed kubectl and the jboss-cli plugin.

Create application

oc new-app quay.io/halconsole/wildfly
oc create route edge --service wildfly --port 9990

Add allowed origin

Use oc get pods to find the name of the pod to connect to and oc get routes to get the hostname of the public route to the management interface.
```
kubectl jboss-cli -p <pod>
```
Login using admin:admin and execute these CLI commands:
```
/core-service=management/management-interface=http-interface:list-add(name=allowed-origins,value=https://<hostname>)
reload
exit
```
Open the management console at https://<hostname> and login using admin:admin.

Online version of the management console

As an alternative to adding the allowed origin, you can also use the online version of the management console available at https://hal.github.io/console. This URL ships the latest version of the management console.

Note

The management console is a single-page application (SPA) without any server side dependencies. As such, it can run on its own and connect to an arbitrary management interface. The online version of the console makes use of this fact. See https://hal.github.io/documentation/get-started/#standalone-mode for more details.

Create the application as above and find the hostname of the public route using oc get routes.
Open https://hal.github.io/console
Add a management interface to the public route:

Give an arbitrary name, select https as a scheme, enter the hostname of the public route without https and port 80:
Click Add and then Connect
Login using admin:admin

Things to keep in mind

Please note that the above instructions are just a workaround to access the OpenShift management console as long as there is no more compatible, container-friendly way. In particular, the approach ignores some principles that should not be applied in a cloud environment:

Changing the management configuration of a pod is an antipattern as it will not outlive a pod restart. At that point, you’ll have to reconfigure the allowed origin.
With a route, you are accessing pods behind a service. If your deployments have multiple pods, it’s complex and hacky to access a specific pod or configure all pods.
Do not use the quay.io/halconsole/wildfly images in production under any circumstances. They contain preconfigured, insecure credentials and are meant only for development and testing purposes.

Outlook

We’re currently working on the next-gen management console. This version will also support a dedicated variant for OpenShift that will integrate with the OpenShift management console and addresses the limitations mentioned above. For more information you can watch the talk on the next-gen management console from the last WildFly mini conference, get the slides or reach out to us in the HAL Zulip channel.