Setup TLS listener for Hivemq cluster using HiveMQ operator

Owned by Sheetal Shet, created
Last updated: Sept 21, 2023
4 min read

In this article, we will walk you through the steps to enable TLS listener for the HiveMQ in the Kubernetes cluster using the HiveMQ Operator. By default, the HiveMQ 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

  • The Hivemq k8s operator repo is already added in the helm repo

  • Ready keystore.jks, (optional) truststore.jks(You can find steps to create these JKS files here)

 Instructions

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

    kubectl create secret generic tls-certificates \ --from-file path/to/keystore.jks \ --from-file path/to/truststore.jks -n <namespace>

  2. Add the Secret to your values.yaml file to mount to the HiveMQ pods:

    hivemq: ... secrets: - name: tls-certificates path: /opt/hivemq/conf

    This will mount both JKS files at the specified Path.

  3. Store the passwords in the Kubernetes secret using the following command:

    kubectl create secret generic tls-passwords \ --from-literal=keystore_pass='password1' -n <namespace>

     

  4. Create environment variables to access the passwords in the HiveMQ listener’s configurations. Update your values.yaml file with the following configuration:

  5. To enable the TLS listener, please add the following block to your values.yaml and add the correct JKS file name and the environment variables names for passwords used while creating the Keystore.

     

  6. In the values.yaml, edit the mqtt port so that it corresponds to the new listener. Update the MQTT port number from 1883 to 8883 in both the Ports section of your values.yaml file and, in case you are exposing these ports via service, then update that file as well.

  7. Deploy the above changes to the Kubernetes cluster

  8. Verify the logs to check if TLS is enabled or not

  9. You will see the following logs if all changes are deployed correctly.

  10. You can also test the connection via the MQTT CLI tool

Troubleshooting

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

    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:

     

  2. Error: 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).