The Kubernetes Custom Resource Concept

Kubernetes is an open-source platform for automating the deployment, scaling, and management of containerized applications.

In Kubernetes, operators are custom controllers that extend the capabilities of Kubernetes and implement custom functionality to manage applications and their components.

The HiveMQ Platform Operator for Kubernetes manages the HiveMQ platform on Kubernetes. A single HiveMQ Platform Operator can manage one or more HiveMQ platforms.

The HiveMQ Platform Custom Resource Definition (CRD) provides all the necessary definitions and configurations to deploy your HiveMQ platform to a Kubernetes system version 1.24 or higher.

Custom Resource Definition for the HiveMQ Platform

When you install the HiveMQ Platform Operator with the HiveMQ Platform Operator Helm chart, the custom resource definition (CRD) for the new HiveMQ Platform object is installed as well.
The CRD is the central definition that enables Kubernetes to recognize your HiveMQ Platform as an object.

To view a list of the available CRDs on your Kubernetes cluster, enter the following command:

kubectl get customresourcedefinitions.apiextensions.k8s.io
kubectl get crds (using the abbreviation)

To view the HiveMQ Platform CRD, enter:

kubectl describe crd hivemq-platforms.hivemq.com

Once the HiveMQ Platform custom resource definition is deployed on your Kubernetes cluster, you can define and deploy as many HiveMQ Platform custom resources as your individual use case requires.

A custom resource is the concrete manifestation of the custom resource definition.

Your HiveMQ Platform custom resource defines what type of HiveMQ Platform cluster is deployed. The custom resource determines which HiveMQ container image is used, the number of nodes in your cluster, and what configurations are used.

The operator watches for the deployment of new custom resources and installs your HiveMQ platform cluster according to your custom resource specification. If you change an existing custom resource, the operator automatically reconciles your HiveMQ platform cluster with the changes.

To install your custom resource, you can use our preconfigured HiveMQ Platform Helm charts or deploy your own custom resource manually:

kubectl apply -f hivemq-custom-resource.yml

If you deploy your HiveMQ custom resource manually, you also need to deploy the HiveMQ configuration as a Kubernetes ConfigMap. A default custom resource example is available on the public Helm chart repository.

List the deployed HiveMQ Platform custom resources:

kubectl get hivemq-platforms.hivemq.com
kubectl get hmqp (using the abbreviation)

View your HiveMQ Platform custom resource:

kubectl get hmqp <your-hivemq-platform-name> -o yaml

Deploying the HiveMQ Platform custom resource gives you the ability to customize your StatefulSet specification and your Service specification. This expert mode provides the highest level of flexibility for deploying your custom HiveMQ platform.

Don’t forget to deploy any configMaps or secrets that your deployment needs in addition.

Custom resource configuration options

The HiveMQ Platform custom resource definition spec contains several configuration sections:

Field Description

Field	Description
`configMapName`	Configures the name of the ConfigMap that contains your HiveMQ platform configuration (`config.xml`). The ConfigMap can contain additional configuration files, such as the configuration to enable tracing.
`healthApiPort`	Defines the HealthAPI port for the HiveMQ platform nodes as an Int. The operator accesses this port to query for the health of the nodes. The default port address is `8889`
`logLevel`	Sets the log level for the HiveMQ platform. Changes to the log level do not prompt a rolling restart of the cluster. The default log level is `INFO`.
`metricsPath`	Defines the path where metrics can be scraped on each HiveMQ platform node. The path is used for monitoring tools such as Prometheus. The default is `/`
`metricsPort`	Defines the port where metrics can be reached on each HiveMQ platform node as an Int. The port is used for monitoring tools such as Prometheus. The default port address is `9399`.
`operatorRestApiPort`	Defines the port where the API and the metrics of the operator can be reached as an Int. The default port address is `7979`
`extensions`	The list of extensions with configuration settings for each extension. `id`: The string that defines the ID of the extension. This ID must match the ID of the extension in the `extension.xml` file. For example, `hivemq-kafka-extension`. `enabled`: Boolean value that defines whether the extension is enabled. The default is `false`. `extensionUri`: Configures from where the extension is provided. The value `preinstalled` defines that the extension is already installed in the container image. This is a valid setting for all HiveMQ Enterprise Extensions that are part of the HiveMQ platform. Alternatively, you can provide a URI from which the extension zip can be downloaded. `supportsHotReload`: Boolean value that indicates whether the extension can hot reload its configuration. `configMapName`: Configures the name of the configMap with the extension configuration.
`services`	Defines a list of service objects that are exposed for the HiveMQ Platform. Refer to the Kubernetes service configuration for valid options. `metadata`: Defines the metadata for the service object. `spec`: Defines the spec configuration for the service object.
`statefulSet`	Defines the statefulSet object that is used to deploy the HiveMQ Platform. Refer to the Kubernetes statefulSet configuration for valid options. `metadata`: Defines the metadata for the statefulSet object. `spec`: Defines the spec configuration for the statefulSet object.

configMapName

Configures the name of the ConfigMap that contains your HiveMQ platform configuration (config.xml). The ConfigMap can contain additional configuration files, such as the configuration to enable tracing.

healthApiPort

Defines the HealthAPI port for the HiveMQ platform nodes as an Int. The operator accesses this port to query for the health of the nodes.
The default port address is 8889

logLevel

Sets the log level for the HiveMQ platform.
Changes to the log level do not prompt a rolling restart of the cluster.
The default log level is INFO.

metricsPath

Defines the path where metrics can be scraped on each HiveMQ platform node. The path is used for monitoring tools such as Prometheus.
The default is /

metricsPort

Defines the port where metrics can be reached on each HiveMQ platform node as an Int. The port is used for monitoring tools such as Prometheus.
The default port address is 9399.

operatorRestApiPort

Defines the port where the API and the metrics of the operator can be reached as an Int.
The default port address is 7979

extensions

The list of extensions with configuration settings for each extension.

id: The string that defines the ID of the extension.
This ID must match the ID of the extension in the extension.xml file. For example, hivemq-kafka-extension.
enabled: Boolean value that defines whether the extension is enabled.
The default is false.
extensionUri: Configures from where the extension is provided.
The value preinstalled defines that the extension is already installed in the container image. This is a valid setting for all HiveMQ Enterprise Extensions that are part of the HiveMQ platform. Alternatively, you can provide a URI from which the extension zip can be downloaded.
supportsHotReload: Boolean value that indicates whether the extension can hot reload its configuration.
configMapName: Configures the name of the configMap with the extension configuration.

services

Defines a list of service objects that are exposed for the HiveMQ Platform. Refer to the Kubernetes service configuration for valid options.

metadata: Defines the metadata for the service object.
spec: Defines the spec configuration for the service object.

statefulSet

Defines the statefulSet object that is used to deploy the HiveMQ Platform. Refer to the Kubernetes statefulSet configuration for valid options.

metadata: Defines the metadata for the statefulSet object.
spec: Defines the spec configuration for the statefulSet object.

Lifecycle Management

In addition to the configuration options, the custom resource of a deployed HiveMQ Platform also contains status information. The HiveMQ Platform Operator manages your custom resource and sets different statuses during operations. You can view the current and previous status of your HiveMQ Platform custom resource with this command.

To view the status at the end of your HiveMQ Platform custom resource, enter:

kubectl describe hmqp <name of your hivemq platform>

Example HiveMQ Platform custom resource status:

Status:
  Message:              HiveMQ Platform is ready
  Observed Generation:  2
  Recovery Information:
    Message:           HiveMQ Platform is starting
    State:             STARTING
    State Phase:       READY
  Restart Extensions:
  State:               RUNNING
  State Phase:         READY