Deploy the HiveMQ Kubernetes Operator

The HiveMQ Kubernetes Operator is a lightweight application that runs on Kubernetes and communicates with the Kubernetes API server. The HiveMQ operator creates the HiveMQ cluster custom resource definition (CRD) on the Kubernetes cluster and watches for any modifications to objects in the HiveMQ cluster custom resource.

There are two ways to deploy the HiveMQ Kubernetes Operator:

  • Deploy the HiveMQ operator with Helm

  • Deploy the HiveMQ operator with manifests

We recommend the Kubernetes command-line tool, kubectl, to run commands against Kubernetes clusters.
You can use kubectl to deploy applications, inspect and manage cluster resources, and view logs.
If you have not yet downloaded and installed kubectl, see Install and Set Up kubectl.
For an overview of kubectl commands, see kubectl Cheat Sheet.

HiveMQ Helm Charts

Helm is a package manager for Kubernetes. Charts are the preconfigured packages of Kubernetes resources that Helm installs.
Helm charts make it easier to package, configure, and deploy applications and services onto your Kubernetes clusters.
A Helm chart usually has three main parts:

  • Chart.yaml : Provides meta information for the package such as descriptions and tags

  • templates/ directory: Contains the templates that Helm renders and deploys to the K8s cluster

  • values.yaml: Defines all available parameters and the default values of the parameters

The HiveMQ Helm Chart is a convenient way to deploy everything you need to run and manage HiveMQ clusters on your Kubernetes environment.

If you have not yet installed Helm, see Install Helm.

The HiveMQ Helm chart is available from the HiveMQ Helm Chart repository on GitHub.

The HiveMQ Helm Chart requires Helm version 3. For detailed information on which Kubernetes versions Helm supports, see Helm Version Support Policy.

The preconfigured HiveMQ Helm chart is the recommended way to deploy the HiveMQ Kubernetes Operator:

  • Create a HiveMQ cluster custom resource definition to extend the Kubernetes API

  • Deploy the HiveMQ operator as a custom controller for HiveMQ clusters on Kubernetes, including all necessary RBAC objects

  • Launch a full Prometheus monitoring stack with a HiveMQ Grafana dashboard (optional)

  • Create a basic HiveMQ cluster custom resource (CR) object that the HiveMQ Operator maintains in your desired state

Deploy HiveMQ Kubernetes Operator with Helm

Use the HiveMQ Helm Chart to create the HiveMQ cluster custom resource definition, install the HiveMQ operator, and create a HiveMQ cluster with the default HiveMQ settings on Kubernetes:

Add the HiveMQ Helm Chart repository to your Helm installations:

helm repo add hivemq https://hivemq.github.io/helm-charts
The commands shown deploy to the current namespace when run.

Install the HiveMQ Helm Chart:

helm upgrade --install hivemq hivemq/hivemq-operator

The result of this command is a running HiveMQ cluster on your Kubernetes cluster that is maintained and managed by the HiveMQ Kubernetes Operator.

When you deploy the HiveMQ Helm Chart, the HiveMQ operator automatically creates a HiveMQ cluster custom resource. The HiveMQ cluster custom resource is deployed with standard default settings.
You can adapt the configuration settings of your HiveMQ cluster as desired. The HiveMQ operator watches for changes to the custom resource and applies your new settings automatically.
For more information, see Revise HiveMQ Cluster Configuration with Helm.

Revise HiveMQ Cluster Configuration with Helm

To change the configuration settings of a HiveMQ cluster custom resource that you manage with Helm, simply copy and edit the appropriate fields in the hivemq section of the values.yaml.

To view the current settings of your HiveMQ cluster, enter:

helm show values hivemq/hivemq-operator

For step-by-step instructions on how to adapt your HiveMQ configuration settings with Helm, see the Adapt section of our Quick Start Guide.
In the background, Helm uses templates to update the configuration of the HiveMQ cluster resource with your new values:

helm upgrade --install -f myCustomValues.yaml hivemq hivemq/hivemq-operator
Example myCustomValues.yaml file
hivemq:
  nodeCount: "4"
  security:
      allowEmptyClientId: false

  ports:
    - name: "mqtt"
      port: 1883
      expose: true
      patch:
      - '[{"op":"add","path":"/spec/selector/hivemq.com~1node-offline","value":"false"},{"op":"add","path":"/metadata/annotations","value":{"service.spec.externalTrafficPolicy":"Local"}}]'
      # If you want Kubernetes to expose the MQTT port
      - '[{"op":"add","path":"/spec/type","value":"LoadBalancer"}]'

The HiveMQ Kubernetes Operator observes the changes and updates your HiveMQ Cluster custom resource to the new desired state.

Update Single HiveMQ Cluster Configuration Value with Helm

You can also change individual settings in the HiveMQ Cluster custom resource.
To edit a specific setting, replace key and value in the following command as desired:

helm upgrade --install hivemq hivemq/hivemq-operator --set key:values

For example, to specify maintenance of a five-node HiveMQ Cluster, enter the following command:

helm upgrade --install hivemq hivemq/hivemq-operator --set hivemq.nodeCount=5

The HiveMQ Kubernetes Operator automatically scales your HiveMQ cluster to five nodes.

To verify your new setting, review the HiveMQ cluster information:

kubectl get hivemq-clusters

The expected result is a HiveMQ cluster with five nodes.

The HiveMQ Kubernetes Operator maintains the HiveMQ Cluster custom resource in the new desired state.

Manifests

It is also possible to deploy the HiveMQ Kubernetes Operator with manually created manifest files. The manifest files specify the desired state of the object that Kubernetes maintains.

Kubernetes manifests are a simple way to create, modify, and delete Kubernetes resources such as pods, deployments, or services.

HiveMQ Operator Manifest Deployment

The HiveMQ Operator manifest files contain all the yaml files that you need to install the HiveMQ CRD and the HiveMQ Kubernetes Operator.

Deploy HiveMQ Kubernetes Operator with Manifests

To deploy the HiveMQ custom resource definition and the HiveMQ operator, use the following kubectl commands:

Manifest deployment

kubectl create namespace hivemq
kubectl apply -n hivemq -f manifests/operator/

To verify that both resources are created in the namespace of your choice, enter:

kubectl get crd && kubectl get deploy

The expected result of this command shows an available hivemq-clusters.hivemq.com custom resource definition and a hivemq-operator deployment.

To deploy a HiveMQ Cluster as a custom resource on Kubernetes, create a manifest yaml file that describes your requirements.
The operator uses the high-level description of a HiveMQ cluster that your yaml file provides to create the HiveMQ cluster.

Example configuration of a simple HiveMQ cluster custom resource
apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  hivemqVersion: 4.3.3
  nodeCount: 3
  cpu: '4000m'
  memory: '4096M'
  logLevel: INFO
  mqtt:
    maxQos: 2

To use the simple-cr.yml file to deploy a HiveMQ cluster, save it to a file and enter:

kubectl apply -f simple-cr.yml

This command instructs the HiveMQ operator to create a HiveMQ cluster as a custom resource on your Kubernetes cluster.
The HiveMQ operator maintains the status of the cluster based on the settings that are specified in the manifest yaml file.

Adapt HiveMQ Cluster Manifest

You can adapt the HiveMQ cluster manifest file as desired to fulfill your individual use case.
The custom resource can be edited directly with any editor.
For available configuration options, see Basic Configuration.

kubectl edit hivemq-clusters <my-cluster-name>

The HiveMQ Kuberbetes Operator automatically applies and maintains your changes.

Restricted user access on a Kubernetes cluster can cause the creation of the custom resource definition to fail for some users. In this case, you can ask a cluster administrator to create the CRD.

Feature Gates

To work properly, the HiveMQ operator requires several feature gates. If you run into issues when you deploy the HiveMQ operator, check for these feature gates on your cluster:

  • CustomResourcePublishOpenAPI

  • CustomResourceSubresources

  • CustomResourceValidation

  • MountPropagation