Configuration Options

You can configure the HiveMQ Platform Operator and the HiveMQ platform cluster to fulfill your individual use case. HiveMQ provides two easy-to-use preconfigured Helm charts, one for the HiveMQ Platform Operator and one for the HiveMQ Platform.
For detailed information on all available configuration options, see HiveMQ Platform Operator Configuration with Helm and HiveMQ Platform Configuration with Helm .

You can also deploy the HiveMQ platform directly by providing the custom resource manifest with the necessary ConfigMaps. This gives you greater flexibility to configure HiveMQ for your use case. For more information, see Custom Resources.
If you make changes to the HiveMQ config.xml configuration ConfigMap, the operator initiates a rolling update of your HiveMQ platform to apply the changes. To maintain a steady load distribution during the upgrade, the operator starts a new HiveMQ pod before it shuts down and upgrades the existing HiveMQ pods. This process temporarily increases the HiveMQ platform cluster by one pod. The additional HiveMQ pod requires proportionally more system resources. For example, enough CPUs, memory, and disk storage need to be available. Once the rolling update is complete, the HiveMQ cluster returns to the configured number of pods and resources.

HiveMQ Platform Operator Configuration with Helm

The Helm chart for the HiveMQ Platform Operator installs the custom resource definition (CRD) for the HiveMQ Platform object on Kubernetes.
The Platform Operator Helm chart also installs the DeploymentSet of the operator, the operator pod, and the necessary RBAC permissions for the operator to manage your HiveMQ platforms on Kubernetes.

To customize your operator installation, export the possible configuration values to a file and edit the file to fit your needs.

To view the possible configuration values for the HiveMQ Platform Operator, enter:

helm show values hivemq/hivemq-platform-operator > operator-values.yml

To apply the changes you make to the operator-values.yml file, enter:

helm upgrade --install my-hivemq-operator hivemq/hivemq-platform-operator -f operator-values.yml -n <namespace>
Example operator-values.yml file:
# HiveMQ Platform Operator Helm Chart default values

# Container image configuration
image:
  repository: docker.io/hivemq
  name: hivemq-platform-operator
  tag: 1.0.0
  initImageName: hivemq-platform-operator-init
  pullPolicy: IfNotPresent
  pullSecretName: ""

# Resources, limits and requests are set to equal values
# Note: Increase resources depending on how many HiveMQ Platforms this operator manages.
resources:
  cpu: 512m
  memory: 256M
  ephemeralStorage: 5Gi

# Configures the log level, possible values are: "TRACE", "DEBUG", "INFO", "WARN", "ERROR".
logLevel: INFO

# Configures the operator ports for http/s. These ports provide access to metrics and other services.
http:
  port: 8080
https:
  port: 8443

# Configures the Java JVM runtime options for the process.
javaOpts: "-XX:+UnlockExperimentalVMOptions -XX:InitialRAMPercentage=75 -XX:MaxRAMPercentage=75"

# Selector name that is used to watch HiveMQ platforms that have a matching selector.
selector: nil

# Configures whether Kubernetes RBAC permissions are created.
rbac:
  create: true

# Configures the service account for Kubernetes RBAC permissions.
serviceAccount:
  # Specifies whether a service account is created.
  create: true
  # The service account name to be used, or "hivemq-<release name>" if not set.
  name: ""

# Configures how the operator pod is scheduled on the Kubernetes cluster nodes.
podScheduling:
  # Kubernetes node affinity configuration
  affinity:
  # podAffinity:
  #    requiredDuringSchedulingIgnoredDuringExecution:
  #      - labelSelector:
  #          matchExpressions:
  #            - key: app
  #              operator: In
  #              values:
  #                - my-app
  #        topologyKey: "kubernetes.io/hostname"

  # Configures the tolerations for the operator pod
  tolerations:
  #  - key: "example-key"
  #    operator: "Exists"
  #    effect: "NoSchedule"

# TLS configuration for the operator to access the Kubernetes API.
tls:
  # Name of the secret that contains keystore and truststore
  secretName: nil
  # The keystore password. Can also be set as "keystore.password" in the secret.
  keystorePassword: nil
  # The truststore password. Can also be set as "truststore.password" in the secret.
  truststorePassword: nil

# Operator security context, requires that the image supports the configured user.
podSecurityContext:
  enabled: false
  runAsNonRoot: true
  runAsUser: 1000

HiveMQ Resource and Image Options

Field Description

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 associated with the variant of the container image 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 this 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 256M.

  • ephemeralStorage: Sets the size of the disk for the operator. Adjust this setting depending on how much disk space is needed.
    The default setting is 5Gi.

javaOpts

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

securityContext

Configures the security context for the operator process in the Kubernetes pod.

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

selector

Sets a selector label to limit the platforms the operator is allowed to manage to HiveMQ platforms that have 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 Options

Field Description

logLevel

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

To view your HiveMQ Platform Operator log output, enter:

kubectl logs deployment/hivemq-platform-operator-<release-name>

Role-Based Access Control Options

To be able to manage your HiveMQ platforms, the operator needs access permissions to Kubernetes resources on your cluster.
By default, the operator Helm chart creates a new service account and the required RBAC permissions.
It is possible to override the default permissions.

Field Description

rbac

Configures the RBAC permissions created on Kubernetes.

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

serviceAccount

Configures which service account is used for RBAC Permissions on Kubernetes.

  • create: Boolean value that determines whether a service account is created.
    The default setting is true.

  • name: The optional name of an existing service account to use.
    By default, a service account with the name hivemq-<release name> is created.

Pod Scheduling Options

Node affinity and tolerations can be configured to control on which Kubernetes worker node the operator pod is placed. Node affinity can be used to optimize workload placement, ensure resource requirements are met, or achieve other scheduling-related goals. All valid Kubernetes node podAffinity and antiPodAffinity options are supported.

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

Field Description

podScheduling

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

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

  • tolerations: Optional setting that defines the pod tolerations configuration for your operator pod.
Example node affinity configuration:
  affinity:
    podAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchExpressions:
              - key: app
                operator: In
                values:
                  - my-app
          topologyKey: "kubernetes.io/hostname"

The example podAffinity configuration specifies that the operator pod can only be deployed on Kubernetes nodes that have the label my-app. If no nodes are available with the my-app label, the operator is not installed and remains in a pending state.
If pod labels change during runtime, the operator remains in a running state.

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

HiveMQ Platform Configuration with Helm

The Helm chart for the HiveMQ Platform installs one HiveMQ platform cluster with the configured number of HiveMQ nodes as a custom resource and a ConfigMap that contains the HiveMQ config.xml configuration for the nodes.

The operator observes the deployment of the new custom resource and creates the HiveMQ platform cluster as defined.

The HiveMQ platform cluster is deployed using a StatefulSet that controls how many HiveMQ nodes are installed.
The services that are needed to access the MQTT port and the HiveMQ Control Center are also installed.

If you want to customize your operator installation, export the possible configuration values to a file and edit the file to fit your needs.

To view the possible configuration values for the HiveMQ Platform, enter:

helm show values hivemq/hivemq-platform > platform-values.yml

To apply changes that you make to the platform-values.yml file, enter:

helm upgrade --install my-hivemq-platform hivemq/hivemq-platform -f platform-values.yml -n <namespace>
Example platform-values.yml file
# HiveMQ Platform Helm Chart default values

# HiveMQ Platform container image configuration
image:
  repository: docker.io/hivemq
  name: hivemq4:4.22.0
  pullPolicy: IfNotPresent
  pullSecretName: ""

# Provides the HiveMQ Platform configuration (config.xml) as a Kubernetes ConfigMap.
config:
  # Creates a new ConfigMap with a standard config.xml.
  create: true
  # Provides the name of the ConfigMap that contains a custom "config.xml" (set create=false).
  name: ""
  # Inlines the config.xml and overrides the default ConfigMap configuration.
  overrideHiveMQConfig: ""
  # Inlines the StatefulSet configuration and overrides the default StatefulSet.
  overrideStatefulSet: ""

# Selector name that is used to match the selector of the managing operator.
# This selector assigns the HiveMQ Platform to a specific operator.
operator:
  selector: nil

# Settings for the HiveMQ platform nodes
nodes:
  # The number of HiveMQ nodes in the cluster
  replicaCount: 2
  logLevel: DEBUG
  javaOpts: "-XX:+UnlockExperimentalVMOptions -XX:InitialRAMPercentage=50 -XX:MaxRAMPercentage=50"

  # Resources, limits and requests are set to equal values.
  # Note: For production use cases, HiveMQ requires a minimum of 4 CPUs and 4G of memory.
  #       See: https://docs.hivemq.com/hivemq/latest/user-guide/system-requirements.html#minimum
  resources:
    cpu: 1024m
    memory: 2048M
    ephemeralStorage: 10Gi

  # Requires that the image provides support for the configured user.
  podSecurityContext:
    enabled: false
    runAsNonRoot: true
    runAsUser: 10000

# Configure exposed Services and ports
# Possible service types are: "control-center", "rest-api", "mqtt", "websocket"
services:
  # MQTT port
  - type: mqtt
    exposed: true
    containerPort: 1883
    # Set if service port is different from the container port
    port: 1883
  # TLS MQTT port
  - type: mqtt
    exposed: false
    containerPort: 8883
    # The name of the Kubernetes secret that contains the keystore file.
    keystoreSecretName: ""
    # The inlined password for the keystore, Base 64 encoded.
    keystorePassword: ""
    # The key of the Kubernetes secret that contains the keystore file. Defaults to `keystore`
    keystoreSecretKey: ""
    # Alternatively, the name of the secret with the password, using the key: "keystore.password".
    keystorePasswordSecretName: ""
    # The name of the Kubernetes secret that contains the truststore file.
    truststoreSecretName: ""
    # The key of the Kubernetes secret that contains the truststore file. Defaults to `truststore`
    truststoreSecretKey: ""
    # The inlined password for the truststore, Base 64 encoded.
    truststorePassword: ""
    # Alternatively, the name of the secret with the password, using the key: "truststore.password".
    truststorePasswordSecretName: ""
    # The way HiveMQ platform authenticates client certificates. Possible values are `NONE`, `OPTIONAL` and `REQUIRED`
    tlsClientAuthenticationMode: "NONE"
  # ControlCenter port
  - type: control-center
    exposed: true
    containerPort: 8080
  # RestAPI port
  - type: rest-api
    exposed: false
    containerPort: 8888
  # Websocket port
  - type: websocket
    exposed: false
    containerPort: 8001

# Configures the HiveMQ license information.
license:
  # The name of a secret with the license information. Add all required licenses into the secret.
  name: ""
  # Inlines the license information as an encoded 64-byte string.
  data: ""
  # Overrides the license information via file using --set-file license.lic.
  overrideLicense: ""

# Overrides the default Control Center username and password.
# Set both values to override the default configuration.
controlCenter:
  username: ""
  # Password as SHA256 HASH. See password generation:
  # https://docs.hivemq.com/hivemq/latest/control-center/configuration.html#generate-password
  password: ""

# HiveMQ platform extension configuration
extensions:
  # By default, HiveMQ is installed with the allow-all extension to permit all MQTT connections for testing.
  # For production, add a security extension and disable this extension.
  - name: hivemq-allow-all-extension
    extensionUri: preinstalled
    # Disable the extension (enabled=false), to secure your deployment.
    enabled: true
    supportsHotReload: false

  # HiveMQ Enterprise Extension for Kafka
  - name: hivemq-kafka-extension
    extensionUri: preinstalled
    enabled: false
    # The Kafka extension supports hot-reload of the configuration.
    supportsHotReload: true
    # The ConfigMap name that contains the Kafka extension configuration.
    configMapName: ""

  # HiveMQ Enterprise Extension for Google Pub/Sub
  - name: hivemq-google-cloud-pubsub-extension
    extensionUri: preinstalled
    enabled: false
    # The Google Pub/Sub extension supports hot-reload of the configuration.
    supportsHotReload: true
    # The ConfigMap name that contains the Google Pub/Sub extension configuration.
    configMapName: ""

  # HiveMQ Enterprise Extension for Amazon Kinesis
  - name: hivemq-amazon-kinesis-extension
    extensionUri: preinstalled
    enabled: false
    # The Amazon Kinesis extension supports hot-reload of the configuration.
    supportsHotReload: true
    # The ConfigMap name that contains the Amazon Kinesis extension configuration.
    configMapName: ""

  # HiveMQ Enterprise Security Extension
  - name: hivemq-enterprise-security-extension
    extensionUri: preinstalled
    enabled: false
    # The Security extension does not support hot-reload of the configuration.
    supportsHotReload: false
    # The ConfigMap name that contains the Security extension configuration.
    configMapName: ""

  # HiveMQ Enterprise Distributed Tracing Extension
  - name: hivemq-distributed-tracing-extension
    extensionUri: preinstalled
    enabled: false
    # The Tracing extension supports hot-reload of the configuration.
    supportsHotReload: true
    # The ConfigMap name that contains the Tracing extension configuration.
    configMapName: ""

  # HiveMQ Enterprise Extension for MongoDB
  - name: hivemq-mongodb-extension
    extensionUri: preinstalled
    enabled: false
    # The MongoDB extension does not support hot-reload of the configuration.
    supportsHotReload: false
    # The ConfigMap name that contains the MongoDB extension configuration.
    configMapName: ""

  # HiveMQ Enterprise Extension for PostgreSQL
  - name: hivemq-mysql-extension
    extensionUri: preinstalled
    enabled: false
    # The PostgreSQL extension does not support hot-reload of the configuration.
    supportsHotReload: false
    # The ConfigMap name that contains the PostgreSQL extension configuration.
    configMapName: ""

  # HiveMQ Enterprise Extension for MySQL
  - name: hivemq-postgresql-extension
    extensionUri: preinstalled
    enabled: false
    # The MySQL extension does not support hot-reload of the configuration.
    supportsHotReload: false
    # The ConfigMap name that contains the MySQL extension configuration.
    configMapName: ""

  # HiveMQ Enterprise Bridge Extension
  - name: hivemq-bridge-extension
    extensionUri: preinstalled
    enabled: false
    # The Bridge extension does not support hot-reload of the configuration.
    supportsHotReload: false
    # The ConfigMap name that contains the Bridge extension configuration.
    configMapName: ""

# Map additional volumes from possible types: "configMap", "secret", "emptyDir", "persistentVolumeClaim".
additionalVolumes: [ ]
#  - type: configMap
#    name: configmap-name
#    mountName: mount-name
#    path: /file/mount/path
#    subPath: ""

# type: Choose a type of volume that you want to mount.
# name: Optional name for the secret or the ConfigMap to be mounted
# mountName: The mountName to be used for the StatefulSet Spec.
# path: The path configures the directory to which the volume is mounted in the container
#       If the directory already exists then the contents are overwritten!
# subPath: Optional name for the subPath. If a volume is mounted with subPath, the content
#          of the directory is not overwritten. However, changes such as a change to a ConfigMap
#          mounted via subPath are not propagated to the container. Therefore, pods have to be restarted.
When you change a list in the configuration, you must provide the entire list again. Otherwise, the previously configured list items are overwritten. For example, you must submit the full list of configured extensions each time you make changes to your list of extensions. The operator automatically applies your changes.

HiveMQ Container Image Options

Field Description

image

Configure the container image details for the HiveMQ Platform.

  • repository: Configure from which repository the HiveMQ platform image is pulled.

  • name: The name of the image to be used.

  • 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.
Example to create a secret for the GitHub ghcr registry:
kubectl create secret docker-registry ghcr \
    --docker-server=ghcr.io \
    --docker-username="$GITHUB_USER_NAME" \
    --docker-password="$GITHUB_PAT" \
    --docker-email="$GITHUB_EMAIL"

HiveMQ Platform Config Options

Field Description

config

Defines how the HiveMQ platform configuration is specified as a 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: Convenience option to provide the HiveMQ configuration from a file, using --set-file config.overrideConfig=your-hivemq-config.xml.

  • overrideStatefulSet: Convenience option to provide the StatefulSetSpec configuration from a file, using --set-file config.overrideStateFulSet=your-statefulsetspec.yml.

controlCenter

Override the default username and password for the ControlCenter, when using the default configuration.

  • username: The name of the Control Center user.

  • password: The SHA256 encoded password for the Control Center user. See password generation for more information.

Example to overwrite the HiveMQ configuration

The HiveMQ configuration can be set from a file via the command line. For more information, see HiveMQ Configuration:

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

Example to overwrite the Kubernetes StatefulSet

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

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

Example custom StatefulSetSpec configuration:

spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: hivemq
          image: hivemq/hivemq4:4.19.0
          imagePullPolicy: IfNotPresent
      ports:
        - containerPort: 1883
          name: mqtt-1883-<release-name>
        - containerPort: 8080
          name: cc-8080-<release-name>
        - containerPort: 9399
          name: metrics-<release-name>
When you define a custom StatefulSetSpec, make sure that ports and services match between the Service configuration and the StatefulSpec configuration. For example, the container port must match the service name section. Port names can contain a maximum of 15 characters and cannot end with a -.

Pod Scheduling Options

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

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

Field Description

podScheduling

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

  • affinity: Optional setting that defines the pod affinity configuration for your HiveMQ platform pods. Any valid podAffinity and antiPodAffinity Kubernetes configuration can be used.

  • tolerations: Optional setting that defines the pod tolerations configuration for your HiveMQ platform pods.
Example node affinity configuration:
  affinity:
    podAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchExpressions:
              - key: app
                operator: In
                values:
                  - my-app
          topologyKey: "kubernetes.io/hostname"

The example podAffinity configuration specifies that the HiveMQ platform pods can only be deployed on Kubernetes nodes that have the label my-app. If no nodes are available with the my-app label, the HiveMQ platform pods are not installed and remain in a pending state.
If pod labels change during runtime, the HiveMQ platform pods remains in a running state.

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

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.

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=60 -XX:MaxRAMPercentage=60.

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.

  • ephemeralStorage: The size of the disk available to HiveMQ.
    Production deployments of HiveMQ require a minimum of 900 IOPS and a disk size of 100Gi or more depending on the use-case.
    To facilitate local testing, the default setting is 10Gi.

podSecurityContext

Configures the podSecurity settings of the HiveMQ process.
The container image must support the configured user and setup.

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

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

Service Options

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-listeners:

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

    • keystoreSecretKey: Configures the key for the secret used holding the keystore file.
      Uses <keystore> as a default key.

    • keystorePassword: The base64 encoded password for the keystore.

    • keystorePasswordSecretName: Alternatively, the name of a secret with the keystore password.
      Use <keystore.password> as a key.

    • truststoreSecretName: Configures the name of a secret with the truststore.
      Use <truststore> as a key.

    • truststoreSecretKey: Configures the key for the secret used holding the truststore file.
      Uses <truststore> as a default key.

    • truststorePassword: The base64 encoded password for the truststore.

    • truststorePasswordSecretName: Alternatively, the name of a secret with the truststore password.
      Use <truststore.password> as a key.

    • tlsClientAuthenticationMode: The way HiveMQ platform authenticates client certificates. Possible values are NONE, OPTIONAL and REQUIRED.
The truststore and keystore secrets can be reused for different listeners/services.
If the keystore or truststore password changes, a rolling restart is required.

Example TLS configuration

The HiveMQ platform can be configured to support TLS and mTLS. For further details on how to configure HiveMQ with TLS see the TLS Listener configuration.

To add a secret with the truststore to Kubernetes, enter:

kubectl create secret generic mqtt-keystore --from-file=keystore=keystore.jks

To configure a service include this snippet in your platform-values.yaml:

services:
  - type: mqtt
    exposed: true
    containerPort: 8883
    keystoreSecretName: "mqtt-keystore"
    keystorePassword: "<password>"
    truststoreSecretName: "mqtt-truststore"
    truststorePassword: "<password>"

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

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

HiveMQ Platform License Options

Field Description

license

Configures the licenses to be used.
If not set HiveMQ uses a standard trial license.

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

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

  • setLicense: Sets the license with your own file by setting the XML path.

Example to set the HiveMQ license from a file

helm upgrade --install <my-hivemq-platform> hivemq/hivemq-platform --set-file license.setLicense=files/license.lic -n <namespace>

HiveMQ Extension Configuration Options

Extensions add functionality to the HiveMQ broker that allows the broker to integrate with other systems.
The HiveMQ Platform Helm Chart and HiveMQ Platform Operator support two types of extensions:

  • Preinstalled HiveMQ Enterprise Extensions.

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

Field Description

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 defines whether the extension configuration can be hot-reloaded. 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 the specification of a customizationUri.
    The default value is "".

  • priority: The priority of the extension. For more information, see Extension Metadata.

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

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. 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: Defines the name of the ConfigMap or secret to be mounted. The name is not needed for emptyDir or persistentVolumeClaim volumes.

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

  • path: Defines the path of the directory to which the volume is mounted.

  • subPath: Defines an optional subPath for a file to be mounted.
If the directory to which a volume is mounted already exists, the contents of the directory are overwritten.
If a volume is mounted with subPath, the contents of the directory are not overwritten.
However, changes to a ConfigMap that are mounted via subPath are not propagated to the container.