Installing HiveMQ Platform Operator (v2.0.0+) in Restricted Kubernetes Environments

Product: HiveMQ Platform Operator Version: 2.0.0 and later

Symptoms

When attempting to install the HiveMQ Platform Operator via Helm in a restricted Kubernetes (K8s) environment, the installation fails. The user or service account performing the installation has permissions limited to a specific namespace, but the installation process attempts to create or modify cluster-scoped resources.

The error may be related to an inability to create CustomResourceDefinition (CRD) or other cluster-level RBAC roles.

Cause

This issue stems from the fundamental architecture of Kubernetes and how Operators work.

1. CRDs are Cluster-Scoped: The HiveMQ Platform Operator uses a Custom Resource Definition (CRD) named hivemq-platforms.hivemq.com-v1.yml. By Kubernetes design, all CRDs are cluster-scoped resources. They define a new type of resource for the entire cluster, not just a single namespace.

2. Operator vs. CRD: While the HiveMQ Platform Operator (since v2.0.0) can be configured to run with reduced, namespace-only RBAC permissions, it still requires its CRD to be installed in the cluster first.

3. The Conflict: The installation fails because the user deploying the Helm chart only has namespace-level rights and is therefore blocked from installing the cluster-scoped CRD, which the chart attempts to do by default.

In short, you cannot deploy the Operator (which manages namespace-level Custom Resources) until its Definition (the cluster-level CRD) exists.

Solution

The installation must be performed in two distinct stages by two different roles:

1. Cluster Admin: Installs the cluster-scoped CRD.

2. Namespace User: Installs the Operator itself using the reduced RBAC configuration.

Part 1: Cluster Admin Task (Cluster-Level Permissions Required)

A user with cluster-admin privileges (or at minimum, permission to create CustomResourceDefinitions) must perform this step.

1. Verify Permissions (Optional): You can check if your current user has the necessary permissions by running:

   kubectl auth can-i create customresourcedefinitions --all-namespaces

   The expected output is yes.

2. Manually Install the CRD: Apply the HiveMQ Platform CRD directly to the cluster:

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

   Once this is complete, the "definition" for HiveMQPlatform resources now exists in the cluster.

Part 2: Namespace User Task (Namespace-Level Permissions)

After the Cluster Admin has installed the CRD, the user with namespace-only permissions can deploy the operator.

1. Configure Reduced RBAC: When deploying the operator via Helm, you must configure it to use namespace-level roles and disable features that require cluster-level access.

2. Follow the Documentation: Refer to the official documentation for the specific Helm values required to install with reduced RBAC permissions: HiveMQ Docs: Example Operator RBAC Permissions

Important Considerations: Future Updates

This is a critical point: When you run the operator with reduced RBAC permissions, it does not have permission to update its own CRD.

When a new version of the HiveMQ Platform Operator is released (e.g., updating from 2.0.0 to 2.1.0), it may include changes to the CRD.

Before the namespace user can update the operator Helm deployment, the Cluster Admin must manually apply the new CRD version from the new chart files, following the same command in Part 1. Failure to update the CRD first will likely cause the operator update to fail.