As we saw in the introduction to ActiveMQ Artemis post, in ActiveMQ Artemis the implementation is separated from the configuration and data, requiring one to create a broker instance after installation of the implementation. One of the advantages of doing this, is that it makes upgrades much easier. Lets take a detailed look at that now.

In order to show the upgrade procedure, we’ll first install an older version of ActiveMQ Artemis and create a broker instance with it. We’ll take a more thorough look at what the instance actually is made up off before we then upgrade the implementation and finally the broker instance.

Prerequisites

As usual we’ll be working from Fedora Linux, but all commands should be easily adaptable to other Linux distributions (even Windows :-). Also remember ActiveMQ requires a JDK - checkout AdoptOpenJDK.

Installation

In this case we’ll install the implementation to the /opt directory. Also we’ll install an older release in order to demonstrate the upgrade.

$ tar xf apache-artemis-2.14.0.tar.gz
$ sudo mv apache-artemis-2.14.0 /opt

Broker instance creation

We now create a broker instance using the artemis command provided by the implementation:

$ /opt/apache-artemis-2.14.0/bin/artemis create artemisbroker --user admin --require-login
Creating ActiveMQ Artemis instance at: /home/bangert/artemisbroker

--password: is mandatory with this configuration:
Please provide the default password:


Auto tuning journal ...
done! Your system can make 41.67 writes per millisecond, your journal-buffer-timeout will be 24000

You can now start the broker by executing:  

   "/home/bangert/artemisbroker/bin/artemis" run

Or you can run the broker in the background using:

   "/home/bangert/artemisbroker/bin/artemis-service" start

Broker instance deep dive

Lets have a closer look at what this separation means in practice. First we will take a look at the newly created broker instance:

$ tree artemisbroker/
artemisbroker/
├── bin
│   ├── artemis
│   └── artemis-service
├── data
├── etc
│   ├── artemis.profile
│   ├── artemis-roles.properties
│   ├── artemis-users.properties
│   ├── bootstrap.xml
│   ├── broker.xml
│   ├── jolokia-access.xml
│   ├── logging.properties
│   ├── login.config
│   └── management.xml
├── lib
├── log
└── tmp

6 directories, 11 files

We see, that at this moment, right after instance creation, the instance does not contain much. Basically just a bunch of configuration files and the instance artemis command used to manage this specific broker instance. But where is the code that would be run, if this instance were to be started?

In the instance artemis script there is a variable called ARTEMIS_HOME which points back to the implementation - in our case /opt/apache-artemis-2.14.0. This variable is set in the etc/artemis.profile of the broker instance configuration. In other words the pointer to the concrete implementation is just configuration as well.

Contrast this with ActiveMQ classic, where this separation is not available. There typically the implementation and the broker instance share the same directory structure. Depending on your specific setup upgrading can become a messy affair, since the broker implementation, configuration, data and logfiles all share the same directory structure.

Here is what the instance directory looks like, once we have started our instance:

$ tree artemisbroker/
artemisbroker/
├── bin
│   ├── artemis
│   └── artemis-service
├── data
│   ├── bindings
│   │   ├── activemq-bindings-1.bindings
│   │   └── activemq-bindings-2.bindings
│   ├── journal
│   │   ├── activemq-data-1.amq
│   │   ├── activemq-data-2.amq
│   │   ├── server.lock
│   │   ├── serverlock.1
│   │   └── serverlock.2
│   ├── large-messages
│   └── paging
├── etc
│   ├── artemis.profile
│   ├── artemis-roles.properties
│   ├── artemis-users.properties
│   ├── bootstrap.xml
│   ├── broker.xml
│   ├── jolokia-access.xml
│   ├── logging.properties
│   ├── login.config
│   └── management.xml
├── lib
├── lock
│   └── cli.lock
├── log
│   ├── artemis.log
│   └── audit.log
└── tmp
    └── webapps

We see a number of additional files like data files and logfiles created in the instance directory by artemis once it has been started.

And you probably guessed it: If you want to see the files of the implementation checkout the directory structure in /opt/apache-artemis-2.15.0 (left as an exercise for the reader).

Upgrading the broker implementation

This is the easy part. As the broker instance is independent of the implementation, upgrading the implementation is actually just installing another version of the broker.

Here we want to upgrade to 2.15.0 so:

$ tar xf apache-artemis-2.15.0.tar.gz
$ sudo cp -r apache-artemis-2.15.0 /opt

So now you’ll have two artemis implementations in your /opt:

$ ls -l /opt
total 20
drwxr-xr-x. 7 root root 4096 Oct 27 09:05 apache-artemis-2.14.0
drwxr-xr-x. 7 root root 4096 Oct 27 09:05 apache-artemis-2.15.0
...

Notice how updating the broker implementation is not an update at all - it’s just installing the new version of ActiveMQ Artimes alongside the already existing version.

Please also note that we do not want to remove the old version before we have upgraded all broker instances using this implementation, as the instances otherwise would become defunct. But we’ll upgrade the broker instance next to finish the upgrade.

Upgrading the broker instance

You may already be able to see, where this is going, but please remember to check the documentation when upgrading - additional steps may be required.

Apache ActiveMQ Artemis appears to be using semantic versioning, so patch level upgrades should generally only need the step below. Minor releases may add new features so additional steps may be necessary while major releases probably require much more work. In any case always check the documentation.

ActiveMQ Artemis documentation has an upgrade chapter which basically outlines the routine described in this blog post and the versions page describes required extra steps during upgrade.

Now, using your favorite editor, update the ARTEMIS_HOME variable in etc/artemis.profile of your broker instance to point to the new broker implementation at /opt/apache-artemis-2.15.0.

Below we use sed, but other editors include nano, vim and emacs.

$ cd artemisbroker
$ sed -i 's|/opt/apache-artemis-2\.14\.0|/opt/apache-artemis-2\.15\.0|' etc/artemis.profile

And now remember to restart your ActiveMQ Artemis instance to complete the instance upgrade. If you used the artemis-service script to start artemis this is easy:

$ cd artemisbroker
$ bin/artemis-service restart

If no other ActiveMQ Artemis instances are using the old implementation, it can now safely be removed:

$ sudo rm -r /opt/apache-artemis-2.14.0

Conclusion

We have seen how to upgrade to a new version of ActiveMQ Artemis.

The separation of implementation from configuration and data provided by ActiveMQ Artemis makes this really easy.

Thilo Bangert

Senior Systems Consultant at Redpill Linpro

Thilo is a systems engineer working with integration and helping customers apply DevOps methodologies. He is hailing from the Copenhagen office and can be contacted by mail using thilo at redpill-linpro dot com.

Migrating to OpenJDK

In the beginning of 2019 Oracle stopped releasing free-of-charge updates to their JDK, except for personal use. At the same time Oracle started requiring a subscription for Oracle JDK use in production environments. In this blog post we will look into OpenJDK as an alternative to the Oracle provided JDK and how one would migrate to it.

... [continue reading]

Moving forward with Cloudformation templates

Published on November 27, 2020

Introducing the caddy webserver: Automatic TLS

Published on November 25, 2020