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

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:

Select or create a Google Cloud project
  • From the dashboard of your Google Cloud project, go to the Pub/Sub service:

Search 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:

Create a Google Cloud Pub/Sub topic
  • 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 Google Cloud Pub/Sub topic page
  • Open the EDIT option and verify that the Delivery type for the Google Cloud Pub/Sub topic subscription is Pull and review other settings:

Verify topic subscription delivery
  • 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

  1. 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.

  2. Edit the config.xml file to match your use case.

  3. For more information, see Configure your HiveMQ extension.

  4. 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).

  5. 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 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.