HiveMQ Platform 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