Page Comparison

\uD83D\uDCD8 Prerequisites

...

You have a Kubernetes cluster with API version >= 1.25 Setting up AKS Cluster in Azure

...

You have a HiveMQ broker cluster with version >= 4.2x installed in the Kubernetes cluster Install HiveMQ on the AKS cluster

Table of Contents

Prequisites

Access to infrastructure with Kubectl
- AKS steps https://hivemq.atlassian.net/wiki/spaces/HMS/pages/2691203114/Setting+up+AKS+Cluster+in+Azure#Manage-the-cluster
Running HiveMQ Cluster Install HiveMQ using Kubernetes Operator
Values.yaml file https://hivemq.atlassian.net/wiki/spaces/HMS/pages/2691039283/Install+HiveMQ+using+Kubernetes+Operator#Add-Helm-repository-and-download-values.yaml-file
(optional) You have added a valid license to the HiveMQ broker Add a valid license to HiveMQ Cluster
(optional) You have added a load balancer and verified the connection

...

Expose MQTT port 1883 and test

...

message flow using MQTT CLI

Instructions

...

Prepare your HiveMQ Enterprise Security Extension configuration files

HiveMQ Enterprise Security Extension

...

Get the values.yaml file from the Helm chart (skip this step if you are already in possession of the values.yaml file)

Code Block

language	bash

helm show values hivemq/hivemq-operator

This will output the values.yaml file to the stdout. You can save it to a file:

Code Block
helm show values hivemq/hivemq-operator > my-values.yaml

...

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

config.xml
View file
name config.xml
file-realm.xml
View file
name 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 license as a ConfigMap

Step 3 is mandatory, setting HIVEMQ_ALLOW_ALL_CLIENTS to false

If you skip step 1 & 2, 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.

Create a new configMap ese-config including all desired config files:
Code Block
language bash
kubectl create configmap
hivemq
ese-
license
config --namespace=hivemq \ --from-file
hivemq-licesen
config.
lic
xml \ --from-file
kafka
ese-
license
file-realm.
elic
xml

Edit the values.yaml file of the hivemq-operator, section hivemq.

configMaps

extensions. Update this:

Code Block

language	yaml

hivemq:

configMaps

extensions:

[]

...

#

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:

Code Block configMaps: - name: hivemq-license

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.

path

initialization:

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

config.xml

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8" ?>
<enterprise-security-extension
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="config.xsd"
        version="1">
    <realms>
        <file-realm>
            <name>file-realm</name>
            <enabled>true</enabled>
            <configuration>
                <file-path>conf/ese-file-realm.xml</file-path>
            </configuration>
        </file-realm>
    </realms>
    <pipelines>
        <!-- secure access to the mqtt broker -->
        <listener-pipeline listener="ALL">
            <!-- authenticate over a file -->
            <file-authentication-manager>
                <realm>file-realm</realm>
            </file-authentication-manager>
            <!-- authorize over a file -->
            <file-authorization-manager>
                <realm>file-realm</realm>
            </file-authorization-manager>
        </listener-pipeline>
        <!-- secure access to the control center -->
        <control-center-pipeline>
            <!-- authenticate over a file -->
            <file-authentication-manager>
                <realm>file-realm</realm>
            </file-authentication-manager>
            <!-- authorize over a file -->
            <file-authorization-manager>
                <realm>file-realm</realm>
            </file-authorization-manager>
        </control-center-pipeline>
        <!-- secure access to the REST API -->
        <rest-api-pipeline listener="ALL">
            <authentication-preprocessors>
                <http-headers-preprocessor>
                    <basic-auth-extraction/>
                </http-headers-preprocessor>
            </authentication-preprocessors>
            <!-- authenticate over a file -->
            <file-authentication-manager>
                <realm>file-realm</realm>
            </file-authentication-manager>
            <!-- authorize over a file -->
            <file-authorization-manager>
                <realm>file-realm</realm>
            </file-authorization-manager>
        </rest-api-pipeline>
    </pipelines>
</enterprise-security-extension>

file-realm.xml

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ese-file-realm xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:noNamespaceSchemaLocation="ese-file-realm.xsd">
    <mqtt>
        <!-- users are fetched via AUTHENTICATION_KEY-->
        <users>
            <user>
                <name>mqtt-user-1</name>
                <password>mqtt-password-1</password>
                <permissions>
                    <permission>
                        <topic>#</topic>
                        <qos>ALL</qos>
                        <activity>ALL</activity>
                        <retain>ALL</retain>
                        <shared-subscription>ALL</shared-subscription>
                        <shared-group>group-1</shared-group>
                    </permission>
                </permissions>
            </user>

            <user>
                <name>mqtt-user-2</name>
                <!-- <password>mqtt-password-2</password> -->
                <!-- https://docs.hivemq.com/ese/latest/enterprise-security-extension/ese-helper.html#hash -->
                <password encoding="Base64">aDGGvi/kW+ba1ZlQxObGZT7kNK7Vg4qkFR7HvHapCGk=</password>
                <iterations>10</iterations>
                <salt>mqtt-password-2-salt</salt>
                <algorithm>PKCS5S2</algorithm>
                <roles>
                    <role>publisher</role>
                    <role>subscriber</role>
                </roles>
            </user>
        </users>

        <!-- roles are fetched via AUTHENTICATION_ROLE_KEY-->
        <roles>
            <role>
                <id>publisher</id>
                <permissions>
                    <permission>
                        <topic>topic-1</topic>
                        <qos>ALL</qos>
                        <activity>PUBLISH</activity>
                    </permission>
                    <permission>
                        <topic>topic-2</topic>
                        <qos>ALL</qos>
                        <activity>PUBLISH</activity>
                    </permission>
                </permissions>
            </role>

            <role>
                <id>subscriber</id>
                <permissions>
                    <permission>
                        <topic>topic-3</topic>
                        <qos>ALL</qos>
                        <activity>SUBSCRIBE</activity>
                    </permission>
                </permissions>
            </role>
        </roles>
    </mqtt>

    <control-center>
        <!-- list of available permissions:
               https://www.hivemq.com/docs/ese/latest/enterprise-security-extension/ese.html#control-center-access-control-permissions -->
        <users>
            <user>
                <name>cc-user-1</name>
                <password>cc-password-1</password>
                <permissions>
                    <permission>HIVEMQ_SUPER_ADMIN</permission>
                </permissions>
            </user>

            <user>
                <name>cc-user-2</name>
                <!-- <password>cc-password-2</password> -->
                <!-- https://docs.hivemq.com/ese/latest/enterprise-security-extension/ese-helper.html#hash -->
                <password encoding="Base64">XW5ESC/iKdtYWIDpcgeFOIXhjA9reoCBzNcFm/SQhWk=</password>
                <iterations>10</iterations>
                <salt>cc-password-2-salt</salt>
                <algorithm>PKCS5S2</algorithm>
                <roles>
                    <role>topics</role>
                    <role>shared-subscriptions</role>
                </roles>
            </user>
        </users>

        <roles>
            <role>
                <id>topics</id>
                <permissions>
                    <permission>HIVEMQ_VIEW_DATA_TOPIC</permission>
                </permissions>
            </role>
            <role>
                <id>shared-subscriptions</id>
                <permissions>
                    <permission>HIVEMQ_VIEW_DATA_TOPIC</permission>
                    <permission>HIVEMQ_VIEW_DATA_SUBSCRIPTION</permission>
                    <permission>HIVEMQ_VIEW_PAGE_SHARED_SUBSCRIPTION_DETAIL</permission>
                    <permission>HIVEMQ_VIEW_PAGE_SHARED_SUBSCRIPTION_LIST</permission>
                </permissions>
            </role>
        </roles>
    </control-center>

    <rest-api>
        <!-- list of available permissions:
                https://docs.hivemq.com/ese/latest/enterprise-security-extension/ese.html#rest-api-access-permissions -->
        <users>
            <user>
                <name>rest-api-user-1</name>
                <password>rest-api-password-1</password>
                <permissions>
                    <permission>HIVEMQ_SUPER_ADMIN</permission>
                </permissions>
            </user>

            <user>
                <name>rest-api-user-2</name>
                <!-- <password>rest-api-password-2</password> -->
                <!-- https://docs.hivemq.com/ese/latest/enterprise-security-extension/ese-helper.html#hash -->
                <password encoding="Base64">apukEACJ+UeyE+onxnseWRZi/QgWOeSTtFwxHJTswxc=</password>
                <iterations>10</iterations>
                <salt>rest-api-password-2-salt</salt>
                <algorithm>PKCS5S2</algorithm>
                <roles>
                    <role>backups</role>
                    <role>subscriptions</role>
                </roles>
            </user>
        </users>

        <roles>
            <role>
                <id>backups</id>
                <permissions>
                    <permission>HIVEMQ_MANAGEMENT_BACKUPS_GET</permission>
                    <permission>HIVEMQ_MANAGEMENT_BACKUPS_POST</permission>
                    <permission>HIVEMQ_MANAGEMENT_BACKUPS_BACKUPID_GET</permission>
                    <permission>HIVEMQ_MANAGEMENT_BACKUPS_BACKUPID_POST</permission>
                    <permission>HIVEMQ_MANAGEMENT_FILES_BACKUPS_BACKUPID_GET</permission>
                </permissions>
            </role>
            <role>
                <id>subscriptions</id>
                <permissions>
                    <permission>HIVEMQ_MQTT_CLIENTS_CLIENTID_SUBSCRIPTIONS_GET</permission>
                </permissions>
            </role>
        </roles>
    </rest-api>
</ese-file-realm>

Place your HiveMQ Enterprise Security Extension configuration files in the conf folder of your HiveMQ Enterprise Security Extension.

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

Code Block

language	bash

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

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

Code Block

language	yaml

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

 |
        # 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:

Code Block

language	yaml

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

Finally, 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:

Code Block

language	yaml

hivemq:
...

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

To this:

Code Block

language	yaml

  env:
    - name: MY_CUSTOM_ENV"HIVEMQ_ALLOW_ALL_CLIENTS"
   #   value: some-value

To this:

Code Block

language	yaml

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

Install HiveMQ with updated configuration.

Code Block

language	bash

: "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

Re-deploy hivemq-operator with updated values.yaml

Code Block
helm upgrade hivemq --install hivemq/hivemq-operator --values

...

values.yaml --namespace hivemq

...

If everything is correct,

...

The HiveMQ log contains info about using the correct license:

Code Block

...


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

...

security'

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

Code Block
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.

...

The HiveMQ log contains info about successful extension start:

Code Block

language	bash

kubectl logs  deployments.apps/hivemq -f | grep -i 'Security'

...


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.

Get the external IP of the MQTT load balancer

Code Block

language	bash

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

Subscribe a mqtt client:
Code Block
language bash
mqtt subscribe -h $mqttHost -p $mqttPort -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.
From a different terminal session, publish a message to the topic “test”:
Code Block
language bash
mqtt publish -h $mqttHost -p $mqttPort -t topic-1 -m Hello -q 1 -u mqtt-user-2 -pw mqtt-password-2
If everything is correct, the subscriber will receive the message:
Code Block
language bash
mqtt subscribe -h $mqttHost -p $mqttPort -t '#' -q 1 -u mqtt-user-1 -pw mqtt-password-1
Code Block
language bash
Hello

\uD83D\uDCCB Related articles

Filter by label (Content by label)

showLabels	false
max	5
spaces	com.atlassian.confluence.content.render.xhtml.model.resource.identifiers.SpaceResourceIdentifier@117ee
sort	modified
showSpace	false
reverse	true
type	page
labels	kb-how-to-article
cql	label = "kb-how-to-article" and type = "page" and space = "HMS"

Versions Compared

Old Version 1

New Version 2

Key

\uD83D\uDCD8 Prerequisites

Prequisites

Instructions

Prepare your HiveMQ Enterprise Security Extension configuration files

Setting up the ESE license as a ConfigMap

Update the configuration

End-to-end testing of mqtt clients

\uD83D\uDCCB Related articles