Installation with Helm
The HiveMQ Platform Operator for Kubernetes is a lightweight application that extends the capabilities of Kubernetes to handle the operational aspects of managing HiveMQ Platforms.
Helm offers a streamlined and manageable approach to install applications in Kubernetes.
For ease of use, HiveMQ provides two preconfigured Helm charts, one for the HiveMQ Platform Operator and one for the HiveMQ Platform.
Our preconfigured Helm charts are a good starting point for most MQTT use cases.
HiveMQ Helm charts, examples, and manifests are publicly available in the HiveMQ Helm Charts GitHub repository. |
The first step is to use the HiveMQ Platform Operator Helm chart to install the HiveMQ Platform Operator with Helm. This step prepares your Kubernetes environment for the installation of HiveMQ Platform clusters.
Next, use the HiveMQ Platform Helm chart to deploy one or more HiveMQ Platform clusters with Helm. The HiveMQ Platform Operator installs and manages each HiveMQ Platform cluster that you deploy.
Reuse the HiveMQ Platform Helm charts to deploy as many HiveMQ clusters as needed into separate Kubernetes namespaces.
Check the Preparation section of our quick start guide for information on how to set up Helm and the Kubernetes command-line tool, kubectl , on your local machine.Also, make sure that your Kubernetes cluster is ready and accessible. |
You can use Helm to configure the HiveMQ Platform Operator and the HiveMQ Platform cluster to fulfill your individual use case. For detailed information on all available configuration options, see HiveMQ Platform Operator Configuration Options with Helm and HiveMQ Platform Configuration Options .
Install HiveMQ Platform Operator with Helm
The HiveMQ Platform Operator Helm chart installs the following items on your Kubernetes environment:
-
The custom resource definition (CRD) for the HiveMQPlatform object.
-
The DeploymentSet and pod for the HiveMQ Platform Operator.
-
The Kubernetes RBAC permissions the operator requires to manage your HiveMQ platforms.
-
To install 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, 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 deployments/<your-operator-deployment-name>
-
To access the available operator metrics, enter:
kubectl port-forward svc/hivemq-platform-operator-<release-name> 8080
-
Next, to review the operator metrics in your browser, enter
http://localhost:8080/q/metrics
.
-
Platform Operator Configuration Options with Helm
You can configure how Helm installs your HiveMQ Platform Operator.
The Helm chart’s values.yaml file defines the default values and configuration parameters that are available.
-
To adjust the default values in the
values.yaml
, export the possible configuration values to a file and edit the file to fit your needs, enter:helm show values hivemq/hivemq-platform-operator > operator-values.yaml
-
To apply the changes you make to the
operator-values.yaml
file, enter:helm upgrade --install my-hivemq-operator hivemq/hivemq-platform-operator -f operator-values.yaml -n <namespace>
This command upgrades/installs the HiveMQ Platform Operator with your custom configuration.
Resource and Image Options
Field | Description | ||
---|---|---|---|
|
Defines which container image is used for the operator.
|
||
|
Sets the CPU and memory resources for the operator. Requests and limits use the same values.
|
||
|
Specifies environment variables to be added to the operator container.
Variables can be defined as a list of
The default setting is an empty list. |
||
|
Configures the Java options for the process that starts the operator. |
||
|
Configures the pod security context for the operator. Fields in the container security context take precedence over fields in the pod security context.
|
||
|
Configures the container security context for the operator. Fields in the container security context take precedence over fields in the pod security context.
|
||
|
Sets a selector label that limits the operator to manage only HiveMQ platforms with a matching selector label. |
||
|
The HiveMQ platform CustomResourceDefinition configuration options.
|
Logging Configuration
Field | Description |
---|---|
|
Configures the log level for the HiveMQ Platform Operator. |
To view your HiveMQ Platform Operator logs, enter:
kubectl logs deployment/<your-operator-deployment-name>
Role-Based Access Control Options
To be able to manage your HiveMQ Platforms, the operator needs access permissions to Kubernetes resources on your cluster.
By default, the operator Helm chart creates a new service account and the required RBAC permissions.
It is possible to override the default permissions and use a custom service account.
Field | Description |
---|---|
|
Configures whether to create the RBAC permissions and the service account on Kubernetes.
|
|
Configures that a custom service account is used for RBAC Permissions on Kubernetes.
|
Pod Scheduling Options
Affinity and tolerations can be configured to control on which Kubernetes worker node the operator pod is placed.
Affinity can be used to optimize workload placement, ensure resource requirements are met, or achieve other scheduling-related goals.
All valid Kubernetes node and pod affinity options such as nodeAffinity, podAffinity and antiPodAffinity are supported.
Tolerations work together with taints to ensure that pods are not scheduled onto inappropriate nodes. All valid Kubernetes tolerations options are supported.
Field | Description |
---|---|
|
Configures how the operator pod is placed on your Kubernetes nodes.
|
podScheduling:
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: <node-label-key>
operator: In
values:
- <node-label-value>
The example nodeAffinity
configuration specifies that the operator pod can only be deployed on Kubernetes nodes that have the label <node-label-key>: <node-label-value>
.
If no nodes with the configured label are available, the operator is not installed and remains in a pending
state.
If node labels change during runtime, the operator remains in a running
state.
tolerations:
- key: "my-key"
operator: "Exists"
effect: "NoSchedule"
The example tolerations
configuration specifies that the operator pod can only be deployed on Kubernetes nodes that have the taint my-key
set.
kubectl taint nodes my-node my-key=a-value:NoSchedule-
If no nodes with a matching taint are available, the operator is not installed and remains in a pending
state.
HTTP Endpoint Options
The HiveMQ Platform Operator exposes an HTTP/HTTPS endpoint.
If desired, you can use the API with webhooks.
Metrics are exposed on http://<address>/q/metrics
.
To use the API with webhooks, you must configure an HTTPS port. |
Field | Description |
---|---|
|
Configures the HTTP port to be used for the API endpoint of the operator.
|
|
Configures the HTTPS port to be used for the API endpoint of the operator.
|
Operator TLS Options
Field | Description |
---|---|
|
Configures the TLS options for the operator to access a secured Kubernetes API server.
|
Install HiveMQ Platform with Helm
The HiveMQ Platform Helm chart installs the following items:
-
A HiveMQ Platform custom resource.
-
The HiveMQ
config.xml
as a Kubernetes ConfigMap.
Check the Preparation section of our quick start guide for information on how to set up Helm and kubectl on your local machine. Make sure that the HiveMQ Platform Operator is installed and running on your Kubernetes cluster. |
When you use the HiveMQ Platform Helm chart, a HiveMQ Platform custom resource is deployed. Your HiveMQ Platform Operator watches for this incoming custom resource and automatically initiates the installation of your HiveMQ Platform.
The HiveMQ Platform cluster is deployed using a Kubernetes StatefulSet and defines how many HiveMQ nodes are installed.
The services that are needed to access the MQTT ports and the HiveMQ Control Center are also installed.
-
To install 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.
In a production deployment, a HiveMQ Platform instance requires a minimum of 4G of memory and 4 CPUs.
Review our minimum requirements for production deployments. -
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=4G
For detailed information on the configuration options the HiveMQ Platform Helm Charts offers, see HiveMQ Platform Configuration Options with Helm.
For production deployments of HiveMQ on Kubernetes, we recommend exclusive allocation of one HiveMQ pod to one Kubernetes node. For more information, see Assigning Pods to Nodes. -
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 sts <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 HiveMQ platform metrics, enter:
kubectl port-forward svc/hivemq-<release-name>-metrics-9399 9399
-
To review the HiveMQ platform metrics in your browser, enter
http://localhost:9399/
.
HiveMQ Platform Configuration Options with Helm
You can customize how Helm installs your HiveMQ Platform.
The values.yaml of the HiveMQ Platform Helm chart file defines the default values and configuration parameters that are available.
The configuration details of your HiveMQ Platform cluster are defined in the config.xml
file.
The HiveMQ Platform Helm chart deploys the config.xml
file to your Kubernetes namespace as either a Kubernetes ConfigMap or Secret, based on the values specified in your chart.
You can configure many standard HiveMQ options via the Helm chart, or you can override the entire config.xml file with your own configuration.If you override the config.xml file, make sure to include all required HealthAPI and cluster configuration settings and align the listener configuration with your services.To learn more about how to configure the HiveMQ Platform to meet your individual business needs, we recommend our informative HiveMQ User Guide. |
-
To adjust the default values in the
values.yaml
, export the possible configuration values to a file and edit the file to fit your needs, enter:helm show values hivemq/hivemq-platform > platform-values.yaml
-
To apply changes that you make to the
platform-values.yaml
file, enter:helm upgrade --install my-hivemq-platform hivemq/hivemq-platform -f platform-values.yml -n <namespace>
HiveMQ Container Image Options
Field | Description |
---|---|
|
Configures the container image details for the HiveMQ Platform.
|
The HiveMQ Platform Operator is compatible with all standard HiveMQ container images published by HiveMQ starting with HiveMQ 4.19. |
pullSecretName
to pull a HiveMQ platform image:Create a Kubernetes Secret for the container registry. The following example uses GitHub Container Registry (ghcr):
kubectl create secret docker-registry ghcr \
--docker-server=ghcr.io \
--docker-username="$GITHUB_USER_NAME" \
--docker-password="$GITHUB_PAT" \
--docker-email="$GITHUB_EMAIL"
Configure your image values using the created Kubernetes Secret ghcr
in your values.yaml file:
image:
repository: ghcr.io/hivemq
name: hivemq4
tag: 4.33.0
pullPolicy: IfNotPresent
pullSecretName: "ghcr"
HiveMQ Node Options
Field | Description | ||||
---|---|---|---|---|---|
|
Configures the settings for the individual HiveMQ platform nodes.
|
HiveMQ Platform Configuration Options
The HiveMQ Platform Helm chart installs a default HiveMQ configuration as a Kubernetes ConfigMap. The default HiveMQ configuration can also be installed as a Kubernetes Secret. For your convenience, the HiveMQ Platform Helm chart supports many standard HiveMQ configuration options.
For advanced use-cases, it is easy to override the HiveMQ configuration config.xml
file and provide your custom configuration to the Helm chart.
It is also possible to override the default Kubernetes StatefulSet object and the Kubernetes Service objects.
Make sure to align configurations that you override. For example, your port definitions need to match between the Kubernetes service, HiveMQ listener configuration, and StatefulSet. |
You can change the HiveMQ configuration during runtime.
The HiveMQ Platform Operator watches for configuration changes and applies them with a rolling upgrade of the HiveMQ Platform.
The rolling upgrade requires enough resources in your Kubernetes cluster to accommodate a HiveMQ surge node
.
The temporary addition of a surge node ensures that your cluster maintains consistent compute power for your use cases.
Once the rolling upgrade is done, the HiveMQ surge node
is removed.
If the operator detects an invalid HiveMQ configuration, the rolling upgrade stops and a Kubernetes event by the operator reports the configuration error.
Once the error is fixed, the rolling upgrade resumes.
You can monitor kubectl get events for such errors.
|
The HiveMQ Platform Helm Chart provides the following configuration options:
Field | Description |
---|---|
|
These settings configure restrictions for HiveMQ. See MQTT restrictions for detailed information.
|
Field | Description |
---|---|
|
These settings configure MQTT options for HiveMQ. See MQTT options for detailed information.
|
Field | Description |
---|---|
|
Optional settings to configure HiveMQ MQTT add-ons. See HiveMQ MQTT Add-ons for detailed information.
|
Field | Description |
---|---|
|
Optional settings to configure MQTT security for HiveMQ. See MQTT Security Configuration Options for detailed information.
|
Field | Description |
---|---|
|
Optional setting to override the default username and password for the HiveMQ Control Center when the default configuration is used.
|
The following configuration options can be used to override the standard config.xml
HiveMQ configuration and the StatefulSet definitions.
In addition, a convenient option to add InitContainers
is provided.
Field | Description |
---|---|
|
Defines how the HiveMQ Platform configuration is deployed as a Kubernetes object.
|
The overrideInitContainers tag is now marked as DEPRECATED and can be removed in a future release.
Please use additionalInitContainers and additionalContainers instead.
For more information, see Init Containers and Sidecars.
|
Example to overwrite the HiveMQ configuration
The HiveMQ configuration can be set from a file via the command line. For detailed information on how to configure HiveMQ, see the HiveMQ MQTT Broker Configuration.
helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set-file config.overrideHiveMQConfig=config.xml -n <namespace>
Example to overwrite the Kubernetes StatefulSet
The StatefulSet spec configuration can be set from a file via the command line. For more information, see StatefulSetSpec:
helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set-file config.overrideStatefulSet=stateful-set-spec.yaml -n <namespace>
Example custom StatefulSetSpec configuration:
spec:
replicas: 2
template:
spec:
containers:
- name: hivemq
image: hivemq/hivemq4:4.23.0
imagePullPolicy: IfNotPresent
ports:
- containerPort: 1883
name: mqtt-1883-<release-name>
- containerPort: 8080
name: cc-8080-<release-name>
- containerPort: 9399
name: metrics-<release-name>
When you define a custom StatefulSetSpec, make sure that ports and services match between your Service configuration, StatefulSpec configuration, and HiveMQ listener configuration.
For example, the container port must match the service name section.
Port names can contain a maximum of 15 characters and cannot end with a - .
|
When using the override configuration option config.overrideStatefulSet for your custom StatefulSetSpec or config.overrideHiveMQConfig for your custom HiveMQ configuration, all other configuration options for StatefulSetSpec and HiveMQ configuration are ignored.
|
Pod Scheduling Options
Node affinity and tolerations can be configured to control on which Kubernetes worker nodes the HiveMQ platform pods are placed. Node affinity can be used to optimize workload placement, ensure resource requirements are met, or achieve other scheduling-related goals. All valid Kubernetes affinity options are supported.
Tolerations work together with taints to ensure that pods are not scheduled onto inappropriate nodes.
Field | Description |
---|---|
|
Configures how the HiveMQ platform pods are placed on your Kubernetes nodes.
|
podScheduling:
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: <node-label-key>
operator: In
values:
- <node-label-value>
The example nodeAffinity
configuration specifies that the HiveMQ Platform pods can only be deployed on Kubernetes nodes that have the label <node-label-key>: <node-label-value>
.
If no nodes are available with this label, the HiveMQ Platform pods are not installed and remain in a pending
state.
If node labels change during runtime, the HiveMQ Platform pods remain in a running
state.
tolerations:
- key: "my-key"
operator: "Exists"
effect: "NoSchedule"
The example tolerations
configuration specifies that the HiveMQ Platform pods can only be deployed on Kubernetes nodes that have the taint my-key
set.
kubectl taint nodes my-node my-key=a-value:NoSchedule-
If no nodes are available with a matching taint, the HiveMQ Platform pods are not installed and remain in a pending
state.
Operator Selector Options
The operator.selector
label defines which HiveMQ Platform Operator manages this HiveMQ Platform cluster.
See the matching selector
label of the operator configuration.
Avoid a configuration where more than one operator manages a HiveMQ Platform. |
Field | Description |
---|---|
|
Provides the selection criteria to identify which operator manages the selected HiveMQ Platform custom resource.
|
Service Options
The service configuration options define how the Kubernetes service objects are created for access to the ports of the HiveMQ nodes. Services can be configured to one or more MQTT ports, WebSocket ports, the RestAPI port, and the Control Center port. By default, the metrics service is enabled to provide access to HiveMQ metrics.
Load balancers in Kubernetes are provided as an external service. Check your Kubernetes environment and external load balance provider for configuration details. Use the annotation configuration option to add your required load balancer annotations. |
Field | Description |
---|---|
|
Defines the Kubernetes Service configuration for the HiveMQ platform.
|
The truststore and keystore Kubernetes Secrets can be reused for different listeners/services. If the keystore or truststore password changes, a rolling restart is required. |
If you use a custom cluster domain name in your Kubernetes cluster, there is no need to specify any custom DNS suffix value for the services.
The operator automatically discovers the cluster service IP as long as the /etc/resolv.conf file in the pods is not overwritten.
For more information, see or Pod’s DNS Policy.
|
Example TLS configuration
The HiveMQ Platform can be configured to support TLS and mTLS. For more information on how to configure HiveMQ with TLS, see TLS Listener configuration.
Two options are available to configure your TLS listeners; using base64 encoded passwords configured in your Helm chart values.yaml
file or using base64 encoded passwords stored in a Kubernetes Secret.
Example with base64 encoded passwords
To add the keystore and truststore files to Kubernetes with passwords in your values.yaml
configuration, enter:
kubectl create secret generic hivemq-keystore --from-file=keystore=keystore.jks --namespace="<namespace>"
kubectl create secret generic hivemq-truststore --from-file=truststore=truststore.jks --namespace="<namespace>"
To configure a secure MQTT service using the created Kubernetes Secrets, include the following snippet in your platform-values.yaml
:
services:
- type: mqtt
exposed: true
containerPort: 8883
keystoreSecretName: "hivemq-keystore"
keystorePassword: "<keystore base64 encoded password>"
keystorePrivatePassword: "<keystore base64 encoded private key>"
truststoreSecretName: "hivemq-truststore"
truststorePassword: "<truststore base64 encoded password>"
tlsClientAuthenticationMode: "REQUIRED"
keystorePrivatePassword is optional. Set only when it is different from the keystore password.
|
To configure a secure WebSocket service using the created Kubernetes Secrets, include the following snippet in your platform-values.yaml
:
services:
- type: websocket
exposed: true
containerPort: 8000
keystoreSecretName: "hivemq-keystore"
keystorePassword: "<keystore base64 encoded password>"
keystorePrivatePassword: "<keystore base64 encoded private key>"
truststoreSecretName: "hivemq-truststore"
truststorePassword: "<truststore base64 encoded password>"
tlsClientAuthenticationMode: "REQUIRED"
keystorePrivatePassword is optional. Set only when it is different from the keystore password.
|
To configure a secure Control Center service using the created Kubernetes Secrets, include the following snippet in your platform-values.yaml
:
services:
- type: control-center
exposed: true
containerPort: 8443
keystoreSecretName: "hivemq-keystore"
keystorePassword: "<keystore base64 encoded password>"
keystorePrivatePassword: "<keystore base64 encoded private key>"
keystorePrivatePassword is optional. Set only when it is different from the keystore password.
|
To install or upgrade the HiveMQ Platform Helm chart, enter:
helm upgrade --install my-hivemq-platform hivemq/hivemq-platform -f platform-values.yaml -n <namespace>
Example with base64 encode passwords stored in a Kubernetes Secret
To add the keystore and truststore files to Kubernetes Secret with passwords in your values.yaml
configuration, enter:
kubectl create secret generic hivemq-keystore --from-file=keystore=keystore.jks --namespace="<namespace>"
kubectl create secret generic hivemq-truststore --from-file=truststore=truststore.jks --namespace="<namespace>"
To add the keystore password and optionally the keystore private password to Kubernetes Secret, enter:
kubectl create secret generic hivemq-keystore-passwords \
--from-literal=my.keystore.password="<keystore password>" \
--from-literal=my.keystore.private.password="<keystore private key>" \
--namespace="<namespace>"
To configure a secure MQTT service using the created Kubernetes Secrets, include the following snippet in your platform-values.yaml
:
services:
- type: mqtt
exposed: true
containerPort: 8883
keystoreSecretName: "hivemq-keystore"
keystorePasswordSecretName: "hivemq-keystore-passwords"
keystorePasswordSecretKey: "my.keystore.password"
keystorePrivatePasswordSecretKey: "my.private.key"
truststoreSecretName: "hivemq-truststore"
truststorePassword: "<truststore base64 encoded password>"
tlsClientAuthenticationMode: "REQUIRED"
keystorePasswordSecretKey is optional. Default value is keystore.password .keystorePrivatePasswordSecretKey is optional.
|
To configure a secure WebSocket service using the created Kubernetes Secrets, include the following snippet in your platform-values.yaml
:
services:
- type: websocket
exposed: true
containerPort: 8000
keystoreSecretName: "hivemq-keystore"
keystorePasswordSecretName: "hivemq-keystore-passwords"
keystorePasswordSecretKey: "my.keystore.password"
keystorePrivatePasswordSecretKey: "my.private.key"
truststoreSecretName: "hivemq-truststore"
truststorePassword: "<truststore base64 encoded password>"
tlsClientAuthenticationMode: "REQUIRED"
keystorePasswordSecretKey is optional. Default value is keystore.password .keystorePrivatePasswordSecretKey is optional.
|
To configure a secure Control Center service using the created Kubernetes Secrets, include the following snippet in your platform-values.yaml
:
services:
- type: control-center
exposed: true
containerPort: 8443
keystoreSecretName: "hivemq-keystore"
keystorePasswordSecretName: "hivemq-keystore-passwords"
keystorePasswordSecretKey: "my.keystore.password"
keystorePrivatePasswordSecretKey: "my.private.key"
keystorePasswordSecretKey is optional. Default value is keystore.password .keystorePrivatePasswordSecretKey is optional.
|
To install or upgrade the HiveMQ Platform Helm chart, enter:
helm upgrade --install my-hivemq-platform hivemq/hivemq-platform -f platform-values.yaml -n <namespace>
Metrics Options
The metrics configuration options define how the HiveMQ Prometheus extension is configured to provide HiveMQ Platform metrics.
By default, metrics options are enabled.
Field | Description |
---|---|
|
Metrics configuration options for the HiveMQ Prometheus extension.
|
HiveMQ Platform License Options
Field | Description |
---|---|
|
Defines all HiveMQ licenses to be used for the HiveMQ Platform.
|
Using additionalLicenses allows you to use multiple HiveMQ licenses simultaneously.
This can be helpful when your existing HiveMQ license is about to expire and you need to verify that your renewed license is correct.
For more information, see Multiple HiveMQ Licenses.
|
Example to configure HiveMQ licenses from several license files
To configure a HiveMQ Platform with all possible licenses, run a Helm command similar to the following example. The example defines a HiveMQ license, an additional HiveMQ license, a HiveMQ Enterprise Extension license, and a HiveMQ Data Hub license:
helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set license.create=true --set-file license.overrideLicense=files/license.lic --set-file license.additionalLicenses=files/additional-license.lic --set-file license.dataHub.license.overrideLicense=files/license.plic --set-file license.extensions.kafka.overrideLicense=files/kafka-license.elic -n <namespace>
HiveMQ Extension Configuration Options
Extensions add functionality to the HiveMQ broker that allows the broker to integrate with external systems, such as databases, data lakes, queues, or security systems.
The HiveMQ Platform Helm Chart and HiveMQ Platform Operator support two types of extensions:
-
Preinstalled HiveMQ Enterprise Extensions.
-
Extensions that are downloaded from a remote server via HTTP.
Field | Description |
---|---|
|
Configures the extensions for the HiveMQ Platform.
|
Example extension configuration
To configure the HiveMQ Enterprise Extension for Kafka, create a ConfigMap of the Kafka configuration with the name config.xml
as the key:
kubectl create configmap hivemq-kafka-configuration --from-file=config.xml=your-config-file.xml
To configure request headers for an authenticated download of the extensionUri
or customizationUri
, create a Kubernetes Secret with the header names as keys:
kubectl create secret generic github-auth-token-secret --from-literal="Authorization=Bearer YOUR-TOKEN" --from-literal="X-GitHub-Api-Version=2022-11-28"
Configure the Kafka extension with a customization in your platform-values.yml
file:
extensions:
- name: hivemq-kafka-extension
enabled: true
supportsHotReload: true
configMapName: "hivemq-kafka-configuration"
requestHeaderSecretName: "github-auth-token-secret"
extensionUri: preinstalled
customizationUri: https://github.com/example/my-kafka-customization/releases/download/1.0.0/my-kafka-customization-1.0.0.zip
To install or upgrade the HiveMQ Platform with the extension, enter:
helm upgrade --install my-hivemq-platform hivemq/hivemq-platform -f platform-values.yml -n <namespace>
Additional Volume Options
Field | Description |
---|---|
|
Provides configuration options to mount additional volumes to specific directories in the HiveMQ container as a list.
This option can be used to mount volumes of type
|
additionalVolume
:Create a Kubernetes Secret that contains your keystore.jks
file:
kubectl create secret generic my-keystore-secret-name \
--from-file=keystore.jks=keystore.jks
Configure your additionalVolumes
values using the created Kubernetes Secret my-keystore-secret-name
and the path where the keystore file should be mounted in your values.yaml
file:
additionalVolumes:
- type: secret
name: my-keystore-secret-name
path: /opt/hivemq/extensions/hivemq-kafka-extension/conf
Init Containers and Sidecars
Additional containers such as Init Containers and Sidecars can be configured to run in the HiveMQ Platform pod.
Init containers and sidecar containers support all valid Kubernetes container options.
Field | Description |
---|---|
|
An optional list of additional Init containers
that run before or alongside the HiveMQ container in the HiveMQ Platform pod.
Any valid Kubernetes |
|
An optional list of additional containers
that run alongside the HiveMQ container in the HiveMQ Platform pod.
Any valid Kubernetes |
additionalInitContainers:
- name: my-custom-init-container
image: busybox:latest
restartPolicy: Always
command: ['/bin/sh', '-c']
args:
- |
trap 'echo "Terminating container"; exit 0' SIGTERM
tail -n 200 -F /opt/hivemq/conf-k8s/config.xml &
while true; do sleep 1; done
volumeMounts:
- name: broker-configuration
mountPath: /opt/hivemq/conf-k8s/
Volume Claim Templates
Volume Claim Templates allow the fine-grained configuration of Persistent Volume Claims for your HiveMQ Platform pods.
The storage option you select determines the level of performance your HiveMQ broker can deliver. To ensure high durability and optimal performance, we recommend the use of dedicated persistent volumes that deliver a minimum of 900 IOPS for HiveMQ in production. For more information, see HiveMQ Minimum Hardware Requirements. |
Each Persistent Volume Claim (PVC) references a Persistent Volume (PV). Each Persistent Volume (PV) represents a piece of storage provisioned using an available Storage Class. All valid Kubernetes Persistent Volume Claims options are supported.
Each configured Persistent Volume Claim needs at least one matching entry by name in additionalVolumes .
The matching entry has to be of type persistentVolumeClaim .
The entry mounts the Persistent Volume to the configured path of the HiveMQ Platform pod.
|
The Persistent Volume is mounted with file permissions that depend on the PodSecurityContext configuration.
Enable the PodSecurityContext and add an fsGroup field to allow the HiveMQ process to write to the mounted volume.
|
Field | Description |
---|---|
|
A list of the Persistent Volume Claims (PVC) that HiveMQ Platform pods should reference.
Configure |
volumeClaimTemplates:
- kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: hivemq-pvc-data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 100Gi
volumeMode: Filesystem
additionalVolumes:
- type: persistentVolumeClaim
name: hivemq-pvc-data
path: /opt/hivemq/data
podSecurityContext:
enabled: true
fsGroup: 0
In the example, the volumeClaimTemplates
configuration defines a Persistent Volume Claim named hivemq-pvc-data
.
The additionalVolumes
configuration defines the matching volume mount with the same name hivemq-pvc-data
and the path /opt/hivemq/data
.
The StatefulSet controller mounts the persistent volume hivemq-pvc-data
to the /opt/hivemq/data
path in the HiveMQ platform container.
The fsGroup
field in the podSecurityContext
ensures the persistent volume is mounted with write permissions for the HiveMQ process.
Claims defined in the volumeClaimTemplates list override volumes with the same name defined for the StatefulSet.
|
If the additionalVolumes configuration is not specified or the name and type elements do not match the Persistent Volume Claim defined in the volumeClaimTemplates configuration, no persistent volume is mounted.
|
Once the Kubernetes StatefulSet controller creates a PersistentVolumeClaim it cannot be reconfigured.
The HiveMQ Platform Operator cannot successfully apply changes to the volumeClaimTemplates in the Helm chart.
Such changes result in a blocked rolling restart of your HiveMQ Platform.
To resolve the issue, revert to the previous volumeClaimTemplates configuration.
This issue is a known limitation in the way Kubernetes handles PersistentVolumesClaims that are attached to StatefulSets.
|
Test Your HiveMQ Platform
Once installation 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 that 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.