Configuration Options
You can configure the HiveMQ Platform Operator and the HiveMQ platform cluster to fulfill your individual use case.
HiveMQ provides two easy-to-use preconfigured Helm charts, one for the HiveMQ Platform Operator and one for the HiveMQ Platform.
For detailed information on all available configuration options, see HiveMQ Platform Operator Configuration with Helm and HiveMQ Platform Configuration with Helm .
You can also deploy the HiveMQ platform directly by providing the custom resource manifest with the necessary ConfigMaps. This gives you greater flexibility to configure HiveMQ for your use case. For more information, see Custom Resources. |
If you make changes to the HiveMQ config.xml configuration ConfigMap, the operator initiates a rolling update of your HiveMQ platform to apply the changes.
To maintain a steady load distribution during the upgrade, the operator starts a new HiveMQ pod before it shuts down and upgrades the existing HiveMQ pods.
This process temporarily increases the HiveMQ platform cluster by one pod.
The additional HiveMQ pod requires proportionally more system resources.
For example, enough CPUs, memory, and disk storage need to be available.
Once the rolling update is complete, the HiveMQ cluster returns to the configured number of pods and resources.
|
HiveMQ Platform Operator Configuration with Helm
The Helm chart for the HiveMQ Platform Operator installs the custom resource definition (CRD) for the HiveMQ Platform object on Kubernetes.
The Platform Operator Helm chart also installs the DeploymentSet of the operator, the operator pod, and the necessary RBAC permissions for the operator to manage your HiveMQ platforms on Kubernetes.
To customize your operator installation, export the possible configuration values to a file and edit the file to fit your needs.
To view the possible configuration values for the HiveMQ Platform Operator, enter:
helm show values hivemq/hivemq-platform-operator > operator-values.yml
To apply the changes you make to the operator-values.yml
file, enter:
helm upgrade --install my-hivemq-operator hivemq/hivemq-platform-operator -f operator-values.yml -n <namespace>
operator-values.yml
file:# HiveMQ Platform Operator Helm Chart default values
# Container image configuration
image:
repository: docker.io/hivemq
name: hivemq-platform-operator
tag: 1.0.0
initImageName: hivemq-platform-operator-init
pullPolicy: IfNotPresent
pullSecretName: ""
# Resources, limits and requests are set to equal values
# Note: Increase resources depending on how many HiveMQ Platforms this operator manages.
resources:
cpu: 512m
memory: 256M
ephemeralStorage: 5Gi
# Configures the log level, possible values are: "TRACE", "DEBUG", "INFO", "WARN", "ERROR".
logLevel: INFO
# Configures the operator ports for http/s. These ports provide access to metrics and other services.
http:
port: 8080
https:
port: 8443
# Configures the Java JVM runtime options for the process.
javaOpts: "-XX:+UnlockExperimentalVMOptions -XX:InitialRAMPercentage=75 -XX:MaxRAMPercentage=75"
# Selector name that is used to watch HiveMQ platforms that have a matching selector.
selector: nil
# Configures whether Kubernetes RBAC permissions are created.
rbac:
create: true
# Configures the service account for Kubernetes RBAC permissions.
serviceAccount:
# Specifies whether a service account is created.
create: true
# The service account name to be used, or "hivemq-<release name>" if not set.
name: ""
# Configures how the operator pod is scheduled on the Kubernetes cluster nodes.
podScheduling:
# Kubernetes node affinity configuration
affinity:
# podAffinity:
# requiredDuringSchedulingIgnoredDuringExecution:
# - labelSelector:
# matchExpressions:
# - key: app
# operator: In
# values:
# - my-app
# topologyKey: "kubernetes.io/hostname"
# Configures the tolerations for the operator pod
tolerations:
# - key: "example-key"
# operator: "Exists"
# effect: "NoSchedule"
# TLS configuration for the operator to access the Kubernetes API.
tls:
# Name of the secret that contains keystore and truststore
secretName: nil
# The keystore password. Can also be set as "keystore.password" in the secret.
keystorePassword: nil
# The truststore password. Can also be set as "truststore.password" in the secret.
truststorePassword: nil
# Operator security context, requires that the image supports the configured user.
podSecurityContext:
enabled: false
runAsNonRoot: true
runAsUser: 1000
HiveMQ 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.
|
|
The Java options for the process that starts the operator. |
|
Configures the security context for the operator process in the Kubernetes pod.
|
|
Sets a selector label to limit the platforms the operator is allowed to manage to HiveMQ platforms that have a matching selector label. |
Logging Configuration Options
Field | Description |
---|---|
|
Configures the log level for the HiveMQ Platform Operator. |
To view your HiveMQ Platform Operator log output, enter:
kubectl logs deployment/hivemq-platform-operator-<release-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.
Field | Description |
---|---|
|
Configures the RBAC permissions created on Kubernetes.
|
|
Configures which service account is used for RBAC Permissions on Kubernetes.
|
Pod Scheduling Options
Node affinity and tolerations can be configured to control on which Kubernetes worker node the operator pod is placed. Node affinity can be used to optimize workload placement, ensure resource requirements are met, or achieve other scheduling-related goals. All valid Kubernetes node podAffinity and antiPodAffinity options are supported.
Tolerations work together with taints to ensure that pods are not scheduled onto inappropriate nodes.
Field | Description |
---|---|
|
Configures how the operator pod is placed on your Kubernetes nodes.
|
affinity:
podAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: app
operator: In
values:
- my-app
topologyKey: "kubernetes.io/hostname"
The example podAffinity
configuration specifies that the operator pod can only be deployed on Kubernetes nodes that have the label my-app
.
If no nodes are available with the my-app
label, the operator is not installed and remains in a pending
state.
If pod 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 are available with a matching taint, 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.
|
HiveMQ Platform Configuration with Helm
The Helm chart for the HiveMQ Platform installs one HiveMQ platform cluster with the configured number of HiveMQ nodes as a custom resource and a ConfigMap that contains the HiveMQ config.xml
configuration for the nodes.
The operator observes the deployment of the new custom resource and creates the HiveMQ platform cluster as defined.
The HiveMQ platform cluster is deployed using a StatefulSet that controls how many HiveMQ nodes are installed.
The services that are needed to access the MQTT port and the HiveMQ Control Center are also installed.
If you want to customize your operator installation, export the possible configuration values to a file and edit the file to fit your needs.
To view the possible configuration values for the HiveMQ Platform, enter:
helm show values hivemq/hivemq-platform > platform-values.yml
To apply changes that you make to the platform-values.yml
file, enter:
helm upgrade --install my-hivemq-platform hivemq/hivemq-platform -f platform-values.yml -n <namespace>
platform-values.yml
file# HiveMQ Platform Helm Chart default values
# HiveMQ Platform container image configuration
image:
repository: docker.io/hivemq
name: hivemq4:4.22.0
pullPolicy: IfNotPresent
pullSecretName: ""
# Provides the HiveMQ Platform configuration (config.xml) as a Kubernetes ConfigMap.
config:
# Creates a new ConfigMap with a standard config.xml.
create: true
# Provides the name of the ConfigMap that contains a custom "config.xml" (set create=false).
name: ""
# Inlines the config.xml and overrides the default ConfigMap configuration.
overrideHiveMQConfig: ""
# Inlines the StatefulSet configuration and overrides the default StatefulSet.
overrideStatefulSet: ""
# Selector name that is used to match the selector of the managing operator.
# This selector assigns the HiveMQ Platform to a specific operator.
operator:
selector: nil
# Settings for the HiveMQ platform nodes
nodes:
# The number of HiveMQ nodes in the cluster
replicaCount: 2
logLevel: DEBUG
javaOpts: "-XX:+UnlockExperimentalVMOptions -XX:InitialRAMPercentage=50 -XX:MaxRAMPercentage=50"
# Resources, limits and requests are set to equal values.
# Note: For production use cases, HiveMQ requires a minimum of 4 CPUs and 4G of memory.
# See: https://docs.hivemq.com/hivemq/latest/user-guide/system-requirements.html#minimum
resources:
cpu: 1024m
memory: 2048M
ephemeralStorage: 10Gi
# Requires that the image provides support for the configured user.
podSecurityContext:
enabled: false
runAsNonRoot: true
runAsUser: 10000
# Configure exposed Services and ports
# Possible service types are: "control-center", "rest-api", "mqtt", "websocket"
services:
# MQTT port
- type: mqtt
exposed: true
containerPort: 1883
# Set if service port is different from the container port
port: 1883
# TLS MQTT port
- type: mqtt
exposed: false
containerPort: 8883
# The name of the Kubernetes secret that contains the keystore file.
keystoreSecretName: ""
# The inlined password for the keystore, Base 64 encoded.
keystorePassword: ""
# The key of the Kubernetes secret that contains the keystore file. Defaults to `keystore`
keystoreSecretKey: ""
# Alternatively, the name of the secret with the password, using the key: "keystore.password".
keystorePasswordSecretName: ""
# The name of the Kubernetes secret that contains the truststore file.
truststoreSecretName: ""
# The key of the Kubernetes secret that contains the truststore file. Defaults to `truststore`
truststoreSecretKey: ""
# The inlined password for the truststore, Base 64 encoded.
truststorePassword: ""
# Alternatively, the name of the secret with the password, using the key: "truststore.password".
truststorePasswordSecretName: ""
# The way HiveMQ platform authenticates client certificates. Possible values are `NONE`, `OPTIONAL` and `REQUIRED`
tlsClientAuthenticationMode: "NONE"
# ControlCenter port
- type: control-center
exposed: true
containerPort: 8080
# RestAPI port
- type: rest-api
exposed: false
containerPort: 8888
# Websocket port
- type: websocket
exposed: false
containerPort: 8001
# Configures the HiveMQ license information.
license:
# The name of a secret with the license information. Add all required licenses into the secret.
name: ""
# Inlines the license information as an encoded 64-byte string.
data: ""
# Overrides the license information via file using --set-file license.lic.
overrideLicense: ""
# Overrides the default Control Center username and password.
# Set both values to override the default configuration.
controlCenter:
username: ""
# Password as SHA256 HASH. See password generation:
# https://docs.hivemq.com/hivemq/latest/control-center/configuration.html#generate-password
password: ""
# HiveMQ platform extension configuration
extensions:
# By default, HiveMQ is installed with the allow-all extension to permit all MQTT connections for testing.
# For production, add a security extension and disable this extension.
- name: hivemq-allow-all-extension
extensionUri: preinstalled
# Disable the extension (enabled=false), to secure your deployment.
enabled: true
supportsHotReload: false
# HiveMQ Enterprise Extension for Kafka
- name: hivemq-kafka-extension
extensionUri: preinstalled
enabled: false
# The Kafka extension supports hot-reload of the configuration.
supportsHotReload: true
# The ConfigMap name that contains the Kafka extension configuration.
configMapName: ""
# HiveMQ Enterprise Extension for Google Pub/Sub
- name: hivemq-google-cloud-pubsub-extension
extensionUri: preinstalled
enabled: false
# The Google Pub/Sub extension supports hot-reload of the configuration.
supportsHotReload: true
# The ConfigMap name that contains the Google Pub/Sub extension configuration.
configMapName: ""
# HiveMQ Enterprise Extension for Amazon Kinesis
- name: hivemq-amazon-kinesis-extension
extensionUri: preinstalled
enabled: false
# The Amazon Kinesis extension supports hot-reload of the configuration.
supportsHotReload: true
# The ConfigMap name that contains the Amazon Kinesis extension configuration.
configMapName: ""
# HiveMQ Enterprise Security Extension
- name: hivemq-enterprise-security-extension
extensionUri: preinstalled
enabled: false
# The Security extension does not support hot-reload of the configuration.
supportsHotReload: false
# The ConfigMap name that contains the Security extension configuration.
configMapName: ""
# HiveMQ Enterprise Distributed Tracing Extension
- name: hivemq-distributed-tracing-extension
extensionUri: preinstalled
enabled: false
# The Tracing extension supports hot-reload of the configuration.
supportsHotReload: true
# The ConfigMap name that contains the Tracing extension configuration.
configMapName: ""
# HiveMQ Enterprise Extension for MongoDB
- name: hivemq-mongodb-extension
extensionUri: preinstalled
enabled: false
# The MongoDB extension does not support hot-reload of the configuration.
supportsHotReload: false
# The ConfigMap name that contains the MongoDB extension configuration.
configMapName: ""
# HiveMQ Enterprise Extension for PostgreSQL
- name: hivemq-mysql-extension
extensionUri: preinstalled
enabled: false
# The PostgreSQL extension does not support hot-reload of the configuration.
supportsHotReload: false
# The ConfigMap name that contains the PostgreSQL extension configuration.
configMapName: ""
# HiveMQ Enterprise Extension for MySQL
- name: hivemq-postgresql-extension
extensionUri: preinstalled
enabled: false
# The MySQL extension does not support hot-reload of the configuration.
supportsHotReload: false
# The ConfigMap name that contains the MySQL extension configuration.
configMapName: ""
# HiveMQ Enterprise Bridge Extension
- name: hivemq-bridge-extension
extensionUri: preinstalled
enabled: false
# The Bridge extension does not support hot-reload of the configuration.
supportsHotReload: false
# The ConfigMap name that contains the Bridge extension configuration.
configMapName: ""
# Map additional volumes from possible types: "configMap", "secret", "emptyDir", "persistentVolumeClaim".
additionalVolumes: [ ]
# - type: configMap
# name: configmap-name
# mountName: mount-name
# path: /file/mount/path
# subPath: ""
# type: Choose a type of volume that you want to mount.
# name: Optional name for the secret or the ConfigMap to be mounted
# mountName: The mountName to be used for the StatefulSet Spec.
# path: The path configures the directory to which the volume is mounted in the container
# If the directory already exists then the contents are overwritten!
# subPath: Optional name for the subPath. If a volume is mounted with subPath, the content
# of the directory is not overwritten. However, changes such as a change to a ConfigMap
# mounted via subPath are not propagated to the container. Therefore, pods have to be restarted.
When you change a list in the configuration, you must provide the entire list again. Otherwise, the previously configured list items are overwritten. For example, you must submit the full list of configured extensions each time you make changes to your list of extensions. The operator automatically applies your changes. |
HiveMQ Container Image Options
Field | Description |
---|---|
|
Configure the container image details for the HiveMQ Platform.
|
kubectl create secret docker-registry ghcr \
--docker-server=ghcr.io \
--docker-username="$GITHUB_USER_NAME" \
--docker-password="$GITHUB_PAT" \
--docker-email="$GITHUB_EMAIL"
HiveMQ Platform Config Options
Field | Description |
---|---|
|
Defines how the HiveMQ platform configuration is specified as a configMap.
|
|
Override the default username and password for the ControlCenter, when using the default configuration.
|
Example to overwrite the HiveMQ configuration
The HiveMQ configuration can be set from a file via the command line. For more information, see HiveMQ Configuration:
helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set-file config.overrideConfig=files/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=files/stateful-set-spec.yaml -n <namespace>
Example custom StatefulSetSpec configuration:
spec:
replicas: 2
template:
spec:
containers:
- name: hivemq
image: hivemq/hivemq4:4.19.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 the Service configuration and the StatefulSpec 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 - .
|
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 node podAffinity and antiPodAffinity 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.
|
affinity:
podAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: app
operator: In
values:
- my-app
topologyKey: "kubernetes.io/hostname"
The example podAffinity
configuration specifies that the HiveMQ platform pods can only be deployed on Kubernetes nodes that have the label my-app
.
If no nodes are available with the my-app
label, the HiveMQ platform pods are not installed and remain in a pending
state.
If pod labels change during runtime, the HiveMQ platform pods remains 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
Field | Description |
---|---|
|
Provides the selection criteria to identify which operator manages the selected HiveMQ Platform custom resource.
|
HiveMQ Node Options
Field | Description |
---|---|
|
Configures the settings for the individual HiveMQ platform nodes.
|
|
The available resources for the HiveMQ platform node.
|
|
Configures the podSecurity settings of the HiveMQ process.
|
Service Options
Field | Description |
---|---|
|
Defines the Kubernetes Service configuration for the HiveMQ platform.
|
The truststore and keystore secrets can be reused for different listeners/services. If the keystore or truststore password changes, a rolling restart is required. |
Example TLS configuration
The HiveMQ platform can be configured to support TLS and mTLS. For further details on how to configure HiveMQ with TLS see the TLS Listener configuration.
To add a secret with the truststore to Kubernetes, enter:
kubectl create secret generic mqtt-keystore --from-file=keystore=keystore.jks
To configure a service include this snippet in your platform-values.yaml
:
services:
- type: mqtt
exposed: true
containerPort: 8883
keystoreSecretName: "mqtt-keystore"
keystorePassword: "<password>"
truststoreSecretName: "mqtt-truststore"
truststorePassword: "<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>
HiveMQ Platform License Options
Field | Description |
---|---|
|
Configures the licenses to be used.
|
HiveMQ Extension Configuration Options
Extensions add functionality to the HiveMQ broker that allows the broker to integrate with other 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 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. This option can be used to mount volumes of type "configMap", "secret", "emptyDir", and "persistentVolumeClaim".
|
If the directory to which a volume is mounted already exists, the contents of the directory are overwritten. |
If a volume is mounted with subPath, the contents of the directory are not overwritten. However, changes to a ConfigMap that are mounted via subPath are not propagated to the container. |