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.

    1. 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.

      For additional Helm command line options, see the official Helm documentation.

      If you are using Helm 4.x and encounter conflicts during installation or upgrade, use the --force-conflicts flag to resolve them. For example: helm upgrade --install <your-hivemq-operator> hivemq/hivemq-platform-operator -n <namespace> --force-conflicts

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

    2. 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>

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

      kubectl get crds hivemq-platforms.hivemq.com

    4. 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>

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

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

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

      kubectl logs deployments/<your-operator-deployment-name>

    7. To access the available operator metrics, enter:

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

    8. Next, to review the operator metrics in your browser, enter http://localhost:8080/metrics. For more details see Operator 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.

  1. 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

  2. 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

image

Defines which container image is used for the operator.
Images are available on DockerHub as multi-architecture images supporting ARM and AMD hardware.

  • repository: The repository from which the HiveMQ Platform Operator container image is pulled.

  • name: The name of the HiveMQ Platform Operator container image to be pulled.

  • tag: The identifier of the HiveMQ Platform Operator container image variant to be pulled.

  • digest: Optional image digest for the HiveMQ Platform Operator image.
    When set, the digest pins the image to an exact version. The rendered image reference is <repository>/<name>:<tag>@<digest>. If tag is empty, the reference is <repository>/<name>@<digest>.
    The digest must be specified in the format <algorithm>:<hex>. For example, sha256:<64 hex chars>.

  • initImageName: the name of the HiveMQ Platform Operator initContainer image to be pulled.

  • initImageDigest: Optional image digest for the HiveMQ Platform Operator init image.
    When set, the digest pins the image to an exact version. The rendered image reference is <repository>/<initImageName>:<tag>@<initImageDigest>. If tag is empty, the reference is <repository>/<initImageName>@<initImageDigest>.
    The digest must be specified in the format <algorithm>:<hex>. For example, sha256:<64 hex chars>.

  • pullPolicy: The Kubernetes imagePullPolicy setting that is used.
    The default setting is IfNotPresent.

  • pullSecretName: The name of the ImagePullSecret the operator uses to authenticate against the selected repository.

resources

Sets the CPU and memory resources for the operator. Requests and limits use the same values.

  • cpu: Sets the CPU resources to be used for the operator. Adjust the CPU setting depending on the number of HiveMQ platforms the operator manages.
    The default setting is 1000m.

  • memory: Sets the memory resources for the operator. Adjust this setting depending on the number of HiveMQ platforms the operator manages.
    The default setting is 1Gi.

  • ephemeralStorage: Sets the disk storage resources available to the operator.
    There is no default setting.

env

Specifies environment variables to be added to the operator container. Variables can be defined as a list of key - value pairs or using valueFrom to reference a Kubernetes Secret or ConfigMap.

  • name: The name of the environment variable.

  • value: The value of the environment variable.

  • valueFrom: The reference to a Kubernetes Secret or ConfigMap that defines the environment variable.

    • secretKeyRef or configMapKeyRef:

      • name: The name of a Kubernetes Secret deployed.

      • key: The key to be used in the Kubernetes Secret.

      • optional: Whether the Kubernetes Secret has to exist. The default setting is false.

The default setting is an empty list.

javaOpts

Configures the Java options for the process that starts the operator.
The default setting is "-XX:+UnlockExperimentalVMOptions -XX:InitialRAMPercentage=75 -XX:MaxRAMPercentage=75".

hivemqPlatformHealthDetailsFormat

Configures the format for the HiveMQ Platform health details in the custom resource and Kubernetes events. Valid values are plain, json and yaml.
The default setting is plain.

concurrentRollingRestartLimit

One operator can manage many HiveMQ platforms. This value configures the maximum number of HiveMQ platforms that can perform a rolling restart at the same time.
The default setting is 0, which disables the limit.

concurrentInitAppUpdateLimit

One operator can manage many HiveMQ platforms. This value configures the maximum number of HiveMQ platforms that can perform an init app update at the same time.
The default setting is 10. To disable the limit, set the value to 0.

podSecurityContext

Configures the pod security context for the operator. Fields in the container security context take precedence over fields in the pod security context.

  • enabled: Defines whether the operator process runs with a security context enabled.
    The default setting is false.

  • runAsNonRoot: Defines whether the operator process runs with a non-root user account.
    The default setting is true.

  • runAsUser: Defines which user ID (UID) runs the operator process inside the pod.
    The default setting is 185.

  • runAsGroup: Defines which group ID (GID) runs the operator process.
    The default setting is 0.

    Other valid Kubernetes pod security context configurations can also be used.

containerSecurityContext

Configures the container security context for the operator. Fields in the container security context take precedence over fields in the pod security context.

  • runAsGroup: Defines which group ID (GID) runs the operator process.
    The default setting is 0.

  • runAsNonRoot: Defines whether the operator process runs with a non-root user account.
    The default setting is true.

  • runAsUser: Defines which user ID (UID) runs the operator process inside the pod.
    The default setting is 185.

    Other valid Kubernetes container security context configurations can also be used.

crd

The HiveMQ Platform CustomResourceDefinition configuration options.

  • apply: Enables the operator to create the HiveMQ Platform CustomResourceDefinition in the Kubernetes cluster during cluster startup.
    The default setting is true.

  • waitReady: Enables the operator to wait for the HiveMQ Platform CustomResourceDefinition to be ready.
    The default setting is true.

  • waitTimeout: Specifies how long the operator waits for the HiveMQ Platform CustomResourceDefinition to be ready.
    If the timeout is exceeded, the operator shuts down. The timeout duration is based on the ISO-8601 format.
    The default setting is PT10S.

Annotation and Label Options

Field Description

podAnnotations

Defines specific annotations to be applied to the HiveMQ Platform Operator pod.

podLabels

Defines specific labels to be applied to the HiveMQ Platform Operator pod.

serviceAnnotations

Defines specific annotations to be applied to the HiveMQ Platform Operator service.

serviceLabels

Defines specific labels to be applied to the HiveMQ Platform Operator service.

HiveMQ Platform Selector Options

Field Description

namespaces

An optional comma-separated list of namespaces this operator manages.
Defaults to watch all namespaces if empty.

selector

Selector name to configure which HiveMQ Platform instances this operator manages. Use the operator.selector value in the HiveMQ Platform Helm chart to configure a matching label.

This option creates an operator=<my-selector-value> label selector for the operator.

selectors

An optional comma-separated list of label selectors that HiveMQ Platform resources must match to be managed by this operator. Use operator.labels in the HiveMQ Platform Helm chart to configure matching labels for these label selectors.

Logging Configuration

Field Description

logLevel

Configures the log level for the HiveMQ Platform Operator.
Possible values are ERROR, WARN, INFO, DEBUG, or TRACE.
The default setting is INFO.

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

rbac

Configures whether to create the RBAC permissions and the service account on Kubernetes.

  • create: Boolean value that determines whether the default RBAC permissions and service accounts are created.
    The default setting is true.

serviceAccount

Configures that a custom service account is used for RBAC Permissions on Kubernetes.

  • create: Boolean value that determines whether a custom service account is created. When set to true, the operator creates a service account with the name hivemq-<release name>.
    The default setting is true.

  • name: The optional name of an existing service account to use that provides the necessary permissions.

  • annotations: Defines specific annotations to be applied to the service account.

hivemqPlatformServiceAccount

Configures the ServiceAccount and RBAC permissions (Role, RoleBinding) the operator creates for the HiveMQ Platform pods.

  • create: Boolean value that determines whether a custom service account is created. When set to true, the operator creates a service account with the name hivemq-platform-pod-<release name>.
    The default setting is true.

  • name: The optional name of an existing service account to use that provides the necessary permissions.

  • validate: Specifies whether the ServiceAccount for all HiveMQ Platforms should be validated.
    The default setting is true.

  • permissions: Configures the RBAC permissions (Role, RoleBinding) the operator creates for the HiveMQ Platform pods.

    • create: Specifies whether the RBAC permissions for the ServiceAccount should be created for all HiveMQ platforms.

    • validate: Specifies whether the RBAC permissions for the ServiceAccount for all HiveMQ platforms should be validated.

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

podScheduling

Configures how the operator pod is placed on your Kubernetes nodes.

  • affinity: Optional setting that defines the affinity configuration for your operator pod.
    Any valid affinity Kubernetes configuration can be used.

  • tolerations: Optional setting that defines the tolerations configuration for your operator pod.
Example node affinity configuration:
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.

Example tolerations configuration:
  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.

Example command to set a taint for a Kubernetes worker node:
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.

Health Probes

You can configure the Kubernetes liveness and readiness probes for the HiveMQ Platform Operator container to tune probe timing and thresholds. The liveness probe checks /health/liveness, and the readiness probe checks /health/readiness on the operator HTTP port.

Field Description

livenessProbe

Configures the liveness probe for the HiveMQ Platform Operator container.

  • initialDelaySeconds: Number of seconds after the container has started before the probe is initiated.
    The default setting is 5.

  • periodSeconds: How often (in seconds) to perform the probe.
    The default setting is 10.

  • timeoutSeconds: Number of seconds after which the probe times out.
    The default setting is 10.

  • failureThreshold: Number of consecutive failures before the container is considered unhealthy.
    The default setting is 3.

For liveness probes, Kubernetes requires successThreshold to be 1. You cannot change this value.

readinessProbe

Configures the readiness probe for the HiveMQ Platform Operator container.

  • initialDelaySeconds: Number of seconds after the container has started before the probe is initiated.
    The default setting is 5.

  • periodSeconds: How often (in seconds) to perform the probe.
    The default setting is 10.

  • timeoutSeconds: Number of seconds after which the probe times out.
    The default setting is 10.

  • successThreshold: Minimum number of consecutive successes required for the probe to be considered successful after a failure.
    The default setting is 1.

  • failureThreshold: Number of consecutive failures before the container is considered not ready.
    The default setting is 3.
Example custom readiness probe configuration:
readinessProbe:
  periodSeconds: 15
  timeoutSeconds: 15

Operator Monitoring

The HiveMQ Platform Operator provides rich metrics that enable monitoring of day-to-day operations. Monitoring can be configured to integrate with Prometheus and Grafana.

Configure your Prometheus ServiceMonitor resource and deploy a Grafana dashboard ConfigMap to enable seamless integration of Operator Metrics with your Prometheus monitoring stack.

For more information, see Monitoring with Prometheus.

Monitoring configuration options require that the Prometheus monitoring stack is installed in your Kubernetes cluster.
Field Description

monitoring

Enables the ServiceMonitor resource and Grafana dashboard creation for the operator.

  • enabled: Defines whether the monitoring configuration for the HiveMQ Platform Operator is enabled.
    The default setting is false.

  • dashboard: Grafana dashboard configuration options.

    • create: Boolean value that configures whether to use the default HiveMQ Platform Operator Grafana dashboard ConfigMap.
      The default setting is true.

    • namespace: Namespace where to deploy the Grafana dashboard ConfigMap. Defaults to the namespace of the HiveMQ Platform Operator.

    • overrideDashboard: Sets the Grafana dashboard content for the HiveMQ Platform Operator Grafana dashboard ConfigMap with your own JSON file from a specified path.

  • serviceMonitor: Prometheus ServiceMonitor configuration options.

    • namespace: Namespace where to deploy the ServiceMonitor. Defaults to the namespace of the HiveMQ Platform Operator.

    • releaseName: Helm chart release name of the Prometheus Monitoring stack installed. Defaults to the HiveMQ Platform Operator Helm chart release name.

    • interval: Defines how often Prometheus scrapes metrics from the operator endpoints.
      Example of a valid format are 1d, 1h30m, 5m, 10s. Defaults to 15 seconds.

    • scrapeTimeout: Defines the maximum duration allowed for scraping metrics from the endpoints defined in the ServiceMonitor resource. Example of a valid format are 1d, 1h30m, 5m, 10s. Defaults to 10 seconds.
If you use Argo CD as a continuous delivery tool, you may exceed the Kubernetes annotations size constraint of 256 KB when creating the default Grafana dashboard. Argo CD sets a kubectl.kubernetes.io/last-applied-configuration annotation that contains the JSON representation of the last applied object configuration. To fix this issue, configure the option to use Server Side Apply in your Argo CD yaml configuration: 
syncPolicy:
  syncOptions:
    - ServerSideApply=true

Operator HTTP Endpoints

The HiveMQ Platform Operator exposes multiple HTTP endpoints. For example, to configure Kubernetes Admission Webhooks or monitor with Operator Metrics.

Field Description

http

Configures the HTTP port to be used for the API endpoint of the operator.

  • port: The HTTP port. The default setting is 8080.

https

Configures the HTTPS port to be used for the API endpoint of the operator.

  • port: The HTTPS port. The default setting is 8443.

  • skipCertificateValidation: Boolean value to skip certificate validation for all managed custom resources that use the HTTPS protocol. For example, when downloading custom extensions and extension customizations. The default setting is false.

  • skipHostnameVerification: Boolean value to skip hostname verification for all managed custom resources that use the HTTPS protocol. For example, when downloading custom extensions and extension customizations. The default setting is false.

Operator TLS Options

Field Description

tls

Configures the TLS options for the operator to access a secured Kubernetes API server.

  • secretName: The name of the Kubernetes Secret that contains the keystore and truststore files for TLS.

  • keystorePassword: The password for the keystore.
    If the keystorePassword value is not set, the keystore.password value in the Kubernetes Secret is used.

  • privateKeystorePassword: The private password for the keystore.
    If the privateKeystorePassword value is not set, the private.keystore.password value in the Kubernetes Secret is used. This configuration option requires HiveMQ Platform Operator version 2.0.0 or higher.

  • truststorePassword: The password for the truststore.
    If the truststorePassword value is not set, the truststore.password value in the Kubernetes Secret is used.

Kubernetes Admission Webhooks

You can use the /mutate and /validate endpoints to configure Kubernetes Admission Webhooks.

To use the HiveMQ Platform Operator with Kubernetes Admission Webhooks, you must configure an HTTPS port.
Example configuration for a validating webhook:
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: "validating.hivemq.com"
webhooks:
  - name: "validating.hivemq.com"
    rules:
      - apiGroups: ["hivemq.com"]
        apiVersions: ["v1"]
        operations: ["*"]
        resources: ["*"]
        scope: "Namespaced"
    clientConfig:
      service:
        namespace: "default"
        name: "<operator-service-name>"
        path: "/validate"
        port: <operator-tls-port> # 8443 by default
      caBundle: <ca-bundle>
    admissionReviewVersions: ["v1"]
    sideEffects: None
    timeoutSeconds: 5
You must replace <ca-bundle> in the above example with a valid PEM-encoded (field value is Base64 encoded) CA bundle for the TLS certificate of the operator.
Example to add the CA bundle to your webhook configuration:
FORMATTED_CRT=$(base64 ca.crt | fold)
yq -i -e ".webhooks[0].clientConfig.caBundle = \"$FORMATTED_CRT\"" your-webhook-configuration.yml

Once a mutating or validating webhook is configured all configured operations (CREATE, UPDATE, DELETE and CONNECT) are passed through the webhook endpoints of the operator. When you apply an invalid HiveMQPlatform custom resource, the operation fails with a detailed error message.

Example of an invalid HiveMQPlatform custom resource and the validating webhook response:
apiVersion: "hivemq.com/v1"
kind: HiveMQPlatform
metadata:
  name: test-example
spec:
  configMapName: hivemq-configuration
  statefulSet:
    spec:
      replicas: 1
kubectl apply -f invalid-custom-resource.yml
Error from server: error when creating "invalid-custom-resource.yml": admission webhook "validating.hivemq.com" denied the request: The first container of the StatefulSet must be the HiveMQ Platform container with the name 'hivemq'

Operator Metrics

All available HiveMQ Platform Operator metrics are exposed on the /metrics endpoint.

Available HiveMQ Platform Operator Metrics

HiveMQ Platform Operator metrics start with the prefix hivemq.platform.operator.

Meter name Type Tag names Description

hivemq.platform.operator.custom.resource.count

Gauge

controller

Number of watched custom resources

hivemq.platform.operator.custom.resource.namespaces.count

Gauge

controller

Number of namespaces that have a watched custom resource

hivemq.platform.operator.custom.resource.state.count

Gauge

controller, state

Number of custom resources with this state

hivemq.platform.operator.slow-reconciliations.count

Gauge

controller

Number of slow reconciliations

hivemq.platform.health.system.current

Gauge

namespace, name

System health metric of the managed HiveMQ Platform

The controller tag is hivemq-controller for all metrics. The state tag is all state values of the HiveMQ custom resource status. The namespace and name tags are the resource identifiers of the managed HiveMQ Platform.

Example HiveMQ Platform Operator metrics:
hivemq_platform_operator_custom_resource_count{controller="hivemq-controller",} 1.0
hivemq_platform_operator_custom_resource_state_count{controller="hivemq-controller",state="RUNNING",} 1.0
hivemq_platform_operator_custom_resource_state_count{controller="hivemq-controller",state="ROLLING_RESTART",} 0.0
hivemq_platform_operator_custom_resource_state_count{controller="hivemq-controller",state="ERROR",} 0.0
hivemq_platform_operator_slow_reconciliations_count{controller="hivemq-controller"} 0.0
hivemq_platform_health_system_current{namespace="default",name="my-hivemq-platform"} 2.0

Each HiveMQ custom resource status state is exposed as a metric, for example: RUNNING, ROLLING_RESTART, SET_LOG_LEVEL or ERROR.

Available Java Operator SDK Metrics

Metrics provided by the Java Operator SDK, the framework that the HiveMQ Platform Operator is based on, are scoped to the controller. A detailed description is available in the Operator SDK metrics documentation.

Meter name Type Tag names Description

reconciliations.started.total

Counter

controller_name

Total number of reconciliations started

reconciliations.success.total

Counter

controller_name

Total number of successful reconciliations

reconciliations.failure.total

Counter

controller_name

Total number of failed reconciliations

reconciliations.retries.total

Counter

controller_name

Total number of retried reconciliations

reconciliations.execution.duration

Timer

controller_name

Duration of reconciliation executions

reconciliations.active

Gauge

controller_name

Number of currently active reconciliations

reconciliations.queue

Gauge

controller_name

Number of reconciliations in queue

events.received

Counter

controller_name, event, action

Number of events received

The controller_name tag is hivemq-controller for all metrics.

Example Java Operator SDK metrics:
reconciliations_success_total{controller_name="hivemq-controller",} 451.0
reconciliations_started_total{controller_name="hivemq-controller",} 453.0
reconciliations_execution_duration_seconds_max{controller_name="hivemq-controller",} 0.099221173
JVM metrics

The remaining JVM metrics are provided by Micrometer and have a jvm prefix.

Example JVM metrics:
jvm.memory.used.bytes{area="heap",id="Tenured Gen",} 3.6756632E7
jvm.memory.used_bytes{area="heap",id="Eden Space",} 1.24372088E8

Operator Init Container Options

The HiveMQ Platform Operator can configure the resource requests and limits for the HiveMQ Platform Operator Init container. This container only runs for a few seconds to copy over files into the HiveMQ Platform main container and can be configured with a small resource footprint. These configuration options require HiveMQ Platform Operator version 1.7.2 or higher.

Field Description

hivemqPlatformInitContainer

Configuration options for the HiveMQ Platform Operator Init container.

  • resources: Configures the resource requests and limits for the HiveMQ Platform Operator Init container.

    • cpu: The CPU resource requests and limits the operator configures for the HiveMQ Platform Operator Init container.
      The default setting is 250m.

    • memory: The memory resource requests and limits the operator configures for the HiveMQ Platform Operator Init container.
      The default setting is 100Mi.

    • ephemeralStorage: The ephemeral resource requests and limits the operator configures for the HiveMQ Platform Operator Init container.
      The default setting is 1Gi.

If the HiveMQ Platform container has no ephemeral storage limit configured, the operator does not set ephemeral storage requests and limits for the init container. This ensures the expected unlimited ephemeral storage for the HiveMQ Platform pod.

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.

  1. 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.

    For additional Helm command line options, see the official Helm documentation.

    If you are using Helm 4.x and encounter conflicts during installation or upgrade, use the --force-conflicts flag to resolve them. For example: helm upgrade --install <your-hivemq-platform> hivemq/hivemq-platform -n <namespace> --force-conflicts
    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.

  2. 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.

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

    helm status <your-hivemq-platform>

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

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

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

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

  6. To view the logs for your HiveMQ Platform node, enter:

    kubectl logs <your-hivemq-pod-name>

  7. 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

  8. To review the available HiveMQ Platform metrics, enter:

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

  9. 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.

  1. 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

  2. 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

image

Configures the container image details for the HiveMQ Platform.

  • repository: Configures from which repository the HiveMQ Platform image is pulled.

  • name: The name of the HiveMQ Platform container image to be used.

  • tag: The identifier of the HiveMQ Platform container image variant to be pulled.

  • digest: Optional image digest for the HiveMQ Platform image.
    When set, the rendered image reference is <repository>/<name>:<tag>@<digest>, or <repository>/<name>@<digest> when tag is empty.
    The digest must be in the form <algorithm>:<hex>, for example sha256:<64 hex chars>.

  • pullPolicy: Defines the imagePullPolicy that Kubernetes uses to download the HiveMQ Platform container image.
    Possible values are: IfNotPresent, Never, or Always.
    The default setting is IfNotPresent.

  • pullSecretName: Configures the name of the ImagePullSecret Kubernetes uses to authenticate against the selected repository. This setting applies to all containers defined in the HiveMQ Platform pods including init and sidecar containers.
The HiveMQ Platform Operator is compatible with all standard HiveMQ container images published by HiveMQ starting with HiveMQ 4.28.
Example to use a private container registry with a 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

nodes

Configures the settings for the individual HiveMQ Platform nodes.

  • replicaCount: The number of HiveMQ Platform nodes to start.
    The default value is 2.

  • logLevel: The log level for the HiveMQ Platform.
    The default is INFO.

  • javaOpts: The Java options to run the HiveMQ process.
    The default setting is -XX:+UnlockExperimentalVMOptions -XX:InitialRAMPercentage=50 -XX:MaxRAMPercentage=50.

  • labels: Defines specific labels to be applied to the HiveMQ Platform pods.

  • annotations: Defines specific annotations to be applied to the HiveMQ Platform pods.

  • env: Specifies environment variables to be added to the HiveMQ Platform container. Environment variables can be defined as a list of key-value pairs or using valueFrom to reference a Kubernetes Secret or ConfigMap.

    • name: The name of an environment variable.

    • value: The value of an environment variable.

    • valueFrom: The reference to a Kubernetes Secret or ConfigMap that defines the environmental variable.

      • secretKeyRef or `configMapKeyRef:

        • name: The name of a Kubernetes Secret deployed.

        • key: The key to be used within the Kubernetes Secret.

        • optional: Defines whether the Kubernetes Secret must exist.
          The default setting is false.

  • serviceAccountName: The name of a custom service account to be used by the HiveMQ Platform pods.
    If not set or empty, a default service account is created.

  • resources: The available resources for the HiveMQ Platform node.
    Requests and limits are set to the same value.

    • cpu: The CPU resources available to HiveMQ.
      Production deployments of HiveMQ require a minimum of 4 CPUs.
      To facilitate local testing, the default setting is 1000m.

    • memory: The memory resources available to HiveMQ.
      Production deployments require a minimum of 4Gb.
      To facilitate local testing, the default setting is 2048M.

    • ephemeralStorage: The disk storage resources available to HiveMQ. There is no default setting.

  • podSecurityContext: Configures the Kubernetes pod security context of the HiveMQ process.
    The container image needs to support the configured user and group. Fields in the container security context take precedence over fields in the pod security context.

    • enabled: Boolean value that enables the podSecurityContext configuration.
      The default setting is false.

    • runAsNonRoot: Defines whether the HiveMQ process runs with a non-root account.
      The default setting is true.

    • runAsUser: Defines which user ID (UID) is used to run the HiveMQ process.
      The default setting is 10000.

    • runAsGroup: Defines which group ID is used to run the HiveMQ process.
      The default setting is 0.

      Other valid Kubernetes pod security context configurations can also be used.

  • containerSecurityContext: Configures the container security context for both the HiveMQ init container and HiveMQ Platform container. Fields in the container security context take precedence over fields in the pod security context.

    • runAsGroup: Defines which group ID (GID) runs the operator process.
      The default setting is 0.

    • runAsNonRoot: Defines whether the operator process runs with a non-root user account.
      The default setting is true.

    • runAsUser: Defines which user ID (UID) runs the operator process inside the pod.
      The default setting is 185.

      Other valid Kubernetes pod security context configurations can also be used.

  • persistentVolumeClaimRetentionPolicy: Optional setting that defines the retention policy controlling the lifecycle of PersistentVolumeClaims created from volumeClaimTemplates for your HiveMQ Platform pods.
    Any valid persistentVolumeClaimRetentionPolicy Kubernetes configuration can be used.

    On Kubernetes 1.24-1.26 the API server drops the StatefulSet persistentVolumeClaimRetentionPolicy field when the StatefulSetAutoDeletePVC feature gate is off, so the field has no effect on those versions.

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

hivemqClientEventHistory

These settings configure the client event history for HiveMQ. See Client Event History for detailed information.

  • enabled: Defines whether the client event history feature is enabled.

  • lifetime: The period of time in seconds that HiveMQ stores events for each client. The minimum length of time that HiveMQ can store events is one second, the maximum event storage lifetime is 864,000 seconds (10 days).
Field Description

hivemqRestrictions

These settings configure restrictions for HiveMQ. See MQTT restrictions for detailed information.

  • maxConnections: The global MQTT client connection limit for HiveMQ.

  • incomingBandwidthThrottling: The maximum amount of incoming traffic for MQTT clients in bytes per second (b/s).

  • noConnectIdleTimeout: The maximum time in milliseconds that HiveMQ waits for the CONNECT message of a client before closing an open TCP connection.

  • maxClientIdLength: The maximum number of characters HiveMQ accepts in an MQTT client ID.

  • maxTopicLength: The maximum number of characters HiveMQ accepts in a topic string.
Field Description

hivemqMqtt

These settings configure MQTT options for HiveMQ. See MQTT options for detailed information.

  • sessionExpiryMaxInterval: Defines the maximum session expiry value in seconds that clients can set.

  • messageExpiryMaxInterval: Defines the maximum message expiry in seconds that clients can set.

  • maxPacketSize: Defines the maximum packet size in bytes that the broker accepts from clients.

  • serverReceiveMaximum: Defines the maximum number of concurrent publishes the broker accepts from one client.

  • keepAliveMax: Defines the maximum keep alive value in seconds.

  • keepAliveAllowUnlimited: Defines whether clients can have unlimited keep alive.

  • topicAliasEnabled: Defines whether clients can use topic aliases.

  • topicAliasMaxPerClient: Defines the maximum number of topic aliases a client can use.

  • subscriptionIdentifier: Defines whether clients can use subscription identifiers.

  • wildcardSubscriptions: Defines whether clients can use wildcard characters in topic filters.

  • sharedSubscriptions: Defines whether clients can use shared subscriptions.

  • maxQualityOfService: Defines the maximum Quality of Service level allowed.

  • retainedMessages: Defines whether retained messages are supported.

  • queuedMessagesMaxSize: Defines the maximum number of messages that are queued per client.

  • queuedMessagesStrategy: Defines how queued messages are handled . Possible values are`discard` and discard-oldest.
Field Description

hivemqMqttAddons

Optional settings to configure HiveMQ MQTT add-ons. See HiveMQ MQTT Add-ons for detailed information.

  • expiredMessagesTopic: Captures all expired messages to the $expired namespace.

  • droppedMessagesTopic: Captures all dropped messages to the $dropped namespace.

  • deadMessagesTopic: Captures all dead messages to the $dead namespace.
Field Description

hivemqMqttSecurity

Optional settings to configure MQTT security for HiveMQ. See MQTT Security Configuration Options for detailed information.

  • allowEmptyClientId: Allows the use of empty client IDs. If allowed, HiveMQ generates random client IDs.

  • payloadFormatValidation: Enables the UTF-8 validation of UTF-8 PUBLISH payloads.

  • utf8Validation: Enables UTF-8 validation of topic names and client IDs.

  • allowRequestProblemInformation: Allows the client to request problem information.

  • controlCenterAuditLog: Defines whether audit logging for the Control Center is enabled.

  • restApiAuditLog: Defines whether audit logging for the REST API is enabled.
Field Description

controlCenter

Optional setting to override the default credentials for the HiveMQ Control Center when the default configuration is used.

  • username: The name of the HiveMQ Control Center user.

  • password: The SHA256 encoded password for the HiveMQ Control Center user. For more information, see password generation.

  • credentialsSecret: Configures the Control Center credentials by using an existing Kubernetes Secret.

    • name: Configures the Control Center credentials by using an existing Kubernetes Secret.

    • usernameKey: Configures the key for the Kubernetes Secret used holding the Control Center username.

    • passwordKey: Configures the key for the Kubernetes Secret used holding the Control Center password.
Field Description

hivemqOverloadProtection

Configuration for the HiveMQ cluster overload protection. For more information, see HiveMQ cluster overload protection.

  • enabled: Optional setting that defines whether HiveMQ cluster overload protection is enabled.
Field Description

hivemqClusterFailureDetection

Configuration for the HiveMQ cluster failure detection. For more information, see HiveMQ cluster failure detection.

  • heartbeat: Optional setting that defines a failure detection mechanism by sending a heartbeat between nodes. You can configure the heartbeat with the following parameters:

    • enabled: Enables the heartbeat.

    • interval: The interval, in milliseconds, in which a heartbeat message is sent to other nodes.

    • timeout: Amount of time, in milliseconds, that is tolerated for the response to a heartbeat message before a node is temporarily removed from the cluster.

  • tcpHealthCheck: Optional setting that defines a failure detection mechanism by holding an open TCP connection between nodes.
    You can configure the heartbeat with the following parameters:

    • enabled: Enables the heartbeat.

    • bindAddress: The network address to bind to.

    • bindPort: The port to bind to. 0 uses an ephemeral port.

    • externalAddress: The external address to bind to if the node is behind some kind of NAT.

    • externalPort: The external port to bind to if the node is behind some kind of NAT.

    • portRange: Port range to check on other nodes.
Field Description

hivemqClusterReplication

Configuration for the HiveMQ cluster replication. For more information, see HiveMQ cluster replication.

  • replicaCount: Optional setting that defines the HiveMQ cluster replication count.
Unless explicitly listed, the HiveMQ Platform Helm Chart does not set default configuration options. For all other configuration defaults, refer to the HiveMQ Broker configuration documentation. When you check the default values, make sure you are referencing the correct version of the HiveMQ Broker.

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

config

Defines how the HiveMQ Platform configuration is deployed as a Kubernetes object.
The default setting is to a Kubernetes ConfigMap. Kubernetes Secret can also be configured.

  • create: Boolean value, that configures whether to use a default HiveMQ configuration.
    The default setting is true.

  • name: The name of an existing Kubernetes ConfigMap or Secret with a valid HiveMQ configuration. To use the specified Kubernetes ConfigMap or Secret, the create value must be set to false.

  • createAs: Optional setting to create a Kubernetes ConfigMap or Secret to hold the HiveMQ configuration. Possible values are: ConfigMap or Secret. The default setting is ConfigMap.

  • labels: Defines custom labels for the Kubernetes ConfigMap or Kubernetes Secret that contains the HiveMQ Platform configuration.

  • annotations: Defines custom annotations for the Kubernetes ConfigMap or Kubernetes Secret that contains the HiveMQ Platform configuration.

  • overrideHiveMQConfig: Optional setting to provide the HiveMQ configuration from a file using --set-file config.overrideHiveMQConfig=your-hivemq-config.xml. When this configuration option is used, all other settings for the HiveMQ Platform configuration are ignored.

  • overrideStatefulSet: Optional setting to provide the StatefulSetSpec configuration from a file using --set-file config.overrideStateFulSet=your-statefulsetspec.yml. When this configuration option is used, all other settings for the StatefulSetSpec configuration are ignored.

  • overrideInitContainers: Optional setting to provide custom init containers for the StatefulSetSpec configuration from a file using --set-file config.overrideInitContainers=your-init-container.yml.

  • customLogbackConfig: Optional setting to provide a custom HiveMQ Platform logging configuration (logback.xml) from a file using --set-file config.customLogbackConfig=your-logback-config.xml.

  • customTracingConfig: Optional setting to provide a custom HiveMQ Platform tracing configuration (tracing.xml) from a file using --set-file config.customTracingConfig=your-tracing-config.xml.

  • platformLicense: Configures the HiveMQ Platform license license.xml. When set, the license.xml file is included in the HiveMQ Platform ConfigMap or Secret. The platformLicense object contains two mutually exclusive sub-options; use licenseKey or overrideLicenseConfig.

    • licenseKey: The platform license key identifier. When set, a license.xml is generated and included in the HiveMQ Platform configuration.

    • overrideLicenseConfig: Optional setting to provide a custom license.xml directly. Use --set-file config.platformLicense.overrideLicenseConfig=your-license.xml to pass the file. When overrideLicenseConfig is set, the licenseKey value is ignored.

  • dataHub: Optional setting to enable HiveMQ Data Hub functionality.

    • includeDisabled: Defines whether all Data Hub options are rendered in HiveMQ Platform configuration, including features set to false. The default setting is false.

    • dataValidationEnabled: Optional setting to enable data validation. The default setting is false.

    • behaviorValidationEnabled: Optional setting to enable behavior validation. The default setting is false.

    • scriptingEnabled: Optional setting to enable scripting functionality. The default setting is false.
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.28.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 you use the override configuration option config.overrideStatefulSet for your custom StatefulSetSpec or config.overrideHiveMQConfig for your custom HiveMQ configuration, all other related configuration options for StatefulSetSpec and HiveMQ configuration are ignored.

HiveMQ Pulse Configuration Options

The HiveMQ Platform Operator can provision HiveMQ Pulse for your broker by managing the required configuration as a Kubernetes Secret. These configuration options require HiveMQ Platform Operator version 2.1.0 or higher. You can create the Secret with the Helm chart in two ways:

  • Inline the Pulse configuration, or

  • Reference an existing Secret that contains the HiveMQ Pulse configuration file.

Field Description

pulse

Defines the HiveMQ Pulse configuration options, either to create a new Kubernetes Secret or reuse an existing Secret that contains the HiveMQ Pulse configuration file the HiveMQ broker uses to provision HiveMQ Pulse.

  • create: Creates a Kubernetes Secret for the HiveMQ Pulse configuration. Pulse configuration data can be inlined using the data value or set from a file with the overridePulseConfig option. The default setting is false.

  • name: Specifies the name of the Kubernetes Secret that contains the HiveMQ Pulse configuration file.

  • labels: Defines custom labels for the Kubernetes Secret that contains the HiveMQ Pulse configuration file.

  • annotations: Defines custom annotations for the Kubernetes Secret that contains the HiveMQ Pulse configuration file.

  • data: The HiveMQ Pulse configuration as a Base64-encoded string.

  • isPulseConfigBase64Encoded: Indicates whether the Pulse configuration data is provided as a Base64-encoded string (data) or a plain string (stringData) for the Kubernetes Secret. The default setting is true and expects a Base64-encoded string.

  • overridePulseConfig: Sets the HiveMQ Pulse configuration with your own file from a specified path using --set-file pulse.overridePulseConfig=your-pulse-config.xml.
Example configuration to create a Pulse Secret from a HiveMQ Pulse configuration file:
helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform \
  --set pulse.create=true \
  --set pulse.name=hivemq-pulse-configuration \
  --set-file pulse.overridePulseConfig=pulse-config.xml \
  -n <namespace>

This command creates a Kubernetes Secret named hivemq-pulse-configuration that contains your HiveMQ Pulse configuration from the pulse-config.xml file.

Example configuration to use an existing Pulse Secret that contains your HiveMQ Pulse configuration:
pulse:
  create: false
  name: my-existing-pulse-secret

This configuration references an existing Kubernetes Secret named my-existing-pulse-secret that you have already created with your HiveMQ Pulse configuration.

When you use an existing Pulse Secret, ensure it contains a key named config.xml with your HiveMQ Pulse configuration.

Rolling Restart Configuration

The HiveMQ Platform Operator allows you to configure the rolling restart behavior on a per-platform basis. You can set the minimum time between pod restarts for individual HiveMQ Platform deployments to control restart pacing independently.

This is useful for platforms with a high number of client connections where restarting pods too quickly can cause reconnect storms.

Field Description

rollingRestart

Configures the rolling restart behavior for this HiveMQ Platform.

  • lastPodMinAgeSeconds: The minimum age in seconds that the last restarted pod must have before the next pod can be restarted during a rolling restart. When set, this overrides the global operator configuration. If not set, the global operator default of 30 seconds is used.
Example configuration to wait at least 5 minutes between pod restarts:
rollingRestart:
  lastPodMinAgeSeconds: 300
Setting lastPodMinAgeSeconds to 0 disables the delay between pod restarts for this platform.

Monitored Resources Configuration

The HiveMQ Platform Operator can monitor Kubernetes ConfigMaps and Secrets for changes and automatically trigger a rolling restart of the HiveMQ Platform pods when monitored resources are updated. This feature allows configuration changes to take effect without manual intervention. These configuration options require HiveMQ Platform Operator version 2.1.0 or higher.

Field Description

monitoredResources

Defines a list of Kubernetes ConfigMaps and Secrets to monitor for changes. When a file in a monitored resource changes, the HiveMQ Platform pods perform a rolling restart.

  • name: The name of the Kubernetes ConfigMap or Secret to monitor.

  • type: The type of Kubernetes resource. Valid values are ConfigMap or Secret.

  • files: Optional list of specific files within the resource to monitor. If not specified, all files in the resource are monitored.
Example configuration to monitor all files in a ConfigMap:
monitoredResources:
  - name: my-files-realm
    type: ConfigMap
Example configuration to monitor specific files in a Secret:
monitoredResources:
  - name: my-credentials-secret
    type: Secret
    files:
      - credentials.xml
      - keystore.jks
A rolling restart is not necessarily required for resources that support hot-reload. Check the reload capabilities of your configuration before you add it to monitored resources.

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

podScheduling

Configures how the HiveMQ Platform pods are placed on your Kubernetes nodes.

  • affinity: Optional setting that defines the affinity configuration for your HiveMQ Platform pods. Any valid affinity Kubernetes configuration can be used.

  • nodeSelector: Optional setting that defines the node selector configuration for your HiveMQ Platform pods. Constrains the HiveMQ Platform pods to run on Kubernetes nodes with matching labels.

  • priorityClassName: Optional setting that defines the priority class name for your HiveMQ Platform pods. The referenced Kubernetes PriorityClass must already exist in the cluster. Protects HiveMQ Platform pods from being preempted during cluster events such as node upgrades or autoscaling.

  • tolerations: Optional setting that defines the pod tolerations configuration for your HiveMQ Platform pods.
Example node affinity configuration:
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.

Example tolerations configuration:
  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.

Example command to set a taint for a Kubernetes worker node:
  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.

Pod Disruption Budget Options

A PodDisruptionBudget can be configured to limit the number of concurrent voluntary disruptions to the HiveMQ Platform pods. This protects the HiveMQ cluster from excessive simultaneous pod evictions during events such as node drains or cluster autoscaler scale-down.

The PodDisruptionBudget only affects voluntary disruptions that go through the Kubernetes Eviction API (for example, node drains or cluster autoscaler scale-down). The HiveMQ Platform Operator’s own rolling restart uses direct pod deletion and is not affected by this budget.
Field Description

podDisruptionBudget

Configures a PodDisruptionBudget for the HiveMQ Platform pods to control voluntary disruptions such as node drains or cluster autoscaler scale-down events.

  • enabled: Defines whether the PodDisruptionBudget resource is created for the HiveMQ Platform pods. Requires either minAvailable or maxUnavailable (but not both) to also be set.

  • maxUnavailable: Maximum number of HiveMQ Platform pods that can be unavailable during voluntary disruptions. Accepts an integer or a percentage string (for example, 1 or "25%"). Mutually exclusive with minAvailable.

  • minAvailable: Minimum number of HiveMQ Platform pods that must remain available during voluntary disruptions. Accepts an integer or a percentage string (for example, 2 or "50%"). Mutually exclusive with maxUnavailable.

  • unhealthyPodEvictionPolicy: Controls how the PodDisruptionBudget treats unhealthy HiveMQ Platform pods. Requires Kubernetes 1.26 or newer. Leave empty to use the cluster default. IfHealthyBudget only allows eviction of unhealthy pods if the budget is satisfied (can deadlock if pods crashloop). AlwaysAllow always allows eviction of unhealthy pods.
Example PodDisruptionBudget configuration:
podDisruptionBudget:
  enabled: true
  maxUnavailable: 1
  unhealthyPodEvictionPolicy: AlwaysAllow

The example podDisruptionBudget configuration ensures that at most one HiveMQ Platform pod is unavailable at any time during voluntary disruptions, and allows eviction of unhealthy pods regardless of the budget.

HiveMQ Platform Operator Selector Options

The operator section defines which HiveMQ Platform Operator manages this HiveMQ Platform cluster.

Avoid a configuration where more than one operator manages a HiveMQ Platform.
Field Description

operator

Provides the selection criteria to identify which operator manages the selected HiveMQ Platform custom resource.
The operator must have a matching label selector configuration.

  • selector: Selector name to configure which operator manages this platform. Use the selector value in the HiveMQ Platform Operator Helm chart to configure a matching label selector.

    This option creates an operator=<my-selector-value> label for the platform.

  • labels: Labels to add to the HiveMQ Platform custom resource. Labels can be used to configure which operator manages this platform. Use the selectors value in the HiveMQ Platform Operator Helm chart to configure matching label selectors.

  • annotations: Annotations to add to the 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

services

Defines the Kubernetes Service configuration for the HiveMQ Platform.

  • type: Specifies the type of service.
    Possible values are: control-center, mqtt, rest-api, websocket and metrics.

  • name: The optional custom name for the Kubernetes Service object. If unset, a default service name is generated with the following format: hivemq-<Helm release name>-<service type>-<service port>.

  • exposed: Boolean value that defines whether the service is exposed.

  • containerPort: Defines the port on the container to be used for the service.

  • port: Defines the port that the service exposes to external clients.

  • nodePort: Defines the port that the service exposes to external clients when the service type is set to NodePort. The port must be within the NodePort range configured for your cluster, and you are responsible for preventing port collisions. If left unset, Kubernetes automatically assigns a port. For more information, see NodePort.

  • serviceType: Defines the service type. Possible values are: ClusterIP, NodePort, or LoadBalancer.

  • externalTrafficPolicy: Configures whether the service routes incoming external traffic to node-local or cluster-wide endpoints. This setting applies only to NodePort and LoadBalancer service types.
    Possible values are: Cluster or Local. See External traffic policy for detailed information.

  • labels: Defines specific labels to be used by the service.

  • annotations: Defines specific annotations to be used by the service.

  • hivemqProxyProtocol: Boolean value that enables the HiveMQ PROXY protocol configuration for MQTT and WebSocket listeners. See PROXY protocol for detailed information.
    The default setting is false.

  • hivemqListenerName: Defines an optional custom name for the HiveMQ MQTT, WebSocket and REST API listeners. See HiveMQ listeners for detailed information.

  • path: Defines the last part of the path to the HiveMQ WebSocket listener. See HiveMQ WebSockets listeners for detailed information.

  • hivemqConnectOverloadProtection: Configures the connect overload protection for the HiveMQ MQTT and WebSocket listeners. For more information, see Connect Overload Protection.

    • enabled: Defines whether connect overload protection is enabled. Possible values are true and false. The default setting is true.

    • connectRate: The maximum sustained rate of CONNECT messages the listener allows per second. The connect rate cannot be set to 0 (zero). The default setting is 500.

    • connectBurstSize: The maximum number of simultaneous CONNECT messages the listener allows for short periods. The burst size cannot be set to 0 (zero). When no burst rate is specified, the listener allows a burst rate that is double the defined connect rate.

  • sessionAffinity: Defines the Session Affinity (session stickiness) for the Kubernetes Service. Possible values are: ClientIP or None. See Session Affinity for detailed information.

  • HiveMQ (m)TLS options for tls-tcp-listeners, tls-websocket-listeners and https Control Center listeners:

    • keystoreSecretName: Configures the name of a Kubernetes Secret with the keystore file.

    • keystoreSecretKey: Configures the key for the Kubernetes Secret used holding the keystore file.
      The default value is keystore.

    • keystorePassword: The base64 encoded password for the keystore.

    • keystorePrivatePassword: The optional base64 encoded private password for the keystore. If not set, the value defined in the keystorePassword is used.

    • keystorePasswordSecretName: Alternatively, the name of a Kubernetes Secret which contains the keystore password and optionally the private key password for the keystore.

    • keystorePasswordSecretKey: The optional entry key for the keystore password in the Kubernetes Secret. The default value is keystore.password.

    • keystorePrivatePasswordSecretKey: The optional entry key for the keystore private password in the Kubernetes Secret.

    • truststoreSecretName: Configures the name of a Kubernetes Secret with the truststore.
      Does not apply to https Control Center listeners.

    • truststoreSecretKey: Configures the key for the Kubernetes Secret used holding the truststore file.
      The default value is truststore.
      Does not apply to https Control Center listeners.

    • truststorePassword: The base64 encoded password for the truststore.
      Does not apply to https Control Center listeners.

    • truststorePasswordSecretName: Alternatively, the name of a Kubernetes Secret with the truststore password.
      Must use truststore.password as a key.
      Does not apply to https Control Center listeners.

    • truststorePasswordSecretKey: The optional entry key for the truststore password in the Kubernetes Secret. The default value is truststore.password.

    • tlsProtocols: Configures the optional settings to define the accepted TLS version.

    • tlsCipherSuites: Configures the optional settings to define the accepted cipher suites.

    • tlsClientAuthenticationMode: The way the HiveMQ Platform authenticates client certificates. Possible values are NONE, OPTIONAL and REQUIRED.
      The default value is NONE.
      Does not apply to https Control Center listeners.
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 REST API service using the created Kubernetes Secrets, include the following snippet in your platform-values.yaml:

services:
  - type: rest-api
    exposed: true
    containerPort: 8888
    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 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 add the truststore password to Kubernetes Secret, enter:

kubectl create secret generic hivemq-truststore-passwords \
      --from-literal=my.truststore.password="<truststore password>" \
      --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"
    truststorePasswordSecretName: "hivemq-truststore-passwords"
    truststorePasswordSecretKey: "my.truststore.password"
    tlsClientAuthenticationMode: "REQUIRED"
keystorePasswordSecretKey is optional. Default value is keystore.password.
keystorePrivatePasswordSecretKey is optional.
truststorePasswordSecretKey is optional. Default value is truststore.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"
    keystorePasswordSecretName: "hivemq-keystore-passwords"
    keystorePasswordSecretKey: "my.keystore.password"
    keystorePrivatePasswordSecretKey: "my.private.key"
    truststoreSecretName: "hivemq-truststore"
    truststorePasswordSecretName: "hivemq-truststore-passwords"
    truststorePasswordSecretKey: "my.truststore.password"
    tlsClientAuthenticationMode: "REQUIRED"
keystorePasswordSecretKey is optional. Default value is keystore.password.
keystorePrivatePasswordSecretKey is optional.
truststorePasswordSecretKey is optional. Default value is truststore.password.

To configure a secure REST API service using the created Kubernetes Secrets, include the following snippet in your platform-values.yaml:

services:
  - type: rest-api
    exposed: true
    containerPort: 8888
    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 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>

Monitoring Options

The HiveMQ Platform provides rich metrics that enable monitoring of day-to-day operations. Monitoring can be configured to integrate with Prometheus and Grafana.

Configure your Prometheus ServiceMonitor resource and deploy a Grafana dashboard ConfigMap to enable seamless integration of Metrics Options with your Prometheus monitoring stack.

For more information, see Monitoring with Prometheus.

Monitoring configuration options require that the Prometheus monitoring stack is installed in your Kubernetes cluster.
The ServiceMonitor uses the Kubernetes endpoints defined by the HiveMQ Platform metric service. The Prometheus port and path can be configured as explained in Metrics Options.
Field Description

monitoring

Enables the ServiceMonitor resource and Grafana dashboard creation for the platform.

  • enabled: Defines whether the monitoring configuration for the HiveMQ Platform is enabled.
    The default setting is false.

  • dashboard: Grafana dashboard configuration options.

    • create: Boolean value that configures whether to use the default HiveMQ Platform Grafana dashboard ConfigMap.
      The default setting is true.

    • namespace: Namespace where to deploy the Grafana dashboard ConfigMap. Defaults to the namespace of the HiveMQ Platform.

    • overrideDashboard: Sets the Grafana dashboard content for the HiveMQ Platform Grafana dashboard ConfigMap with your own JSON file from a specified path.

  • serviceMonitor: Prometheus ServiceMonitor configuration options.

    • namespace: Namespace where to deploy the ServiceMonitor. Defaults to the namespace of the HiveMQ Platform.

    • releaseName: Helm chart release name of the Prometheus Monitoring stack available in the Kubernetes cluster. Defaults to the HiveMQ Platform Helm chart release name.

    • interval: Defines how often Prometheus scrapes metrics from the operator endpoints.
      Valid formats include 1d, 1h30m, 5m, and 10s. Defaults to 15 seconds.

    • scrapeTimeout: Defines the maximum duration allowed for scraping metrics from the endpoints defined in the ServiceMonitor resource.
      Valid formats include 1d, 1h30m, 5m, and 10s. Defaults to 10 seconds.
If you use Argo CD as a continuous delivery tool, you may exceed the Kubernetes annotations size constraint of 256 KB when creating the default Grafana dashboard. Argo CD sets a kubectl.kubernetes.io/last-applied-configuration annotation that contains the JSON representation of the last applied object configuration. To fix this issue, configure the option to use Server Side Apply in your Argo CD yaml configuration: 
syncPolicy:
  syncOptions:
    - ServerSideApply=true

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

Metrics configuration options for the HiveMQ Prometheus extension.

  • enabled: Boolean value that defines whether the HiveMQ Prometheus extension is enabled.
    The default setting is true.

  • port: Defines the port the HiveMQ Prometheus extension uses.
    The default port is 9399.

  • path: Defines the URL path the HiveMQ Prometheus extension uses.
    The default path is /.

Example to disable metrics

To disable metrics, set the enabled flag to false.
This disables the Prometheus extension and prevents the creation of a Metrics Service in Kubernetes.

metrics:
  - enabled: false

Example to disable the metrics Service only

To disable the Metrics Service only, add a custom service of type metrics and set the expose flag to false.

metrics:
  - enabled: true
    port: 9399
    path: /

services:
  - type: metrics
    exposed: false
    containerPort: 9399

HiveMQ Platform License Options

Field Description

license

Defines all HiveMQ file-based licenses to be used for the HiveMQ Platform.
If no valid license is provided for the broker, HiveMQ uses a standard trial license with a limit of 25 connections. If no valid license is provided for an Enterprise Extension or Data Hub, HiveMQ uses a standard trial license with a limit of 5 hours. After the trial period, the extension is disabled and the Data Hub reverts to the Free mode or the installed license, depending on your configuration.

  • create: Creates a Kubernetes Secret for all configured HiveMQ file-based licenses. License data can be inlined with the data value or set from a file with the overrideLicense option. All configured licenses are placed in the same Kubernetes Secret.
    The default setting is false.

  • name: Defines the name of the Kubernetes Secret that contains the HiveMQ file-based licenses.

  • data: The main HiveMQ file-based license in an encoded 64-byte string.

  • labels: Defines custom labels for the Kubernetes Secret that contains the HiveMQ file-based licenses.

  • annotations: Defines custom annotations for the Kubernetes Secret that contains the HiveMQ file-based licenses.

  • isLicenseBase64Encoded: Indicates whether the license data is provided as Base64 encoded string (data) or plain string (stringData) for the Kubernetes Secret. The default setting is true and expects a Base64 encoded string.

  • overrideLicense: Sets the main HiveMQ file-based license with a custom license file. Use --set-file config.overrideLicense=<path-to-license-file> to specify the path.

  • additionalLicenses: Adds additional main HiveMQ file-based licenses to the Kubernetes Secret as .lic files, if applicable.

    • <license-name>: Defines the name of the additional main HiveMQ file-based license. A .lic suffix is added automatically. Replace the <license-name> with the license name of your choice.

      • data: The additional main HiveMQ file-based license in an encoded 64-byte string.

      • overrideLicense: Sets the additional main HiveMQ file-based license with a custom license file. Use --set-file config.overrideLicense=<path-to-license-file> to specify the path.

  • extensions: Defines a list of HiveMQ Enterprise Extension licenses to include as part of the Kubernetes Secret.

    • <extension-license-name>: Defines the name of the HiveMQ Enterprise Extension license in the Kubernetes Secret (an .elic suffix is added automatically). Replace the <extension-license-name> with the license name of your choice.

      • data: The HiveMQ Enterprise Extension license information in an encoded 64-byte string.

      • overrideLicense: Sets the HiveMQ Enterprise Extension license with your own file from a specified license path.

  • dataHub: Configures a list of HiveMQ Data Hub licenses to include as part of the Kubernetes Secret.

    • <data-hub-license-name>: Defines the name of the HiveMQ Data Hub license in the Kubernetes Secret (a .plic suffix is added automatically). Replace the <data-hub-license-name> with the license name of your choice.

      • data: The HiveMQ Data Hub license information in an encoded 64-byte string.

      • overrideLicense: Sets the HiveMQ Data Hub license with your own file from a specified license path.
Use additionalLicenses to install multiple HiveMQ file-based licenses simultaneously. This can be helpful when your existing HiveMQ file-based license is about to expire, and you need to verify that your renewed license is correct. For more information, see Multiple HiveMQ file-based licenses.

Example to configure HiveMQ file-based 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 file-based license, an additional HiveMQ file-based 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>

Example to configure a HiveMQ Platform license key

To configure a HiveMQ Platform with a platform license key, run a Helm command similar to the following example:

helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set config.platformLicense.licenseKey=<your-platform-license-key> -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

extensions

Configures the extensions for the HiveMQ Platform.

  • name: The defined name of the extension from the extensions.xml file.

  • enabled: Boolean value that defines whether the extension is enabled. Possible values are true and false.

  • supportsHotReload: Boolean value that specifies whether the extension configuration is hot-reloadable. The extension must explicitly support hot-reload.
    The default setting is false.

  • configMapName: Configures the name of the Kubernetes ConfigMap that contains the extension configuration. The ConfigMap must be located in the same namespace as your HiveMQ Platform.
    The operator mounts the ConfigMap to the extension-home/conf directory of the HiveMQ instance. /opt/hivemq/extensions/extension-home/conf/config.xml is the default naming and location for all HiveMQ Enterprise Extension configurations. For HiveMQ Enterprise Extensions, the ConfigMap with the configuration must use the name config.xml as the key.

  • secretName: Configures the name of the Kubernetes Secret that contains the extension configuration. The Secret must be located in the same namespace as your HiveMQ Platform.
    The operator mounts the Secret to the extension-home/conf directory of the HiveMQ instance. /opt/hivemq/extensions/extension-home/conf/config.xml is the default naming and location for all HiveMQ Enterprise Extension configurations. For HiveMQ Enterprise extensions, the Secret with the configuration must use the name config.xml as the key.

  • requestHeaderSecretName: Configures the name of the Kubernetes Secret that contains headers for HTTP requests for custom extension and extension customization downloads.

  • extensionUri: The location from which to load the extension.
    Possible values are: preinstalled or an HTTP URL.

  • customizationUri: The HTTP URL from which to load the extension customization. Currently, the HiveMQ Enterprise Extensions for Kafka, Google Pub/Sub, and Amazon Kinesis support a customizationUri option.

  • priority: The priority of the extension. For more information, see Extension Metadata.
    The default value is 1000.

  • startPriority: The start priority of the extension. For more information, see Extension Metadata.
    The default value is 1000.

  • startMandatory: Determines how the HiveMQ broker behaves if the startup of the extension fails. For more information, see Extension Metadata.
    The default value is false.

  • skipHttpsCertificateValidation: Boolean value to skip certificate validation when downloading a custom extension and extension customizations via the HTTPS protocol. The default setting is false.

  • skipHttpsHostnameVerification: Boolean value to skip hostname verification when downloading a custom extension and extension customizations via the HTTPS protocol. The default setting is false.

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>

Map-based extension configuration

As an alternative to the array-based extensions field, the extensionMap field provides a map-based configuration where the key is the extension name. This approach is useful when you manage multiple clusters with layered value files (for example, -f base.yaml -f region.yaml -f cluster.yaml), because you can override individual extension fields without duplicating the entire extension list.

Both extensions and extensionMap can be used together. When an extension name appears in both, the extensionMap values take precedence on a per-field basis. Extensions defined only in extensionMap are added as new entries.

Field Description

extensionMap

Map-based extension configuration. Keys are extension names. Entries override matching extensions array entries by name. Extensions defined only in extensionMap are added as new entries.

All fields from the extensions configuration are supported (except name, which is derived from the map key):

  • enabled

  • supportsHotReload

  • configMapName

  • secretName

  • requestHeaderSecretName

  • extensionUri

  • customizationUri

  • priority

  • startPriority

  • startMandatory

  • skipHttpsCertificateValidation

  • skipHttpsHostnameVerification

Setting a field to null removes it from the result, unless a later value file sets the same field to a non-null value. Setting an entire entry to null in an override file removes the extension entirely, unless a later value file redefines the entry.
Example: Base configuration with extensionMap

Define a shared base configuration for all clusters in a base-values.yaml file:

extensionMap:
  hivemq-enterprise-security-extension:
    enabled: true
    configMapName: hivemq-platform-ese-config
    supportsHotReload: true
  hivemq-kafka-extension:
    enabled: true
    configMapName: hivemq-kafka-configuration
    supportsHotReload: true
  hivemq-distributed-tracing-extension:
    enabled: true
    supportsHotReload: true
    configMapName: hivemq-platform-tracing-config
Example: Cluster-specific override

To disable the Kafka extension for a specific cluster, create a cluster-values.yaml file that overrides only the field you want to change:

extensionMap:
  hivemq-kafka-extension:
    enabled: false

Install or upgrade with layered value files:

helm upgrade --install my-hivemq-platform hivemq/hivemq-platform -f base-values.yaml -f cluster-values.yaml -n <namespace>

The Kafka extension retains all fields from base-values.yaml (configMapName, supportsHotReload) but enabled is overridden to false.

Example: Multiple override files

When you use more than two value files, each file can override specific fields independently. Later files in the command take precedence over earlier files for the same field.

For example, with a base, region, and cluster configuration:

# base-values.yaml
extensionMap:
  hivemq-kafka-extension:
    enabled: true
    configMapName: kafka-config
    supportsHotReload: false

# region-values.yaml - overrides supportsHotReload
extensionMap:
  hivemq-kafka-extension:
    supportsHotReload: true

# cluster-values.yaml - overrides enabled
extensionMap:
  hivemq-kafka-extension:
    enabled: false
helm upgrade --install my-hivemq-platform hivemq/hivemq-platform -f base-values.yaml -f region-values.yaml -f cluster-values.yaml -n <namespace>

The result for the Kafka extension is enabled: false (from cluster-values.yaml), supportsHotReload: true (from region-values.yaml), and configMapName: kafka-config (from base-values.yaml). Fields that are not mentioned in later files keep their values from earlier files.

Example: Remove an extension in a specific cluster

To remove an extension that is defined in the base configuration from a specific cluster, set the entry to null in the cluster-specific file:

extensionMap:
  hivemq-kafka-extension: null

The Kafka extension is not included in the resulting HiveMQ Platform custom resource for that cluster.

This works because the cluster-specific file is the last value file applied. If another file applied after it redefines the same entry with a non-null value, the extension is recreated using that file’s values. The general rule is the standard Helm precedence: the last value file wins.

Additional Volume Options

Field Description

additionalVolumes

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 configMap, csi, secret, emptyDir, persistentVolumeClaim, projected, and sharedPersistentVolumeClaim.

  • type: Defines the type of volume to be mounted.

  • name: The name of the Kubernetes resource backing the volume.
    Required for types configMap, secret, persistentVolumeClaim and sharedPersistentVolumeClaim. For persistentVolumeClaim and sharedPersistentVolumeClaim, this entry is used as the PersistentVolumeClaim name. For types csi, emptyDir and projected, name is used as the volume identifier only when mountName is not set (prefer setting mountName).

  • mountName: Defines the name of the volume mount to be used for the StatefulSet spec.
    For type sharedPersistentVolumeClaim, the mountName (or name, if not set) must match a volumeClaimTemplates entry.

  • containerName: The optional name of the container to which the volume is mounted.
    The default container name is hivemq.

  • path: Configures the path of 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 a subPath for a file to be mounted.
    The generated volume mount path is the concatenation of the path and subPath values.
    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. In such cases, a pod restart is required to apply changes.
    Not applicable for the sharedPersistentVolumeClaim type.

  • hivemqFolders: Redirects specific HiveMQ platform directories into named subfolders within the same PersistentVolumeClaim mount path.
    Each key selects a HiveMQ directory type and each value defines the subfolder name where that directory content is stored.
    The chart automatically sets the corresponding environment variable for each configured key.
    Only applicable when type is set to sharedPersistentVolumeClaim.
    A matching volumeClaimTemplates entry is required to ensure each pod in the StatefulSet gets its own PersistentVolumeClaim. The volumeClaimTemplates entry name must match the mountName (or name if mountName is not set).
    Available keys:

    • data: Configures the subfolder name for the HiveMQ data directory. Sets the HIVEMQ_DATA_FOLDER environment variable.

    • log: Configures the subfolder name for the HiveMQ log directory. Sets the HIVEMQ_LOG_FOLDER environment variable.

    • heapDump: Configures the subfolder name for the HiveMQ heap dump directory. Sets the HIVEMQ_HEAPDUMP_FOLDER environment variable.

    • backup: Configures the subfolder name for the HiveMQ backup directory. Sets the HIVEMQ_BACKUP_FOLDER environment variable.

    • audit: Configures the subfolder name for the HiveMQ audit log directory. Sets the HIVEMQ_AUDIT_FOLDER environment variable.

  • projectedSources: Configures sources for additional volumes of type projected.
    This entry must contain a list of the volume source configurations that the Kubernetes Projected Volumes support.

  • csi: Configures the Container Storage Interface (CSI) volume source.
    Required when type is set to csi.
    Available fields:

    • driver: The name of the CSI driver to use (e.g. secrets-store.csi.k8s.io). Required.

    • fsType: The filesystem type to mount (e.g. ext4, xfs, ntfs). The value is passed through to the CSI driver and the supported types depend on the driver and the host operating system.

    • nodePublishSecretRef: The name of the Kubernetes Secret to pass to the CSI driver for NodePublishVolume.

    • readOnly: Mounts the CSI volume as read-only.

    • volumeAttributes: Driver-specific key-value attributes passed through to the CSI driver.
Example to use a TLS keystore file that is defined in a Kubernetes Secret with 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
Example to use a shared PersistentVolumeClaim for multiple HiveMQ directories:

Configure your additionalVolumes and volumeClaimTemplates values in your values.yaml file. The volumeClaimTemplates entry ensures each pod in the StatefulSet gets its own PersistentVolumeClaim, which prevents data conflicts when multiple pods run simultaneously.

additionalVolumes:
  - type: sharedPersistentVolumeClaim
    name: hivemq-shared-pvc
    path: /opt/hivemq/pvc
    hivemqFolders:
      data: my-data
      log: my-log
      heapDump: my-dump
      backup: my-backup
      audit: my-audit
volumeClaimTemplates:
  - kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: hivemq-shared-pvc
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 10Gi
      volumeMode: Filesystem
nodes:
  podSecurityContext:
    enabled: true
    fsGroup: 0

This configuration provisions a dedicated PersistentVolumeClaim for each pod, mounts it at /opt/hivemq/pvc, and sets the following environment variables:

  • HIVEMQ_DATA_FOLDER=/opt/hivemq/pvc/my-data

  • HIVEMQ_LOG_FOLDER=/opt/hivemq/pvc/my-log

  • HIVEMQ_HEAPDUMP_FOLDER=/opt/hivemq/pvc/my-dump

  • HIVEMQ_BACKUP_FOLDER=/opt/hivemq/pvc/my-backup

  • HIVEMQ_AUDIT_FOLDER=/opt/hivemq/pvc/my-audit

The result stores the HiveMQ data, log, heap dump, backup, and audit directories as separate subfolders within a single PersistentVolumeClaim.

A matching volumeClaimTemplates entry with the same name as the sharedPersistentVolumeClaim is required. This ensures each pod gets its own isolated PersistentVolumeClaim, which is necessary to prevent multiple instances from sharing the same data directory.
Enable nodes.podSecurityContext with an fsGroup to allow the HiveMQ process to write to the mounted volume.
Example to consume externally managed secrets as environment variables, licenses, TLS keystores, or Control Center credentials with the Secrets Store CSI driver:

The Secrets Store CSI driver is a CNCF project that integrates external secret management systems such as Azure Key Vault, AWS Secrets Manager, GCP Secret Manager, and HashiCorp Vault with Kubernetes. It can synchronize the mounted external secrets into a regular Kubernetes Secret via the secretObjects field of the SecretProviderClass. Once synchronized, every HiveMQ Platform chart field that accepts a Kubernetes Secret reference (for example license.name, controlCenter.credentialsSecret, nodes.env[].valueFrom.secretKeyRef, TLS keystoreSecretName, Data Hub licenses, and so on) can consume the synchronized Secret without any additional chart configuration. This pattern keeps the chart cloud-agnostic while allowing customers to store sensitive values in Azure Key Vault, AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault as the single source of truth.

The following example synchronizes two secrets from HashiCorp Vault into a Kubernetes Secret named hivemq-synced-secrets and consumes them as an environment variable and as Control Center credentials.

First, define the SecretProviderClass with a secretObjects section that describes the synchronized Secret:

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: hivemq-external-secrets
  namespace: <your-namespace>
spec:
  provider: vault
  secretObjects:
    - secretName: hivemq-synced-secrets
      type: Opaque
      data:
        - objectName: mqtt-password
          key: mqtt-password
        - objectName: cc-password
          key: cc-password
  parameters:
    vaultAddress: "http://vault.vault:8200"
    roleName: "hivemq-role"
    objects: |
      - objectName: "mqtt-password"
        secretPath: "secret/data/hivemq"
        secretKey: "mqtt-password"
      - objectName: "cc-password"
        secretPath: "secret/data/hivemq"
        secretKey: "cc-password"

Then configure the HiveMQ Platform chart to mount the CSI volume (which triggers the synchronization) and to consume the synchronized Secret through existing chart fields:

additionalVolumes:
  - type: csi
    mountName: external-secrets
    path: /mnt/secrets
    csi:
      driver: secrets-store.csi.k8s.io
      readOnly: true
      volumeAttributes:
        secretProviderClass: hivemq-external-secrets
nodes:
  env:
    - name: MQTT_DEFAULT_PASSWORD
      valueFrom:
        secretKeyRef:
          name: hivemq-synced-secrets
          key: mqtt-password
controlCenter:
  credentialsSecret:
    name: hivemq-synced-secrets
    usernameKey: cc-username
    passwordKey: cc-password
The Secrets Store CSI driver and a matching provider (e.g. Azure, AWS, GCP, or Vault) must be installed on the Kubernetes cluster before using this volume type.
When using workload identity, ensure the HiveMQ pod uses a ServiceAccount with the appropriate identity annotations. Set nodes.serviceAccountName in your values to reference the configured ServiceAccount.
The synchronized Secret is only created and maintained while at least one Pod is mounting the corresponding SecretProviderClass volume. Always include the additionalVolumes entry in the Pod that consumes the synchronized Secret to ensure it exists and stays up to date.
The same pattern applies to other chart fields that accept a Secret reference, such as license.name, extensions[].licenses, dataHub.license.name, and TLS keystoreSecretName / truststoreSecretName.

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

additionalInitContainers

An optional list of additional Init containers that run before or alongside the HiveMQ container in the HiveMQ Platform pod. Any valid Kubernetes container configuration can be used.

additionalContainers

An optional list of additional containers that run alongside the HiveMQ container in the HiveMQ Platform pod. Any valid Kubernetes container configuration can be used.
Example Sidecar Container configuration:
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

volumeClaimTemplates

A list of the Persistent Volume Claims (PVC) that HiveMQ Platform pods should reference. Configure additionalVolumes of type persistentVolumeClaim to mount the Persistent Volumes.
Example Persistent Volume Claim configuration:
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 hivemq-pvc-data persistent volume 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.

Helm Telemetry Configuration

The HiveMQ Platform includes telemetry configuration options that provide insight into product usage. These insights help the HiveMQ team improve product quality, performance, and overall user experience.

Field Description

telemetry

Defines the Helm telemetry configuration for the HiveMQ Platform.

  • anonymousUsageStatistics: Configures the collection of anonymous usage statistics.

    • enabled: A boolean value that enables or disables the collection of anonymous usage statistics.
      The default setting is true.
Example configuration to disable the statistics collection:
telemetry:
  anonymousUsageStatistics:
    enabled: false

Helm Test Configuration

The HiveMQ Platform Helm chart can include test pod definitions to validate connectivity to your HiveMQ Platform after installation or upgrade. When enabled, the Helm chart renders test resources that can be executed with the helm test command. Running helm test creates a test pod for each exposed MQTT service that connects to the service and verifies that the connection is successful.

Field Description

testing

Defines the Helm test configuration for the HiveMQ Platform.

  • enabled: Boolean value to enable the creation of Helm test pods. When set to true, a test pod is created for each exposed MQTT service to verify connectivity. When set to false, no test pods are rendered, and a helm test command does not run any tests.
    The default setting is true.
Example configuration to enable Helm tests:
testing:
  enabled: true

To run the Helm tests after you install your HiveMQ Platform, enter:

helm test <your-hivemq-platform> -n <namespace>
Helm tests only verify basic MQTT connectivity to each exposed service. For comprehensive testing procedures, see the Test Your HiveMQ Platform section.

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

  1. Create a kubectl port-forward to access your MQTT port:

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

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

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

  3. 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.

  1. Create an additional port-forward for the Control Center:

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

  2. 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.

Verify the HiveMQ Helm charts

We sign the HiveMQ Helm charts with PGP keys during the packaging. These signed charts have a .prov file generated alongside the packaged chart, which includes the chart and the signature.

To verify the authenticity of the charts, download the HiveMQ public PGP key and import the public key into your GPG keyring. Then use helm verify or helm install --verify command to verify the chart integrity.

Helm does not support GPG version 2 or higher so you have to convert your GPG keyring to the legacy GPG format before verifying. 
gpg --export >~/.gnupg/pubring.gpg
Example commands to verify a HiveMQ Platform chart:
curl -L -o public.pgp https://www.hivemq.com/public.pgp
gpg --import public.pgp
gpg --export >~/.gnupg/pubring.gpg
curl -L -o hivemq-platform-x.y.z.prov https://github.com/hivemq/helm-charts/releases/download/hivemq-platform-x.y.z/hivemq-platform-x.y.z.tgz.prov
curl -L -o hivemq-platform-x.y.z.tgz https://github.com/hivemq/helm-charts/releases/download/hivemq-platform-x.y.z/hivemq-platform-x.y.z.tgz
helm verify hivemq-platform-x.y.z.tgz