Advanced Installation

The HiveMQ Platform Operator and the HiveMQ Platform can be installed without Helm. Use the Kubernetes command line tool kubectl to deploy the respective manifest files for the HiveMQ Platform Operator and the HiveMQ Platform.

HiveMQ provides up-to-date manifest files for this purpose in the HiveMQ Helm chart repository. You can download the manifest files and customize them for your deployment as needed.

It is also possible to generate the default deployment manifest files with Helm with the following commands:

helm template hivemq/hivemq-platform-operator > operator-manifests.yaml
helm template hivemq/hivemq-platform > platform-manifests.yaml

Install HiveMQ Platform Operator with kubectl

The following procedure outlines how to use our default manifest files to deploy the HiveMQ Platform Operator with the Kubernetes command line tool kubectl.

Install the HiveMQPlatform custom resource definition (CRD):

kubectl apply -f https://raw.githubusercontent.com/hivemq/helm-charts/master/charts/hivemq-platform-operator/crds/hivemq-platforms.hivemq.com-v1.yml

Download or clone the public Helm chart repository with the manifest files:
```
git clone https://github.com/hivemq/helm-charts.git
```
Install the HiveMQ Platform Operator from files in the manifests/hivemq-platform-operator directory:
```
kubectl apply -f ./manifests/hivemq-platform-operator -n default
```
The manifest files use a default namespace because the required ServiceAccount relies on a specific namespace. Customize the manifests to use your desired namespace.

HiveMQ Platform Operator Configuration

All HiveMQ Platform Operator configuration options can be set via system properties or environment variables. To customize the configuration, update the environment variable section of your deployment manifest file.

Property name / Environment variable Type Description

Property name / Environment variable	Type	Description
`hivemq.platform.operator.cache-sync-timeout` `HIVEMQ_PLATFORM_OPERATOR_CACHE_SYNC_TIMEOUT`	`Duration`	The time the operator waits for informers to complete cache synchronization at startup before timing out. The timeout duration follows the ISO-8601 format. The default setting is `PT2M`.
`hivemq.platform.operator.concurrent-reconciliation-threads` `HIVEMQ_PLATFORM_OPERATOR_CONCURRENT_RECONCILIATION_THREADS`	`Integer`	The maximum number of reconciliation requests dispatched concurrently to controllers. The default setting is `50`.
`hivemq.platform.operator.concurrent-workflow-threads` `HIVEMQ_PLATFORM_OPERATOR_CONCURRENT_WORKFLOW_THREADS`	`Integer`	The maximum number of concurrent workflow processing requests. The default setting is `50`.
`hivemq.platform.operator.crd.apply` `HIVEMQ_PLATFORM_OPERATOR_CRD_APPLY`	`Boolean`	Enables the operator to create the HiveMQ Platform CustomResourceDefinition in the Kubernetes cluster during operator startup. The default setting is `true`.
`hivemq.platform.operator.crd.wait-until-ready` `HIVEMQ_PLATFORM_OPERATOR_CRD_WAIT_UNTIL_READY`	`Boolean`	Enables the operator to wait for the HiveMQ Platform CustomResourceDefinition to become ready once installed. The default setting is `true`.
`hivemq.platform.operator.crd.wait-until-ready.timeout` `HIVEMQ_PLATFORM_OPERATOR_CRD_WAIT_UNTIL_READY_TIMEOUT`	`Duration`	Specifies how long the operator waits for the HiveMQ Platform CustomResourceDefinition to become ready once installed. The timeout duration follows the ISO-8601 format. The default setting is `PT10S`.
`hivemq.platform.operator.http.port` `HIVEMQ_PLATFORM_OPERATOR_HTTP_PORT`	`Integer`	Configures the HTTP port for the operator. The default setting is `8080`.
`hivemq.platform.operator.http.ssl-port` `HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_PORT`	`Integer`	Configures the HTTPS port for the operator. The default setting is `8443`.
`hivemq.platform.operator.http.ssl.certificate.key-store-file` `HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE`	`String`	An optional keystore that holds the certificate information.
`hivemq.platform.operator.http.ssl.certificate.key-store-file-type` `HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE_TYPE`	`String`	An optional parameter to specify the type of the keystore file. If not given, the type is automatically detected based on the file name.
`hivemq.platform.operator.http.ssl.certificate.key-store-password` `HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD`	`String`	A parameter to specify the password of the keystore.
`hivemq.platform.operator.http.ssl.certificate.key-store-private-key-password` `HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_KEY_STORE_PRIVATE_KEY_PASSWORD`	`String`	A parameter to specify the password of the private key in the keystore.
`hivemq.platform.operator.http.ssl.certificate.trust-store-file` `HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_TRUST_STORE_FILE`	`String`	An optional trust store that holds the certificate information of the trusted certificates.
`hivemq.platform.operator.http.ssl.certificate.trust-store-password` `HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_TRUST_STORE_PASSWORD`	`String`	A parameter to specify the password of the trust store file.
`hivemq.platform.operator.image.pull.secret` `HIVEMQ_PLATFORM_OPERATOR_IMAGE_PULL_SECRET`	`String`	The image pull secret the operator configures for the HiveMQ Platform Operator Init container.
`hivemq.platform.operator.init-app.update.url` `HIVEMQ_PLATFORM_OPERATOR_INIT_APP_UPDATE_URL`	`String`	Optional parameter to customize the URL for the HiveMQ Platform Init App update.
`hivemq.platform.operator.init.image` `HIVEMQ_PLATFORM_OPERATOR_INIT_IMAGE`	`String`	The Docker image for the HiveMQ Platform Operator Init container. The default setting is the `hivemq/hivemq-platform-operator-init` image on Docker Hub.
`hivemq.platform.operator.init.image.resources.cpu` `HIVEMQ_PLATFORM_OPERATOR_INIT_IMAGE_RESOURCES_CPU`	`String`	The CPU resource requests and limits the operator configures for the HiveMQ Platform Operator Init container. The default setting is `250m`.
`hivemq.platform.operator.init.image.resources.ephemeral-storage` `HIVEMQ_PLATFORM_OPERATOR_INIT_IMAGE_RESOURCES_EPHEMERAL_STORAGE`	`String`	The ephemeral resource requests and limits the operator configures for the HiveMQ Platform Operator Init container. The default setting is `1Gi`.
`hivemq.platform.operator.init.image.resources.memory` `HIVEMQ_PLATFORM_OPERATOR_INIT_IMAGE_RESOURCES_MEMORY`	`String`	The memory resource requests and limits the operator configures for the HiveMQ Platform Operator Init container. The default setting is `100Mi`.
`hivemq.platform.operator.log.configuration` `HIVEMQ_PLATFORM_OPERATOR_LOG_CONFIGURATION`	`Boolean`	Logs the configuration values at operator startup. Sensitive values are redacted. The log information is useful for debugging the configuration of system properties and environment variables. The default setting is `false`.
`hivemq.platform.operator.log.level` `HIVEMQ_PLATFORM_OPERATOR_LOG_LEVEL`	`Level`	Configures the log level. Possible values are: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` The default setting is `INFO`.
`hivemq.platform.operator.namespaces` `HIVEMQ_PLATFORM_OPERATOR_NAMESPACES`	`String`	An optional comma-separated list of namespaces the operator manages. If this property is left empty or set to `JOSDK_ALL_NAMESPACES`, the operator watches all namespaces. To watch the namespace in which the operator is currently deployed, set the value to `JOSDK_WATCH_CURRENT`. The default setting is `JOSDK_ALL_NAMESPACES`.
`hivemq.platform.operator.release.name` `HIVEMQ_PLATFORM_OPERATOR_RELEASE_NAME`	`String`	The name of the operator release. For example, the Helm release name. This value is used to determine the operator service name. The service name is used in the URL for the HiveMQ Platform Init App update.
`hivemq.platform.operator.selector` `HIVEMQ_PLATFORM_OPERATOR_SELECTOR`	`String`	An optional comma-separated list of label selectors that HiveMQ Platform resources must match to be managed by the operator.
`hivemq.platform.operator.serviceaccount.create` `HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_CREATE`	`Boolean`	Specifies whether a ServiceAccount for HiveMQ Platform pods is created for all managed platforms. The default setting is `true`.
`hivemq.platform.operator.serviceaccount.name` `HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_NAME`	`String`	The ServiceAccount name that is used for all HiveMQ Platforms pods. This overrides the default name `hivemq-platform-pod-<platform-name>` of the operator. The ServiceAccount can also be overridden in the HiveMQ Platform Helm chart (see nodes.serviceAccountName) for each specific HiveMQ Platform.
`hivemq.platform.operator.serviceaccount.permissions.create` `HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_PERMISSIONS_CREATE`	`Boolean`	Specifies whether the RBAC permissions for the ServiceAccount for HiveMQ Platform pods are created for all managed platforms. The default setting is `true`.
`hivemq.platform.operator.serviceaccount.permissions.validate` `HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_PERMISSIONS_VALIDATE`	`Boolean`	Specifies whether the RBAC permissions for the ServiceAccount for all HiveMQ Platform pods are validated. The default setting is `true`.
`hivemq.platform.operator.serviceaccount.validate` `HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_VALIDATE`	`Boolean`	Specifies whether the ServiceAccount for HiveMQ Platform pods is validated. The default setting is `true`.
`hivemq.platform.operator.skip-https-certificate-validation` `HIVEMQ_PLATFORM_OPERATOR_SKIP_HTTPS_CERTIFICATE_VALIDATION`	`Boolean`	Configures whether certificate validation is skipped for all managed custom resources. These settings are used for all operator-related HTTP clients. For example, to download custom extensions and extension customizations. The default setting is `false`.
`hivemq.platform.operator.skip-https-hostname-verification` `HIVEMQ_PLATFORM_OPERATOR_SKIP_HTTPS_HOSTNAME_VERIFICATION`	`Boolean`	Configures whether hostname verification is skipped for all managed custom resources. These settings are used for all operator-related HTTP clients. For example, to download custom extensions and extension customizations. The default setting is `false`.
`hivemq.platform.operator.statefulset.rolling-restart-on-template-metadata-change` `HIVEMQ_PLATFORM_OPERATOR_STATEFULSET_ROLLING_RESTART_ON_TEMPLATE_METADATA_CHANGE`	`Boolean`	Specifies whether changes to StatefulSet template metadata trigger a rolling restart. When set to `false`, the rollout of updated annotations and labels to the HiveMQ Platform pods is delayed until the next rolling restart occurs. The default setting is `false`.
`hivemq.platform.operator.termination-timeout-seconds` `HIVEMQ_PLATFORM_OPERATOR_TERMINATION_TIMEOUT_SECONDS`	`Integer`	The time in seconds the operator waits for reconciliation threads to terminate before shutting down. The default setting is `10`.

hivemq.platform.operator.cache-sync-timeout

HIVEMQ_PLATFORM_OPERATOR_CACHE_SYNC_TIMEOUT

Duration

The time the operator waits for informers to complete cache synchronization at startup before timing out. The timeout duration follows the ISO-8601 format.

The default setting is PT2M.

hivemq.platform.operator.concurrent-reconciliation-threads

HIVEMQ_PLATFORM_OPERATOR_CONCURRENT_RECONCILIATION_THREADS

Integer

The maximum number of reconciliation requests dispatched concurrently to controllers.

The default setting is 50.

hivemq.platform.operator.concurrent-workflow-threads

HIVEMQ_PLATFORM_OPERATOR_CONCURRENT_WORKFLOW_THREADS

Integer

The maximum number of concurrent workflow processing requests.

The default setting is 50.

hivemq.platform.operator.crd.apply

HIVEMQ_PLATFORM_OPERATOR_CRD_APPLY

Boolean

Enables the operator to create the HiveMQ Platform CustomResourceDefinition in the Kubernetes cluster during operator startup.

The default setting is true.

hivemq.platform.operator.crd.wait-until-ready

HIVEMQ_PLATFORM_OPERATOR_CRD_WAIT_UNTIL_READY

Boolean

Enables the operator to wait for the HiveMQ Platform CustomResourceDefinition to become ready once installed.

The default setting is true.

hivemq.platform.operator.crd.wait-until-ready.timeout

HIVEMQ_PLATFORM_OPERATOR_CRD_WAIT_UNTIL_READY_TIMEOUT

Duration

Specifies how long the operator waits for the HiveMQ Platform CustomResourceDefinition to become ready once installed. The timeout duration follows the ISO-8601 format.

The default setting is PT10S.

hivemq.platform.operator.http.port

HIVEMQ_PLATFORM_OPERATOR_HTTP_PORT

Integer

Configures the HTTP port for the operator.

The default setting is 8080.

hivemq.platform.operator.http.ssl-port

HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_PORT

Integer

Configures the HTTPS port for the operator.

The default setting is 8443.

hivemq.platform.operator.http.ssl.certificate.key-store-file

HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE

String

An optional keystore that holds the certificate information.

hivemq.platform.operator.http.ssl.certificate.key-store-file-type

HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE_TYPE

String

An optional parameter to specify the type of the keystore file. If not given, the type is automatically detected based on the file name.

hivemq.platform.operator.http.ssl.certificate.key-store-password

HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD

String

A parameter to specify the password of the keystore.

hivemq.platform.operator.http.ssl.certificate.key-store-private-key-password

HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_KEY_STORE_PRIVATE_KEY_PASSWORD

String

A parameter to specify the password of the private key in the keystore.

hivemq.platform.operator.http.ssl.certificate.trust-store-file

HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_TRUST_STORE_FILE

String

An optional trust store that holds the certificate information of the trusted certificates.

hivemq.platform.operator.http.ssl.certificate.trust-store-password

HIVEMQ_PLATFORM_OPERATOR_HTTP_SSL_CERTIFICATE_TRUST_STORE_PASSWORD

String

A parameter to specify the password of the trust store file.

hivemq.platform.operator.image.pull.secret

HIVEMQ_PLATFORM_OPERATOR_IMAGE_PULL_SECRET

String

The image pull secret the operator configures for the HiveMQ Platform Operator Init container.

hivemq.platform.operator.init-app.update.url

HIVEMQ_PLATFORM_OPERATOR_INIT_APP_UPDATE_URL

String

Optional parameter to customize the URL for the HiveMQ Platform Init App update.

hivemq.platform.operator.init.image

HIVEMQ_PLATFORM_OPERATOR_INIT_IMAGE

String

The Docker image for the HiveMQ Platform Operator Init container.

The default setting is the hivemq/hivemq-platform-operator-init image on Docker Hub.

hivemq.platform.operator.init.image.resources.cpu

HIVEMQ_PLATFORM_OPERATOR_INIT_IMAGE_RESOURCES_CPU

String

The CPU resource requests and limits the operator configures for the HiveMQ Platform Operator Init container.

The default setting is 250m.

hivemq.platform.operator.init.image.resources.ephemeral-storage

HIVEMQ_PLATFORM_OPERATOR_INIT_IMAGE_RESOURCES_EPHEMERAL_STORAGE

String

The ephemeral resource requests and limits the operator configures for the HiveMQ Platform Operator Init container.

The default setting is 1Gi.

hivemq.platform.operator.init.image.resources.memory

HIVEMQ_PLATFORM_OPERATOR_INIT_IMAGE_RESOURCES_MEMORY

String

The memory resource requests and limits the operator configures for the HiveMQ Platform Operator Init container.

The default setting is 100Mi.

hivemq.platform.operator.log.configuration

HIVEMQ_PLATFORM_OPERATOR_LOG_CONFIGURATION

Boolean

Logs the configuration values at operator startup.

Sensitive values are redacted. The log information is useful for debugging the configuration of system properties and environment variables.

The default setting is false.

hivemq.platform.operator.log.level

HIVEMQ_PLATFORM_OPERATOR_LOG_LEVEL

Level

Configures the log level. Possible values are: TRACE, DEBUG, INFO, WARN, ERROR

The default setting is INFO.

hivemq.platform.operator.namespaces

HIVEMQ_PLATFORM_OPERATOR_NAMESPACES

String

An optional comma-separated list of namespaces the operator manages.

If this property is left empty or set to JOSDK_ALL_NAMESPACES, the operator watches all namespaces. To watch the namespace in which the operator is currently deployed, set the value to JOSDK_WATCH_CURRENT.

The default setting is JOSDK_ALL_NAMESPACES.

hivemq.platform.operator.release.name

HIVEMQ_PLATFORM_OPERATOR_RELEASE_NAME

String

The name of the operator release. For example, the Helm release name.

This value is used to determine the operator service name. The service name is used in the URL for the HiveMQ Platform Init App update.

hivemq.platform.operator.selector

HIVEMQ_PLATFORM_OPERATOR_SELECTOR

String

An optional comma-separated list of label selectors that HiveMQ Platform resources must match to be managed by the operator.

hivemq.platform.operator.serviceaccount.create

HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_CREATE

Boolean

Specifies whether a ServiceAccount for HiveMQ Platform pods is created for all managed platforms.

The default setting is true.

hivemq.platform.operator.serviceaccount.name

HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_NAME

String

The ServiceAccount name that is used for all HiveMQ Platforms pods.

This overrides the default name hivemq-platform-pod-<platform-name> of the operator. The ServiceAccount can also be overridden in the HiveMQ Platform Helm chart (see nodes.serviceAccountName) for each specific HiveMQ Platform.

hivemq.platform.operator.serviceaccount.permissions.create

HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_PERMISSIONS_CREATE

Boolean

Specifies whether the RBAC permissions for the ServiceAccount for HiveMQ Platform pods are created for all managed platforms.

The default setting is true.

hivemq.platform.operator.serviceaccount.permissions.validate

HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_PERMISSIONS_VALIDATE

Boolean

Specifies whether the RBAC permissions for the ServiceAccount for all HiveMQ Platform pods are validated.

The default setting is true.

hivemq.platform.operator.serviceaccount.validate

HIVEMQ_PLATFORM_OPERATOR_SERVICEACCOUNT_VALIDATE

Boolean

Specifies whether the ServiceAccount for HiveMQ Platform pods is validated.

The default setting is true.

hivemq.platform.operator.skip-https-certificate-validation

HIVEMQ_PLATFORM_OPERATOR_SKIP_HTTPS_CERTIFICATE_VALIDATION

Boolean

Configures whether certificate validation is skipped for all managed custom resources.

These settings are used for all operator-related HTTP clients. For example, to download custom extensions and extension customizations.

The default setting is false.

hivemq.platform.operator.skip-https-hostname-verification

HIVEMQ_PLATFORM_OPERATOR_SKIP_HTTPS_HOSTNAME_VERIFICATION

Boolean

Configures whether hostname verification is skipped for all managed custom resources.

These settings are used for all operator-related HTTP clients. For example, to download custom extensions and extension customizations.

The default setting is false.

hivemq.platform.operator.statefulset.rolling-restart-on-template-metadata-change

HIVEMQ_PLATFORM_OPERATOR_STATEFULSET_ROLLING_RESTART_ON_TEMPLATE_METADATA_CHANGE

Boolean

Specifies whether changes to StatefulSet template metadata trigger a rolling restart.

When set to false, the rollout of updated annotations and labels to the HiveMQ Platform pods is delayed until the next rolling restart occurs.

The default setting is false.

hivemq.platform.operator.termination-timeout-seconds

HIVEMQ_PLATFORM_OPERATOR_TERMINATION_TIMEOUT_SECONDS

Integer

The time in seconds the operator waits for reconciliation threads to terminate before shutting down.

The default setting is 10.

Install HiveMQ Platform with kubectl

The following procedure outlines how to use the default HiveMQ platform manifest files to deploy a HiveMQ platform with the Kubernetes command line tool kubectl.

To install the HiveMQ platform from files in the manifests/hivemq-platform directory, enter:
```
kubectl apply -f ./manifests/hivemq-platform -n default
```

To test whether your HiveMQ platform is available via services for MQTT connections, see Test Your HiveMQ Platform.

You can customize the HiveMQ platform manifest files to match your business needs. This includes changing the StatefulSet, Service objects, and the HiveMQ configuration. Be sure to align changes across all objects. For example port definitions have to be changed across all three objects. Specifically, your HiveMQ listener configuration must match your StatefulSet configuration and Service configuration.