Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Configure Least-Privilege Operator Permissions

Restrict the ClickHouse operator to a named set of namespaces instead of granting it permissions across the whole cluster.

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:

Scope Resources
Cluster-wide namespaces, persistentvolumes, and the licenses custom resource
Each watched namespace statefulsets, pods, services, configmaps, secrets, persistentvolumeclaims, poddisruptionbudgets, events, and the namespaced ClickHouse custom resources
Operator namespace, by default clickhouse-operator-system the same namespaced set, because the operator reads its license secret there

The operator always watches its own namespace in addition to the list you supply, so you do not need to include it yourself.

Steps

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.

Enable Namespace-Scoped RBAC

Add both values to your operator values file, operator-values.yaml:

operator:
  watchNamespaces:
    - ns-default-xx-01
    - ns-default-xx-02
  rbac:
    namespaceScoped: true

Apply them by upgrading the operator release, keeping your existing values:

helm upgrade clickhouse-operator \
  oci://<your-registry>/helm/clickhouse-operator-helm \
  --version <version> \
  --namespace clickhouse-operator-system \
  --values operator-values.yaml

The namespaces must exist before the operator release is upgraded, because the chart creates a Role and RoleBinding in each one.

Verify the Permissions

Confirm the operator is watching the namespaces you listed. Its own namespace appears alongside them:

kubectl -n clickhouse-operator-system logs deploy/clickhouse-operator-clickhouse-operator-helm | grep "informer cache is scoped"

Check that a Role exists in each watched namespace:

kubectl -n ns-default-xx-01 get role,rolebinding

Confirm what the operator can do, which resolves every binding that applies to it:

kubectl auth can-i --list -n ns-default-xx-01 \
  --as=system:serviceaccount:clickhouse-operator-system:clickhouse-operator-clickhouse-operator-helm

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:

operator:
  serviceAccount:
    create: false
    name: my-operator-sa

To manage the operator’s permissions yourself, stop the chart creating them:

operator:
  rbac:
    create: false

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.