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/foo/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/foo/artemisbroker/bin/artemis" run

Or you can run the broker in the background using:

   "/home/foo/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 log-files 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 log-files 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 Artemis 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.

Containerized Development Environment

Do you spend days or weeks setting up your development environment just the way you like it when you get a new computer? Is your home directory a mess of dotfiles and metadata that you’re reluctant to clean up just in case they do something useful? Do you avoid trying new versions of software because of the effort to roll back software and settings if the new version doesn’t work?

Take control over your local development environment with containerization and Dev-Env-as-Code!

... [continue reading]

Ansible-runner

Published on February 27, 2024

Portable Java shell scripts with Java 21

Published on February 21, 2024