/
Setup ESE File Realm using HiveMQ Operator

Setup ESE File Realm using HiveMQ Operator

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

HiveMQ Enterprise Security Extension is preinstalled with HiveMQ so once you enable it, it will look for its configuration file. You must prepare this file before enabling the extension. If you skip this step, the extension will not find its configuration file and will not load any configuration.

Please download the following sample files

  1. config.xml

  2. ese-file-realm.xml

In case you are running a local setup, please place your HiveMQ Enterprise Security Extension configuration files in the conf folder of your HiveMQ Enterprise Security Extension.

Setting up the ESE config as a ConfigMap

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

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

    kubectl create configmap ese-config --namespace=hivemq \ --from-file config.xml \ --from-file ese-file-realm.xml

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

    hivemq: extensions: ... - name: hivemq-enterprise-security-extension extensionUri: preinstalled enabled: false # Note that this is just an example initialization routine. Make sure this points to the current JDBC version you require for your configuration. initialization: | # Download JDBC driver for PostgreSQL [[ ! -f drivers/postgres-jdbc.jar ]] && curl -L https://jdbc.postgresql.org/download/postgresql-42.2.14.jar --output drivers/jdbc/postgres.jar

    To this:

    hivemq: extensions: ... - name: hivemq-enterprise-security-extension extensionUri: preinstalled enabled: true configMap: ese-config initialization: | [[ ! -f conf/config.xml ]] && [[ -f /conf-override/extensions/hivemq-enterprise-security-extension/config.xml ]] && ln -s /conf-override/extensions/hivemq-enterprise-security-extension/config.xml conf/config.xml && [[ ! -f conf/ese-file-realm.xml ]] && [[ -f /conf-override/extensions/hivemq-enterprise-security-extension/ese-file-realm.xml ]] && ln -s /conf-override/extensions/hivemq-enterprise-security-extension/ese-file-realm.xml conf/ese-file-realm.xml

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:

hivemq: ... env: [] ## Skip config validation # - name: "HIVEMQ_SKIP_CONFIG_VALIDATION" # value: "true" ## Add custom environment variables (e.g. for your extension) here. # - name: MY_CUSTOM_ENV # value: some-value

To this:

env: - name: "HIVEMQ_ALLOW_ALL_CLIENTS" value: "false"

Update the configuration

for ease of use we can switch the namespace back to hivemq kubectl config set-context --current --namespace=hivemq

In case the redeployment does not restart the pods, please use helm uninstall hivemq --namespace hivemq and redeploy it again.
Note that it will uninstall the hivemq, but will not delete any configMap created by you, which should be deleted independently, in case of any changes to configMap files

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

helm upgrade hivemq --install hivemq/hivemq-operator --values values.yaml --namespace hivemq

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

kubectl logs deployment/hivemq --namespace=hivemq | grep -i 'security'

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

2024-01-30 10:36:12,693 INFO - Using valid license (ese-license.elic) for enterprise extension with name "HiveMQ Enterprise Security Extension", valid until 2024-03-31. 2024-01-30 10:36:12,943 INFO - Starting extension with id "hivemq-enterprise-security-extension" at /opt/hivemq/extensions/hivemq-enterprise-security-extension 2024-01-30 10:36:13,599 INFO - HiveMQ Enterprise Security Extension: Successfully loaded configuration from '/opt/hivemq/extensions/hivemq-enterprise-security-extension/conf/config.xml'. 2024-01-30 10:36:13,602 INFO - Starting HiveMQ Enterprise Security Extension. 2024-01-30 10:36:14,152 INFO - Started HiveMQ Enterprise Security Extension successfully in 1206ms. 2024-01-30 10:36:14,152 INFO - Extension "HiveMQ Enterprise Security Extension" version 4.24.0 started successfully.

  1. Get the external IP of the MQTT load balancer

    mqttHost=$(kubectl get svc hivemq-hivemq-mqtt -o jsonpath='{.status.loadBalancer.ingress[0].ip}{"\n"}') mqttPort=$(kubectl get svc hivemq-hivemq-mqtt -o jsonpath='{.spec.ports[0].port}{"\n"}')

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)

    kubectl get services --namespace hivemq

     

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

    mqtt subscribe -h 20.113.42.183 -p 1883 -t '#' -q 1 -u mqtt-user-1 -pw mqtt-password-1

    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)

    mqtt publish -h 20.113.42.183 -p 1883 -t topic-1 -m Hello -q 1 -u mqtt-user-2 -pw mqtt-password-2

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

Next steps

Please read the official documentation for more configuration options https://docs.hivemq.com/hivemq-enterprise-security-extension/latest/ese.html#file-based