Managing JBoss EAP/Wildfly using Jcliff

Systems management can be a difficult task. Not only does one need to determine what the end state should be but, more importantly, how to ensure systems attain and remain at this state. Doing so in an automated fashion is just as critical, because there may be a large number of target instances. In regard to enterprise Java middleware application servers, these instances are typically configured using a set of XML based files. Although these files may be manually configured, most application servers have a command-line based tool or set of tools that abstracts the end user from having to worry about the underlying configuration. WebSphere Liberty includes a variety of tools to manage these resources, whereas JBoss contains the jboss-cli tool.

Although each tool accomplishes its utilitarian use case as it allows for proper server management, it does fail to adhere to one of the principles of automation and configuration management: idempotence. Ensuring the desired state does not equate to executing the same action with every iteration. Additional intelligence must be introduced. Along with idempotence, another core principle of configuration management is that values be expressed declaratively and stored in a version control system.

Jcliff is a Java-based utility that is built on top of the JBoss command-line interface and allows for the desired intent for the server configuration to be expressed declaratively, which in turn can be stored in a version control system. We'll provide an overview of the Jcliff utility including inherent benefits, installation options, and several examples showcasing the use.

The problem space

Before beginning to work with Jcliff, one must be cognizant of the underlying JBoss architecture. The configuration of the JBoss server can be expressed using Dynamic Model Representation (DMR) notation. The following is an example of DMR:

{
   "system-property"   =>   {
      "foo"      => "bar",
      "bah"      => "gah"
   }
}

The DMR example above describes several Java system properties that will be stored within the JBoss configuration. These properties can be added using the JBoss CLI by executing the following command:

/system-property=foo:add(value=bar)
/system-property=bah:add(value=gah)

The challenge is that the same commands cannot be executed more than once. Otherwise, an error similar to the following is produced.

{
    "outcome" => "failed",
    "failure-description" => "WFLYCTL0212: Duplicate resource [(\"system-property\" => \"foo\")]",
    "rolled-back" => true
}

Where Jcliff excels is that it includes the necessary intelligence to determine the current state of the JBoss configuration and then applying the appropriate configurations necessary. This is critical to adopting proper configuration management when working with JBoss.

Installing Jcliff

With a baseline understanding of Jcliff, let's discuss the methods in which one can obtain the utility. First, Jcliff can be built from source from the project repository, given that it’s a freely open source project. Alternatively, Jcliff can be installed using popular software packaging tools in each of the primary operating system families.

Linux (rpm)

Jcliff can be consumed on a Linux package when capable of consuming an rpm using a package manager.

First, install the yum repository:

$ cat /etc/yum.repos.d/jcliff.repo
[jcliff]
baseurl = http://people.redhat.com/~rpelisse/jcliff.yum/
gpgcheck = 0
name = JCliff repository

Once this repository has been added, JCliff can be installed by using Yum or Dnf:

Using yum:

$ sudo yum install jcliff

Or using dnf:

$ sudo dnf install jcliff

Manual installation

Jcliff can also be installed manually without the need to leverage a package manager. This is useful for those on Linux distributions that cannot consume rpm packages. Simply download and unpack the archive from the release artifact from the project repository.

$ curl -O \
https://github.com/bserdar/jcliff/releases/download/v2.12.1/jcliff-2.12.1-dist.tar.gz
$ tar xzvf jcliff-2.12.1-dist.tar.gz

Place the resulting Jcliff folder in the destination of your choosing. This location is known as JCLIFF_HOME. Add this environment variable and add it to the path as described below:

$ export JCLIFF_HOME=/path/to/jcliff-2.12.1/
$ export PATH=${JCLIFF_HOME}/bin:${PATH}

At this point, you should be able to execute the jcliff command.

OSX

While users on OSX can take advantage of the manual installation option, those making use of the brew package manager can use this tool as well.

Execute the following commands to install Jcliff using Brew:

$ brew tap redhat-cop/redhat-cop
$ brew install redhat-cop/redhat-cop/jcliff

Windows

Fear not, Windows users; you can also make use of Jcliff without having to compile from source. Windows, in the same vein as OSX, does not have an official package manager, but Chocolatey has been given this role.

Execute the following command to install Jcliff using Chocolatey:

$ choco install jcliff

Using Jcliff

With Jcliff properly installed on your machine, let’s walk through a simple example to demonstrate the use of the tool. As discussed previously, Jcliff makes use of files that describe the target configuration. At this point, you may have questions like: What is the format of these configurations, and where do I begin?

Let’s take a simple example and look into adding a new system property to the JBoss configuration. Launch an instance of JBoss and connect using the JBoss command-line interface:

$ /bin/jboss-cli.sh --connect
[standalone@localhost:9990 /] ls /system-property
[standalone@localhost:9990 /] 

Now, use Jcliff to update the configuration. First, we’ll need to create a Jcliff rule. The rule resembles DMR format and appears similar to the following:

$ cat jcliff-prop
{ "system-property" => {
  "jcliff.enabled" => "true",
  }
}

Then we can simply ask JCliff to run this script against our JBoss server:

$ jcliff jcliff-prop
Jcliff version 2.12.4
2019-10-02 17:03:40:0008: /core-service=platform-mbean/type=runtime:read-attribute(name=system-properties)
2019-10-02 17:03:41:0974: /system-property=jcliff.enabled:add(value="true")

Use the JBoss CLI to verify the changes have been applied.

$ “${JBOSS_HOME}/bin/jboss-cli.sh” --connect --command=/system-property=jcliff.enabled:read-resource
{
	"outcome" => "success",
	"result" => {"value" => "true"}
}

To demonstrate how Jcliff handles repetitive executions, run the previous Jcliff command again. Inspect the output.

$ jcliff jcliff-prop
Jcliff version 2.12.4
2019-10-02 17:05:34:0107: /core-service=platform-mbean/type=runtime:read-attribute(name=system-properties)

Notice that only 1 command was executed against the JBoss server instead of two? This action was a result of assessing the current state within JBoss and determining that no action was necessary to reach the desired state. Mission accomplished.

Next steps

Although the preceding scenario was not overly complex, you should now have the knowledge necessary to understand the capabilities and functionality of the Jcliff utility as well as the benefits afforded through declarative configurations and automation. When building out enterprise-grade systems, however, Jcliff would not be executed manually. You would want to integrate the utility into a proper configuration management tool that employs many of the automation and configuration principles described earlier. Fortunately, Jcliff has been integrated into several popular configuration management tools.

In an upcoming article, we'll provide an overview of the configuration management options available with Jcliff, along with examples that will allow you to quickly build out enterprise-grade confidence with Jcliff.