Skip to main content
Restrict the ClickHouse operator to a named set of namespaces instead of granting it permissions across the whole cluster.
Requires ClickHouse operator version 1.22950.1 or later. The operator image and the clickhouse-operator-helm chart share the same version.
By default the operator is granted its permissions through a single ClusterRole, so it can act on the resources it manages in every namespace. That is a poor fit when the operator runs in a cluster you share with other workloads. Namespace scoping grants most of those permissions through a Role in each namespace you nominate instead.

Prerequisites

  • Follow the deployment tutorial for your platform until you are ready to deploy the operator.
  • The namespaces your ClickHouse clusters will live in, decided up front (this guide uses ns-default-xx-01 and ns-default-xx-02)
  • Permission to install or upgrade the operator Helm release

Enabling Namespace Scoping in the Operator

Two values control this:
  • operator.watchNamespaces lists the namespaces the operator watches. A ClickHouseCluster in any other namespace is never reconciled.
  • operator.rbac.namespaceScoped grants the operator’s permissions on namespaced resources through a Role in each of those namespaces, instead of one cluster-wide ClusterRole.
Set both. The operator still needs a small ClusterRole, because some of the resources it reads are not namespaced: The operator always watches its own namespace in addition to the list you supply, so you do not need to include it yourself.

Steps

1

Decide Which Namespaces the Operator Watches

Each ClickHouse cluster needs its own namespace, so note down every namespace you intend to deploy into.Adding a cluster later means adding its namespace to the list and upgrading the operator release first. Plan for the namespaces you expect to need, including any you will use for compute-compute separation.
2

Enable Namespace-Scoped RBAC

Add both values to your operator values file, operator-values.yaml:
Apply them by upgrading the operator release, keeping your existing values:
The namespaces must exist before the operator release is upgraded, because the chart creates a Role and RoleBinding in each one.
3

Verify the Permissions

Confirm the operator is watching the namespaces you listed. Its own namespace appears alongside them:
Check that a Role exists in each watched namespace:
Confirm what the operator can do, which resolves every binding that applies to it:
Running the same command against a namespace you did not nominate should show only the cluster-wide resources from the table above.

Supplying Your Own ServiceAccount or RBAC

If your organisation provisions identities and permissions outside the chart, you can take over either part. To run the operator as a ServiceAccount you manage, create it first and name it. A name is required, otherwise the chart would bind to an account it did not create:
To manage the operator’s permissions yourself, stop the chart creating them:
Setting operator.rbac.create to false removes the operator’s permissions entirely. It will not reconcile anything until you bind an equivalent Role or ClusterRole to its ServiceAccount. Use the resources the chart generates with rbac.create enabled as the reference for what to grant.
For a worked example, see Minimal Operator RBAC.

Limitations

  • The watch list is fixed at deploy time. Adding a namespace requires an operator release upgrade, so it is not suitable for namespaces created on demand.
  • The operator still needs the cluster-wide permissions listed above. A deployment with no cluster-scoped permissions at all is currently not supported.
Last modified on November 9, 2026