/
Overriding HiveMQ's Config.xml with HiveMQ Platform Operator

Overriding HiveMQ's Config.xml with HiveMQ Platform Operator

We are actively expanding the configurations available in our new Platform Operator. In the interim, if you have specific requirements to incorporate additional configurations not covered by the platform's default settings, this guide is designed to assist you.

This step-by-step guide provides instructions on how to override HiveMQ's config.xml when the required configurations are not available in the platform's values.yaml. This is particularly useful when you need to customize specific HiveMQ configurations not exposed to the platform's default settings.
Examples: https://docs.hivemq.com/hivemq/latest/user-guide/configuration.html#default or https://docs.hivemq.com/hivemq/latest/user-guide/configuration.html#mqtt-config or internal options, etc.

Prerequisites:

  1. Helm version v3+

  2. Running Kubernetes cluster version 1.18.0 or higher

  3. kubectl latest version

When utilizing the Platform Operator, the default location for the config.xml file is '/opt/hivemq/conf-k8s/config.xml'. To confirm any modifications made after overriding the config.xml, please inspect this directory. This is where you can validate and ensure that the changes have been successfully applied to the configuration.


 Instructions

In the HiveMQ Platform Helm chart, it is possible to override the default HiveMQ config.xml using a configMap.

  1. Prepare the config map manifest, hivemq-configuration-override.yml.

    # Source: hivemq-platform/templates/hivemq-configuration.yml apiVersion: v1 kind: ConfigMap metadata: name: hivemq-configuration-broker-override namespace: hivemq data: # noinspection XmlPathReference config.xml: |- <?xml version="1.0"?> <hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="config.xsd"> <listeners> <tcp-listener> <port>1883</port> <bind-address>0.0.0.0</bind-address> </tcp-listener> <tls-websocket-listener> <port>8000</port> <bind-address>0.0.0.0</bind-address> <path>/mqtt</path> <tls> <keystore> <path>/path/to/broker-keystore.jks</path> <password>${ENV:BROKER_KEYSTORE_PASS}</password> <private-key-password>${ENV:BROKER_KEY_PASSPHRASE}</private-key-password> </keystore> <client-authentication-mode>NONE</client-authentication-mode> </tls> </tls-websocket-listener> </listeners> <cluster> <transport> <tcp> <bind-address>0.0.0.0</bind-address> <bind-port>7000</bind-port> </tcp> </transport> <enabled>true</enabled> <discovery> <extension/> </discovery> </cluster> <!-- required and should not be configured different --> <health-api> <enabled>true</enabled> <listeners> <http> <port>8889</port> <bind-address>0.0.0.0</bind-address> </http> </listeners> </health-api> <control-center> <listeners> <http> <port>8080</port> <bind-address>0.0.0.0</bind-address> </http> </listeners> </control-center> </hivemq>

  2. Create the config map.

    kubectl apply -f hivemq-configuration-override.yml --namespace hivemq

Optionally, you can create a configMap directly with your ready config.xml with the following command.

kubectl create configmap hivemq-configuration-broker-override --from-file path/to/config.xml --namespace hivemq

  1. Update the HiveMQ Platform values.yaml, disable to create the config map (create: false), and specify the new name of the config map (name: "hivemq-configuration-broker-override").

    config: create: false name: "hivemq-configuration-broker-override" overrideHiveMQConfig: "" overrideStatefulSet: "" overrideInitContainers: ""

  2. Update the HiveMQ Platform.

    helm upgrade broker --install hivemq/hivemq-platform --values values.yaml

    Specify the updated in the step 3 values.yaml in the --values values.yaml

  3. Check the broker pods status and ensure that all pods are running and all containers are ready.

    kubectl get pods --namespace hivemq -o wide

  4. Review the content of the config.xml file on the broker pod and make sure that it is overridden:

    kubectl exec broker-0 -c hivemq -- cat conf-k8s/config.xml

  5. Review the hivemq.log to confirm that config.xml is loaded successfully.

    kubectl logs <pod name> -n <namespace>

  6. Perform Quick Tests:

    Utilize the MQTT CLI to conduct quick tests to verify changes

 

Note: Helm values.yaml broker configurations will be overridden when custom config.xml is used, and services must be configured in Helm values.yaml as per custom config.xml to avoid conflicts.

 Related articles