> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Least-Privilege Operator Permissions

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

> [!NOTE]
>
> 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:

| 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

**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](https://clickhouse.com/docs/cloud/clickhouse-private/how-to/configure-compute-compute-separation.md).

**2. Enable Namespace-Scoped RBAC**

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

```yaml theme={null}
operator:
  watchNamespaces:
    - ns-default-xx-01
    - ns-default-xx-02
  rbac:
    namespaceScoped: true
```

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

```sh theme={null}
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.

**3. Verify the Permissions**

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

```sh theme={null}
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:

```sh theme={null}
kubectl -n ns-default-xx-01 get role,rolebinding
```

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

```sh theme={null}
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:

```yaml theme={null}
operator:
  serviceAccount:
    create: false
    name: my-operator-sa
```

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

```yaml theme={null}
operator:
  rbac:
    create: false
```

> [!WARNING]
>
> 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](https://clickhouse.com/docs/cloud/clickhouse-private/reference/operator-minimal-rbac.md).

## 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.
