Setting up HiveMQ Bridge extension with mTLS enabled using HiveMQ Platform Operator (new)

This guide walks you through securely connecting a HiveMQ broker to a remote broker using the Bridge Extension with mTLS (Mutual TLS) in a Kubernetes environment.

Prerequisites

• Kubernetes cluster running

• Helm installed

• HiveMQ Platform Operator installed

• HiveMQ Enterprise Docker image access

• Bridge client certificates for mTLS :
  In case certificates are not ready, we have a script to help you with creating client keystore and truststore and remote broker keystore and truststore.

• External remote broker or HiveMQ cluster to bridge to

 Instructions

Install the HiveMQ Platform Operator

If not already installed

Deploy a remote HiveMQ broker with MTLS configurations:

This broker will receive data from the local broker through the bridge extension.

1. Create Kubernetes Secrets for TLS

   kubectl create secret generic hivemq-keystore \ --from-file=keystore=broker-keystore.jks -n hivemq kubectl create secret generic hivemq-truststore \ --from-file=truststore=broker-truststore.jks -n hivemq

2. In case you don't have hivemq-platform values.yaml then you can create it by following the command.

   helm show values hivemq/hivemq-platform > remote-values.yaml

   Open remote-values.yaml and find the section called listeners with port 8883. Update with this configuration:

   - type: mqtt # The custom name of the Kubernetes service resource. If not set or empty, the default service name will be as follows: # "hivemq-<release-name>-<.Values.services.type>-<.Values.services.port>" name: "mqtt-tls" exposed: true containerPort: 8883 # The name of the Kubernetes secret that contains the keystore file. keystoreSecretName: "hivemq-keystore" # The key of the Kubernetes secret that contains the keystore file. Defaults to `keystore` keystoreSecretKey: "" # Two options are available to configure secure MQTT listeners: # 1. Using base64 encoded passwords configured via Helm chart values, as below # The inlined password for the keystore, Base 64 encoded. keystorePassword: "Y2hhbmdlbWU=" # The inlined private key password for the keystore, Base 64 encoded. Defaults to the `keystorePassword` value. keystorePrivatePassword: "Y2hhbmdlbWU=" # 2. Using base64 encoded passwords stored in a Kubernetes secret, as below # Alternatively, the name of the Kubernetes secret which contains the keystore password and optionally the private key password for the keystore. keystorePasswordSecretName: "" # The optional entry key for the keystore password in the Kubernetes secret. Defaults to `keystore.password` keystorePasswordSecretKey: "" # The optional entry key for the keystore private password in the Kubernetes secret. keystorePrivatePasswordSecretKey: "" # Mutual TLS configuration values # The name of the Kubernetes secret that contains the truststore file. truststoreSecretName: "hivemq-truststore" # The key of the Kubernetes secret that contains the truststore file. Defaults to `truststore` truststoreSecretKey: "" # The inlined password for the truststore, Base 64 encoded. truststorePassword: "Y2hhbmdlbWU=" # Alternatively, the name of the secret with the password, using the key: `truststore.password`. truststorePasswordSecretName: "" # The way HiveMQ platform authenticates client certificates. Possible values are `NONE`, `OPTIONAL` and `REQUIRED` tlsClientAuthenticationMode: "OPTIONAL"

   The passwords are base64-encoded for Kubernetes. "Y2hhbmdlbWU=" is base64 for changeme.

3. Deploy a remote broker

   helm upgrade --install hivemq hivemq/hivemq-platform -f remote-values.yaml -n hivemq

4. Check the logs, and verify if the remote broker is successfully deployed

   kubectl get pods -n hivemq kubectl logs -n hivemq <POD_NAME>

Deploy the Local Broker with the Bridge Extension

This broker will connect to the remote broker using the Bridge Extension and send messages over mTLS.

1. Create ConfigMap for Bridge Certificates

   kubectl create configmap bridge-certs \ --from-file=certs_JKS_20250513_154522/clients-keystore.jks \ --from-file=certs_JKS_20250513_154522/client-truststore.jks \ -n hivemq

2. Create Bridge Extension config.xml

   <hivemq-bridge-extension> <bridges> <bridge> <enabled>true</enabled> <name>mtls-bridge</name> <remote-broker> <connection> <static> <host>mqtt-tls.hivemq.svc.cluster.local</host> <port>8883</port> </static> </connection> <tls> <enabled>true</enabled> <keystore> <path>/opt/hivemq/conf/certs/clients-keystore.jks</path> <password>changeme</password> <private-key-password>changeme</private-key-password> </keystore> <truststore> <path>/opt/hivemq/conf/certs/client-truststore.jks</path> <password>changeme</password> </truststore> </tls> </remote-broker> <topics> <topic> <filter>bridge/topic/test</filter> <mode>PUB</mode> </topic> </topics> </bridge> </bridges> </hivemq-bridge-extension>

   create configmap for bridge extension config.xml make sure to have certs location matching with additionalVolumes mount path.

   kubectl create configmap bridge-config \ --from-file=config.xml \ -n hivemq

3. Update local-values.yaml to enable the Bridge Extension and configure additionalVolumes for bridge client certificates to mount. This mounts the keystore/truststore at the expected path used in config.xml.

   ... extensions: # HiveMQ Enterprise Bridge Extension . # This extension does not support hot-reload of the configuration. - name: hivemq-bridge-extension enabled: true # The ConfigMap name that contains the Bridge extension configuration. configMapName: "bridge-config" additionalVolumes: - type: configMap name: bridge-certs mountName: bridge-certs containerName: hivemq path: /opt/hivemq/conf/certs ...

4. Deploy the Local Broker

   helm upgrade --install hivemq-local hivemq/hivemq-platform -f local-values.yaml -n hivemq

   
   Verify Bridge Connection;

   kubectl logs -n hivemq <hivemq-local-pod-name>

   Check the logs for lines like:

   • INFO - HiveMQ Enterprise Bridge Extension: Successfully loaded configuration from '/opt/hivemq/extensions/hivemq-bridge-extension/conf/config.xml'. INFO - Bridge Extension: Connecting to remote brokers... INFO - Bridge Extension: Connected to bridge 'mtls-bridge', session present 'false'. INFO - Extension "HiveMQ Enterprise Bridge Extension" version 4.39.0 started successfully.

 Related articles