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:

k8s version 1.16+ and < 1.25 is installed
Helm version 3 is installed
A running Kubernetes cluster on any environment or providers cloud provider

\uD83D\uDCD8 Instructions

Let's get started with installing the remote hivemq broker

First, create a namespace to install the remote hivemq broker
```
kubectl ns create <namespace name>
```

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

Create your custom values.yaml to deploy HiveMQ broker

Full values of the HiveMQ operator can be found herehttps://github.com/hivemq/helm-charts/blob/master/charts/hivemq-operator/values.yaml

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

Deploy remote broker

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

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.

Install the hivemq broker(with bridge extension)

Create a namespace to install the hivemq broker.
```
kubectl ns create <namespace name>
```
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
```
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>
```

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>

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.

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>

create configmap for edited logback.xml.

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

configure created configmap in your custom values.yaml. Please check the following example.
```
configMaps:
    - name: logback
      path: /opt/hivemq/config
```

Create your custom values.yaml to deploy HiveMQ broker

Full values of the HiveMQ operator can be found herehttps://github.com/hivemq/helm-charts/blob/master/charts/hivemq-operator/values.yaml

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

Deploy hivemq broker

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

Verify pods and HiveMQ logs to confirm deployment is successful

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.

By default enterprise bridge extension will work for 5 hours and will be disabled automatically if no valid license found.

How to setup bridge extension using HiveMQ operator

Prerequisites:

\uD83D\uDCD8 Instructions

\uD83D\uDCCB Related articles