HiveMQ Platform and HiveMQ Platform Operator Helm Chart Installation Examples

Install the HiveMQ Enterprise Extension for Kafka

This example shows you how to deploy a Kubernetes ConfigMap that contains the configuration for the HiveMQ Enterprise Extension for Kafka. The example also shows you how to configure the way the extension is loaded.
For additional information, see the HiveMQ Enterprise Extension for Kafka documentation.

Kafka Extension Configuration

  1. Define the HiveMQ Enterprise Extension for Kafka configuration in a config.xml file:

    <?xml version="1.0" encoding="UTF-8" ?>
<kafka-configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:noNamespaceSchemaLocation="config.xsd">
    <kafka-clusters>
        <kafka-cluster>
            <id>cluster01</id>
            <bootstrap-servers>your-kafka-servers:9092</bootstrap-servers>
        </kafka-cluster>
    </kafka-clusters>
    <mqtt-to-kafka-mappings>
        <mqtt-to-kafka-mapping>
            <id>mapping01</id>
            <cluster-id>cluster01</cluster-id>
            <mqtt-topic-filters>
                <mqtt-topic-filter>data/#</mqtt-topic-filter>
            </mqtt-topic-filters>
            <kafka-topic>your-kafka-topic</kafka-topic>
        </mqtt-to-kafka-mapping>
    </mqtt-to-kafka-mappings>
</kafka-configuration>

  2. Deploy the config.xml file as a Kubernetes ConfigMap:

    kubectl create configmap kafka-configuration -n <namespace> --from-file=config.xml

  3. Add the following section to your HiveMQ Platform platform-values.yaml configuration file:

    extensions:
  - name: hivemq-kafka-extension
    extensionUri: preinstalled
    enabled: true
    supportsHotReload: true
    configMapName: "kafka-configuration"

  4. Install the HiveMQ Platform:

    helm upgrade -i <your-hivemq-platform> hivemq/hivemq-platform -f platform-values.yaml

  5. The HiveMQ platform is deployed into your Kubernetes environment and the Kafka Extension starts with the specified configuration..

Install a custom JDBC driver for the HiveMQ Enterprise Security Extension

Since HiveMQ 4.26, the HiveMQ Enterprise Security Extension ships with default JDBC drivers.
For specific use-cases, it is possible override the default drivers and install a custom JDBC driver.

This example shows how to use a Kubernetes InitContainer to download a specific driver and install the driver with the Enterprise Security Extension. For additional information, see the HiveMQ Enterprise Security Extension documentation.

Configuration

  1. Add the following sections to your HiveMQ Platform platform-values.yaml configuration:

    additionalVolumes:
  - type: emptyDir
    mountName: jdbc-driver-volume
    path: /opt/hivemq/extensions/hivemq-enterprise-security-extension/drivers/jdbc

additionalInitContainers:
  - name: download-mysql-driver
    image: busybox:latest
    command: [ 'sh', '-c', 'wget -P /jdbc-driver https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.30/mysql-connector-java-8.0.30.jar' ]
    volumeMounts:
      - name: jdbc-driver-volume
        mountPath: /jdbc-driver
    Make sure you download the appropriate driver version. For more information, see the HiveMQ Enterprise Security Extension documentation list of supported drivers.

  2. Install the HiveMQ Platform with the HiveMQ Platform Helm Chart:

    helm upgrade -i <your-hivemq-platform> hivemq/hivemq-platform -f platform-values.yaml

  3. The specified driver is now available.

Install the HiveMQ Enterprise Extension for Google Cloud Pub/Sub

The following example shows how to deploy a Kubernetes ConfigMap that contains the configuration for the HiveMQ Enterprise Extension for Google Cloud Pub/Sub. The example also shows you how to configure the way the extension is loaded.
For additional information, see the HiveMQ Enterprise Extension for Google Cloud Pub/Sub documentation.

Requirements

Configuration

  1. Define the HiveMQ Enterprise Extension for Google Pub/Sub configuration as a config.xml file:

    <?xml version="1.0" encoding="UTF-8" ?>
<hivemq-google-cloud-pubsub-extension xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="config.xsd">
    <pubsub-connections>
        <pubsub-connection>
            <id>connection01</id>
            <google-cloud-project-id>your-gcp-project</google-cloud-project-id>
            <authentication>
                <service-account>
                    <file-path>/opt/hivemq/extensions/hivemq-google-cloud-pubsub-extension/google/pubsub-credentials.json</file-path>
                </service-account>
            </authentication>
        </pubsub-connection>
    </pubsub-connections>

    <mqtt-to-pubsub-mappings>
        <mqtt-to-pubsub-mapping>
            <id>mapping-01</id>
            <pubsub-connection>connection01</pubsub-connection>
            <mqtt-topic-filters>
                <mqtt-topic-filter>#</mqtt-topic-filter>
            </mqtt-topic-filters>
            <pubsub-topics>
                <pubsub-topic>
                    <name>your-pubsub-topic</name>
                </pubsub-topic>
            </pubsub-topics>
        </mqtt-to-pubsub-mapping>
    </mqtt-to-pubsub-mappings>

</hivemq-google-cloud-pubsub-extension>
    Check the HiveMQ Enterprise Extension for Google Cloud Pub/Sub documentation for details on available configuration options.

  2. Deploy the configuration as a Kubernetes ConfigMap:

    kubectl create configmap pubsub-configuration -n <namespace> --from-file=config.xml

  3. Add the following section to your HiveMQ Platform platform-values.yaml configuration file:

    extensions:
   - name: hivemq-google-cloud-pubsub-extension
     extensionUri: preinstalled
     enabled: true
     supportsHotReload: true
     configMapName: "pubsub-configuration"

  4. Create a Kubernetes secret that contains the Google Cloud Pub/Sub credentials as a file:

    kubectl create secret generic pubsub-credentials --from-file=pubsub-credentials.json

  5. Add the following section to your HiveMQ Platform platform-values.yaml configuration:

    additionalVolumes:
  - type: secret
    name: pubsub-credentials
    mountName: credentials-volume
    path: /opt/hivemq/extensions/hivemq-google-cloud-pubsub-extension/google

  6. Install the HiveMQ Platform with the HiveMQ Platform Helm Chart:

    helm upgrade -i <your-hivemq-platform> hivemq/hivemq-platform -f platform-values.yaml

  7. The HiveMQ Platform is deployed to your Kubernetes environment and the HiveMQ Enterprise Extension for Google Cloud Pub/Sub is loaded with the specified configuration.

Install the HiveMQ MQTT Message Log Extension

This example shows you how to deploy the HiveMQ MQTT Message Log Extension. This extension logs MQTT messages from connected clients and is a popular choice for debugging and development purposes.

The MQTT Message Log Extension uses an mqttMessageLog.properties configuration file in the <extension-home> directory.

The following example shows you how to use an additionalVolume to configure an extension that uses the <extensions-home> directory as the configuration file location.
For more information on HiveMQ extension configuration with ConfigMaps, see HiveMQ Extension Configuration Options.

Because the MQTT Message Log extension can produce a large volume of log statements, it is not recommended for use in production installations.

MQTT Message Log Extension configuration

  1. Define the extension configuration in the mqttMessageLog.properties file:

    # Example properties file that logs MQTT events
# By default all events are logged.

#verbose=true

publish-received=false
publish-send=false
#client-connect=false
#connack-send=false
#client-disconnect=false
#subscribe-received=false
#suback-send=false
#unsubscribe-received=false
#unsuback-send=false
#ping-request-received=false
#ping-response-send=false
#puback-received=false
#puback-send=false
#pubrec-received=false
#pubrec-send=false
#pubrel-received=false
#pubrel-send=false
#pubcomp-received=false
#pubcomp-send=false

  2. Deploy the mqttMessageLog.properties file as a Kubernetes ConfigMap:

    kubectl create configmap message-log-configuration -n <namespace> --from-file=mqttMessageLog.properties

  3. Add the following sections to your HiveMQ Platform platform-values.yaml configuration file:

    extensions:
  - name: hivemq-mqtt-message-log-extension
    enabled: true
    supportsHotReload: false
    extensionUri: "https://github.com/hivemq/hivemq-mqtt-message-log-extension/releases/download/1.1.4/hivemq-mqtt-message-log-extension-1.1.4.zip"
    additionalVolumes:
  - type: configMap
    name: message-log-conf
    mountName: log-config-mount-name
    path: /opt/hivemq/extensions/hivemq-mqtt-message-log-extension
    subPath: "mqttMessageLog.properties"

  4. The HiveMQ platform is deployed into your Kubernetes environment and the MQTT Message Log Extension starts with the specified configuration.

When configuration files are mounted with the subPath configuration option, they cannot be modified without restarting the pod. This means that all changes require a rolling restart of your cluster.

Install the HiveMQ File RBAC Extension

This example shows you how to deploy the HiveMQ File RBAC Extension. The File RBAC Extension implements access control based on a configuration file.

You can use the following procedure as a guide for installing other HiveMQ extensions that have multiple configuration files with one Kubernetes ConfigMap.

The HiveMQ File RBAC Extension uses the standard HIVEMQ_HOME/extensions/extension-home/conf/ directory for configuration files.

File RBAC Extension Configuration

  1. Define the extension configuration in the config.xml file:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<extension-configuration>
    <credentials-reload-interval>60</credentials-reload-interval>
    <password-type>HASHED</password-type>
</extension-configuration>

  2. Define the RBAC permissions in the credentials.xml file:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<file-rbac>
    <users>
        <user>
            <name>user1</name>
            <!--- password hash for "pass1" -->
            <password>WFNQUVB0UkxjM04xa0hSR1BQNGhuOTJKVzdlbXA4bjk=:100:FY12nwpUEbBK9EKQ/Aw/rQKSoA7jXsC0HKELwU2mLCVU39bJVK0zf4NemuFeDOHPO4BW1nOjxi6NporkC6rUog==</password>
            <roles>
                <id>role1</id>
            </roles>
        </user>
        <user>
            <name>admin-user</name>
            <!-- password hash for "admin-password" -->
            <password>Vjc1a0lxQ3Nvb0ljNFVHNE9WRnM3RG1IZmdNUFcwVGY=:100:PL2FLqfpdhONG7qXjAMmdVn4wlMiXnypdXiFW09zqorFhKgoiixFQw2EVJJfE9Zn79q45V7Xpc6JeKLp0ntmYA==</password>
            <roles>
                <id>role1</id>
                <id>superuser</id>
            </roles>
        </user>
    </users>
    <roles>
        <role>
            <id>role1</id>
            <permissions>
                <permission>
                    <!-- PUBLISH and SUBSCRIBE to all topics below "data/<clientid>/" -->
                    <topic>data/${{clientid}}/#</topic>
                </permission>
                <permission>
                    <!-- PUBLISH to topic "outgoing/<clientid>", retained only-->
                    <topic>outgoing/${{clientid}}</topic>
                    <activity>PUBLISH</activity>
                    <retain>RETAINED</retain>
                </permission>
                <permission>
                    <!-- SUBSCRIBE to topic "incoming/<username>"-->
                    <topic>incoming/${{username}}/actions</topic>
                    <activity>SUBSCRIBE</activity>
                </permission>
            </permissions>
        </role>
        <role>
            <id>superuser</id>
            <permissions>
                <permission>
                    <!-- Allow everything -->
                    <topic>#</topic>
                </permission>
            </permissions>
        </role>
    </roles>
</file-rbac>

  3. Deploy the config.xml file and the credentials.xml file as a Kubernetes ConfigMap:

    kubectl create configmap rbac-configuration -n <namespace> --from-file=config.xml --from-file=credentials.xml

  4. Add the following section to your HiveMQ Platform platform-values.yaml configuration file:

    extensions:
  - name: hivemq-file-rbac-extension
    enabled: true
    supportsHotReload: false
    configMapName: "rbac-configuration"
    extensionUri: "https://github.com/hivemq/hivemq-file-rbac-extension/releases/download/4.6.1/hivemq-file-rbac-extension-4.6.1.zip"

  5. For testing purposes, the HiveMQ Platform ships with the HiveMQ Allow All Extension enabled by default. To disable the allow-all extension, add the following configuration to your platform-values.yaml configuration file:

    - name: hivemq-allow-all-extension
  enabled: false

  6. The HiveMQ platform is deployed into your Kubernetes environment and the File RBAC Extension starts with the specified configuration.

Configure a Short-Lived ServiceAccount Token

This example shows you how to deploy a HiveMQ Platform that uses a projected volume to mount a short-lived service account token. The example also shows you how to configure the token’s audience and expiration time for secure access to the Kubernetes API server from within the HiveMQ Platform Pod.

For more information, see Additional Volume Options and Kubernetes Projected Volumes.

Kubernetes Configuration

  1. Create a Service Account for the HiveMQ Platform:

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: metrics-reader
  namespace: default

  2. Create RBAC permissions for the Service Account:

    apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: metrics-reader-role
  namespace: default
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: metrics-reader-binding
  namespace: default
subjects:
  - kind: ServiceAccount
    name: metrics-reader
    namespace: default
roleRef:
  kind: Role
  name: metrics-reader-role
  apiGroup: rbac.authorization.k8s.io

Helm Configuration

  1. Add the following section to your HiveMQ Platform platform-values.yaml configuration file:

    nodes:
  serviceAccountName: metrics-reader
additionalVolumes:
  - type: projected
    mountName: k8s-api-token
    path: /var/run/secrets/tokens
    projectedSources:
      - serviceAccountToken:
          path: token
          expirationSeconds: 3600
          audience: api

Configure the HiveMQ Platform Operator RBAC Permissions

This example shows how to install the HiveMQ Platform Operator with only namespace-scoped RBAC permissions when using HiveMQ Platform Operator 2.0.0 or newer. By default, the operator is granted cluster-wide permissions through ClusterRole and ClusterRoleBinding resources. To restrict the operator’s permissions to specific namespaces, you can configure it to use namespace-scoped Role and RoleBinding resources instead.

Helm Configuration

Specify the namespaces that the operator should watch. By default, the operator monitors all namespaces, which requires broad cluster-wide RBAC permissions. To limit permissions, provide a comma-separated list of namespaces in your Helm values.

The operator also requires cluster-wide permissions to validate the RBAC permissions of the HiveMQ Platform pod ServiceAccount. To further reduce the operator’s required permissions, disable this RBAC validation feature.

If you disable RBAC validation, you are responsible for ensuring that your custom ServiceAccount has all necessary permissions.

Additionally, cluster-wide permissions are needed to manage the CustomResourceDefinition (CRD). Helm installs a CRD only if it is missing and does not update it. If you disable CRD management, you must manually update the CRD before upgrading the operator to a new version.

  1. Add the following section to your HiveMQ Platform Operator platform-operator-values.yaml file:

    namespaces: "platform-namespace-1,platform-namespace-2,platform-namespace-3"
hivemqPlatformServiceAccount:
  permissions:
    validate: false
crd:
  apply: false
  waitReady: false
It is highly recommended to keep CRD management enabled. This feature ensures that the CRD version always matches the requirements of the newest operator installed in the cluster. If you disable this feature, you must manually update the CRD to the correct, latest version whenever you upgrade or install a new operator.

Trigger a Rolling Restart of the HiveMQ Platform

This example shows how to manually trigger a rolling restart of a HiveMQ Platform deployment when using HiveMQ Platform Operator 2.0.0 or newer.

Helm Configuration

To initiate a rolling restart, add or update any annotation on the HiveMQ Platform pods. You can use any key and value, but it is helpful to use annotations to document who triggered the restart and the reason for it.

Example values-trigger-rolling-restart.yaml to trigger a rolling restart
nodes:
  # Annotations to add to the HiveMQ Pods
  annotations:
    com.example/rolling-restart-trigger-date: "YYYY-MM-DD HH:MM:SS"
    com.example/rolling-restart-trigger-by: "user@example.com"
    com.example/rolling-restart-trigger-reason: "Routine maintenance"