Setup TLS listener for Hivemq cluster using HiveMQ platform operator (new)

This guide explains how to configure a TLS-secured MQTT listener for HiveMQ using the HiveMQ Platform Operator. By default, the HiveMQ platform operator will always enable TCP listener with port 1883.

Prerequisites:

The Kubernetes cluster is already set up and running.
k8s version 1.16+ is installed
Helm version 3 is installed
HiveMQ Platform Operator installed.
- helm upgrade --install <your-hivemq-operator> hivemq/hivemq-platform-operator -n <namespace>
Ready keystore.jks, (optional) truststore.jks(You can find steps to create these JKS files here)

Instructions

Create a Secret from TLS certificate files. Use the following command:

1.1 Upload `keystore.jks`

kubectl create secret generic hivemq-keystore \
  --from-file=keystore=keystore.jks \
  --namespace <namespace>

1.2 Upload `truststore.jks`

(Skip this step is client are not presenting certs while connecting broker)

kubectl create secret generic hivemq-truststore \
  --from-file=truststore=truststore.jks \
  --namespace <namespace>

1.3 Upload Keystore Passwords

kubectl create secret generic hivemq-keystore-passwords \
  --from-literal=my.keystore.password="<keystore-password>" \
  --from-literal=my.keystore.private.password="<private-key-password>" \
  --namespace <namespace>

✅ Use consistent secret key names for referencing in values.yaml

Update platform-values.yaml

Add the following block to the services: section of your platform-values.yaml:

services:
  - type: mqtt
    exposed: true
    containerPort: 8883
    keystoreSecretName: "hivemq-keystore"
    keystorePasswordSecretName: "hivemq-keystore-passwords"
    keystorePasswordSecretKey: "my.keystore.password"
    keystorePrivatePasswordSecretKey: "my.keystore.private.password"
    truststoreSecretName: "hivemq-truststore"
    truststorePassword: "<base64-encoded-truststore-password>"
    tlsClientAuthenticationMode: "REQUIRED" # or OPTIONAL based on your need

📌 The truststorePassword must be base64 encoded, as expected by the Platform Operator.

You can encode with:

echo -n 'your-truststore-password' | base64

Deploy the above changes to the Kubernetes cluster
helm upgrade --install hivemq hivemq/hivemq-platform \ -f platform-values.yaml -n <namespace>
Verify the logs to check if TLS is enabled or not
kubectl logs <pod name> -n <namespace>
You will see the following logs if all changes are deployed correctly.
You can also test the connection via the MQTT CLI tool

Troubleshooting

Error: 'No subject alternative names present
Meaning: the server CA file, supplied by to the client, contains CN that is not the same as the --hostname
Example command:
mqtt subscribe --topic # --jsonOutput \ --hostname 127.0.0.1 --port 8883 \ --cafile server.pem --cafile server.pem \ --key client-key.pem \ --cert client-cert.pem -d -s
Unable to connect. Reason: 'No subject alternative names present'
Reason: When the server.pem has CN that is not the IP address. For example, the server certificate has CN “example.domain.com”.
Workaround: On the client machine, edit the /etc/hosts and append <ip-address> example.domain.com. This way you can use the command successfully:
mqtt subscribe --topic # --jsonOutput \ --hostname example.domain.com --port 8883 \ --cafile server.pem \ --key client-key.pem \ --cert client-cert.pem -d -s
Error: Unable to connect. Reason: 'No name matching localhost found'
mqtt subscribe --topic # --jsonOutput \ --host localhost --port 8883 \ --cafile server.pem \ --key client-key.pem \ --cert client-cert.pem -d -s
Unable to connect. Reason: 'No name matching localhost found'
Reason: the --hostname does not match the CN of the server.pem
Solution: Open the server.pem with a certificate viewer and find out the correct CN (hostname).