Configure Your HiveMQ Cluster

The following configuration descriptions assume that you are using Helm to manage your deployment of the HiveMQ Operator and HiveMQ Cluster custom resource on Kubernetes. You can also use a different method to create and manage your manifests manually.

When you use the default configuration of the HiveMQ Helm Chart to deploy the HiveMQ Kubernetes Operator, the operator automatically creates a HiveMQ Cluster custom resource on your Kubernetes cluster.
For most use cases, you need to adjust some configuration settings. For more information, see our recommended settings.

Basic Configuration

Set HiveMQ License File

  1. Create a ConfigMap that contains your license file:

    kubectl create configmap hivemq-license --from-file=/path/to/my-license.lic
  2. Configure the mapping in your HiveMQ Cluster custom resource:

apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  configMaps:
  - name: hivemq-license
    path: /opt/hivemq/license

HiveMQ Extensions

Add and Remove Extensions

By default, your HiveMQ deployment includes the Prometheus, DNS discovery, and HiveMQ allow-all extensions. Use the extensions field in your custom values.yaml file to install additional extensions such as the HiveMQ Enterprise Extension for Kafka or the HiveMQ Enterprise Security Extension.

extensions:
  - name: hivemq-kafka-extension
    extensionUri: https://www.hivemq.com/releases/extensions/hivemq-kafka-extension-1.1.0.zip
    configMap: kafka-configuration
    enabled: true
Table 1. Extension configuration options
Property Name Description

name

The name of the extension.

extensionUri

The URL where to the extension is stored. For example, the HiveMQ Marketplace or a publicly available URL.

configMap

The name of the ConfigMap that stores the configuration files for your extension. For more information, see Configuration of Extensions.

enabled

Sets the desired state of the selected extension.

static

Defines whether the extension is restarted when the linked ConfigMap changes. The default setting is false.

initialization

An (idempotent) initialization script that runs when the extension is installed or updated. The default setting is an undefined string. If you edit the script, the script automatically re-executes.

updateStrategy

Defines whether updates to the extension are processed in series or in parallel. The default setting is serial.

If you want to add a custom extension, consider using a Continuous Deployment pipeline to release the extension to a cluster-internal object storage such as MinIO. You can link to public objects or the extension URI to your artifact storage.

To add multiple extensions to your HiveMQ cluster, specify a list of extensions. Each extension must have a name, extension URI and an enabled flag.

To remove an extension from your HiveMQ deployment, remove the extension declaration in your custom values yaml file. For more information see, Revise HiveMQ Cluster Configuration with Helm.

Enable / Disable Extensions at Runtime

Removing an extension usually leads to a rolling upgrade of your HiveMQ deployment. Sometimes, it makes sense to disable an extension instead of removing it from the cluster. To disable or enable a HiveMQ extensions at runtime, change the enabled flag of the extension in your custom values yaml file. For more information, see Revise HiveMQ Cluster Configuration with Helm.

Extension Configuration with a ConfigMap

HiveMQ extensions are configured with configuration files. To allow the HiveMQ Kubernetes Operator to manage the extension configuration files, you provide the extension configuration in a ConfigMap.

A ConfigMap is a Kubernetes API object that lets you store and share non-sensitive, unencrypted configuration information. ConfigMaps allow you to decouple your configurations from your Pods and components, which helps keep your workloads portable.

Plain text values in your ConfigMaps are not encrypted. Do not use ConfigMaps for confidential information such as passwords, OAuth tokens, or SSH keys.

ConfigMaps provide a data section where you can store items (keys) and their values.

ConfigMaps cannot be added at run-time. Adding, removing, or editing the configMap field initiates a rolling upgrade of the CR.

Create a ConfigMap

The following procedure shows you how to place the open-source message log extension into a ConfigMap that a HiveMQ Cluster configuration references.
1. Save the example ConfigMap yaml file to your local file system as myConfig.yaml.

Example ConfigMap yaml file
apiVersion: v1
kind: ConfigMap
data:
  mqttMessageLog.properties: |-
    verbose=true
    client-connect=false
metadata:
  labels:
    app: hivemq
  name: config-extension
2. To create the ConfigMap in Kubernetes, enter:
kubectl apply -f myConfig.yaml
3. Copy the HiveMQ Cluster configuration to HiveMQ extensions section of your values yaml file.

This example creates the following HiveMQ Cluster extension configuration that references the ConfigMap that contains your extension configuration information.

Example HiveMQ Cluster extension configuration
    - name: hivemq-mqtt-message-log-extension
      configMap: config-extension
      enabled: true
      extensionUri: https://www.hivemq.com/releases/extensions/hivemq-mqtt-message-log-extension-1.1.0.zip
      static: true
      updateStrategy: serial
Each time you change the ConfigMap, the HiveMQ operator automatically initiates a rolling update of the extension configuration.

Add Prometheus Monitoring Integration

The HiveMQ Kubernetes Operator provides seamless integration with the Prometheus Operator. Use the monitoring field to enable Prometheus and associated Grafana dashboard:

apiVersion: hivemq.com/v1
kind: HiveMQCluster
spec:
  monitoring:
    enablePrometheus: true
You must configure the serviceMonitorSelector of your Prometheus manifests to pick up the HiveMQ ServiceMonitor. Otherwise, Prometheus does not scrape the target.
Currently, when you deploy a Prometheus operator with the HiveMQ Helm Chart, multiple skipping unknown hook: “crd-install” warnings are logged. These warnings can be ignored.

Define Initialization Routines

You can pre-provision your HiveMQ container with init containers.

Use the initialization field in your custom resource to append init containers to your HiveMQ deployment:

apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  hivemqVersion: latest
  initialization:
  - name: init-plugin
    args:
      - wget https://www.hivemq.com/releases/extensions/hivemq-file-rbac-extension-4.0.0.zip;
        unzip hivemq-file-rbac-extension-4.0.0.zip -d /hivemq-data/extensions

All init containers provide a volume mount on /hivemq-data. The volume mount allows you to add files and folder structures that are recursively copied to the HiveMQ directory when the container starts.

To facilitate specification of basic script steps, the initialization field uses the default image busybox:latest and command ["/bin/sh", "-c"].
Ownership and file mode changes to the files in /hivemq-data can be overwritten upon startup.

Set Resource Limits and Requests

By default, your HiveMQ deployment sets sensible resource limits. To override the default resource limits, use the following fields:

Resource Default Description

cpuLimitRatio

2

Ratio of the CPU limit. For example, a ratio setting of 2 = cpu: 500m → limit ⇒ 1000m.

cpu

500m

Amount of CPU requested

memoryLimitRatio

1

Ratio for the memory limit. This ratio is usually 1.

memory

4096M

Amount of memory requested

ephemeralStorageLimitRatio

1

Ratio for the ephemeral storage limit

ephemeralStorage

10Gi

Amount of ephemeral disk space requested. By default, the HiveMQ data folder uses this amount.
This space is used for the whole container. The usable storage size for HiveMQ is slightly smaller than the configured value.

Configure HiveMQ Ports

In the root of the specification, you can use the ports field to configure which ports are mapped to your pods. To map a port, use the following fields:

Field Description

name

The name of the port

port

The port number that is exposed

expose

Creates a service that points to the selected port. The naming schema is: hivemq-<cluster-name>-<port-name>.

patch

A list of strings with JSON patches that are applied to the resulting service when expose is set to true.

The default values for the ports field are as follows:

apiVersion: hivemq.com/v1
kind: HiveMQCluster
spec:
  ports:
    - name: "mqtt"
      port: 1883
      expose: true
      patch:
      - '[{"op":"add","path":"/spec/selector/hivemq.com~1node-offline","value":"false"},{"op":"add","path":"/metadata/annotations","value":{"service.spec.externalTrafficPolicy":"Local"}}]'
      # If you want Kubernetes to expose the MQTT port
      # - '[{"op":"add","path":"/spec/type","value":"LoadBalancer"}]'
    - name: "cc"
      port: 8080
      expose: true
      patch:
      - '[{"op":"add","path":"/spec/sessionAffinity","value":"ClientIP"}]'
      # If you want Kubernetes to expose the HiveMQ control center via load balancer.
      # Warning: You should consider configuring proper security and TLS beforehand. Ingress may be a better option here.
      # - '[{"op":"add","path":"/spec/type","value":"LoadBalancer"}]'

Configure Your HiveMQ Cluster

Field Default Description

clusterReplicaCount

2

The number of copies the cluster maintains for each piece of persistent data. A replica count of 2 = one original and one copy.

clusterOverloadProtection

true

Automatically reduces the rate of incoming messages from message producing MQTT clients that significantly contribute to the overload of the cluster.

nodeCount

3

the number of cluster nodes in the HiveMQ cluster.

For more information on high availability clustering with HiveMQ, see HiveMQ Clusters.

TLS Listener

This procedure shows you how to configure and verify a TLS listener. You can create the necessary server and client certificates and the corresponding keystores with the keytool and OpenSSL command line tools.

This sample procedure is not intended for production use. For more information, see TLS for your cloud-based MQTT broker.
1. To generate keystore, enter:
keytool -genkey -keyalg RSA -alias hivemq -keystore hivemq.jks -storepass changeme -validity 360 -keysiz
2. To generate the secret, in the same namespace as the cluster, enter:
kubectl create secret generic --from-file=hivemq.jks hivemq-jks
3. Either edit your custom values.yaml, or edit your HiveMQ cluster CR directly:
kubectl edit hivemq-cluster <my-cluster>
4. In the cluster specification, add mapping in the secrets area to mount the key store into the configuration directory:
  secrets:
  - name: hivemq-jks
    path: /opt/hivemq/conf
5. In the cluster specification, add the new listener in the listenerConfiguration field:
   <tls-tcp-listener>
        <port>8883</port>
        <bind-address>0.0.0.0</bind-address>
        <proxy-protocol>true</proxy-protocol>
        <tls>
            <keystore>
                <path>/opt/hivemq/conf/hivemq.jks</path>
                <password>changeme</password>
                <private-key-password>changeme</private-key-password>
            </keystore>
        </tls>
    </tls-tcp-listener>
6. In the cluster specification, edit the mqtt port so that it corresponds to the new listener.
  - expose: true
    name: mqtt
    patch:
    - '[{"op":"add","path":"/spec/selector/hivemq.com~1node-offline","value":"false"},{"op":"add","path":"/metadata/annotations","value":{"service.spec.externalTrafficPolicy":"Local"}}]'
    port: 8883
You must always specify a port named mqtt as this port will be used for the liveness check of the resulting Pods.
7. Apply or save your changes. To verify your changes, wait until the status of your cluster returns to RUNNING and enter:
kubectl port-forward svc/hivemq-hivemq-mqtt-tls 8883:8883
8. To connect, enter:
mqtt sub -p 8883 -t test --cafile server.pem -d

Configure HiveMQ

This section lists specific sections of the config.xml that are represented in the HiveMQ Custom Resource Definition.

You must specify these parameters in the restrictions, mqtt, and security section in your manifest:

apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  mqtt:
    maxQos: 1

If you need to edit the config.xml of your deployment at a more granular level, use the configOverride field.

To ensure HiveMQ can still interact with the operator correctly, start with the default value of the configOverride field when you make low-level changes to the configuration.

Restrictions

Field Value Description

maxClientIdLength

65535

The maximum number of characters HiveMQ accepts in an MQTT-client ID

maxTopicLength

65535

The maximum number of characters HiveMQ accepts in a topic string

maxConnections

-1

The maximum number of MQTT connections HiveMQ allows. A setting of -1 = unlimited.

incomingBandwidthThrottling

0

The maximum incoming traffic as bytes per second (b/s)

noConnectIdleTimeout

10000

The time in seconds that HiveMQ waits for the CONNECT message of a client before closing an open TCP socket

For more information, see Throttling and Limits.

MQTT Options

Field Value Description

sessionExpiryInterval

4294967295

The amount of time, in seconds, that can pass after the client disconnects before the session expires

maxPacketSize

268435460

The maximum size, in bytes, of MQTT packet that the HiveMQ broker accepts

serverReceiveMaximum

10

The maximum number of PUBLISH messages that are not yet acknowledged by the HiveMQ broker each client can send

keepaliveMax

65535

The maximum value that the HiveMQ broker accepts in the keepAlive field in the CONNECT packet of an MQTT client

keepaliveAllowUnlimited

true

Allows connections from clients that send a CONNECT packet with a keepAlive=0 setting

topicAliasEnabled

true

To reduce the packet size of PUBLISH messages, an alias can replace the topic. Topic aliases must be number between 1 and 65535. '0' is not allowed.

topicAliasMaxPerClient

5

Limits the number of topic aliases per client

subscriptionIdentifierEnabled

true

Associates an identifier with every topic filter in a SUBSCRIBE message

wildcardSubscriptionEnabled

true

Defines whether the HiveMQ broker accepts subscriptions with a topic filter that use wildcard characters

sharedSubscriptionEnabled

true

Defines whether the HiveMQ broker supports shared subscriptions

retainedMessagesEnabled

true

Defines whether the retained messages feature is enabled on the HiveMQ broker

maxQos

2

Defines the maximum Quality of Service (QoS) level that can be used in MQTT PUBLISH messages

queuedMessagesMaxQueueSize

1000

Limits the number of messages the HiveMQ broker queues per client

queuedMessageStrategy

discard

Defines how the HiveMQ handles new messages for a client when the queue of the client is full

For more information, see MQTT Specific Configuration Options.

Security

Field Value Description

allowEmptyClientId

true

Allows the use of empty client IDs. If this is set to true, HiveMQ automatically generates a random client ID when the clientId of a CONNECT packet is empty.

payloadFormatValidation

false

Enables UTF-8 validation of UTF-8 PUBLISH payloads

topicFormatValidation

true

Enables UTF-8 validation of topic names and client IDs

allowRequestProblemInformation

true

Allows the client to request problem information. If this is set to false, no reason string and user property values are sent to clients.

For more information, see the Security Configuration section of MQTT Configuration.

Allow-all Extension

By default, the HiveMQ Docker image comes with the allow-all extension that permits all MQTT connections without requiring authentication. Before you use HiveMQ in production, add an appropriate security extension and remove the HiveMQ allow-all extension.
To disable the extension, set the HIVEMQ_ALLOW_ALL_CLIENTS environment variable to false:

apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  env:
  - name: HIVEMQ_ALLOW_ALL_CLIENTS
    value: "false"

For more information, see Default Authentication Behaviour

Use a HiveMQ Custom Image

Currently, the HiveMQ Operator renders the hivemqVersion as the image tag.

apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  hivemqVersion: latest
  image: my-repo/hivemq-k8s-image

NOTE: If necessary, You can also define `imagePullPolicy`.

Specify Log Level

Use the logLevel field to specify the log level for the root logger:

apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  logLevel: INFO

Specify Custom Java Options

To specify java flags such as GC options or network properties, use the javaOptions field.

The default value of the javaOptions field works well on most environments:
-XX:+UnlockExperimentalVMOptions -XX:InitialRAMPercentage=40 -XX:MaxRAMPercentage=50 -XX:MinRAMPercentage=30.

Specify Custom Environment Variables

To append custom variables to the existing environment of the HiveMQ container, use the env field:

apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  env:
  - name: TEST_VAR
    value: FOO

Use a Custom Controller Template

The HiveMQ Operator supports the use of custom controller templates to deploy HiveMQ. Custom templates make it possible to use controllers such as StatefulSet and DaemonSet for your cluster deployments.

The method is similar to how Helm templates are written, but instead of gotemplate the HiveMQ operator uses a Jinja-like language (Jinjava).

The context provided to the template consists of the HiveMQCluster object (variable name spec) as well as some built-in templating functions.

apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  controllerTemplate: "my-deployment.yaml"

Deployments can be YAML based (.yaml, .yml) or JSON based (.json).

Template Functions

The the template context provides built-in functions for some common tasks:

  • util:escapeJson(String): Escapes a given input string to be JSON compliant

  • util:indent(Integer, String): Indents the given multi-line input string for YAML templates

  • util:getPort(ClusterSpec, String): Returns the port object for the given port name

  • util:stringReplace(String, String, String): Runs replaceAll on the first argument and replaces the 2nd argument string with the 3rd argument string.

  • util:render(ClusterSpec, String): Renders a given string with the same templating context as the template itself. For example, renders a custom property from the cluster specification.

Custom Variables

You can also specify additional properties on the HiveMQCluster specification:

apiVersion: hivemq.com/v1
kind: HiveMQCluster
metadata:
  name: hivemq-cluster1
spec:
  customProperties:
    myCustomProperty: "customValue"

This value can be used in custom templates. For example, {{ spec.customProperties.myCustomProperty }}.
In this example, the value evaluates to customValue.

HiveMQ Custom Resource Patches

Use these files as a basis for your own custom resource file structures. The sample files include patches that you can use to update your HiveMQ Cluster deployment is various ways:

  • Install and configure your extensions

  • Configure your HiveMQ licenses

  • Configure how ports are mapped and exposed

for more information, see Patch Kubernetes objects.

Configuration Override Patch

The example config-override.yaml patch shows how you can override the default config.xml template of your HiveMQ cluster custom resource. The override is useful when you need to configure detailed parameters that are not included in the hivemqCluster.json schema.

To demonstrate how block scalar strings are formatted for this kind of structure, the patch file applies the default template that is configured in the hivemqCluster.json schema.

Example comfig-override.yaml patch
apiVersion: hivemq.com/v1
kind: HiveMQCluster
spec:
  configOverride: |-
    <?xml version="1.0"?>
    <hivemq>
      <listeners>
        --LISTENER-CONFIGURATION--
      </listeners>
      <control-center>
        <listeners>
          <http>
            <port>${HIVEMQ_CONTROL_CENTER_PORT}</port>
            <bind-address>0.0.0.0</bind-address>
          </http>
        </listeners>
        <users>
          <user>
            <name>${HIVEMQ_CONTROL_CENTER_USER}</name>
            <password>${HIVEMQ_CONTROL_CENTER_PASSWORD}</password>
          </user>
        </users>
      </control-center>
      <cluster>
        <transport>
          --TRANSPORT_TYPE--
        </transport>
        <enabled>true</enabled>
        <discovery>
          <extension>
            <reload-interval>${HIVEMQ_DNS_DISCOVERY_INTERVAL}</reload-interval>
          </extension>
        </discovery>
        <replication>
          <replica-count>${HIVEMQ_CLUSTER_REPLICA_COUNT}</replica-count>
        </replication>
        <overload-protection>
          <enabled>${HIVEMQ_CLUSTER_OVERLOAD_PROTECTION}</enabled>
        </overload-protection>
      </cluster>
      <restrictions>
        <max-client-id-length>${HIVEMQ_MAX_CLIENT_ID_LENGTH}</max-client-id-length>
        <max-topic-length>${HIVEMQ_MAX_TOPIC_LENGTH}</max-topic-length>
        <max-connections>-${HIVEMQ_MAX_CONNECTIONS}</max-connections>
        <incoming-bandwidth-throttling>${HIVEMQ_INCOMING_BANDWIDTH_THROTTLING}</incoming-bandwidth-throttling>
        <no-connect-idle-timeout>${HIVEMQ_NO_CONNECT_IDLE_TIMEOUT}</no-connect-idle-timeout>
      </restrictions>
      <mqtt>
        <session-expiry>
          <max-interval>${HIVEMQ_SESSION_EXPIRY_INTERVAL}</max-interval>
        </session-expiry>
        <packets>
          <max-packet-size>${HIVEMQ_MAX_PACKET_SIZE}</max-packet-size>
        </packets>
        <receive-maximum>
          <server-receive-maximum>${HIVEMQ_SERVER_RECEIVE_MAXIMUM}</server-receive-maximum>
        </receive-maximum>
        <keep-alive>
          <max-keep-alive>${HIVEMQ_KEEPALIVE_MAX}</max-keep-alive>
          <allow-unlimited>${HIVEMQ_KEEPALIVE_ALLOW_UNLIMITED}</allow-unlimited>
        </keep-alive>
        <topic-alias>
          <enabled>${HIVEMQ_TOPIC_ALIAS_ENABLED}</enabled>
          <max-per-client>${HIVEMQ_TOPIC_ALIAS_MAX_PER_CLIENT}</max-per-client>
        </topic-alias>
        <subscription-identifier>
          <enabled>${HIVEMQ_SUBSCRIPTION_IDENTIFIER_ENABLED}</enabled>
        </subscription-identifier>
        <wildcard-subscriptions>
          <enabled>${HIVEMQ_WILDCARD_SUBSCRIPTION_ENABLED}</enabled>
        </wildcard-subscriptions>
        <shared-subscriptions>
          <enabled>${HIVEMQ_SHARED_SUBSCRIPTION_ENABLED}</enabled>
        </shared-subscriptions>
        <quality-of-service>
          <max-qos>${HIVEMQ_MAX_QOS}</max-qos>
        </quality-of-service>
        <retained-messages>
          <enabled>${HIVEMQ_RETAINED_MESSAGES_ENABLED}</enabled>
        </retained-messages>
        <queued-messages>
          <max-queue-size>${HIVEMQ_QUEUED_MESSAGE_MAX_QUEUE_SIZE}</max-queue-size>
          <strategy>${HIVEMQ_QUEUED_MESSAGE_STRATEGY}</strategy>
        </queued-messages>
      </mqtt>
      <security>
        <!-- Allows the use of empty client ids -->
        <allow-empty-client-id>
          <enabled>${HIVEMQ_ALLOW_EMPTY_CLIENT_ID}</enabled>
        </allow-empty-client-id>
        <!-- Configures validation for UTF-8 PUBLISH payloads -->
        <payload-format-validation>
          <enabled>${HIVEMQ_PAYLOAD_FORMAT_VALIDATION}</enabled>
        </payload-format-validation>
        <!-- test-->
        <utf8-validation>
          <enabled>${HIVEMQ_TOPIC_FORMAT_VALIDATION}</enabled>
        </utf8-validation>
        <!-- Allows clients to request problem information -->
        <allow-request-problem-information>
          <enabled>${HIVEMQ_ALLOW_REQUEST_PROBLEM_INFORMATION}</enabled>
        </allow-request-problem-information>
      </security>
    </hivemq>
To eliminate the need for any special formatting, you can also use a JSON patch.
For more information, see JSON Patch.

Initialization Patch

The example initialization.yaml patch shows how to use initialization routines. This example shows how to install an extension. However, you usually use the 'extensions' field for this type of task.

Example initialization.yaml patch
apiVersion: hivemq.com/v1
kind: HiveMQCluster
spec:
  initialization:
    - name: init-kafka-plugin
      args:
        - |
          # Setup extension
          wget https://www.hivemq.com/releases/extensions/hivemq-kafka-extension-1.0.0.zip
          unzip hivemq-kafka-extension-1.0.0.zip -d /hivemq-data/extensions
          rm /hivemq-data/extensions/hivemq-kafka-extension/kafka-configuration.example.xml
          chmod -R 777 /hivemq-data/extensions/hivemq-kafka-extension

HiveMQ Enterprise Extension for Kafka Patch

The example kafka.yaml patch shows how to manage extensions.
For more information, see Kafka Extension Configuration.

Example kafka.yaml patch
apiVersion: hivemq.com/v1
kind: HiveMQCluster
spec:
  extensions:
    - name: hivemq-kafka-extension
      extensionUri: https://www.hivemq.com/releases/extensions/hivemq-kafka-extension-1.1.0.zip
      configMap: kafka-configuration
      enabled: true
Before you apply the Kafka extension patch, you must create ConfigMaps for the configuration of the extension and your enterprise extension licence.
Example ConfigMap for the Kafka extension configuration
apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    app: hivemq
  name: kafka-configuration
data:
  kafka-configuration.xml: |-
    <kafka-configuration
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="kafka-extension.xsd">
        <kafka-clusters>
            <kafka-cluster>
                <id>cluster01</id>
                <bootstrap-servers>kafka.operator.svc.cluster.local:9071</bootstrap-servers>
                <authentication>
                    <plain>
                        <username>test</username>
                        <password>test123</password>
                    </plain>
                </authentication>
            </kafka-cluster>
        </kafka-clusters>
        <topic-mappings>
            <topic-mapping>
                <id>sensor-data</id>
                <cluster-id>cluster01</cluster-id>
                <mqtt-topic-filters>
                    <mqtt-topic-filter>vehicles/sensor/data/#</mqtt-topic-filter>
                </mqtt-topic-filters>
                <kafka-topic>sensor-data</kafka-topic>
            </topic-mapping>
        </topic-mappings>
    </kafka-configuration>
Example ConfigMap for a Kafka extension license
apiVersion: v1
data:
  hivemq.lic: |-
    my-license-file
  kafka-license.elic: |-
    my-extension-license-file
kind: ConfigMap
metadata:
  labels:
    app: hivemq
  name: hivemq-license

To apply the Kafka extension patch, after your create the necessary ConfigMaps, enter:

kubectl patch hmqc <cluster-name> --type=merge --patch "$(cat kafka.yaml)"

License Patch

The example license.yaml shows how to install a license when you use the HiveMQ operator.

Example license.yaml patch

[source,yaml

apiVersion: hivemq.com/v1
kind: HiveMQCluster
spec:
  configMaps:
    - name: hivemq-license
      path: /opt/hivemq/license
Before you apply the license patch, you must create a ConfigMap for the associated license.
For more information, see the Example ConfigMap for a Kafka extension license.

Listener Patch

The example listener-config.yaml shows how to configure additional listeners.

This example uses the default listener and templated environment variable as well as an additional hardcoded listener on port 1884.

You can use this method to configure other types of listeners. For more information, see Listeners.

To directly reference a service on Kubernetes and use the correct port even if the loadbalancer port changes, you can use service port environment variables in this definition. For more information, see Kubernetes Environment Variables.
#
apiVersion: hivemq.com/v1
kind: HiveMQCluster
spec:
  listenerConfiguration: >
    <tcp-listener>
      <port>${HIVEMQ_MQTT_PORT}</port>
      <bind-address>0.0.0.0</bind-address>
    </tcp-listener>
    <tcp-listener>
      <port>1884</port>
      <bind-address>0.0.0.0</bind-address>
    </tcp-listener>
To configure a TLS listener, you must provide the associated keystore and truststore in the configurations field.

Ports Patch

The example ports.yaml shows how to configure additional ports. When you apply this patch to a HiveMQ cluster that uses the default configuration, this example simply adds an additional API port and expose it as a service.

Example ports.yaml patch
apiVersion: hivemq.com/v1
kind: HiveMQCluster
spec:
  ports:
    # These are the default ports that get exposed if you don't override this field.
    - name: mqtt
      port: 1883
      patch:
        - '[{"op":"add","path":"/spec/selector/hivemq.com~1node-offline","value":"false"},{"op":"add","path":"/metadata/annotations","value":{"service.spec.externalTrafficPolicy":"Local"}}]'
    - name: "cc"
      port: 8080
      expose: true
      patch:
        - '[{"op":"add","path":"/spec/sessionAffinity","value":"ClientIP"}]'
    # If you want Kubernetes to expose the HiveMQ control center via load balancer.
    # End of default ports
    # If your extension exposes a custom REST API, you can expose the port to a service like such:
    # The service will be called "hivemq-<cluster-name>-<port-name>"
    - name: my-api
      port: 8082
      expose: true