chore: Describe RBAC rules, remove unnecessary rules

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Changed
+
+- Helm deployed RBAC permissions documented, with unnecessary permissions removed ([#1020]).
+
+[#1020]: https://github.com/stackabletech/zookeeper-operator/pull/1020
+
 ## [26.3.0] - 2026-03-16
 
 ## [26.3.0-rc1] - 2026-03-16

deploy/helm/zookeeper-operator/templates/roles.yaml

@@ -6,37 +6,44 @@ metadata:
   labels:
   {{- include "operator.labels" . | nindent 4 }}
 rules:
+  # For automatic cluster domain detection via the local kubelet configz endpoint.
   - apiGroups:
       - ""
     resources:
-      - nodes
+      - nodes/proxy
     verbs:
-      - list
-      - watch
-  # For automatic cluster domain detection
+      - get
+  # Manage core workload resources created per ZookeeperCluster.
+  # All resources are applied via Server-Side Apply (create + patch) and tracked for
+  # orphan cleanup (list + delete). Resources watched by the controller also need watch.
+  # - configmaps: role-group configuration and discovery ConfigMaps (owned by zk and znode controllers)
+  # - services: role-group headless and metrics services (owned by zk controller)
   - apiGroups:
       - ""
     resources:
-      - nodes/proxy
+      - configmaps
+      - services
     verbs:
+      - create
+      - delete
       - get
+      - list
+      - patch
+      - watch
+  # ServiceAccounts are created per ZookeeperCluster to bind the product ClusterRole.
+  # Applied via SSA and tracked for orphan cleanup; not watched by the controller.
   - apiGroups:
       - ""
     resources:
-      - pods
-      - configmaps
-      - secrets
-      - services
-      - endpoints
       - serviceaccounts
     verbs:
       - create
       - delete
       - get
       - list
       - patch
-      - update
-      - watch
+  # RoleBindings bind the product ClusterRole to per-cluster ServiceAccounts.
+  # Applied via SSA and tracked for orphan cleanup; not watched by the controller.
   - apiGroups:
       - rbac.authorization.k8s.io
     resources:
@@ -47,8 +54,7 @@ rules:
       - get
       - list
       - patch
-      - update
-      - watch
+  # Required to create RoleBindings that reference the product ClusterRole.
   - apiGroups:
       - rbac.authorization.k8s.io
     resources:
@@ -57,30 +63,21 @@ rules:
       - bind
     resourceNames:
       - {{ include "operator.name" . }}-clusterrole
+  # StatefulSets are created per role-group. Applied via SSA, tracked for orphan cleanup,
+  # and watched by the zk controller (via .owns()) to trigger reconciliation on changes.
   - apiGroups:
       - apps
     resources:
       - statefulsets
-    verbs:
-      - get
-      - create
-      - delete
-      - list
-      - patch
-      - update
-      - watch
-  - apiGroups:
-      - batch
-    resources:
-      - jobs
     verbs:
       - create
       - delete
       - get
       - list
       - patch
-      - update
       - watch
+  # PodDisruptionBudgets are created per role. Applied via SSA and tracked for orphan
+  # cleanup; not watched by the controller.
   - apiGroups:
       - policy
     resources:
@@ -91,8 +88,6 @@ rules:
       - get
       - list
       - patch
-      - update
-      - watch
   - apiGroups:
       - apiextensions.k8s.io
     resources:
@@ -108,6 +103,7 @@ rules:
       - list
       - watch
       {{- end }}
+  # AuthenticationClasses are read to resolve TLS and client authentication configuration.
   - apiGroups:
       - authentication.stackable.tech
     resources:
@@ -116,34 +112,51 @@ rules:
       - get
       - list
       - watch
+  # Events are emitted to report reconciliation progress and errors.
   - apiGroups:
       - events.k8s.io
     resources:
       - events
     verbs:
       - create
       - patch
+  # Listeners are created per role for load-balanced access to the ZooKeeper cluster.
+  # Applied via SSA and tracked for orphan cleanup. The znode controller also reads them
+  # directly (client.get) to build discovery ConfigMaps. Not watched by the controller.
   - apiGroups:
       - listeners.stackable.tech
     resources:
       - listeners
     verbs:
+      - create
+      - delete
       - get
       - list
-      - watch
       - patch
-      - create
-      - delete
+  # ZookeeperClusters are the primary resource watched by the zk controller (via
+  # Controller::new), and also watched by the znode controller (via .watches()) to
+  # trigger znode reconciliation when the cluster changes.
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
       - {{ include "operator.name" . }}clusters
+    verbs:
+      - get
+      - list
+      - watch
+  # ZookeeperZnodes are the primary resource watched by the znode controller (via
+  # Controller::new). patch is required because the znode controller manages a finalizer
+  # on ZookeeperZnode objects to clean up the ZooKeeper znode before deletion.
+  - apiGroups:
+      - {{ include "operator.name" . }}.stackable.tech
+    resources:
       - {{ include "operator.name" . }}znodes
     verbs:
       - get
       - list
       - patch
       - watch
+  # Status subresource patches are used to report cluster state and znode path.
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
@@ -159,6 +172,9 @@ metadata:
   labels:
   {{- include "operator.labels" . | nindent 4 }}
 rules:
+  # ZooKeeper pods read their own ConfigMap for runtime configuration, their Secret for
+  # TLS credentials (mounted by secret-operator), and their ServiceAccount token for
+  # Kubernetes API authentication.
   - apiGroups:
       - ""
     resources:
@@ -167,6 +183,7 @@ rules:
       - serviceaccounts
     verbs:
       - get
+  # ZooKeeper pods emit events to report operational status.
   - apiGroups:
       - events.k8s.io
     resources:
@@ -175,6 +192,7 @@ rules:
       - create
       - patch
 {{ if .Capabilities.APIVersions.Has "security.openshift.io/v1" }}
+  # Required on OpenShift to allow ZooKeeper pods to run as non-root (nonroot-v2 SCC).
   - apiGroups:
       - security.openshift.io
     resources: