How to setup bridge extension using HiveMQ operator

This article explains steps by step details about how to configure bridge extension using the HiveMQ operator

Prerequisites:

1. k8s version 1.16+ and < 1.25 is installed

2. Helm version 3 is installed

3. A running Kubernetes cluster on any environment or providers cloud provider

 Instructions

1. Let's get started with installing the remote hivemq broker

   1. First, create a namespace to install the remote hivemq broker

      kubectl ns create <namespace name>

   2. This step is optional.
      Create configmap for hivemq license. (You can get this license from the Customer Success team).

      kubectl create configmap hivemq-license --from-file hivemq4.lic --from-file hivemq4-bridge-extension-valid-until-28-03-2023.elic -n hivemq-1630

   3. Create your custom values.yaml to deploy HiveMQ broker

      1. Full values of the HiveMQ operator can be found herehelm-charts/charts/hivemq-operator/values.yaml at master · hivemq/helm-charts

      2. example of custom hivemq_values.yaml

         hivemq: image: hivemq/hivemq4:k8s-4.9.1 imagePullPolicy: Always cpu: 8 memory: 8Gi nodeCount: "2" logLevel: "INFO" configMaps: - name: hivemq-license path: /opt/hivemq/license ports: - name: "mqtt" port: 1883 expose: true patch: - '[{"op":"add","path":"/spec/selector/hivemq.com~1node-offline","value":"false"},{"op":"add","path":"/metadata/annotations","value":{"service.spec.externalTrafficPolicy":"Local"}}]' - '[{"op":"add","path":"/spec/type","value":"LoadBalancer"}]' - name: "cc" port: 8080 expose: true patch: - '[{"op":"add","path":"/spec/sessionAffinity","value":"ClientIP"}]' monitoring: dedicated: false enabled: true operator: admissionWebhooks: enabled: false

   4. Deploy remote broker

      helm upgrade --install -f path/to/hivemq_values.yaml <release name> hivemq/hivemq-operator

   5. Verify whether the deployment is successful or not

      1. Check the pods status

         kubectl get pods

      2. Check the hivemq logs

         kubectl logs <pod>

      3. If no error is observed in the logs and all pod statuses are Running then this installation is completed.

2. Install the hivemq broker(with bridge extension)

   1. Create a namespace to install the hivemq broker.

      kubectl ns create <namespace name>

   2. This step is optional. By default HiveMQ extensions only runs for 5 hrs and then get disabled if no valid license is found.
      Create configmap for hivemq license and bridge extension license. (You can get these licenses from the Customer Success team).

      kubectl create configmap hivemq-license --from-file path/to/hivemq4.lic --from-file path/to/hivemq4-bridge-extension-valid-until-28-03-2023.elic -n hivemq-1630

   3. Edit your bridge configuration file and make sure to do the following changes.

      1. Configure your remote host. Following is syntax

         <remote broker mqtt service name>.<remote broker namespace>.svc.cluster.local

         Example:

         <connection> <static> <host>hivemq-hivemq-test-mqtt.hivemq-remote.svc.cluster.local</host> <port>1883</port> </static> </connection>

      2. Next, Configure a topic filter to forward incoming publishes from MQTT clients on the bridge broker to the remote broker. You can find detailed information in our documentation.

      3. This step is optional. The HiveMQ Enterprise Bridge Extension can log key activity between the bridge and the remote broker. It is possible to log the following events. You can also add the <message-log> configuration to log activities. For more information check here.
         Please refer following example.

         <hivemq-bridge-extension> <bridges> ... </bridges> <message-log> <enabled>true</enabled> <log-level>DEBUG</log-level> <mqtt-packets>CONNECT, DISCONNECT, INCOMING-PUBLISH, SUBSCRIBE, OUTGOING-PUBLISH</mqtt-packets> </message-log> </hivemq-bridge-extension>

   4. Create configmap for bridge configuration and this will be hivemq values.yaml under extensions block.

      kubectl create configmap bridge-configuration --from-file path/to/brigde-configuration.xml -n <namespace>

   5. This step is optional. By default, you will see all the bridge extension-related logs in hivemq.log. You can edit logback.xml to get separate logs for the Bridge extension.

      1. Edit logback.xml to add Appender and logger for bridge extension logs. Please refer following example.

         <appender name="BRIDGE-MQTT-LOG-FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>${hivemq.log.folder}/bridge-mqtt-message.log</file> <append>true</append> <encoder> <pattern>%~24(%d)~ %msg%n%ex</pattern> </encoder> <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> <fileNamePattern>${hivemq.log.folder}/bridge-mqtt-message-%i.log.gz</fileNamePattern> <minIndex>1</minIndex> <maxIndex>5</maxIndex> </rollingPolicy> <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> <maxFileSize>100MB</maxFileSize> </triggeringPolicy> </appender> <logger name="com.hivemq.bridge.log" additivity="false" level="DEBUG" > <appender-ref ref="BRIDGE-MQTT-LOG-FILE"/> </logger>

      2. create configmap for edited logback.xml.

         kubectl create configmap logback --from-file path/to/logback.xml -n <bridge broker namespace>

      3. configure created configmap in your custom values.yaml. Please check the following example.

         configMaps: - name: logback path: /opt/hivemq/config

   6. Create your custom values.yaml to deploy HiveMQ broker

      1. Full values of the HiveMQ operator can be found herehelm-charts/charts/hivemq-operator/values.yaml at master · hivemq/helm-charts

      2. example of custom hivemq_bridge_values.yaml

         global: rbac: pspEnabled: false hivemq: image: hivemq/hivemq4:k8s-4.9.1 imagePullPolicy: Always cpu: 8 memory: 8Gi nodeCount: "2" logLevel: "INFO" configMaps: - name: logback path: /opt/hivemq/config extensions: - configMap: bridge-configuration enabled: true extensionUri: preinstalled name: hivemq-bridge-extension ports: - name: "mqtt" port: 1883 expose: true patch: - '[{"op":"add","path":"/spec/selector/hivemq.com~1node-offline","value":"false"},{"op":"add","path":"/metadata/annotations","value":{"service.spec.externalTrafficPolicy":"Local"}}]' - '[{"op":"add","path":"/spec/type","value":"LoadBalancer"}]' - name: "cc" port: 8080 expose: true patch: - '[{"op":"add","path":"/spec/sessionAffinity","value":"ClientIP"}]' monitoring: dedicated: false enabled: true operator: admissionWebhooks: enabled: false

   7. Deploy hivemq broker

      helm upgrade --install -f path/to/hivemq_bridge_values.yaml <release name> hivemq/hivemq-operator

   8. Verify pods and HiveMQ logs to confirm deployment is successful

      1. hivemq.log will have entries about the Bridge extension. Please find below sample log entries.

         2022-11-25 09:42:19,316 INFO - Starting extension with id "hivemq-bridge-extension" at /opt/hivemq/extensions/hivemq-bridge-extension 2022-11-25 09:42:19,595 INFO - Bridge Extension: Connecting to remote brokers... 2022-11-25 09:42:19,840 INFO - Bridge Extension: Connected to bridge 'My-Bridge', session present 'false'. 2022-11-25 09:42:19,871 INFO - Extension "HiveMQ Enterprise Bridge Extension" version 4.9.1 started successfully.

 Related articles