HiveMQ Enterprise Extension for Kafka Upgrade Process
Releases of the HiveMQ Enterprise Extensions for Kafka use semantic versioning:
Major versions are extensive feature releases that add functionality that is not downward compatible with previous versions.
Minor versions provide new features and functionality that are downward compatible with previous versions.
Patch versions (also known as bugfix releases) adjust existing functionality in a downward compatible manner and are drop-in replacements for the current minor version.
Prepare Your Upgrade Folder
The goal of your upgrade preparation is to collect and configure the files that you need to upgrade from the version of the extension that you currently use to the desired new version.
Before you begin the upgrade process, create a backup of the entire
Download and unzip the new version of the extension from the HiveMQ Marketplace. In this procedure, you modify the files in the downloaded
hivemq-kafka-extensionfolder as needed in preparation for the upgrade.
hivemq-kafka-extensionfolder that you downloaded and use the
kafka-configuration.example.xmlto create a new
kafka-configuration.xmlfile. Based on your use case and new features that the version adds, adapt the
kafka-configuration.xmlfile that you create accordingly. For more information, see Configuration.
If you use a local schema file, add this information to the
local-schema-registryfolder in the
hivemq-kafka-extensionfolder that you downloaded. For more information, see Schema Registries.
If you currently use any third-party licenses with the extension, add this information to the
third-party-licensesfolder in the
hivemq-kafka-extensionfolder that you downloaded.
|Before you upgrade the extensions in your production environment, test the new configuration of the extension in a test environment.|
Rolling Upgrade of Enterprise Extensions in Your Cluster
HiveMQ extensions can be hot-reloaded. This means that extensions can be installed, enabled, and disabled at runtime. Hot-reloading of extensions enhances HiveMQs high-availability strategy and provides a way to change extensions without introducing any kind of downtime.
To avoid any unwanted impact on performance, the addition of a new node when you do a rolling upgrade is a best practice for all production environments. For more information, see steady resource utilization.
|If you run your HiveMQ installation on a single node, you must add a node when you upgrade the extension to prevent data loss during the upgrade.|
Example Upgrade Procedure
Cluster management methods vary, the following upgrade procedure assumes that the added node is installed with the same version of the extension as the rest of the cluster. Example commands use Linux.
Add a node to your HiveMQ cluster and switch to the HiveMQ home folder. The addition of a node is a recommended optional step.
# Switch to HiveMQ home folder cd /path/to/hivemq
Disable the old version of the HiveMQ Enterprise Extension for Kafka and wait until the extension stops successfully. You do not need to shut down HiveMQ. HiveMQ extensions can be enabled and disabled at runtime (hot reload). For more information on how to disable an extension, see Extension Lifecycle.
# Disable extension touch extensions/hivemq-kafka-extension/DISABLED
Overwrite files in the
hivemq-kafka-extensionfolder with new files from the
hivemq-kafka-extensionfolder that you prepared from the download.
# Overwrite old extension files with files from the new extension (You must overwrite individual files. If you try to overwrite the entire folder, HiveMQ throws an exception.) (To receive a confirm-overwrite prompt, use \cp -ri) \cp -r /path/to/new/hivemq-kafka-extension/ extensions/
hivemq-kafka-extension-x.x.x.jarfile from the old version of the extension.
# Remove old JAR file rm -f extensions/hivemq-kafka-extension/hivemq-kafka-extension-1.0.0.jar
To enable the new version, delete the DISABLE file that you added. Wait until the extension successfully starts and proceed to the next node.
# Enable extension again rm -f extensions/hivemq-kafka-extension/DISABLED
Repeat the replacement procedure on each node in the cluster until all old versions of the extension are replaced.
Once all nodes are updated, remove the node that you added at the start of this procedure.
To maintain a seamless record of all configuration changes across different versions of the extension, do not delete the
To verify that the extension is installed and configured properly, check your HiveMQ logs and the Kafka tab of your HiveMQ Control Center.
Maintain steady resource utilization during your upgrade
Before you disable an old version of the extension, we recommend that you add a node to your cluster that is configured with the new extension version. When you disable an extension on one of the nodes in your cluster during the upgrade process, the workload of the extension you disable is redistributed over the remaining extensions that are available in the cluster. This redistributed workload increases the amount of work each remaining extension must do. The addition of a new node with the new extension, before you disable any of the existing extensions, helps you maintain a steady workload in your cluster as you upgrade the extension on each node. Once the extensions on all previously-existing nodes are upgraded and enabled, you can remove the node that you added to the cluster.
1.1.0 to 1.2.x Migration Guide
Upgrading the HiveMQ Extension for Kafka from version 1.1.0 to a higher version while using the HiveMQ Enterprise Security Extension changes the ability of some users to see the Kafka view on their Control Center dashboard.
To ensure continued access to the Kafka view, you must assign the
HIVEMQ_VIEW_PAGE_KAFKA_DASHBOARD permission to all users who lack
For more information, see the Control Center Permissions.
If you need help with the HiveMQ Enterprise Extension for Kafka or have suggestions on how we can improve the extension, please contact us at firstname.lastname@example.org