Connect a Broker or Edge with the Platform

A broker or edge becomes part of the platform only after it connects to the platform. A deployed or running broker is not enough on its own. To connect it, you generate a connection string in the platform, apply the string to your deployment, and restart the broker. The instance then reports to the platform and appears in the Connect tab.

Use this task for a broker you just deployed (see Deploy a Broker) or a broker you were already running before you adopted the platform.

Prerequisites

  • A running HiveMQ broker or edge on HiveMQ 4.53 or later.

  • Filesystem access to the deployment, so you can create configuration files and restart the broker.

Step 1: Generate a Connection String

  1. In the Connect tab, select Connect what you already run.

  2. Select HiveMQ Broker or HiveMQ Edge.

  3. Enter a name and an optional description. The name is the display name shown in the broker and edge list.

  4. Generate the connection string and copy it. In the next step, you paste the string into your deployment.

As soon as you generate the connection string, the instance appears in the list with a Data Intelligence state of Ready to connect. The platform knows about the instance, but the instance is not yet connected. See Broker and Edge Listing Reference.

Step 2: Add the Pulse Configuration to Your Deployment

The connection to the platform is configured through a Pulse configuration file that is not part of the default HiveMQ distribution. You create this configuration yourself inside your HiveMQ directory.

  1. In your HiveMQ home directory, create a folder named pulse.

  2. Inside the pulse folder, create a sub-folder named conf.

  3. Inside pulse/conf, create a file named config.xml. Use the following structure and paste the connection string you copied into the <connection-string> element:

    <HIVEMQ_HOME>/pulse/conf/config.xml
    <pulse>
    <enabled>true</enabled>
    <bootstrap>true</bootstrap>
    <agent>
        <connection-string>YOUR_PLATFORM_CONNECTION_STRING</connection-string>
    </agent>
</pulse>
    Do not add spaces inside the <connection-string>…​</connection-string> element value.

  4. Save the file.

The resulting layout inside your HiveMQ home directory is:

<HIVEMQ_HOME>/
└── pulse/
    └── conf/
        └── config.xml

Step 3: Apply the configuration for your deployment method

Where pulse/conf/config.xml lives and how you persist the file depend on how the broker runs.

Local install

Create pulse/conf/config.xml directly under your HiveMQ home directory as shown above, then restart the broker.

Docker

In the official HiveMQ image, the HiveMQ home directory is /opt/hivemq. Persist the pulse directory outside the container and mount it into the HiveMQ home directory so the configuration survives restarts:

docker run -p 8080:8080 -p 1883:1883 \
  -v /path/to/pulse:/opt/hivemq/pulse \
  hivemq/hivemq4:latest

Kubernetes

Provide the Pulse configuration to the HiveMQ Platform Operator. The operator manages the configuration as a Kubernetes Secret. For the pulse configuration options (inline data, an existing Secret by name, or overridePulseConfig from a file), see HiveMQ Pulse Configuration Options.

Step 4: Restart the Broker

Restart the broker so it picks up the Pulse configuration. On startup, the broker reads the config.xml file and connects to the platform with the connection string.

Result

In the Connect tab, the instance moves from Ready to connect to Connected after it reaches the platform. If the instance does not connect, check the pulse/conf/config.xml path, the connection string, and confirm that the broker was restarted.

For more information about each state in the list, see Broker and Edge Listing Reference.

Next Steps

  • Get a License: if you have a Software broker that you have not yet licensed.

  • Contextualize: Structure the data now streams through your connected broker.