HiveMQ Enterprise Extension for Kafka Upgrade Process

Releases of the HiveMQ Enterprise Extensions for Kafka use semantic versioning:

major.minor.patch

Major

Major versions are extensive feature releases that add functionality that is not downward compatible with previous versions.

Minor

Minor versions provide new features and functionality that are downward compatible with previous versions.

Patch

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 hivemq-kafka-extension folder that is located in the extensions folder of your HiveMQ installation. This backup preserves all configuration information that is associated with the extension version that you currently use.

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-extension folder as needed in preparation for the upgrade.
Open the hivemq-kafka-extension folder that you downloaded and use the conf/examples/config.xml to create a new conf/config.xml file. Based on your use case and new features that the version adds, adapt the config.xml file that you create accordingly. For more information, see Configuration.
If you use a local schema file, add this information to the local-schema-registry folder in the hivemq-kafka-extension folder 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-licenses folder in the hivemq-kafka-extension folder 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-extension folder with new files from the hivemq-kafka-extension folder 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/

Remove the hivemq-kafka-extension-x.x.x.jar file 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 config-archive subfolder from the previous version.

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 HIVEMQ_SUPER_ADMIN permission. For more information, see the Control Center Permissions.

Support

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 contact@hivemq.com