Setup ESE File Realm using HiveMQ Operator

Setting up the ESE license as a ConfigMap

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:

   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

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

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

2. 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.

3. 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