Setup ESE (with Postgresql)

\uD83D\uDCD8 Prerequisites

A running Kubernetes cluster (we use AKS cluster with Kubenetes API 1.28)
A PostgreSQL client installed locally (we use psql (PostgreSQL) 14.10)
1. MacOS: brew install PostgreSQL
2. Windows: link
3. Linux: link

Prequisite: A running Kubernetes cluster. In this article, AKS v.1.28 is used.

If you are not logged in, please use the following commands to log in to your Azure cluster, please replace the group and name as needed. (Our reference: Setting up AKS Cluster in Azure | Set Up Your Kubernetes Cluster With AKS)

az login

az aks get-credentials -g hmqResourceGroup -n HiveMQCluster

\uD83D\uDCD8 Instructions

Installation of PostgreSQL server

Add the PostgreSQL repo to your Helm:

helm repo add bitnami https://charts.bitnami.com/bitnami

Update the repo to the latest version:
```
helm repo update bitnami
```
Create a new namespace to place the PostgreSql in:
```
kubectl create namespace db
```

Switch the KubeCtl context to the new namespace:

kubectl config set-context --current --namespace=db

Install PostgreSQL to the new namespace:

helm upgrade postgres --install bitnami/postgresql --namespace db

If everything is correct, then PostgreSQL in installed to namespace “db”. The default name for the admin user is “postgres”. To get the password for "postgres" user run the following command and note the password:
```
export PGPASSWORD=$(kubectl get secret --namespace db postgres-postgresql -o jsonpath="{.data.postgres-password}" | base64 -d) && echo $PGPASSWORD
```

Create tables for the ESE

Port-forward service postgres-postgresql to localhost:

kubectl port-forward svc/postgres-postgresql 5432:5432

Create a new database. When asked “Password for user postgres: ", input the value of the PGPASSWORD variable:
```
psql -h localhost -p 5432 -U postgres -c 'CREATE DATABASE "ese-db";'
```

Insert test credentials into the ESE database

Save the attached script to the file. Execute the script to create all the necessary tables in the ese-db.
```
psql -h localhost -p 5432 -U postgres -d ese-db -a -f postgresql_create.sql
```
Save the attached script to the file. If asked “Password for user postgres: ", input the value of the PGPASSWORD variable.
```
psql -h localhost -p 5432 -U postgres -d ese-db -a -f create-users.sql
```
Check your work. If asked “Password for user postgres: ", input the value of the PGPASSWORD variable.
```
psql -h localhost -p 5432 -U postgres -d ese-db -c 'SELECT * from public.users;'
```

Setting up the ESE license as a ConfigMap

If you skip this step, 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.

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
```

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.

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

Configuring the extension

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.

Prepare a simple configuration file for Enterprise Security Extensions in the example below.
Replace the “password” in <db-password>password</db-password> with the value of PGPASSWORD variable.
config.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>
        <!-- a postgresql db-->
        <sql-realm>
            <name>postgres-backend</name>
            <enabled>true</enabled>
            <configuration>
                <db-type>POSTGRES</db-type>
                <db-name>ese-db</db-name>
                <db-host>postgres-postgresql.db.svc.cluster.local</db-host>
                <db-port>5432</db-port>
                <db-username>postgres</db-username>
                <db-password>password</db-password>
            </configuration>
        </sql-realm>
    </realms>
    <pipelines>
        <!-- secure access to the mqtt broker -->
        <listener-pipeline listener="ALL">
            <!-- authenticate over a sql db -->
            <sql-authentication-manager>
                <realm>postgres-backend</realm>
            </sql-authentication-manager>
            <!-- authorize over a sql db -->
            <sql-authorization-manager>
                <realm>postgres-backend</realm>
                <use-authorization-key>false</use-authorization-key>
                <use-authorization-role-key>true</use-authorization-role-key>
            </sql-authorization-manager>
        </listener-pipeline>
        <!-- secure access to the control center -->
        <control-center-pipeline>
            <!-- authenticate over a sql db -->
            <sql-authentication-manager>
                <realm>postgres-backend</realm>
            </sql-authentication-manager>
            <!-- authorize over a sql db -->
            <sql-authorization-manager>
                <realm>postgres-backend</realm>
                <use-authorization-key>true</use-authorization-key>
                <use-authorization-role-key>true</use-authorization-role-key>
            </sql-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 sql db -->
            <sql-authentication-manager>
                <realm>postgres-backend</realm>
            </sql-authentication-manager>
            <!-- authorize over a sql db -->
            <sql-authorization-manager>
                <realm>postgres-backend</realm>
                <use-authorization-key>true</use-authorization-key>
                <use-authorization-role-key>true</use-authorization-role-key>
            </sql-authorization-manager>
        </rest-api-pipeline>
    </pipelines>
</enterprise-security-extension>

In the hivemq namespace create a configMap ese-config from the file config.xml
```
kubectl create configmap ese-config --from-file config.xml --namespace hivemq
```

Edit values.yaml file of hivemq-operator and update section hivemq.extensions, having name: hivemq-enterprise-security-extension
Update this:

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

    - 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 drivers/postgres-jdbc.jar ]] &&
        curl -L https://jdbc.postgresql.org/download/postgresql-42.7.1.jar --output drivers/jdbc/postgres.jar

Re-deploy hivemq-operator with updated values.yaml
```
helm upgrade hivemq --install hivemq/hivemq-operator --values values.yaml --namespace hivemq
```
– for ease of use we switch the namespace back to hivemq kubectl config set-context --current --namespace=hivemq
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.

End-to-end testing

Find the MQTTListenerURL or IP using the following command (hivemq-hivemq-mqtt in our case with IP 20.79.142.120)
```
kubectl get services --namespace hivemq
```

Subscribe (update url/ip for host, taken from last step, localhost in case of port forward)

mqtt subscribe --topic "topic/+/status" --qos 1 --host 20.79.142.120 --port 1883 --showTopics \
  --user backendservice --password backendpassword

Publish (update url/ip for host, taken from last step, localhost in case of port forward)

mqtt publish --identifier TheClient1 --topic topic/TheClient1/status \
 --host 20.79.142.120 --port 1883 --qos 1 \
  --user frontendclient --password clientpassword --message "test"

If everything is correct, the subscriber will receive Hello

\uD83D\uDCCB Related articles

Filter by label

There are no items with the selected labels at this time.