chore: Describe RBAC rules, remove unnecessary rules

Author: NickLarsenNZ

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

@@ -6,6 +6,7 @@ metadata:
   labels:
   {{- include "operator.labels" . | nindent 4 }}
 rules:
+  # For automatic cluster domain detection (list+watch required by the kube controller runtime)
   - apiGroups:
       - ""
     resources:
@@ -20,95 +21,102 @@ rules:
       - nodes/proxy
     verbs:
       - get
+  # Manage core workload resources created per OpaCluster.
+  # All resources are applied via Server-Side Apply (create + patch) and tracked for
+  # orphan cleanup (list + delete). The get verb is required by the ReconciliationPaused
+  # strategy (which calls client.get() instead of apply_patch() when paused).
+  # Resources watched by the controller also need watch.
+  # - configmaps: role-group configs and discovery ConfigMaps; watched via .owns()
+  # - services: role service, per-rolegroup headless and metrics services; watched via .owns()
+  # - serviceaccounts: per-cluster ServiceAccount for the product workload pods
   - apiGroups:
       - ""
     resources:
-      - pods
       - configmaps
-      - secrets
       - services
-      - endpoints
-      - serviceaccounts
     verbs:
       - create
       - delete
       - get
       - list
       - patch
-      - update
       - watch
   - apiGroups:
-      - rbac.authorization.k8s.io
+      - ""
     resources:
-      - rolebindings
+      - serviceaccounts
     verbs:
       - create
       - delete
       - get
       - list
       - patch
-      - update
-      - watch
+  # Per-cluster RoleBinding binding the product ClusterRole to the workload ServiceAccount;
+  # applied via SSA and tracked for orphan cleanup; not watched by the controller.
   - apiGroups:
-      - apps
+      - rbac.authorization.k8s.io
     resources:
-      - daemonsets
+      - rolebindings
     verbs:
-      - get
       - create
       - delete
+      - get
       - list
       - patch
-      - update
-      - watch
+  # Per-rolegroup DaemonSet for OPA server pods; applied via SSA, tracked for orphan
+  # cleanup, and watched via .owns().
   - apiGroups:
-      - batch
+      - apps
     resources:
-      - jobs
+      - daemonsets
     verbs:
       - create
+      - delete
       - get
       - list
       - patch
-      - update
       - watch
+  # Read the CRD at startup to confirm it is established before starting the controller.
+  # With maintenance enabled the operator also creates, patches, lists and watches CRDs
+  # to maintain the CRD (e.g. entering generated certificates into the conversion webhook).
   - apiGroups:
       - apiextensions.k8s.io
     resources:
       - customresourcedefinitions
     verbs:
       - get
-      # Required to maintain the CRD. The operator needs to do this, as it needs to enter e.g. it's
-      # generated certificate in the conversion webhook.
       {{- if .Values.maintenance.customResourceDefinitions.maintain }}
       - create
       - patch
       # Required for startup condition
       - list
       - watch
       {{- end }}
+  # For publishing Kubernetes events from the controller reconciliation loop
   - apiGroups:
       - events.k8s.io
     resources:
       - events
     verbs:
       - create
       - patch
+  # Watch and read OpaCluster resources to drive reconciliation
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
       - {{ include "operator.name" . }}clusters
     verbs:
       - get
       - list
-      - patch
       - watch
+  # Patch OpaCluster status to report conditions back to the user
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
       - {{ include "operator.name" . }}clusters/status
     verbs:
       - patch
+  # Allow binding the product ClusterRole to per-cluster ServiceAccounts
   - apiGroups:
       - rbac.authorization.k8s.io
     resources:
@@ -126,6 +134,8 @@ metadata:
   labels:
   {{- include "operator.labels" . | nindent 4 }}
 rules:
+  # OPA workload pods read ConfigMaps (bundle ConfigMaps, product config) and Secrets
+  # (TLS credentials) and ServiceAccounts (for token projection) at runtime.
   - apiGroups:
       - ""
     resources:
@@ -136,6 +146,7 @@ rules:
       - get
       - list
       - watch
+  # OPA workload pods publish Kubernetes events (e.g. from the user-info-fetcher sidecar)
   - apiGroups:
       - events.k8s.io
     resources:
@@ -144,6 +155,7 @@ rules:
       - create
       - patch
 {{ if .Capabilities.APIVersions.Has "security.openshift.io/v1" }}
+  # Allow the workload pods to use the nonroot-v2 SCC on OpenShift
   - apiGroups:
       - security.openshift.io
     resources: