HiveMQ Platform Helm Chart Installation Examples

The following examples show how to customize the deployment of the HiveMQ Platform using the HiveMQ Platform Helm Chart:

Install the HiveMQ Enterprise Extension for Kafka
Install a custom JDBC driver for the HiveMQ Enterprise Security Extension
Install the HiveMQ Enterprise Extension for Google Cloud PubSub
Install the HiveMQ MQTT Message Log Extension
Install the HiveMQ File RBAC Extension

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

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>

Deploy the config.xml file as a Kubernetes ConfigMap:

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

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"

Install the HiveMQ Platform:

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

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

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.

Install the HiveMQ Platform with the HiveMQ Platform Helm Chart:

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

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

See the HiveMQ Operator Requirements.
The downloaded Google Cloud Pub/Sub credentials file.

Configuration

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.

Deploy the configuration as a Kubernetes ConfigMap:

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

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"

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
```

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

Install the HiveMQ Platform with the HiveMQ Platform Helm Chart:

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

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

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

Deploy the mqttMessageLog.properties file as a Kubernetes ConfigMap:

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

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"

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

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>

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>

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

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"

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
```
The HiveMQ platform is deployed into your Kubernetes environment and the File RBAC Extension starts with the specified configuration.