HAL on OpenShift

_posts/2024-12-18-Management-Console-on-OpenShift.adoc

@@ -0,0 +1,77 @@
+---
+layout: post
+title:  "Using the management console on OpenShift"
+date:   2024-12-18
+tags:   hal management console openshift
+author: hpehl
+description: How to use the management console for WildFly instances running on OpenShift.
+---
+
+In this blog post I'd like to show how you can use the management console (aka https://hal.github.io[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 https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API[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 https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS[CORS policies] for more details).
+
+You can build such an image on your own based on the official WildFly images available at https://quay.io/repository/wildfly/wildfly[quay.io/wildfly/wildfly] (see "Extending the image"). Another way is to use the pre-built images from https://quay.io/repository/halconsole/wildfly[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.
+
+To add the allowed origin for the public route, we make use of the https://jmesnil.net/weblog/2024/12/11/a-kubectl-plugin-for-wildfly-jboss-cli/[`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://jmesnil.net/weblog/2024/12/11/a-kubectl-plugin-for-wildfly-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
++
+[source,shell]
+----
+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.
++
+[source,shell]
+----
+kubectl jboss-cli -p <pod>
+----
++
+Login using `admin:admin` and execute these CLI commands:
++
+[source,shell]
+----
+/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`.
+
+'''
+
+NOTE: As an alternative to adding the allowed origin, you can also use of the latest online version of the management console available at https://hal.github.io/console.
+
+Background: The management console is a single-page application (https://en.wikipedia.org/wiki/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 scheme, enter the hostname of the public route _without_ https and port *80*:
++
+image::hal/add-management-interface.png[Add management interface]
+. Click *Add* and then *Connect*
+. Login using `admin:admin`
+
+== Outlook
+
+We're currently working on the https://github.com/hal/foundation[next-gen management console]. This version will also support a dedicated variant for OpenShift that will integrate with the OpenShift management console. For more information you can watch the https://www.youtube.com/watch?v=Karu90yDIhs&t=571s[talk] on the next-gen management console from the last https://www.wildfly.org/conference/[WildFly mini conference], get the https://www.wildfly.org/assets/data/conference/202411_wmc_nextgen_console.pdf[slides] or reach out to us in the HAL Zulip https://wildfly.zulipchat.com/#narrow/channel/174373-hal[channel].