Deployment Options

The HiveMQ Platform Operator is a lightweight application that extends the capabilities of Kubernetes to handle the operational aspects of managing HiveMQ platforms. By default, the operator is installed as a DeploymentSet with one Kubernetes pod. The operator itself is stateless and can be restarted if necessary.

The Custom Resource Definition (CRD) for the HiveMQ Platform is installed along with the operator and extends the Kubernetes API with HiveMQ-specific features.

The operator can be installed using our preconfigured HiveMQ Helm charts. This prepares your Kubernetes cluster with all the necessary resources to install and manage one or more HiveMQ platforms.

Deploy the HiveMQ Platform Operator with Helm

The HiveMQ Platform Operator Helm chart bundles the installation of the Kubernetes DeploymentSet for the operator pod, the RBAC permissions for the operator to access the Kubernetes API, the HiveMQ Custom Resource Definition (CRD) for HiveMQ Platform, and the necessary service objects to access monitoring endpoints.

Check the Preparation section of our quick start guide for information on how to set up Helm and kubectl on your local machine.
Also, make sure that your Kubernetes cluster ready and accessible.

To deploy the HiveMQ Platform Operator with default values into a dedicated Kubernetes namespace, enter:

helm upgrade --install <your-hivemq-operator> hivemq/hivemq-platform-operator -n <namespace>

This Helm command installs all the resources the HiveMQ Platform Operator needs into your Kubernetes cluster.

Helm offers additional command line options to support the installation:

  • --wait: Reports back only after the resources you create are ready for use.

  • --atomic: Attempts to create all resources successfully or in case of failure removes all resources.

  • -n <namespace>: Installs the operator into the specified namespace.

  • --create-namespace: Creates the namespace if the namespace does not exist.

For detailed configuration options of the HiveMQ Platform Operator Helm, see HiveMQ Platform Operator Configuration with Helm.

To verify that your HiveMQ Platform Operator installed successfully, enter the following command to view the status of the Helm release:

helm status <your-hivemq-operator>

To verify that the HiveMQ Platform Operator custom resource definition was created, enter:

kubectl get crds hivemq-platforms.hivemq.com

To view your HiveMQ Platform Operator deployment and pod details, enter:

kubectl describe pod <your-operator-pod-name>
kubectl describe deploy <your-operator-deployment-name>

To view the Kubernetes events for your HiveMQ Platform Operator, enter:

kubectl get events --sort-by='.metadata.creationTimestamp'

To view the log files of your HiveMQ Platform Operator, enter:

kubectl logs deployment/hivemq-platform-operator-<your-hivemq-operator>

To review the available operator metrics:

kubectl port-forward svc/hivemq-platform-operator-<release-name> 8080

Now enter http://localhost:8080/q/metrics into your browser and review the metrics.

Deploy the HiveMQ Platform with Helm

The HiveMQ platform Helm chart bundles the installation of your HiveMQ Platform custom resource and the configMap with your HiveMQ configuration. The HiveMQ Platform Operator watches for new incoming HiveMQ Platform custom resources and automatically initiates the installation of your HiveMQ platform based on the custom resource.

Check the Preparation section of our quick start guide for information on how to set up Helm and kubectl on your local machine.
Also, make sure that your Kubernetes cluster ready and accessible.

To deploy your HiveMQ Platform with default values into a dedicated Kubernetes namespace, enter:

helm upgrade --install <your-hivemq-platform> hivemq/hivemq-platform -n <namespace>

This command installs a two-node HiveMQ platform cluster with sensible default settings for local installation and testing purposes. For production installations, see our minimum requirements.

To install a system with the minimum amount of CPU and memory required for production use, enter the following command:

helm install <your-hivemq-platform> hivemq/hivemq-platform -n <namespace> --set-string nodes.resources.cpu=4 --set-string nodes.resources.memory=8G
In a production deployment, the HiveMQ platform process requires a minimum of 4G of memory. Additionally, the HiveMQ process should not consume more than 50% of the available memory. As a result, the minimum memory configuration for the container resources is 8G.
For more information on how to configure the HiveMQ platform for your use case, see the HiveMQ User Guide.

For detailed configuration options of the HiveMQ platform Helm charts see, Configuration Options.

To verify that your HiveMQ Platform Operator installed successfully, enter:

helm status <your-hivemq-platform>

To view your HiveMQ Platform StatefulSet and pod details, enter:

kubectl describe pod <your-platform-pod-name>
kubectl describe deploy <your-platform-statefulset-name>

To view the Kubernetes events for your HiveMQ platform, enter:

kubectl get events --sort-by='.metadata.creationTimestamp'

To view the logs for your HiveMQ platform node, enter:

kubectl logs <your-hivemq-pod-name>

To view the current status of your HiveMQ platform, enter:

 kubectl get hmqp <release-name>
Example status display:
NAME     MESSAGE                    STATE     STATEPHASE
<name>   HiveMQ Platform is ready   RUNNING   READY

To review the available operator metrics:

kubectl port-forward svc/hivemq-<release-name>-metrics-9399 9399

Now enter http://localhost:9399/ into your browser and review the metrics.

Test Your HiveMQ Platform

Once the deployment finishes, your HiveMQ platform is available to serve MQTT connections for clients. The following procedure shows you how to test the functionality of your HiveMQ platform with a simple local setup and does not require a load balancer.

We use the open source MQTT CLI for ease of use and to simplify the explanation of this sample procedure. However, feel free to use whichever MQTT client you prefer.
For more information, see MQTT CLI.

Connect an MQTT Client

  • Create a kubectl port-forward to access your MQTT port:

    kubectl port-forward svc/hivemq-<release-name>-mqtt-1883 1883

  • Start the MQTT CLI command line tool and connect to your local cluster:

    mqtt sh
con -h <your-cluster-url>

    Now you are ready to publish MQTT messages and subscribe to topics.

Check Your HiveMQ Control Center

Access the HiveMQ Control Center and check your Clients overview to verify that your test client is connected.

  • Create an additional port-forward for the Control Center:

    kubectl port-forward svc/hivemq-<release-name>-cc-8080 8080

  • Navigate with your browser to http://localhost:8080, and log into your HiveMQ Control Center.
    Use the default credentials: user: admin, password: hivemq.

    For more information about the HiveMQ Control Center, see HiveMQ Control Center.