Setup ESE File Realm using HiveMQ Operator

Owned by Daria Samkova, created
Last updated: Feb 26, 2024 by Harsh Bansal
4 min read

Prequisites

Setting up the ESE license as a ConfigMap

If you skip the following steps, then the enterprise-security-extension will start in trial mode, limited to 5h, and will be automatically disabled by the HiveMQ broker after 5h.

In case you get error configmaps "hivemq-license" already exists , please delete the last configmap using kubectl delete configmap hivemq-license --namespace hivemq and try the addition step again.

  1. HiveMQ Enterprise Security Extension requires a separate license file, e.g. ese-license.elic, in the $HIVEMQ_HOME/license directory. To add the ese-license.elic along with the hivemq-license.lic, create a new configmap hivemq-license including all desired license files:

    kubectl create configmap hivemq-license --namespace=hivemq \ --from-file hivemq-license.lic \ --from-file ese-license.elic

  2. Edit the values.yaml file of the hivemq-operator, section hivemq.configMaps. Update this:

    configMaps: [] # ConfigMaps to mount to the HiveMQ pods. These can be mounted to existing directories without shadowing the folder contents as well. #- name: hivemq-license # path: /opt/hivemq/license

    To this:

    configMaps: - name: hivemq-license path: /opt/hivemq/license

    This will mount the content of the configMap hivemq-license to the directory /opt/hivemq/license of the hivemq-broker pods.

Prepare your HiveMQ Enterprise Security Extension configuration files

Please download the following sample files

  1. config.xml

  2. ese-file-realm.xml

Setting up the ESE config as a ConfigMap

  1. Create a new configMap ese-config including all desired config files:

  2. Edit the values.yaml file of the hivemq-operator, section hivemq.extensions. Update this:

    To this:

Disable the default security extension

By default, the HiveMQ distribution comes with the allow-all extension that permits all MQTT connections without requiring authentication. Before you use HiveMQ in production, add an appropriate security extension and remove the HiveMQ allow-all extension.
To disable the extension, set the HIVEMQ_ALLOW_ALL_CLIENTS environment variable to false.
Edit the values.yaml file of the hivemq-operator, section hivemq.env. Update this:

To this:

Update the configuration

  1. Re-deploy hivemq-operator with updated values.yaml

  1. If everything is correct, The HiveMQ log contains info about using the correct license:

The output would contain the following data around license and extension:

  1. Get the external IP of the MQTT load balancer

End-to-end testing of mqtt clients

  1. Find the MQTTListenerURL or IP using the following command (hivemq-hivemq-mqtt in our case with IP 20.113.42.183)

     

  2. Subscribe a mqtt client: (update url/ip for host, taken from last step, localhost in case of port forward)

    Do not close this terminal session. This will allow you to see the results.

  3. From a different terminal session, publish a message to the topic “test”: (update url/ip for host, taken from last step, localhost in case of port forward)

  4. If everything is correct, the subscriber will receive the message:

Next steps