DNS Discovery Plugin

Version: 1.0.0
License: Apache v2

The HiveMQ DNS Discovery Plugin utilizes DNS discovery as the discovery mechanism for HiveMQ cluster nodes.
To do so, a correctly configured DNS service with Round Robin A records is necessary.

Round-robin DNS is a technique that is typically used to provide load distribution, load balancing and fault-tolerance for Services based on the Internet Protocol, such as Webservers or FTP servers. When using Round-robin DNS a DNS response contains a list of servers providing the same service instead of responding with a singe IP address for a single server.

This plugin accomplishes HiveMQ cluster discovery by reading the IP addresses of other HiveMQ nodes from the A records of the Round-robin DNS response.

While a DNS-SD service can be installed on any environment, the plugin is best suited for the use with cloud providers like AWS or container orchestration like Kubernetes.

How it works

Following is an overview of how this type of discovery works in a deployment of HiveMQ inside of a container environment like Kubernetes, Mesos or Docker Swarm.

1. The user creates a deployment on the container environment.
2. The container environment orchestrates the creation of HiveMQ containers.
3. The container environment creates a DNS round robin record on its local DNS server, which it provides to the containers.
4. The HiveMQ containers start up and periodically request the DNS record provided to them by the container environment.
5. The HiveMQ containers attempt to form a cluster from the addresses stored in the DNS record.
6. When scaling up or down, the container environment will also update the DNS record accordingly.

An overview of a deployment utilizing DNS discovery

Installation

1. Copy the jar file plugins/dns-cluster-discovery-plugin-[version].jar to your [HIVEMQ_HOME]/plugins folder
2. Copy the conf/dnsdsicovery.properties file to your [HIVEMQ_HOME]/conf folder
3. Configure environment variables for the plugin or modify the dnsdiscovery.properties file for your needs
4. Done

Configuration

The HiveMQ DNS Discovery Plugin can be configured using environment variables or the configuration file. On startup the plugin will try reading the configuration file first. If no configuration file exists, the plugin will not attempt to reload the properties from the configuration and instead try to read from the environment variables repeatedly until broker shutdown.

Environment variable Property Key Description Default

HIVEMQ_DNS_DISCOVERY_ADDRESS

discoveryAddress

Address providing the A record for the usage as cluster node addresses

HIVEMQ_DNS_DISCOVERY_TIMEOUT

resolutionTimeout

Wait time for DNS resolution to complete in seconds.

30

For detailed information on how to configure the DNS discovery plugin see the README file included in the download or visit the GitHub page.

Example Usage

1. Build a Docker HiveMQ image that includes this plugin (See here)
2. Run multiple instances of HiveMQ inside a Kubernetes environment, using that Docker image and an appropriate deployment (example)
2. A HiveMQ cluster will form.