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/q/metrics.

Platform Operator Configuration Options with Helm

You can configure how Helm installs your HiveMQ Platform Operator.
The Helm chart’s values.yaml file defines the default values and configuration parameters that are available.

  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 container image is pulled.

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

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

  • initImageName: the name of the 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 512m.

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

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 secret or configMap.

  • name: The name of an environment variable.

  • value: The value of an environment variable.

  • valueFrom: The reference to a secret of configMap that defines the environmental variable.

    • secretKeyRef or `configMapKeyRef:

      • name: The name of a secret deployed.

      • key: The key to be used within the secret.

      • optional: Whether the secret has to exist. Default is false.

The default setting is an empty list.

javaOpts

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 security context for the operator process in the pod.

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

selector

Sets a selector label that limits the operator to manage only HiveMQ platforms with a matching selector label.
If no selector is set, the operator manages all HiveMQ platforms across all Kubernetes namespaces.
The default setting is nil (not set).

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 are available with this label, 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 are available with a matching taint, the operator is not installed and remains in a pending state.

HTTP Endpoint Options

The HiveMQ Platform Operator exposes an HTTP/HTTPS endpoint.
If desired, you can use the API with webhooks. Metrics are exposed on http://<address>/q/metrics.

To use the API with webhooks, you must configure an HTTPS port.
Field Description

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.

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 secret that contains the keystore and truststore files for TLS.
    The default value is nil.

  • keystorePassword: The password for the keystore.
    If the keystorePassword value is not set, the keystore.password value in the secret is used.
    The default value is nil.

  • truststorePassword: The password for the truststore.
    If the truststorePassword value is not set, the truststore.password value in the secret is used.
    The default value is nil.

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 HiveMQPlatform 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 production installations, see our minimum requirements.

  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=8G
    In a production deployment, the HiveMQ platform process requires a minimum of 4G of memory. Additionally, the HiveMQ process should not consume more than 50% of the available memory. As a result, the minimum memory configuration for the container resources is 8G.

    For detailed information on the configuration options the HiveMQ Platform Helm Charts offers, see HiveMQ Platform Configuration Options with Helm.

  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 Helm chart deploys the config.xml file as a Kubernetes ConfigMap to your Kubernetes namespace.

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 required settings for the HealthAPI, cluster configuration and align the listener configuration with your services.
To learn more about how to configure a HiveMQ platform for your use case, 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 image to be used.

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

  • pullPolicy: Defines the imagePullPolicy that Kubernetes uses to download the 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.
The HiveMQ Platform Operator is compatible with all standard HiveMQ container images published by HiveMQ starting with HiveMQ 4.19.
Example to create a secret for the 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"

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.

  • 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 either key-value pairs or using valueFrom to reference a secret or config map.

    • name: The name of an environment variable.

    • value: The value of an environment variable.

    • valueFrom: The reference to a secret of configMap that defines the environmental variable.

      • secretKeyRef or `configMapKeyRef:

        • name: The name of a secret deployed.

        • key: The key to be used within the secret.

        • optional: Whether the secret has to exist. Default is false.

  • serviceAccountName: The name of a custom service account to be used by the 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 1024m.

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

podSecurityContext

Configures the podSecurity settings of the HiveMQ process.
The container image needs to support the configured user and group.

  • enabled: Boolean value that enables the podSecurity 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'.

HiveMQ Platform Configuration Options

The HiveMQ Platform Helm chart installs a default HiveMQ configuration as a Kubernetes ConfigMap. Many standard HiveMQ configuration options are supported by the Helm chart for your convenience.

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

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

hivemqRestrictions

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

  • maxConnections: The global MQTT client connection limit for HiveMQ.
    The default setting is -1. (unlimited)

  • incomingBandwidthThrottling: The maximum amount of incoming traffic for MQTT clients as bytes per second (b/s)+ The default setting is 0. (unlimited)

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

  • maxClientIdLength: The maximum number of characters HiveMQ accepts in an MQTT client ID+ The default setting is 65535.
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.
    The default setting is "4294967295".

  • messageExpiryMaxInterval: Defines the maximum message expiry in seconds that clients can set.
    The default setting is "4294967296".

  • maxPacketSize: Defines the maximum packet size in bytes that the broker accepts from clients.
    The default setting is "268435460".

  • serverReceiveMaximum: Defines the maximum number of concurrent publishes the broker accepts from one client.
    The default setting is 10.

  • keepAliveMax: Defines the maximum keep alive value in seconds.
    The default setting is 65535.

  • keepAliveAllowUnlimited: Defines whether clients can have unlimited keep alive.
    The default setting is true.

  • topicAliasEnabled: Defines whether clients can use topic aliases.
    The default setting is true.

  • topicAliasMaxPerClient: Defines the maximum number of topic aliases a client can use.
    The default setting is 5.

  • subscriptionIdentifier: Defines whether clients can use subscription identifiers.
    The default setting is true.

  • wildcardSubscriptions: Defines whether clients can use wildcard characters in topic filters.
    The default setting is true.

  • sharedSubscriptions: Defines whether clients can use shared subscriptions.
    The default setting is true.

  • maxQualityOfService: Defines the maximum Quality of Service level allowed.
    The default setting is 2.

  • retainedMessages: Defines whether retained messages are supported.
    The default setting is true.

  • queuedMessagesMaxSize: Defines the maximum number of messages that are queued per client.
    The default setting is 1000.

  • queuedMessagesStrategy: Defines how queued messages are handled . Possible values [discard, discard-oldest]
    The default setting is "discard".
Field Description

hivemqMqttAddons

These settings configure MQTT add-on options for HiveMQ. See MQTT add-on options for detailed information.

  • expiredMessagesTopic: Captures all expired messages to the $expired namespace.
    The default setting is false.

  • droppedMessagesTopic: Captures all dropped messages to the $dropped namespace.
    The default setting is false.

  • deadMessagesTopic: Captures all dead messages to the $dead namespace.
    The default setting is false.
Field Description

hivemqMqttSecurity

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

  • allowEmptyClientId: Allows the use of empty client ids. If allowed HiveMQ generates random client ids.
    The default setting is true.

  • payloadFormatValidation: Enables the UTF-8 validation of UTF-8 PUBLISH payloads.
    The default setting is false.

  • utf8Validation: Enables the UTF-8 validation of topic names and client ids.
    The default setting is true.

  • allowRequestProblemInformation: Allows the client to request problem information.
    The default setting is true.

  • controlCenterAuditLog: Enables audit logging for the Control Center.
    The default setting is true.
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.

The following configuration options are provided 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 specified as a Kubernetes ConfigMap.

  • 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 with a valid HiveMQ configuration. Set create to false to use this option.

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

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

Example to overwrite the HiveMQ configuration

The HiveMQ configuration can be set from a file via the command line. For more information on how to configure HiveMQ, see the HiveMQ User Guide.

helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set-file config.overrideHiveMQConfig=config.xml -n <namespace>

Example to overwrite the Kubernetes StatefulSet

The StatefulSet spec configuration can be set from a file via the command line. For more information, see StatefulSetSpec:

helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set-file config.overrideStatefulSet=stateful-set-spec.yaml -n <namespace>

Example custom StatefulSetSpec configuration:

spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: hivemq
          image: hivemq/hivemq4:4.23.0
          imagePullPolicy: IfNotPresent
      ports:
        - containerPort: 1883
          name: mqtt-1883-<release-name>
        - containerPort: 8080
          name: cc-8080-<release-name>
        - containerPort: 9399
          name: metrics-<release-name>
When you define a custom StatefulSetSpec, make sure that ports and services match between your Service configuration, StatefulSpec configuration, and HiveMQ listener configuration. For example, the container port must match the service name section. Port names can contain a maximum of 15 characters and cannot end with a -.
When using the override configuration option config.overrideStatefulSet for your custom StatefulSetSpec or config.overrideHiveMQConfig for your custom HiveMQ configuration, all other configuration options for StatefulSetSpec and HiveMQ configuration are ignored.

Pod Scheduling Options

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

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

Field Description

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.

Operator Selector Options

The operator.selector label defines which HiveMQ Platform Operator manages this HiveMQ Platform cluster. See the matching selector label of the operator configuration.

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

operator

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

  • selector: Defines the operator selector label of the HiveMQ platform.
    The default setting is nil.

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.

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, and websocket.

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

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

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

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

    • keystoreSecretKey: Configures the key for the 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 secret with the truststore.
      Does not apply to https Control Center listeners.

    • truststoreSecretKey: Configures the key for the 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 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 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 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 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 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 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 secret holding 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 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 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 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>

HiveMQ Platform License Options

Field Description

license

Configures the licenses to be used.
If no valid license is provided, HiveMQ uses a standard trial license with a limit of 25 connections.

  • create: Creates a HiveMQ Platform license as a Kubernetes Secret, based on the content specified in the data value of this section. The default setting is false.

  • name: Configures the name of the Kubernetes Secret that contains the license information.

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

  • overrideLicense: Sets the license with your own file by specifying the XML path.

Example to set the HiveMQ license from a file

helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set-file license.overrideLicense=files/license.lic -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.

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

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

Example extension configuration

To configure the HiveMQ Enterprise Extension for Kafka, create a ConfigMap of the Kafka configuration with the name config.xml as the key:

kubectl create configmap hivemq-kafka-configuration --from-file=config.xml=your-config-file.xml

To configure request headers for an authenticated download of the extensionUri or customizationUri, create a secret with the header names as keys:

kubectl create secret generic github-auth-token-secret --from-literal="Authorization=Bearer YOUR-TOKEN" --from-literal="X-GitHub-Api-Version=2022-11-28"

Configure the Kafka extension with a customization in your platform-values.yml file:

extensions:
  - name: hivemq-kafka-extension
    enabled: true
    supportsHotReload: true
    configMapName: "hivemq-kafka-configuration"
    requestHeaderSecretName: "github-auth-token-secret"
    extensionUri: preinstalled
    customizationUri: https://github.com/example/my-kafka-customization/releases/download/1.0.0/my-kafka-customization-1.0.0.zip

To install or upgrade the HiveMQ Platform with the extension, enter:

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

Additional Volume Options

Field Description

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

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

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

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

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.