chore: simplify the rule descriptions

Author: NickLarsenNZ

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

@@ -15,10 +15,7 @@ rules:
       - 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
+  # orphan cleanup (list + delete).
   - apiGroups:
       - ""
     resources:
@@ -31,8 +28,8 @@ rules:
       - list
       - patch
       - watch
-  # ServiceAccount created per cluster instance by build_rbac_resources.
-  # Applied via SSA and tracked for orphan cleanup. Not watched by the controller.
+  # ServiceAccount created per HiveCluster for workload pod identity.
+  # Applied via SSA and tracked for orphan cleanup.
   - apiGroups:
       - ""
     resources:
@@ -43,9 +40,8 @@ rules:
       - get
       - list
       - patch
-  # 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.
+  # RoleBinding created per HiveCluster to bind the product ClusterRole to the workload
+  # ServiceAccount. Applied via SSA and tracked for orphan cleanup.
   - apiGroups:
       - rbac.authorization.k8s.io
     resources:
@@ -56,8 +52,8 @@ rules:
       - get
       - list
       - patch
-  # StatefulSet created per role group. Applied via SSA and tracked for orphan cleanup.
-  # Watched by the controller (.owns()).
+  # StatefulSet created per role group. Applied via SSA, tracked for orphan cleanup, and
+  # owned by the controller.
   - apiGroups:
       - apps
     resources:
@@ -69,8 +65,7 @@ rules:
       - list
       - patch
       - watch
-  # PodDisruptionBudget created per role for availability guarantees.
-  # Applied via SSA and tracked for orphan cleanup. Not watched by the controller.
+  # PodDisruptionBudget created per role. Applied via SSA and tracked for orphan cleanup.
   - apiGroups:
       - policy
     resources:
@@ -97,16 +92,15 @@ rules:
       # Required for startup condition
       - list
       - watch
-  # For emitting Kubernetes events during reconciliation.
+  # Required to report reconciliation results and warnings back to the HiveCluster object.
   - 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.
+  # Primary CRD: watched by Controller::new() and read during reconciliation.
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
@@ -115,14 +109,14 @@ rules:
       - get
       - list
       - watch
-  # For patching the status subresource of HiveCluster objects via apply_patch_status.
+  # Status subresource: updated at the end of every reconciliation.
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
       - {{ include "operator.name" . }}clusters/status
     verbs:
       - patch
-  # Read S3Connection objects to configure the metastore's S3 storage.
+  # Read S3Connection configuration referenced in the HiveCluster spec.
   - apiGroups:
       - s3.stackable.tech
     resources:
@@ -131,7 +125,7 @@ rules:
       - get
       - list
       - watch
-  # Bind the product ClusterRole to per-cluster ServiceAccounts.
+  # Required to bind the product ClusterRole to the per-cluster ServiceAccount.
   - apiGroups:
       - rbac.authorization.k8s.io
     resources:
@@ -140,8 +134,8 @@ 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.
+  # Listener created per role group for external access. Applied via SSA and tracked for orphan
+  # cleanup.
   - apiGroups:
       - listeners.stackable.tech
     resources:
@@ -160,7 +154,7 @@ metadata:
   labels:
   {{- include "operator.labels" . | nindent 4 }}
 rules:
-  # For workload pods to emit Kubernetes events.
+  # Allows Hive pods to emit Kubernetes events.
   - apiGroups:
       - events.k8s.io
     resources:
@@ -169,7 +163,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.
+  # Required on OpenShift to allow the Hive pods to run as a non-root user.
   - apiGroups:
       - security.openshift.io
     resources: