Merge pull request #708 from hpehl/hal-on-os

HAL on OpenShift

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

@@ -0,0 +1,87 @@
+---
+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.
+
+WARNING: The additions in the https://quay.io/repository/halconsole/wildfly[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 https://github.com/jmesnil/kubectl-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://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
++
+[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`.
+
+=== 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 (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 a 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`
+
+== 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 https://quay.io/repository/halconsole/wildfly[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 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 and addresses the limitations mentioned above. 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].