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.
- Download ActiveMQ Artemis from the download page. In this case we want an older release which you may get from the past release page. Direct link to 2.14.0.
- Unpack the tarball
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:
- Download ActiveMQ Artemis from the website http://activemq.apache.org/components/artemis/download/.
- Unpack the tarball
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.
