Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Current »

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)

\uD83D\uDCD8 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' \
  --from-literal=truststore_pass='password2' -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:

    hivemq:
  ...
  
  env:
    - name: KEYSTORE_PASS
      valueFrom:
        secretKeyRef:
          key: keystore_pass
          name: tls-passwords
    - name: TRUSTSTORE_PASS
      valueFrom:
        secretKeyRef:
          key: truststore_pass
          name: tls-passwords

  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.

    hivemq:
  ...
  listenerConfiguration: |
    <tls-tcp-listener>
        <port>8883</port>
        <bind-address>0.0.0.0</bind-address>
        <proxy-protocol>true</proxy-protocol>
        <tls>
            <keystore>
                <path>conf/keystore.jks</path>
                <password>${KEYSTORE_PASS}</password>
                <private-key-password>${KEYSTORE_PASS}</private-key-password>
            </keystore>
            <client-authentication-mode>OPTIONAL</client-authentication-mode>
            <truststore>
                <path>conf/truststore.jks</path>
                <password>${TRUSTSTORE_PASS}</password>
            </truststore>
        </tls>
    </tls-tcp-listener>

  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. 

    hivemq:
  ports:
    - expose: true
      name: mqtt
      patch:
      - '[{"op":"add","path":"/spec/selector/hivemq.com~1node-offline","value":"false"},{"op":"add","path":"/metadata/annotations","value":{"service.spec.externalTrafficPolicy":"Local"}}]'
      port: 8883

  7. Deploy the above changes to the Kubernetes cluster

    helm upgrade hivemq --install hivemq/hivemq-operator \
  -f values.yaml -n <namespace>

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

    kubectl logs <pod name> -n <namespace>

  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:

    mqtt subscribe --topic # --jsonOutput \
  --hostname 127.0.0.1 --port 8883 \
  --cafile server.pem
    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

  2. Error: Unable to connect. Reason: 'No name matching localhost found'

    mqtt subscribe --topic # --jsonOutput \
  --host somehost --port 8883 \
  --cafile server.pem
    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).

  • No labels