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 ([#693]).
+
+[#693]: https://github.com/stackabletech/hive-operator/pull/693
+
 ## [26.3.0] - 2026-03-16
 
 ## [26.3.0-rc1] - 2026-03-16

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

@@ -6,6 +6,7 @@ metadata:
   labels:
   {{- include "operator.labels" . | nindent 4 }}
 rules:
+  # For automatic cluster domain detection
   - apiGroups:
       - ""
     resources:
@@ -20,59 +21,64 @@ rules:
       - nodes/proxy
     verbs:
       - get
+  # Manage core workload resources created per HiveCluster.
+  # All resources are applied via Server-Side Apply (create + patch) and tracked for
+  # orphan cleanup (list + delete). get is also needed for the ReconciliationPaused strategy.
+  # ConfigMaps and Services are watched by the controller (.owns()) so they also need watch.
+  # - configmaps: role group configuration and discovery ConfigMaps
+  # - services: headless and metrics Services per role group
   - apiGroups:
       - ""
     resources:
-      - pods
       - configmaps
-      - secrets
       - services
-      - endpoints
-      - serviceaccounts
     verbs:
       - create
       - delete
       - get
       - list
       - patch
-      - update
       - watch
+  # ServiceAccount created per cluster instance by build_rbac_resources.
+  # Applied via SSA and tracked for orphan cleanup. Not watched by the controller.
   - apiGroups:
-      - rbac.authorization.k8s.io
+      - ""
     resources:
-      - rolebindings
+      - serviceaccounts
     verbs:
       - create
       - delete
       - get
       - list
       - patch
-      - update
-      - watch
+  # RoleBinding created per cluster instance by build_rbac_resources, binding the
+  # product ClusterRole to the per-cluster ServiceAccount.
+  # Applied via SSA and tracked for orphan cleanup. Not watched by the controller.
   - apiGroups:
-      - apps
+      - rbac.authorization.k8s.io
     resources:
-      - statefulsets
+      - rolebindings
     verbs:
-      - get
       - create
       - delete
+      - get
       - list
       - patch
-      - update
-      - watch
+  # StatefulSet created per role group. Applied via SSA and tracked for orphan cleanup.
+  # Watched by the controller (.owns()).
   - apiGroups:
-      - batch
+      - apps
     resources:
-      - jobs
+      - statefulsets
     verbs:
       - create
       - delete
       - get
       - list
       - patch
-      - update
       - watch
+  # PodDisruptionBudget created per role for availability guarantees.
+  # Applied via SSA and tracked for orphan cleanup. Not watched by the controller.
   - apiGroups:
       - policy
     resources:
@@ -83,8 +89,6 @@ rules:
       - get
       - list
       - patch
-      - update
-      - watch
   - apiGroups:
       - apiextensions.k8s.io
     resources:
@@ -100,28 +104,32 @@ rules:
       - list
       - watch
       {{- end }}
+  # For emitting Kubernetes events during reconciliation.
   - apiGroups:
       - events.k8s.io
     resources:
       - events
     verbs:
       - create
       - patch
+  # Watch HiveCluster objects (the primary CRD) and read them during reconciliation.
+  # get is also needed for the ReconciliationPaused strategy.
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
       - {{ include "operator.name" . }}clusters
     verbs:
       - get
       - list
-      - patch
       - watch
+  # For patching the status subresource of HiveCluster objects via apply_patch_status.
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
       - {{ include "operator.name" . }}clusters/status
     verbs:
       - patch
+  # Read S3Connection objects to configure the metastore's S3 storage.
   - apiGroups:
       - s3.stackable.tech
     resources:
@@ -130,6 +138,7 @@ rules:
       - get
       - list
       - watch
+  # Bind the product ClusterRole to per-cluster ServiceAccounts.
   - apiGroups:
       - rbac.authorization.k8s.io
     resources:
@@ -138,17 +147,18 @@ rules:
       - bind
     resourceNames:
       - {{ include "operator.name" . }}-clusterrole
+  # Listener resource created per role for load balancer / NodePort access.
+  # Applied via SSA and tracked for orphan cleanup. Not watched by the controller.
   - apiGroups:
       - listeners.stackable.tech
     resources:
       - listeners
     verbs:
+      - create
+      - delete
       - get
       - list
-      - watch
       - patch
-      - create
-      - delete
 ---
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
@@ -157,6 +167,8 @@ metadata:
   labels:
   {{- include "operator.labels" . | nindent 4 }}
 rules:
+  # Workload pods need to read their own ConfigMaps (configuration), Secrets (credentials,
+  # TLS certs), and ServiceAccount tokens at runtime.
   - apiGroups:
       - ""
     resources:
@@ -165,6 +177,7 @@ rules:
       - serviceaccounts
     verbs:
       - get
+  # For workload pods to emit Kubernetes events.
   - apiGroups:
       - events.k8s.io
     resources:
@@ -173,6 +186,7 @@ rules:
       - create
       - patch
 {{ if .Capabilities.APIVersions.Has "security.openshift.io/v1" }}
+  # Required on OpenShift to allow the workload pods to run as non-root.
   - apiGroups:
       - security.openshift.io
     resources: