HiveMQ Platform Operator for Kubernetes 2.0 is now available!

The HiveMQ Team is excited to announce HiveMQ Platform Operator for Kubernetes 2.0. This release enhances monitoring and observability with aggregated Health Details and an upgraded Grafana dashboard, adds numerous improvements for change detection and reconciliation, and delivers additional bug fixes and general enhancements.

Highlights

• Aggregated Health Status and Details
• New Change Detection System

New Aggregated HiveMQ Platform Health Status and Details

HiveMQ Platform Operator 2.0 now aggregates health information across your entire HiveMQ cluster and reports unhealthy components from all nodes. This provides a unified view of overall cluster health as well as the status of individual components such as installed extensions.

How it works

The HiveMQ Platform Init App runs alongside each HiveMQ node in your cluster. The Init App fetches the node’s Health API status and reports any unhealthy components to the HiveMQ Platform Operator. Starting with HiveMQ Platform Operator version 2.0, the operator aggregates health data from all HiveMQ Platform Pods and provides the overall health status through the custom resource, Kubernetes events, and metrics.

View the health status and details in the custom resource

To view your custom resource (CR) and the current health status, run this command:

    kubectl get hivemq-platforms.hivemq.com <your-hivemq-platform> -o yaml
  

The response includes the custom resource and the current status with detailed health information:

    healthDetails: |
    extensions/hivemq-kafka-extension/internals/entrypoint
      Pod: pl-0
      Node ID: SHO8p
      Status: DOWN
      Version: 4.43.0
      Details:
        last-startup-failure: Cannot load the configuration from 
         '/opt/hivemq/extensions/hivemq-kafka-extension/conf/config.xml' 
         because of the following errors:
          - XML schema violation in line '4' and column '3' caused by: "The element 
            type "kafka-configuration" must be terminated by the matching end-tag 
            "</kafka-configuration>"."
        started-at: 0
      Pod: pl-1
      Node ID: mpW1R
      .....
       
  healthStatus: DOWN
  message: HiveMQ Platform is ready
  platformReplicas: 2
  state: RUNNING
  

The example response shows the HiveMQ cluster is running, but a configuration error in the Kafka extension causes the overall health status to be reported as down.

View health status and details in Kubernetes events

To view Kubernetes events sorted by time with full details, run the following command:

    kubectl get events --sort-by='.lastTimestamp' -o yaml
  

The response includes events with the current health status and detailed information:

    apiVersion: v1
count: 896
eventTime: null
firstTimestamp: "2025-09-17T12:40:17Z"
involvedObject:
  kind: HiveMQPlatform
  name: pl
  namespace: hivemq
  uid: 6c327c23-1d3f-4e15-8d50-e0904c9aa259
kind: Event
lastTimestamp: "2025-09-17T14:46:07Z"
message: |
  Platform Status: DOWN

  extensions/hivemq-kafka-extension/internals/entrypoint
    Pod: pl-0
    Node ID: SHO8p
    Status: DOWN
    Version: 4.43.0
    Details:
      last-startup-failure: Cannot load the configuration from
      '/opt/hivemq/extensions/hivemq-kafka-extension/conf/config.xml' 
      because of the following errors:
        - XML schema violation in line '9' and column '7' caused by: 
          "The element type "kafka-configuration" must be terminated by the 
           matching end-tag "</kafka-configuration>"."
      started-at: 0
      ....
metadata:
  creationTimestamp: "2025-09-17T12:40:17Z"
  labels:
    app.kubernetes.io/instance: pl
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: hivemq-platform
    app.kubernetes.io/version: 4.43.0
    hivemq-platform: pl
  name: pl-hivemq-platform-health-status
  namespace: hivemq
  ownerReferences:
  - apiVersion: hivemq.com/v1
    kind: HiveMQPlatform
    name: pl
    uid: 6c327c23-1d3f-4e15-8d50-e0904c9aa259
  resourceVersion: "55768"
  uid: 0db5d1d6-620e-4548-9c8c-5282b5153d44
reason: Health Status
reportingComponent: ""
reportingInstance: ""
source:
  component: hivemq-platform-operator
type: Warning
  

View health status as a metric:

The HiveMQ Platform Operator Helm charts provide a pre-configured Grafana dashboard. This dashboard features a Platform Health Status widget that displays system health status using the broker’s com.hivemq.health.system.current metric semantics:

Metrics enable automated monitoring and alerting. For more information, see this health metrics example in our documentation.

To enable monitoring for your HiveMQ Platform Operator and your HiveMQ Platforms, refer to the installation instructions in our documentation.

How it helps

The new aggregated health status provides more options to automate and watch your HiveMQ clusters. The detailed status information removes blind spots, especially for DEGRADED health states that require user actions. For example, if keystore certificates expire for TLS MQTT listeners, the status of the MQTT listener changes to DEGRADED. The DEGRADED status alerts the user to take action and deploy updated certificates before a broker restart to minimize downtime.

Enhanced Change Detection and Reconciliation

HiveMQ Platform Operator 2.0 detects changes in the cluster configuration and setup during each reconciliation cycle. This improves reliability for changes that require a rolling restart, scaling, or extension restarts, and is particularly useful in situations where many changes are made concurrently.

Previous HiveMQ Platform Operator 1.x versions used a one-time detection system to identify changes that require a rolling restart, scaling, or restart extension requests.

How it helps

The previous one-time detection method could result in a lost update if the custom resource status could not be updated successfully, or cause unnecessary rolling restarts during concurrent changes. Our new change detection system provides predictable, reliable update handling.

Additional Features and Improvements

HiveMQ Platform Operator Helm Charts

• Added the option to configure the port for NodePort service types.

HiveMQ Platform Operator for Kubernetes

• Added an aggregated health status and details of all HiveMQ Platforms to the custom resource status.
• Added a new operator metric with the aggregated system health status for each managed HiveMQ Platform.
• Added a configuration option to limit the number of concurrent rolling restarts that a HiveMQ Platform Operator will start concurrently.
• Added error detection if HiveMQ Platform Pods cannot be created due to an invalid StatefulSet specification.
• Added error detection if HiveMQ Platform Pods cannot become ready due to a CreateContainerConfigError state.
• Added the HiveMQ Platform version annotation platform.hivemq.com/version to HiveMQ Platform Pods.
• Improved the annotation prefix on HiveMQ Platform Pods to a valid DNS subdomain. For example, operator.platform.hivemq.com/init-app-version.
• Improved the extraction of warning and error logs when the HiveMQ Platform process is terminated exceptionally, and no hivemq.log file is present.
• Improved log messages for exceptional HiveMQ Platform process termination.
• Reduced the RBAC permissions for the HiveMQ Platform Operator to enable a setup without cluster-wide permissions.
• Removed metadata inheritance from the custom resource to all managed Kubernetes resources and the HiveMQ Platform Pods.
• Removed metadata inheritance from the StatefulSet to the HiveMQ Platform Pods.
• Rolling restarts are now triggered on StatefulSet template metadata changes.
• Fixed an issue where a rolling restart is not properly detected when the StatefulSet is updated.
• Fixed an issue where multiple rolling restarts were triggered from multiple concurrent configuration changes.
• Fixed a concurrency issue when the extensions configuration is updated while the extensions are still being restarted.
• Fixed an issue where configuration options could not be removed from HiveMQ Platforms created without server-side-apply.
• Fixed an issue where custom HiveMQ extensions failed to start during runtime installation.

Get Started Today

To get started with the new HiveMQ Platform Operator, see our HiveMQ Platform Operator Quick Start Guide.

To update from a previous version of the HiveMQ Platform Operator for Kubernetes, you need to update your HiveMQ Platform custom resource definition (CRD). For step-by-step instructions, see our Upgrade Guide.

To learn more about our new operator, see HiveMQ Platform Operator for Kubernetes.