Quick Start Guide for the HiveMQ Enterprise Extension for Google Cloud Pub/Sub

The HiveMQ Enterprise Extension for Google Cloud Pub/Sub allows you to seamlessly integrate your HiveMQ MQTT broker with Google Cloud through the Google Cloud Pub/Sub service.

Get Started

Follow this easy quick start guide to learn how to set up the HiveMQ Enterprise Extension for Google Cloud Pub/Sub with your Google Cloud account.

Requirements

An active Google Cloud account.
Running HiveMQ Professional or Enterprise Edition installation, version 4.9.x or higher.
For production use, a valid HiveMQ Enterprise Extension for Google Cloud Pub/Sub license, 4.9.x or higher.

If you do not provide a valid license, HiveMQ automatically uses a free trial license.
Trial licenses for HiveMQ Enterprise Extensions are valid for 5 hours. For more license information or to request an extended evaluation license, contact HiveMQ sales.

Set up your Google Cloud Project

Connect to your Google Cloud account, and select or create a Google Cloud project:

From the dashboard of your Google Cloud project, go to the Pub/Sub service:

Create a Google Cloud Pub/Sub topic and verify that the Add a default subscription option is selected to automatically add a topic subscription:

Select the newly-created Google Cloud Pub/Sub topic to open a page where you can add topic subscriptions, view subscription information, and access editing options:

Open the EDIT option and verify that the Delivery type for the Google Cloud Pub/Sub topic subscription is Pull and review other settings:

Open Service Accounts in the IAM & Admin menu of your Google Cloud account. Form the service account options menu for the Google Cloud service account that has permission to access Pub/Sub, select Manage keys and click Add key to create a new key:

Set up service account for Google Cloud Pub/Sub

Download the private key for the Google Cloud service account in JSON file format:

Download Google Cloud service account key

Install the HiveMQ extension

Copy and rename the HIVEMQ_HOME/extensions/hivemq-google-cloud-pubsub-extension/conf/examples/config.xml example to HIVEMQ_HOME/extensions/hivemq-google-cloud-pubsub-extension/conf/config.xml.
Edit the config.xml file to match your use case.
For more information, see Configure your HiveMQ extension.
To enable the extension, go to the HIVEMQ_HOME/extensions/hivemq-gcp-pubsub-extension directory of your HiveMQ installation and remove the DISABLED file (if present).
Start your HiveMQ instance (if not already running).

Configure your HiveMQ extension

Configuration of the HiveMQ Enterprise Extension for Google Cloud Pub/Sub consists of the following elements:

Google Cloud Pub/Sub connections <pubsub-connections>
MQTT to Google Cloud Pub/Sub mappings <mqtt-to-pubsub-mappings>
Google Cloud Pub/Sub to MQTT mappings <pubsub-to-mqtt-mappings>
MQTT to Google Cloud Pub/Sub transformer <mqtt-to-pubsub-transformer>
Google Cloud Pub/Sub to MQTT transformer <pubsub-to-mqtt-transformer>

Google Cloud connection for Pub/Sub configuration

Edit the conf/config.xml file of the HiveMQ extension to add a Google Cloud Pub/Sub connection definition:

Example Google Cloud Pub/Sub connection configuration

<pubsub-connections>
    <pubsub-connection>
        <id>your-custom-connection-id</id>
        <google-cloud-project-id>your-google-cloud-project-id</google-cloud-project-id>
        <authentication>
            <service-account>
                <file-path>/absolute/or/relative/path/to/service-account.json</file-path>
            </service-account>
        </authentication>
    </pubsub-connection>
</pubsub-connections>

MQTT to Google Cloud Pub/Sub mapping configuration

Edit the conf/config.xml file of the HiveMQ extension to add a mapping from MQTT to Google Cloud Pub/Sub:

Example MQTT to Google Cloud Pub/Sub mapping configuration

<mqtt-to-pubsub-mappings>
    <mqtt-to-pubsub-mapping>
        <id>mapping-01</id>
        <pubsub-connection>your-custom-connection-id</pubsub-connection>
        <mqtt-topic-filters>
            <mqtt-topic-filter>topic/a</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>

Google Cloud Pub/Sub to MQTT mapping

Edit the conf/config.xml file of the HiveMQ extension to add a mapping from Google Cloud Pub/Sub to MQTT:

Example Google Cloud Pub/Sub to MQTT mapping configuration

<pubsub-to-mqtt-mappings>
    <pubsub-to-mqtt-mapping>
        <id>mapping-02</id>
        <pubsub-connection>connection01</pubsub-connection>
        <mqtt-topics>
            <mqtt-topic>topic/b</mqtt-topic>
        </mqtt-topics>
        <pubsub-subscriptions>
            <pubsub-subscription>
                <name>my-pubsub-topic-subscription</name>
            </pubsub-subscription>
        </pubsub-subscriptions>
    </pubsub-to-mqtt-mapping>
</pubsub-to-mqtt-mappings>

MQTT to Google Cloud Pub/Sub transformer

Edit the conf/config.xml file of the HiveMQ extension to add a custom MQTT to Google Cloud Pub/Sub transformer:

Example MQTT to Google Cloud Pub/Sub transformer configuration

<mqtt-to-pubsub-transformer>
    <id>my-mqtt-to-pubsub-transformer-01</id>
    <pubsub-connection>your-custom-connection-id</pubsub-connection>
    <mqtt-topic-filters>
        <mqtt-topic-filter>mqtt/topic/a</mqtt-topic-filter>
    </mqtt-topic-filters>
    <transformer>my.pubsub.to.mqtt.MyCustomTransformer</transformer>
    <custom-settings>
        <custom-setting>
            <name>destination</name>
            <value>destination/pubsub/topic/a</value>
        </custom-setting>
        <custom-setting>
            <name>destination</name>
            <value>destination/pubsub/topic/b</value>
        </custom-setting>
        <custom-setting>
            <name>filepath</name>
            <value>path-to-file</value>
        </custom-setting>
    </custom-settings>
</mqtt-to-pubsub-transformer>

Google Cloud Pub/Sub to MQTT transformer

Edit the conf/config.xml file of the HiveMQ extension to add a custom Google Cloud Pub/Sub to MQTT transformer:

Example Google Cloud Pub/Sub to MQTT transformer configuration

<pubsub-to-mqtt-transformer>
    <id>my-pubsub-to-mqtt-transformer-01</id>
    <pubsub-connection>your-custom-connection-id</pubsub-connection>
    <pubsub-subscriptions>
        <pubsub-subscription>
            <name>sub-for-a</name> <!-- REQUIRED -->
        </pubsub-subscription>
    </pubsub-subscriptions>
    <transformer>my.pubsub.to.mqtt.MyCustomTransformer</transformer>
</pubsub-to-mqtt-transformer>

For detailed information and configuration options, see HiveMQ Enterprise Extension for Google Cloud Pub/Sub documentation.