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.

      Helm offers additional command line options to support the installation:

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

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

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

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

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

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

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

      kubectl get crds hivemq-platforms.hivemq.com

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

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

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

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

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

    6. To access the available operator metrics, enter:

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

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

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

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

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.

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.

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.

  • 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

The controller tag is hivemq-controller for all metrics. The state tag is all state values of the HiveMQ custom resource status.

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

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 prefixed with operator.sdk. A detailed description is available in the Operator SDK metrics documentation.

Example Java Operator SDK metrics:
operator.sdk.reconciliations.success.total{group="hivemq.com",kind="HiveMQPlatform",name="my-platform",namespace="default",scope="namespace",version="v1",} 451.0
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

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.

    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.

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

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 username and password 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.
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.

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

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

    • behaviorValidationEnabled: Optional setting to enable behavior validation.
      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 using the override configuration option config.overrideStatefulSet for your custom StatefulSetSpec or config.overrideHiveMQConfig for your custom HiveMQ configuration, all other configuration options for StatefulSetSpec and HiveMQ configuration are ignored.

Pod Scheduling Options

Node affinity and tolerations can be configured to control on which Kubernetes worker nodes the HiveMQ Platform pods are placed. Node affinity can be used to optimize workload placement, ensure resource requirements are met, or achieve other scheduling-related goals. All valid Kubernetes affinity options are supported.

Tolerations work together with taints to ensure that pods are not scheduled onto inappropriate nodes.

Field Description

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.

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

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.

  • 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 and WebSocket listeners. See HiveMQ 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.

    • 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 Control Center service using the created Kubernetes Secrets, include the following snippet in your platform-values.yaml:

services:
  - type: control-center
    exposed: true
    containerPort: 8443
    keystoreSecretName: "hivemq-keystore"
    keystorePassword: "<keystore base64 encoded password>"
    keystorePrivatePassword: "<keystore base64 encoded private key>"
keystorePrivatePassword is optional. Set only when it is different from the keystore password.

To install or upgrade the HiveMQ Platform Helm chart, enter:

helm upgrade --install my-hivemq-platform hivemq/hivemq-platform -f platform-values.yaml -n <namespace>
Example with base64 encode passwords stored in a Kubernetes Secret

To add the keystore and truststore files to Kubernetes Secret with passwords in your values.yaml configuration, enter:

kubectl create secret generic hivemq-keystore --from-file=keystore=keystore.jks --namespace="<namespace>"
kubectl create secret generic hivemq-truststore --from-file=truststore=truststore.jks --namespace="<namespace>"

To add the keystore password and optionally the keystore private password to Kubernetes Secret, enter:

kubectl create secret generic hivemq-keystore-passwords \
      --from-literal=my.keystore.password="<keystore password>" \
      --from-literal=my.keystore.private.password="<keystore private key>" \
      --namespace="<namespace>"

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

services:
  - type: mqtt
    exposed: true
    containerPort: 8883
    keystoreSecretName: "hivemq-keystore"
    keystorePasswordSecretName: "hivemq-keystore-passwords"
    keystorePasswordSecretKey: "my.keystore.password"
    keystorePrivatePasswordSecretKey: "my.private.key"
    truststoreSecretName: "hivemq-truststore"
    truststorePassword: "<truststore base64 encoded password>"
    tlsClientAuthenticationMode: "REQUIRED"
keystorePasswordSecretKey is optional. Default value is keystore.password.
keystorePrivatePasswordSecretKey is optional.

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

services:
  - type: websocket
    exposed: true
    containerPort: 8000
    keystoreSecretName: "hivemq-keystore"
    keystorePasswordSecretName: "hivemq-keystore-passwords"
    keystorePasswordSecretKey: "my.keystore.password"
    keystorePrivatePasswordSecretKey: "my.private.key"
    truststoreSecretName: "hivemq-truststore"
    truststorePassword: "<truststore base64 encoded password>"
    tlsClientAuthenticationMode: "REQUIRED"
keystorePasswordSecretKey is optional. Default value is keystore.password.
keystorePrivatePasswordSecretKey is optional.

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

services:
  - type: control-center
    exposed: true
    containerPort: 8443
    keystoreSecretName: "hivemq-keystore"
    keystorePasswordSecretName: "hivemq-keystore-passwords"
    keystorePasswordSecretKey: "my.keystore.password"
    keystorePrivatePasswordSecretKey: "my.private.key"
keystorePasswordSecretKey is optional. Default value is keystore.password.
keystorePrivatePasswordSecretKey is optional.

To install or upgrade the HiveMQ Platform Helm chart, enter:

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

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

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

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

  • annotations: Defines custom annotations for the Kubernetes Secret that contains the HiveMQ 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 license with your own file from a specified license path.

  • additionalLicenses: Adds additional main HiveMQ licenses to the Kubernetes Secret as .lic files, if needed.

    • <license-name>: Defines the name of the additional main HiveMQ license (a .lic suffix is added automatically). Replace the <license-name> with the license name of your choice.

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

      • overrideLicense: Sets the additional main HiveMQ license with your own file from a specified license 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.
Using additionalLicenses allows you to use multiple HiveMQ licenses simultaneously. This can be helpful when your existing HiveMQ license is about to expire and you need to verify that your renewed license is correct. For more information, see Multiple HiveMQ Licenses.

Example to configure HiveMQ licenses from several license files

To configure a HiveMQ Platform with all possible licenses, run a Helm command similar to the following example. The example defines a HiveMQ license, an additional HiveMQ license, a HiveMQ Enterprise Extension license, and a HiveMQ Data Hub license:

helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set license.create=true --set-file license.overrideLicense=files/license.lic --set-file license.additionalLicenses=files/additional-license.lic --set-file license.dataHub.license.overrideLicense=files/license.plic --set-file license.extensions.kafka.overrideLicense=files/kafka-license.elic -n <namespace>

HiveMQ Extension Configuration Options

Extensions add functionality to the HiveMQ broker that allows the broker to integrate with external systems, such as databases, data lakes, queues, or security systems.
The HiveMQ Platform Helm Chart and HiveMQ Platform Operator support two types of extensions:

  • Preinstalled HiveMQ Enterprise Extensions.

  • Extensions that are downloaded from a remote server via HTTP.

Field Description

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.

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

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

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

  • name: The optional name of a Kubernetes ConfigMap or Secret to be mounted.
    The name is ignored for type emptyDir, persistentVolumeClaim and projected.

  • mountName: Defines the name of the volume mount to be used for the StatefulSet spec.

  • 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, the pods must be restarted.

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

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.

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