A kubectl plugin to run WildFly management operations on Kubernetes

December 11, 2024

A few months ago, I wrote for a EAP customer a kubectl plugin to make it easier to connect to the CLI console of WildFly running in Kubernetes. I did not publicize it but I realize that this simple tool can be useful for a lot of users operating JBoss EAP or WildFly on Kubernetes or OpenShift.

kubectl, the CLI tool to interact with Kubernetes clusters, can be extended with plugins that provide additional commands to its default set.

The jboss-cli plugin allows to connect to one or many WildFly servers to execute management operations.

It can be install on you local machine by executing:

curl -sL https://raw.githubusercontent.com/jmesnil/kubectl-jboss-cli/main/install.sh | bash

You then need to add the downloaded file to your $PATH and you are good to go:

$ kubectl jboss-cli -h

jboss-cli is a Kubernetes plugin to connect to WildFly servers running in pods and run jboss-cli sessions.

Usage:

  jboss-cli [-h]
     - Displays this help
  jboss-cli [-p <pod>] [-f file] [-- <jboss-cli parameters>]
     - Connects to a single pod
  jboss-cli [-l <pod selector label>] [-f file] [-- <jboss-cli parameters>]
     - Connects to multiple pods matching the label

Where the parameters are:
  * <pod> - Name of the pod running the application image
  * <pod selector label> - Labels to select all the pods belonging to the application
  * <file> - A file containing CLI commands
  * <jboss-cli parameters> - Parameters passed to the jboss-cli session (including --command, --commands, etc.)

To play with it, let's deploy a my-app WildFly application on Kubernetes with 3 replicas:

$ kubectl create deployment my-app --replicas=3 --image=quay.io/wildfly/wildfly
$ kubectl get deployment my-app
NAME     READY   UP-TO-DATE   AVAILABLE   AGE
my-app   3/3     3            3           66s
$ kubectl get pods
NAME                      READY   STATUS    RESTARTS   AGE
my-app-84b45f6b74-6xldb   1/1     Running   0          69s
my-app-84b45f6b74-ct8g4   1/1     Running   0          69s
my-app-84b45f6b74-m824q   1/1     Running   0          69s

Now that the application is deployed, you can use the jboss-cli plugin to directly connect to the servers running on one of its pods in an interactive:

$ kubectl jboss-cli -p my-app-84b45f6b74-6xldb
Running on my-app-84b45f6b74-6xldb
[standalone@localhost:9990 /] :read-attribute(name=name)
{
    "outcome" => "success",
    "result" => "my-app-84b45f6b74-6xldb"
}
[standalone@localhost:9990 /] :read-attribute(name=product-version)
{
    "outcome" => "success",
    "result" => "34.0.1.Final"
}

It works with any WildFly or JBoss EAP servers (even those that are running in a Bootable Jar).

You can then interact with the server and use any management operations. However, any changes you make are transient and will not be persisted if the pod is killed and a new pod is created.

It is still useful if you want to make some changes to the running server, for example, changing the log level to DEBUG to understand some weird behaviours:

$ kubectl jboss-cli -p my-app-84b45f6b74-6xldb
Running on my-app-84b45f6b74-6xldb
[standalone@localhost:9990 /] /subsystem=logging/console-handler=CONSOLE:write-attribute(name=level,value=DEBUG)
{"outcome" => "success"}
[standalone@localhost:9990 /]  /subsystem=logging/root-logger=ROOT:write-attribute(name=level,value=DEBUG)
{"outcome" => "success"}
[standalone@localhost:9990 /] exit

The WildFly server running on the pod my-app-84b45f6b74-6xldb will now log at the DEBUG level.

Without parameters, the plugin connects to the WildFly server in an interactive mode but you can pass a --command to execute the management operations in a non-interactive mode:

$ kubectl jboss-cli -p my-app-84b45f6b74-6xldb  -- --command=':read-attribute\(name=product-version\)'
Running on my-app-84b45f6b74-6xldb
{
    "outcome" => "success",
    "result" => "34.0.1.Final"
}

Any parameter after the first -- is passed directly to the WildFly CLI console. You can find more information about the WildFly CLI console in its documentation.

If the management operations are more complex, it is possible to write them in a file and use the plugin to execute this management script on the server by using the -f <file> parameter:

$ cat change-log-level.cli
/subsystem=logging/console-handler=CONSOLE:write-attribute(name=level,value=DEBUG)
/subsystem=logging/root-logger=ROOT:write-attribute(name=level,value=DEBUG)

$ kubectl jboss-cli -p my-app-84b45f6b74-6xldb -f ./change-log-level.cli
Running on my-app-84b45f6b74-6xldb
{"outcome" => "success"}
{"outcome" => "success"}

This allows to have a playbook of frequent management operations (changing log level, flush connection pools, pause/resume Jakarta Messaging Destinations) and execute them in a quick and simple fashion.

Finally, it is also possible to connect to multiple WildFly server identified by their Kubernetes labels using the -l <label> parameters.

$ kubectl get pods --show-labels
NAME                      READY   STATUS    RESTARTS   AGE    LABELS
my-app-84b45f6b74-6xldb   1/1     Running   0          101m   app=my-app,pod-template-hash=84b45f6b74
my-app-84b45f6b74-ct8g4   1/1     Running   0          101m   app=my-app,pod-template-hash=84b45f6b74
my-app-84b45f6b74-m824q   1/1     Running   0          101m   app=my-app,pod-template-hash=84b45f6b74

$ kubectl jboss-cli -l app=my-app -- --commands=":read-attribute\(name=name\),:read-attribute\(name=uuid\)"
Running on my-app-84b45f6b74-6xldb
{
    "outcome" => "success",
    "result" => "my-app-84b45f6b74-6xldb"
}
{
    "outcome" => "success",
    "result" => "5a1bcc3b-ffb1-4c32-9c96-ce47173b0441"
}
Running on my-app-84b45f6b74-ct8g4
{
    "outcome" => "success",
    "result" => "my-app-84b45f6b74-ct8g4"
}
{
    "outcome" => "success",
    "result" => "1110f54f-5762-4ce6-91fd-b45601cbd0bd"
}
Running on my-app-84b45f6b74-m824q
{
    "outcome" => "success",
    "result" => "my-app-84b45f6b74-m824q"
}
{
    "outcome" => "success",
    "result" => "527761ea-a529-42d9-b4b6-b354f2748229"
}

The plugin connects to each server sequentially so the -l parameter is best used in a non-interactive mode.

I hope this kubectl plugin can be useful and if you think that there improvements to make or new features to add, do not hesitate to contribute by opening Pull Requests or Issues in its GitHub project.