HiveMQ Platform Operator for Kubernetes

The HiveMQ Platform Operator for Kubernetes is a tool for managing your HiveMQ deployments in a Kubernetes environment. The operator allows you to install, scale, configure, and monitor your HiveMQ Platform deployments in a versatile, adaptable manner.

The operator installs the HiveMQ Platform based on your configuration. When you make changes to the configuration, the operator automatically reconciles the changes with your running HiveMQ nodes, minimising downtime and need for manual intervention. This automates many aspects of platform management for DevOps engineers and makes operational tasks such as platform upgrades, new component installation, or configuration updates far simpler.

The operator also provides logs, metrics, and Kubernetes events to help you monitor your HiveMQ deployments and make it easy to integrate into your own observability stack.

A single HiveMQ Platform Operator can manage one or more HiveMQ deployments in your Kubernetes cluster. This makes it possible to manage HiveMQ deployments for multiple, differing environments, such as staging and production, or environments with separate production use cases.

Starting in April 2024, HiveMQ 4.28 becomes the Long Term Support (LTS) version of the HiveMQ Platform.
The HiveMQ Platform Operator for Kubernetes is the supported operator for HiveMQ 4.28 and future releases.

HiveMQ Platform Operator Features

Deploy, operate, and maintain your HiveMQ deployments
Manage multiple HiveMQ deployments
Install and configure HiveMQ Enterprise Extensions and custom extensions
Easy, automatic, zero downtime upgrades
Painless deployment scalability
Support for all major hosted Kubernetes providers and on-premise installations
Full observability with metrics, events, and logging

Requirements of HiveMQ Platform Operator for Kubernetes

Running Kubernetes cluster version 1.24.x or higher
Helm version 3.10.x or higher
The Kubernetes command line tool kubectl
HiveMQ Professional or Enterprise Edition, versions 4.28 or higher

HiveMQ Platform Operator for Kubernetes Quick Start Guide

This quick start guide uses the Helm package manager for Kubernetes to bootstrap the deployment and management of your HiveMQ Platform.

Two Helm charts supply the resources necessary to deploy and manage the HiveMQ Platform:

The HiveMQ Platform Operator Helm chart prepares your Kubernetes cluster by installing the HiveMQ Platform custom resource definition (CRD) and the operator.
The HiveMQ Platform Helm chart installs a HiveMQ Platform.

Use the HiveMQ Platform Operator Helm chart first to prepare your Kubernetes cluster for HiveMQ deployments.
Once the operator is installed, use the HiveMQ Platform Helm chart one or more times to deploy as many HiveMQ platforms as you need.
The operator automatically detects each HiveMQ platform deployment requests and installs each new HiveMQ platform as requested.

Preparation

Before you continue, take a moment to check that you have the following tools and resources on hand:

Verify that you have access to a running Kubernetes cluster version 1.24.0 or higher on any environment or cloud provider
Install Helm version 3.10.x or higher
Install kubectl
Install the MQTT CLI command line tool (optional)

Add the HiveMQ Helm repository to your local Helm setup:

helm repo add hivemq https://hivemq.github.io/helm-charts && \
helm repo update

HiveMQ Platform Operator Installation

To use Helm to install the HiveMQ Platform Operator and a two-node HiveMQ platform into the currently selected Kubernetes namespace on your Kubernetes cluster, usually named default, enter the following commands:

Many Kubernetes distributions provide a default namespace out of the box that serves as the initial landing place for resources when no specific namespace is specified during their creation. The default namespace simplifies the process of getting started.
For HiveMQ production deployments, the best practice is to create separate namespaces for the HiveMQ Platform Operator and each HiveMQ Platform cluster. For more information, see Install HiveMQ Platform Operator with Helm.

The name you assign to the operator release can help you easily identify its purpose within your Kubernetes cluster. Consistent and descriptive names are beneficial for maintaining order and organization in Kubernetes environments with many Helm releases.

# Replace <your-operator> with the desired name for your HiveMQ platform operator Helm release
# Replace <your-platform> with the desired name for your HiveMQ platform Helm release

# Install HiveMQ platform operator
helm install <your-operator> hivemq/hivemq-platform-operator --wait && \
# Install HiveMQ platform
helm install <your-platform> hivemq/hivemq-platform --wait

These commands install your new HiveMQ Platform Operator and then a two-node HiveMQ platform in your namespace.

To facilitate local installation and testing, the HiveMQ platform is installed with minimal resources by default. For production use, you must adjust your settings to fulfill our minimum requirements. For example, in a production deployment the HiveMQ platform process requires a minimum of 4 CPUs and 4Gs of memory.
For more details on production installation, see HiveMQ Platform Configuration Options with Helm.

To verify that your HiveMQ Platform Operator and your HiveMQ platform are successfully installed, enter the following commands:
To check HiveMQ Platform Operator:
```
# Replace <your-operator> with the name you assigned to the HiveMQ Platform Operator Helm release
helm status <your-operator>
```
To check HiveMQ platform:
```
# Replace <your-platform> with the name you assigned to the HiveMQ platform Helm release
helm status <your-platform>
```
Once you deploy your first default HiveMQ platform with Helm, you are ready to adapt and configure your installation.

To clean up your Kubernetes environment and remove the resources you created in this quick start guide, use the following Helm commands:

# Replace <your-platform> with the name you assigned to the HiveMQ platform Helm release
# Replace <your-operator> with the name you assigned to the HiveMQ Platform Operator Helm release

# First, delete the Helm release for your HiveMQ platform and wait for it to be deleted
helm delete <your-platform> --wait
# Next, delete the Helm release for your HiveMQ Platform Operator and wait for it to be deleted
helm delete <your-operator> --wait

Next Steps

For in-depth installation and configuration options with Helm, see:

For examples and instructions on how to install in specific Kubernetes environments, see: