Connect a Broker or Edge to the Platform

A broker or edge becomes part of the platform only after you connect it to the platform. Deploying or running a 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 Connect.

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.

Before You Begin

Before you connect a broker or en edge to the platform, you must have:

A running HiveMQ broker or edge, version HiveMQ 4.53 or later.
Filesystem access to the deployment, so that you can create configuration files and restart the broker.

Step 1: Generate a Connection String

On Connect, click Get Broker or Edge.
On How do you want to get started?, select Connect what you already run.
Select HiveMQ Broker or HiveMQ Edge, then click Continue.
Enter a name and an optional description. The name is the display name shown in the broker and edge list.
Click Generate connection string. A generated string value displays.
In Connection string, copy the generated string value. In the next step, you add this value to your deployment.

As soon as you generate the connection string, the instance appears in Connect 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 a Connection String to Your Deployment

A broker connects to the platform through a configuration file that is not part of the default HiveMQ distribution. You create this configuration file within your HiveMQ deployment. The configuration file location and the way you persist the file depend on how the broker runs.

Local install

Create pulse/conf/config.xml directly under your HiveMQ home 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.

Save the file.

The resulting layout inside your HiveMQ home directory is:

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

Restart the broker.
```
./bin/run.sh
```

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

To learn more about HiveMQ clustering with Docker, see Run HiveMQ on Docker.

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 that it loads the updated configuration. On startup, the broker connects to the platform with the connection string.

Result

In Connect, the instance status changes from Ready to connect to Connected after it reaches the platform. If the instance does not connect, check the path to the configuration file, the connection string, and confirm that the broker was restarted.

For more information about each state shown in the Connect 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.